Improve permalinks docs #5693
Improve permalinks docs #5693
Conversation
See #5630 for more details on the update. @jekyll/documentation @DirtyF
| using template variables will. | ||
| </p> | ||
| <h5>Specifying permalinks through the YAML Front Matter</h5> | ||
| <p>Built-in permalink styles are not recognized in YAML Front Matter. As a result, <code>permalink: pretty</code> will not work, but the equivalent <code>/:categories/:year/:month/:day/:title/</code> using template variables will.</p> |
There was a problem hiding this comment.
This just means you can't use template variables in the permalink attribute in the individual files. I think it is mostly true.
There was a problem hiding this comment.
I tried putting this into a page's front matter and got an error:
---
permalink: "/:categories/:year/:month/:day/:title/"
---
What am I missing here? How does that work? Or is this note trying to say that if you wrote out something like this it would work:
---
permalink: /mycat/2016/12/28/mypagetitle/
---
That's not what the note says. It says you can use template variables in the page permalink. I don't see how one does that.
| </div> | ||
| {% endcomment %} | ||
|
|
||
| When you use permalinks that omit the `.html` file extension (called "clean URLs") Jekyll builds the file as index.html placed inside a folder with the page's name. For example: |
There was a problem hiding this comment.
We should make the distinction here between "clean URLs" and "pretty URLs", as they can be easily confused. I call these extensionless URL's, as they omit the extension of the file.
There was a problem hiding this comment.
Actually, in the "Extensionless permalinks" section, it defines these by saying "Jekyll supports permalinks that contain neither a trailing slash nor a file extension." In other words, here is an extensionless permalink by that definition: /somefileurl. Is that section wrong? I don't see how "Extensionless" describes a URL that lacks a trailing slash, so I'll update that subheading.
Re clean versus pretty, good point. I didn't realize the difference, but now I see that clean URLs omit the query string, whereas pretty URLs omit the file extension. Personally, I like my URLs both clean and pretty, but if only given one of the two, I will take pretty over clean. <joke/>
| │ └── index.html | ||
| ``` | ||
|
|
||
| Servers automatically load the index.html file inside of any folder, so users can simply navigate to `http://somedomain.com/mypageurl` to get to `mypageurl/index.html`. |
There was a problem hiding this comment.
This is incorrect.
http://somedomain.com/mypageurl attempts to read http://somedomain.com/mypageurl.html.
http://somedomain.com/mypageurl/ attempts to read http://somedomain.com/mypageurl/index.html.
There was a problem hiding this comment.
ahh, i didn't realize this. thanks.
There was a problem hiding this comment.
If I go to http://jekyllrb.com/news/2016/11/14/jekyll-3-3-1-released, the server auto-updates the path to http://jekyllrb.com/news/2016/11/14/jekyll-3-3-1-released/. Is the server first looking at http://jekyllrb.com/news/2016/11/14/jekyll-3-3-1-released.html and then, not finding the file, re-directing to http://jekyllrb.com/news/2016/11/14/jekyll-3-3-1-released/index.html?
| [multiviews]: https://httpd.apache.org/docs/current/content-negotiation.html#multiviews | ||
| ### Posts | ||
|
|
||
| No matter how many subfolders you organize your posts into inside the `_posts` folder, all posts are pulled out of those subfolders and flattened into the `_site`'s root directory upon build. |
There was a problem hiding this comment.
The last bit here is kind of misleading. Could we say:
The subfolders you may organize your posts into inside
_postswill not be a part of the permalink.
|
|
||
| ### Pages | ||
|
|
||
| Unlike posts, pages are *not* removed from their subfolder directories when you build your site. Pages remain in the same folder structure in which you organized your pages in the source directory, except that the structure is now mirrored in `_site`. (The only exception is if your page has a `permalink` declared its front matter — in that case, the structure honors the permalink setting instead of the source folder structure.) |
There was a problem hiding this comment.
I don't like talking about what pages don't do.
Unlike posts, pages by default mimic exactly the source directory structure.
- made updates from Parkr's review - update to Extensionless permalinks section - update to note about not using built-in perm styles in front matter - update for readability in places
|
Made the updates. Submitting for review. |
|
I have to say I like the care and attention the team places on docs. I wish people were this quick to review docs at my work. One thing I don't get, though, is why the "documentation team" (the Github team organization) seems so quiet. |
|
Another question. I have the box checked that says "Allow edits from maintainers." This means you can make edits directly on the content. Just wondering why you guys never do that, esp. for small typos or formatting issues. Does it create conflicts or something? |
|
@jekyllbot: merge +docs |
See #5630 for more details on the update.
@jekyll/documentation