Knowing how Jekyll forms the url for you makes it easier to work with.
Posts categories and permalink
To publish a jekyll post, you put it under the directory _posts/
, which is automatically recognized by Jekyll. It is mandatory that the file name has the format yyyy-mm-dd-post-name.md
, so it can be used to generate the associated post url.
For example, the markdown file of this page is 2018-10-04-post-url-by-jekyll.md (under _posts/
), which should show up as a page at my-host-name/2018/10/04/post-url-by-jekyll.html.
Note, however, that the post URL is modified when “categories” and “permalink” are set in the front matter of the post.
Post front matter | Post URL (omitting host-name) |
---|---|
- | /2018/10/04/article-name.html |
categories: catA |
/catA/2018/10/04/article-name.html |
categories: [catA, catB] |
/catA/catB/2018/10/04/article-name.html |
permalink: /pl/ |
/pl/2018/10/04/article-name.html |
permalink: /pl/pl/ |
/pl/pl/2018/10/04/article-name.html |
- “permalink” dominates when is set, in which case “categories” no longer affects the url (The category setting still works, but is not reflected in the url).
- “tags” does not change the url.
- The directory structure under
_post/
does not change the url (even when both categories and permalink are not present.)
Pages permalink
You can freely create pages that are not posts and put them outside the _posts
directly. They simply become stand-alone web pages. The url of these pages are determined by the directory structure. This can be overwritten by specifying a permalink in the front matter.
For example, if I have a file under a directly page_dir/
(not special to jekyll, unlike _posts/
), say page_dir/pageA.md
. then directory becomes part of the page url unless a permalink is specified.
Page front matter | Page URL (omitting host-name) |
---|---|
- | /page_dir/pageA.html |
permalink: /pageA.html | /pageA.html |
Unlike for posts:
- “categories” does not matter.
- “permalink” completely decide the page url. So include everything needed.