New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve permalinks docs #5693

Merged
merged 3 commits into from Jan 2, 2017

Conversation

Projects
None yet
4 participants
@tomjoht
Contributor

tomjoht commented Dec 26, 2016

See #5630 for more details on the update.

@jekyll/documentation

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

@jekyll/documentation
@DirtyF
@parkr

parkr approved these changes Dec 29, 2016

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

Show outdated Hide outdated 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>

This comment has been minimized.

@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.

@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.

This comment has been minimized.

@tomjoht

tomjoht Dec 29, 2016

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.

@tomjoht

tomjoht Dec 29, 2016

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.

Show outdated Hide outdated 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:

This comment has been minimized.

@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.

@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.

This comment has been minimized.

@tomjoht

tomjoht Dec 29, 2016

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

@tomjoht

tomjoht Dec 29, 2016

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

Show outdated Hide outdated 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`.

This comment has been minimized.

@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.

@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.

This comment has been minimized.

@tomjoht

tomjoht Dec 29, 2016

Contributor

ahh, i didn't realize this. thanks.

@tomjoht

tomjoht Dec 29, 2016

Contributor

ahh, i didn't realize this. thanks.

This comment has been minimized.

@tomjoht

tomjoht 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?

@tomjoht

tomjoht 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?

Show outdated Hide outdated 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.

This comment has been minimized.

@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.

@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.

This comment has been minimized.

@tomjoht

tomjoht Dec 29, 2016

Contributor

updated

@tomjoht

tomjoht Dec 29, 2016

Contributor

updated

Show outdated Hide outdated 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.)

This comment has been minimized.

@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.

@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.

This comment has been minimized.

@tomjoht

tomjoht Dec 29, 2016

Contributor

okay, updated.

@tomjoht

tomjoht Dec 29, 2016

Contributor

okay, updated.

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
@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Dec 29, 2016

Contributor

Made the updates. Submitting for review.

Contributor

tomjoht commented Dec 29, 2016

Made the updates. Submitting for review.

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Dec 29, 2016

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.

Contributor

tomjoht commented Dec 29, 2016

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.

@tomjoht

This comment has been minimized.

Show comment
Hide comment
@tomjoht

tomjoht Dec 29, 2016

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?

Contributor

tomjoht commented Dec 29, 2016

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

@DirtyF

This comment has been minimized.

Show comment
Hide comment
@DirtyF

DirtyF Jan 2, 2017

Member

@jekyllbot: merge +docs

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

jekyllbot added a commit that referenced this pull request Jan 2, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment