Improve permalinks docs #5693

Merged
merged 3 commits into from Jan 2, 2017

Projects

None yet

4 participants

@tomjohnson1492
Contributor
tomjohnson1492 commented Dec 26, 2016 edited

See #5630 for more details on the update.

@jekyll/documentation

@tomjohnson1492 tomjohnson1492 Improve permalinks docs
See jekyll#5630 for more details on the update. 

@jekyll/documentation
@DirtyF
93cd0cd
@parkr
parkr approved these changes Dec 29, 2016 View changes

Great! Just a few comments. Thanks again for this!

docs/_docs/permalinks.md
- 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>
@parkr
parkr Dec 29, 2016 Member

This just means you can't use template variables in the permalink attribute in the individual files. I think it is mostly true.

@tomjohnson1492
tomjohnson1492 Dec 29, 2016 edited Contributor

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.

docs/_docs/permalinks.md
</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:
@parkr
parkr Dec 29, 2016 Member

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.

@tomjohnson1492
tomjohnson1492 Dec 29, 2016 edited Contributor

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/>

docs/_docs/permalinks.md
+│   └── 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`.
@parkr
parkr Dec 29, 2016 Member

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.

@tomjohnson1492
tomjohnson1492 Dec 29, 2016 Contributor

ahh, i didn't realize this. thanks.

@tomjohnson1492
tomjohnson1492 Dec 29, 2016 Contributor

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?

docs/_docs/permalinks.md
-[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.
@parkr
parkr Dec 29, 2016 Member

The last bit here is kind of misleading. Could we say:

The subfolders you may organize your posts into inside _posts will not be a part of the permalink.

@tomjohnson1492
tomjohnson1492 Dec 29, 2016 Contributor

updated

docs/_docs/permalinks.md
+
+### 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 &mdash; in that case, the structure honors the permalink setting instead of the source folder structure.)
@parkr
parkr Dec 29, 2016 Member

I don't like talking about what pages don't do.

Unlike posts, pages by default mimic exactly the source directory structure.

@tomjohnson1492
tomjohnson1492 Dec 29, 2016 Contributor

okay, updated.

@tomjohnson1492 tomjohnson1492 made updates
- 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
b1b0d00
@tomjohnson1492
Contributor

Made the updates. Submitting for review.

@tomjohnson1492
Contributor

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.

@tomjohnson1492
Contributor

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?

@DirtyF
DirtyF approved these changes Jan 2, 2017 View changes
@DirtyF DirtyF Merge branch 'master' into patch-7
a44a1ef
@DirtyF
Member
DirtyF commented Jan 2, 2017

@jekyllbot: merge +docs

@DirtyF DirtyF closed this Jan 2, 2017
@jekyllbot jekyllbot merged commit da28991 into jekyll:master Jan 2, 2017

1 of 2 checks passed

continuous-integration/appveyor/pr Waiting for AppVeyor build to complete
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment