From f5eb869e58dba5e25fbcab52584a8f45b08b7b4d Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Sun, 25 Dec 2016 20:34:20 -0800 Subject: [PATCH 1/4] Improve collections docs See https://github.com/jekyll/jekyll/pull/5630 for more details on the update. @jekyll/documentation @DirtyF --- docs/_docs/collections.md | 128 +++++++++++++++++++++++++++++++------- 1 file changed, 106 insertions(+), 22 deletions(-) diff --git a/docs/_docs/collections.md b/docs/_docs/collections.md index 22a86e60..06f8fd75 100644 --- a/docs/_docs/collections.md +++ b/docs/_docs/collections.md @@ -7,12 +7,18 @@ permalink: /docs/collections/ Not everything is a post or a page. Maybe you want to document the various methods in your open source project, members of a team, or talks at a conference. Collections allow you to define a new type of document that behave -like Pages or Posts do normally, but also have their own unique properties and +like Pages or Posts do normally but which also have their own unique properties and namespace. ## Using Collections -### Step 1: Tell Jekyll to read in your collection +To start using collections, follow these 3 steps: + +* [Step 1: Tell Jekyll to read in your collection](#step1) +* [Step 2: Add your content](#step2) +* [Step 3: Optionally render your collection's documents into independent files](#step3) + +### Step 1: Tell Jekyll to read in your collection {#step1} Add the following to your site's `_config.yml` file, replacing `my_collection` with the name of your collection: @@ -41,11 +47,11 @@ defaults: layout: page ``` -### Step 2: Add your content +### Step 2: Add your content {#step2} -Create a corresponding folder (e.g. `/_my_collection`) and add +Create a corresponding folder (for example, `/_my_collection`) and add documents. YAML Front Matter is read in as data if it exists, and everything -after it is stuck in the Document's `content` attribute. If no YAML Front +after it is available in the document's `content` attribute. If no YAML Front Matter is provided, Jekyll will not generate the file in your collection.
@@ -56,7 +62,7 @@ your _config.yml file, with the addition of the preceding _
-### Step 3: Optionally render your collection's documents into independent files +### Step 3: Optionally render your collection's documents into independent files {#step3} If you'd like Jekyll to create a public-facing, rendered version of each document in your collection, set the `output` key to `true` in your collection @@ -73,19 +79,6 @@ For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be rendered using Liquid and the Markdown converter of your choice and written out to `/my_collection/some_subdir/some_doc.html`. -As for posts with [Permalinks](../permalinks/), the document -URL can be customized by setting `permalink` metadata for the collection: - -```yaml -collections: - my_collection: - output: true - permalink: /awesome/:path/ -``` - -For example, if you have `_my_collection/some_subdir/some_doc.md`, it will be -written out to `/awesome/some_subdir/some_doc/index.html`. -
Don't forget to add YAML for processing

@@ -95,6 +88,21 @@ written out to `/awesome/some_subdir/some_doc/index.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: + +```yaml +collections: + my_collection: + output: true + permalink: /awesome/:path/:title.output_ext +``` + +In this example, the collection documents will the have the URL of `awesome` followed by the path to the document and its file extension. + +Collections have the following template variables available for permalinks: +
@@ -149,14 +157,90 @@ written out to `/awesome/some_subdir/some_doc/index.html`.
+## 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 -Each collection is accessible via the `site` Liquid variable. For example, if +Each collection is accessible through the `site` variable. For example, if you want to access the `albums` collection found in `_albums`, you'd use `site.albums`. Each collection is itself an array of documents -(e.g. `site.albums` is an array of documents, much like `site.pages` and +(for example, `site.albums` is an array of documents, much like `site.pages` and `site.posts`). See below for how to access attributes of those documents. The collections are also available under `site.collections`, with the metadata @@ -335,7 +419,7 @@ file, each document has the following attributes: Attributes from the YAML front matter can be accessed as data anywhere in the site. Using the above example for configuring a collection as `site.albums`, -one might have front matter in an individual file structured as follows (which +you might have front matter in an individual file structured as follows (which must use a supported markup format, and cannot be saved with a `.yaml` extension): From 6c5f6ce164c7535aa23e4351c37f151119786283 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 19:48:38 -0800 Subject: [PATCH 2/4] Made requested updates on this topic Made minor grammar updates --- docs/_docs/collections.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_docs/collections.md b/docs/_docs/collections.md index 06f8fd75..ee0747be 100644 --- a/docs/_docs/collections.md +++ b/docs/_docs/collections.md @@ -7,7 +7,7 @@ permalink: /docs/collections/ Not everything is a post or a page. Maybe you want to document the various methods in your open source project, members of a team, or talks at a conference. Collections allow you to define a new type of document that behave -like Pages or Posts do normally but which also have their own unique properties and +like Pages or Posts do normally, but also have their own unique properties and namespace. ## Using Collections @@ -51,7 +51,7 @@ defaults: Create a corresponding folder (for example, `/_my_collection`) and add documents. YAML Front Matter is read in as data if it exists, and everything -after it is available in the document's `content` attribute. If no YAML Front +after it is accessible via the document's `content` attribute. If no YAML Front Matter is provided, Jekyll will not generate the file in your collection.
From caf5c00842f600f643d12394c8bb2aa3b53a15b2 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Thu, 29 Dec 2016 00:29:45 -0800 Subject: [PATCH 3/4] made requested updates --- docs/_docs/collections.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/_docs/collections.md b/docs/_docs/collections.md index ee0747be..7c606177 100644 --- a/docs/_docs/collections.md +++ b/docs/_docs/collections.md @@ -96,7 +96,7 @@ You can customize the [Permalinks](../permalinks/) for your collection's documen collections: my_collection: output: true - permalink: /awesome/:path/:title.output_ext + permalink: /awesome/:path/:title.:output_ext ``` In this example, the collection documents will the have the URL of `awesome` followed by the path to the document and its file extension. @@ -237,11 +237,12 @@ Based on this scenario, here are a few permalink options. ### Collections -Each collection is accessible through the `site` variable. For example, if +Each collection is accessible as a field on the `site` variable. For example, if you want to access the `albums` collection found in `_albums`, you'd use -`site.albums`. Each collection is itself an array of documents -(for example, `site.albums` is an array of documents, much like `site.pages` and -`site.posts`). See below for how to access attributes of those documents. +`site.albums`. + +Each collection is itself an array of documents (e.g., `site.albums` is an array of documents, much like `site.pages` and +`site.posts`). See the table below for how to access attributes of those documents. The collections are also available under `site.collections`, with the metadata you specified in your `_config.yml` (if present) and the following information: From c8ef313d036b8d1f1f5eb02c43dce030689e892e Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Thu, 29 Dec 2016 09:31:30 -0800 Subject: [PATCH 4/4] fixing sentence in dispute --- docs/_docs/collections.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/_docs/collections.md b/docs/_docs/collections.md index 7c606177..149fdea6 100644 --- a/docs/_docs/collections.md +++ b/docs/_docs/collections.md @@ -49,10 +49,10 @@ defaults: ### Step 2: Add your content {#step2} -Create a corresponding folder (for example, `/_my_collection`) and add -documents. YAML Front Matter is read in as data if it exists, and everything -after it is accessible via the document's `content` attribute. If no YAML Front -Matter is provided, Jekyll will not generate the file in your collection. +Create a corresponding folder (e.g. `/_my_collection`) and add +documents. YAML front matter is processed if the front matter exists, and everything +after the front matter is pushed into the document's `content` attribute. If no YAML front +matter is provided, Jekyll will not generate the file in your collection.
Be sure to name your directories correctly