Revamp Permalink section #5912
Revamp Permalink section #5912
Conversation
The previous version contained errors regarding the definition and usage of the `:path` permalink template variable. This version corrects those errors, removes redundant language where possible, and restructures the section to place examples before template variable definitions. The reasoning behind the third change is that it's generally easier for learners to understand a generalized or abstracted definition after having seen concrete examples in action first.
|
/cc @jekyll/documentation |
docs/_docs/collections.md
Outdated
| ``` | ||
| ├── _apidocs | ||
| │ └── archive | ||
| │ └── deprecated.md |
There was a problem hiding this comment.
Why do you have "deprecated.md" as an example of the file here? What's this about?
There was a problem hiding this comment.
Ha, I was worried that might raise an eyebrow.
I figured that a generic-but-realistic use case would make for a more descriptive example than apidocs/mydocs/doc1.md; i.e., that it would be easier to imagine why you might choose to set your permalinks up as, say, doc/deprecated.html than awesome/doc1.html. But I also wrote it in a hurry, and I recognize that maybe apidocs/archive/deprecated.md is not as realistic as it could be.
If it creates more confusion than it resolves, I'm happy to change it back to apidocs/mydocs/doc1.md and resubmit the PR.
There was a problem hiding this comment.
I suggest using a generic file name that doesn't call attention to itself like "deprecated" does. Maybe myfile.my or something. I have some more comments that I'll insert inline.
There was a problem hiding this comment.
We could use a more generic file name, but I don't mind the current example here, seems pretty explanatory to me.
docs/_docs/collections.md
Outdated
| @@ -89,18 +89,59 @@ choice and written out to `<dest>/my_collection/some_subdir/some_doc.html`. | |||
|
|
|||
| ## Configuring permalinks for collections {#permalinks} | |||
|
|
|||
| You can customize the [Permalinks](../permalinks/) for your collection's documents by setting `permalink` property in the collection's configuration as follows: | |||
| You can specify a pattern for the URLs where your Collection documents will reside with the [`permalink` property](../permalinks/): | |||
There was a problem hiding this comment.
There's a modifier problem with the last "with the ..." clause. Maybe recast as "Through the permalink property, you can specify a pattern for the URLs for your Collection documents. The permalink also defines the structure for the files in the output."
|
In the Examples section, the tree formatting is messed up. This may be intentional, but it looks awkward like this to me. Can you preserve the tree formatting in the examples in a way that leaves the tree diagrams complete? |
|
If you don't want to use the complete tree diagrams there, you could use forward slashes instead. |
|
@DirtyF Where are you with this? Need more info? |
|
Sorry to ghost you guys, I'm happy to make the changes @tomjohnson1492 requested, and will get to work on it this weekend. |
|
Okay folks, I've made the changes requested. @tomjohnson1492:
Let me know if there's anything else I should do! |
docs/_docs/collections.md
Outdated
|
|
||
| ```yaml | ||
| collections: | ||
| my_collection: | ||
| categories: |
There was a problem hiding this comment.
Did you mean to replace my_collection with categorieshere?
docs/_docs/collections.md
Outdated
| output: true | ||
| permalink: /awesome/:path/:title.:output_ext | ||
| permalink: /category/:name |
docs/_docs/collections.md
Outdated
|
|
||
| * **Default** | ||
| Same as `permalink: /:collection/:path`. | ||
| ``` |
There was a problem hiding this comment.
Please insert carriage returns to create a paragraph before each code sample
|
Good looking out! |
|
@rlue Thanks for making Jekyll's documentation better 📗 @jekyllbot: merge +docs |
The previous version contained errors regarding the definition and usage of the
:pathpermalink template variable (see Issue #5901). This version corrects those errors, removes redundant language where possible, and restructures the section to place examples before template variable definitions.The reasoning behind the third change is that it's generally easier for learners to understand a generalized or abstracted definition after having seen concrete examples in action first.