From 94e6b65ad4a25094846e810a1f91dc388a69e171 Mon Sep 17 00:00:00 2001 From: Ryan Lue Date: Wed, 5 Apr 2017 06:40:29 +0800 Subject: [PATCH] Revamp Permalink section (#5912) Merge pull request 5912 --- docs/_docs/collections.md | 153 +++++++++++++++++--------------------- 1 file changed, 67 insertions(+), 86 deletions(-) diff --git a/docs/_docs/collections.md b/docs/_docs/collections.md index 97ca6ecb..fa82e096 100644 --- a/docs/_docs/collections.md +++ b/docs/_docs/collections.md @@ -89,18 +89,75 @@ choice and written out to `/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: +If you wish to specify a custom pattern for the URLs where your Collection pages +will reside, you may do so with the [`permalink` property](../permalinks/): ```yaml collections: my_collection: output: true - permalink: /awesome/:path/:title.:output_ext + permalink: /:collection/:name ``` -In this example, the collection documents will the have the URL of `awesome` followed by the path to the document and its file extension. +### Examples -Collections have the following template variables available for permalinks: +For a collection with the following source file structure, + +``` +_my_collection/ +└── some_subdir + └── some_doc.md +``` + +each of the following `permalink` configurations will produce the document structure shown below it. + +* **Default** + Same as `permalink: /:collection/:path`. + + ``` + _site/ + ├── my_collection + │   └── some_subdir + │   └── some_doc.html + ... + ``` +* `permalink: pretty` + Same as `permalink: /:collection/:path/`. + + ``` + _site/ + ├── my_collection + │   └── some_subdir + │   └── some_doc + │   └── index.html + ... + ``` +* `permalink: /doc/:path` + + ``` + _site/ + ├── doc + │   └── some_subdir + │   └── some_doc.html + ... + ``` +* `permalink: /doc/:name` + + ``` + _site/ + ├── doc + │   └── some_doc.html + ... + ``` +* `permalink: /:name` + + ``` + _site/ + ├── some_doc.html + ... + ``` + +### Template Variables
@@ -113,7 +170,7 @@ Collections have the following template variables available for permalinks:
-

collection

+

:collection

Label of the containing collection.

@@ -121,7 +178,7 @@ Collections have the following template variables available for permalinks:
-

path

+

:path

Path to the document relative to the collection's directory.

@@ -129,7 +186,7 @@ Collections have the following template variables available for permalinks:
-

name

+

:name

The document's base filename, with every sequence of spaces @@ -138,7 +195,7 @@ Collections have the following template variables available for permalinks:

-

title

+

:title

The document's lowercase title (as defined in its front matter), with every sequence of spaces and non-alphanumeric characters replaced by a hyphen. If the document does not define a title in its front matter, this is equivalent to name.

@@ -146,92 +203,16 @@ Collections have the following template variables available for permalinks:
-

output_ext

+

:output_ext

 -

Extension of the output file.

+

Extension of the output file. (Included by default and usually unnecessary.)
-## Permalink examples for collections - -Depending on how you declare the permalinks in your configuration file, the permalinks and paths get written differently in the `_site` folder. A few examples will help clarify the options. - -Let's say your collection is called `apidocs` with `doc1.md` in your collection. `doc1.md` is grouped inside a folder called `mydocs`. Your project's source directory for the collection looks this: - -``` -├── \_apidocs -│   └── mydocs -│   └── doc1.md -``` - -Based on this scenario, here are a few permalink options. - -**Permalink configuration 1**: [Nothing configured]
-**Output**: - -``` -├── apidocs -│   └── mydocs -│   └── doc1.html -``` - -**Permalink configuration 2**: `/:collection/:path/:title:output_ext`
-**Output**: - -``` -├── apidocs -│   └── mydocs -│   └── doc1.html -``` - -**Permalink configuration 3**: No collection permalinks configured, but `pretty` configured for pages/posts.
-**Output**: - -``` -├── apidocs -│   └── mydocs -│   └── doc1 -│   └── index.html -``` - -**Permalink configuration 4**: `/awesome/:path/:title.html`
-**Output**: - -``` -├── awesome -│   └── mydocs -│   └── doc1.html -``` - -**Permalink configuration 5**: `/awesome/:path/:title/`
-**Output**: - -``` -├── awesome -│   └── mydocs -│   └── doc1 -│   └── index.html -``` - -**Permalink configuration 6**: `/awesome/:title.html`
-**Output**: - -``` -├── awesome -│   └── doc1.html -``` - -**Permalink configuration 7**: `:title.html` -**Output**: - -``` -├── doc1.html -``` - ## Liquid Attributes ### Collections