I'm looking into prose.io and I would like to find out more about the content management work flow.
Do prose.io content contributors get access via prose.io to the master repository on GitHub or do they work on a branch or even on a fork?
I'm wondering how much can go wrong and how messy the master repo gets when everyone has access?
Is there an option to combine pull requests with prose?
Using prose for my personal blog and its the master repo prose gets access to.
However there is something you can do. In Jekyll _config.yml you can set prose parameter option for rooturl: "DIRECTORY NAME" what this does is limits the prose access to directory. In my case there is directory called _posts and prose cannot edit anything outside of it. There is also ignore option that basically makes folders invisible on prose. I
Here is my prose config for use as an example. Here I use both root and ignore options.
prose:
rooturl: '_posts'
media: 'img'
ignore:
- 404.html
- LICENSE
- feed.xml
- _config.yml
- /_layouts
- /_includes
- /css
- /img
- /js
metadata:
_posts:
- name: "layout"
field:
element: "hidden"
value: "post"
- name: "title"
field:
element: "text"
label: "Post title"
placeholder: "Title"
alterable: true
- name: "subtitle"
field:
element: "textarea"
label: "Subtitle"
placeholder: "A description of your post."
alterable: true
- name: "date"
field:
element: "text"
label: "Date"
help: "Enter date of post."
placeholder: "yyyy-mm-dd"
alterable: true
- name: "published"
field:
element: "checkbox"
label: "Publish"
help: "Check to publish post, uncheck to hide."
More on the options here >
https://github.com/prose/prose/wiki/Prose-Configuration
Prose doesn't necessarily commit to master, rather it commits to your default branch. That is usually master, but you can change it. For instance, if you're using GitHub Pages your default branch would be gh-pages.
In our workflow, we're now trying to separate the branch that contributors edit on from the version we use for production. We leave the default as master (for simplicity), but keep our production version in a separate branch (e.g. production). Project owners then carefully merge or cherry pick from master into production.
Prose may soon allow you to change the branch it commits to from the GitHub default branch, at which point we'll revisit our workflow.
Related
I have a manually triggered job that builds and deploys an image based on the tag I specify. Is there a way to make the workflow name dynamic?
name: Build and push
on:
workflow_dispatch:
inputs:
tag:
description: 'Image Tag'
required: true
jobs:
...
I would like to do something like
name: "Build and push ${{ github.event.inputs.tag }}"
As of Sep 26th 2022, this is now supported. Here's the announcement (which contains a link to the documentataion): https://github.blog/changelog/2022-09-26-github-actions-dynamic-names-for-workflow-runs/
Workflow names are not dynamic, but fixed.
To get at the actual data of a workflow run, you'll have to chose the specific run from the Actions > All Workflows > [name-of-your-workflow] list.
Alternatively, you can think about other ways to propagate the outcomes of your builds.
Our team, for example, propagates build outcomes to teams chat channel (in our case Microsoft Teams using the action notify-microsoft-teams). If you search the market place you'll find plenty of actions for this.
Another alternative could be to generated custom badges, which you could then make visible to your team. A nice action for this is bring-your-own-badge.
Last but not least you can propagate your workflow run data using emails (again, there are actions which do this for you).
I'm setting up a website with multi language support.
In the root directory I have one or more directories based on the language locale, e.g.: /en /it
I'm trying to set one language as default and let Jekyll generate its pages in the root of the _site directory, by setting the defaults section in _config.yml as described below. Other directories will be generated as usual.
I don't want:
to use a plugin since it have to work also with GitHub pages
to set a lang: en variable in each page front-matter but setting it globally in _config.yml instead if possible
put a load of files/directories in the root directory, just the various en, it, fr etc (if not having something like described below, but using a master pages directory).
I tried various solutions, including:
using collections: it works as expected with the example below but I don't want to use them for various reasons, like not having sitemap plugin working with them
using this solution, but it doesn't work with multiple pages with same name and other types of documents
This works with collections with an _en directory in the root:
collections:
en:
output: true
permalink: /:path
defaults:
...
- scope:
path: ""
type: "en"
values:
layout: "default"
lang: "en"
permalink: /:path
Not this, IMHO as it should be for pages:
defaults:
...
- scope:
path: "en"
type: "pages"
values:
layout: "default"
lang: "en"
permalink: /:path
In brief I need:
custom variables set for each page in the specified directory globally instead in each page front matter
make Jekyll to generate all pages from the specified directory to build in the root of _site directory using a global permalink
What I'm trying to do
Jekyll can use front matter variables like tags and categories and access them with site.tags and site.categories to iterate over them using liquid.
Now my problem is that I can't do this with a custom front matter variable like author (as in site.authors) because Jekyll will not store it in a list format. This makes it very hard to paginate it.
The problem
Every solution I have looked at i.e.
how to handle multiple authors in Jekyll
adding authors to Jekyll
jekyll-author
requires me to hardcode a list of authors to _config.yml or some other .yml (i.e. in _data/authors.yml).
The problem here is that I don't use a fixed list of authors. The authors list needs to get updated when I throw in another post with a front-matter tag author: exampleAuthor or a list of authors (as in multiple authors per post, as currently only possible with categories and tags as well), while the server is running. It works with tags and categories splendidly, but not with custom tags like authors.
The easiest solution would to have a site.authors list to iterate over and just extending it with a ruby plugin.
I haven't found a plugin that provides me with a solution and thinking this was a common problem that I'm probably not the first to have.
What I tried
I then looked at writing my own ruby plugin (Which is hard on it's own because of the lack of documentation. Maybe I'm to dumb to google, but the resources I found where very limited and hardly enough to guide you through the process) but there has to be a reason why this is so hard to do that makes all the existing solutions require hard-coding the author list in a .yml (or .json, but most people go with .yml for some reason).
Doing this is out of the question for me, since I want to only throw in posts with author names in it later on and manipulating a .yml (I am under the impression that .yml-files don't get compiled once the server is started, like _config.yml, correct me if I'm wrong) would be counterproductive because it requires you to restart the server to have them compiled.
Even very advanced plugins like jekyll-paginate-v2 (which I use successfully to paginate posts by tags and categories) don't have a solution to this, as shown by this issue. As per this issue, it is getting recommended to misuse the category variable to paginate by author. In my opinion, that is desperate workaround and too hacky to be considered.
I have found suggestions that it could also be done with collections, but this would again
requiring to hard-coding the author list (again, I don't want that. I don't have a fixed list of authors. All of the author information has to come from the front-matter in the /_posts directory .md files)
As of now I don't see how it can be done with collections.
However I'm open to suggestions.
Edit: I found this dated issue on Jekylls github page which highlights that people are trying to do the same but to no avail.
Has this become viable in the last 4 years?
For someone still looking for a way to
Generate author pages automatically just by dropping author: name to post front matter,
Have pagination on the author pages (a good optimization).
I built a plugin jekyll-auto-authors that works in sync with jekyll-paginate-v2 to enable author auto pages along with pagination.
I wrote this guide and made this video to help with the setup.
The bare minimum setup instructions:
Install the plugin:
group :jekyll_plugins do
# other gems
gem "jekyll-paginate-v2" # reqiured for jekyll-auto-authors to work
gem "jekyll-auto-authors"
end
Enable it:
plugins:
# other plugins
- jekyll-paginate-v2
- jekyll-auto-authors
Make a data file with author data, for example using _data/authors.yml:
johndoe:
name: "John Doe"
bio: "John Doe is a software engineer."
email: "john#example.com"
socials:
github: "john-doe"
twitter: "john_doe"
janedoe:
name: "Jane Doe"
bio: "Jane Doe is a systems engineer."
email: "jane#example.com"
socials:
github: "jane-doe"
twitter: "jane_doe"
Make a layout for the author page, let's say _layout/author.html. Example layout can be taken from the article.
Enable pagination and auto pages for authors in _config.yml file:
pagination:
enabled: true
per_page: 9
permalink: '/page/:num/'
title: ':title - page :num'
sort_field: 'date'
sort_reverse: true
autopages:
enabled: true
# enable auto pages for tags/categories/collections as per need. Disabling for this demo.
tags:
enabled: false
categories:
enabled: false
collections:
enabled: false
authors:
enabled: true # adding false here stops the auto-generation
data: '_data/authors.yml' # Data file with the author details
layouts:
- 'author.html' # We'll define this layout later, will be used for each author
title: 'Posts by :author'
permalink: '/author/:author/'
slugify:
mode: 'default' # choose from [raw, default, pretty, ascii or latin]
cased: true # if true, the uppercase letters in slug will be converted to lowercase ones.
That's the initial setup!
Now drop in the author value in the front matter of posts:
---
# other configs
author: johndoe
---
This will generate a page as defined in the permalink block of the auto pages configuration. If there's pagination enabled, and per_page value is exceeded, the additional pages will be generated in /page/:num/ format.
To render the author values, the plugin exposes page.pagination.author_data value
{% assign author = page.pagination.author_data %}
<!-- Use {{ author.name }} or any such value, as defined inside the data file -->
To show next and previous buttons, you can use this logic that paginator exposes:
{% if paginator.total_pages > 1 %}
<ul>
{% if paginator.previous_page %}
<li>
Newer
</li>
{% endif %}
{% if paginator.next_page %}
<li>
Older
</li>
{% endif %}
</ul>
{% endif %}
The initial setup is overwhelming, but once done you can then just drop in author data inside _data/authors.yml file and add author: value inside post frontmatter and it is fairly easy then!
P.S. I developed this solution for Genics Blog as managing multiple authors got hard. To learn how I've implemented it at Genics, please check out the theme-files repository.
Update
I released v1.0.1 just now, which makes adding the data parameter to author autopage configuration optional.
If data isn't defined, you can still access the author username string with page.pagination.author. You can use it to show the username on the page.
If data is defined, page.pagination.author_data variable is available. This would be a hashmap that has data as defined in the data file.
This means that you just have to:
Add and enable the plugin.
Set up pagination and author pages config.
Make a layout file.
And you can just drop in author: username to post files to generate autopages for them with pagination!
Adding authors to Jekyll posts is easy with collections. Here's a proof of concept for you. Specifically, in this commit I add everything you need for it.
As for your question about pagination, will need to use a pagination plugin (paginate-v2 is good), as I believe the built in pagination only supports the posts collection.
I am trying to add a new post to my Jekyll site, but I cannot see it on the generated pages when I run jekyll serve.
What are some common reasons for a Jekyll post to not be generated?
The post is not placed in the _posts directory.
When you change the collections_dir in your config from . (default) to my_col_folder all your posts have to move as well below my_col_folder/_posts jekyll defaults
The post has incorrect title. Posts should be named YEAR-MONTH-DAY-title.MARKUP (Note the MARKUP extension, which is usually .md or .markdown)
The post's date is in the future. You can make the post visible by setting future: true in _config.yml (documentation)
The post has published: false in its front matter. Set it to true.
The title contains a : character. Replace it with :. Works in jekyll 3.8.3 (and probably in other 'recent' releases).
You can use jekyll build --verbose to view build process in detail.
Exmaple output:
Logging at level: debug
Configuration file: /home/fangxing/fffx.github.io/_config.yml
Logging at level: debug
Requiring: jekyll-archives
Requiring: jekyll-livereload
Requiring: kramdown
Source: /home/fangxing/fffx.github.io
Destination: /home/fangxing/fffx.github.io/_site
Incremental build: enabled
Generating...
EntryFilter: excluded /Gemfile
EntryFilter: excluded /Gemfile.lock
Reading: _posts/2018-01-14-new-post.md
Reading: _posts/2014-01-01-example-content.md
Reading: _posts/2014-01-02-introducing-lanyon.md
Reading: _posts/2017-11-21-welcome-to-jekyll.markdown
Reading: _posts/2018-01-14-boot-android-on-charge.md
Reading: _posts/2013-12-31-whats-jekyll.md
Skipping: _posts/2018-01-14-boot-android-on-charge.md has a future date
Generating: Jekyll::Archives::Archives finished in 0.000122873 seconds.
Generating: JekyllFeed::Generator finished in 0.000468846 seconds.
...
from the log I found jeklly skipped 2018-01-14-boot-android-on-charge.md because it has a future date.
One possible reason is that the date specified in the front matter does not contain a time zone offset, in which case it defaults to UTC, not the time zone of the local machine as you might expect. I wasted an hour on this until UTC "caught up" with my current local time zone, BST.
I haven't found a definitive answer to this but I think the date in the front matter must be given in UTC with a timezone offset (which defaults to zero if omitted).
So date: 2018-05-03 12:34:27 is in UTC irrespective of where in the world you are, and irrespective of the timezone setting in _config.yml.
So be careful to specify datetimes like this:
date: 2018-05-03 12:34:27 +0100
Or it can be browser cache as well if you are looking not in the _site folder but directly on the blog's main page with the list of posts.
I have written Rspec tests for my blog that express these rules:
require 'spec_helper'
require 'yaml'
# Documented at https://jekyllrb.com/news/2017/03/02/jekyll-3-4-1-released/
post_regex = %r!^(?:.+/)*(\d{2,4}-\d{1,2}-\d{1,2})-(.*)(\.[^.]+)$!
def date_in_front_matter(date)
return date if date.is_a?(Date)
return date.to_date if date.is_a?(Time)
return Date.parse(date) if date.is_a?(String)
end
describe 'posts' do
Dir.glob("_posts/*md").each do |file|
basename = File.basename(file)
context basename do
front_matter = YAML.load(File.read(file).split(/---/)[1])
it 'filename must match documented post regex' do
expect(basename).to match post_regex
end
it 'date in file name same day as date in front matter' do
date_in_file_name = Date.parse(post_regex.match(basename).captures[0])
expect(date_in_front_matter(front_matter['date'])).to eq date_in_file_name
end
it 'title in front matter should not contain a colon' do
expect(front_matter['title']).to_not match /:/
end
it 'front matter should not have published: false' do
expect(front_matter['published']).to_not be false
end
end
end
end
This may be of use to others as I was losing a lot of time due to typos in the date etc.
These tests along with the rest of the Rspec config can be seen in context here.
Just to add one more reason, when you move an article from _drafts to _post, you sometimes need to delete the _site for the article to be regenerated.
In my case it often happens that _site will not be entirely deleted before re-generation so the new article won't appear.
Anyway rm -rf _site and bundle exec jekyll serve works :)
If you are unable to track the file in --verbose and if the file is silently ignored then try removing collections_dir in the config.yml file. That solved the issue for me.
My post also did not appear an the error was, that in my name I used a dot, e.g. 2017-10-18-test.2.md.
This is not accepted, you have to use 2017-10-18-test2.md.
If you have checked your front matter, and all seems well, and even jekyll build --verbose doesn't reveal anything (in my case, it just acted as if the file didn't exist at all, not even listing it as excluded), check the encoding of your file. Apparently, it needs to be UTF-8 without signature. It it's UTF-8 BOM (or UTF-8 with Signature as some text editors call it), then it will be silently ignored. To make matters worse, some editors will display both types as just UTF-8, making the difference even harder to spot.
I've set up mercurial server and default mercurial web interface. I've set collapse option to true so I can see folder hierarchy when viewing repositories in web interface. I know that I can set name, description, contact etc. for each repository and all that stuff will be shown in web interface. Is it possible to do the same for the folders?
Found answer in mercurial sources.
Here you can see than contact and description fields are always empty for directories:
# add '/' to the name to make it obvious that
# the entry is a directory, not a regular repository
row = {'contact': "",
'contact_sort': "",
'name': name + '/',
'name_sort': name,
'url': url,
'description': "",
'description_sort': "",
'lastchange': d,
'lastchange_sort': d[1]-d[0],
'archives': [],
'isdirectory': True}
seendirs.add(name)
yield row
When you try to cheat and create empty .hg folder by yourself, mercurial will treat that folder as a mercurial repository and when you try to open this folder in web interface, you'll see repository overview instead of directory listing.
So, I can't do what I want without modifying sources.