From 845580a2588e7e4d57f55c3a74fef653b131ba3c Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 23:15:22 -0800 Subject: [PATCH 01/11] Documentation on how to build navigation I added a documentation page on how to build navigation for your site. This topic is primarily intended for users who have a lot of pages on their site (such as for documentation websites), and want to build a more robust sidebar navigation. Jekyll combines Liquid with YAML in interesting ways that aren't really documented clearly in the existing docs, except for a brief reference [here](http://jekyllrb.com/docs/datafiles/#the-data-folder). You can read about Liquid on Shopify and YAML in YAML's docs, but exactly how you store YAML files in a Jekyll project and iterate through them using Liquid loops and filters to generate lists of pages is something that isn't clear to a lot of people. (You can see origins of these questions in [previous help issues](https://github.com/jekyll/jekyll-help/issues/266).) The documentation on navigation would fit well into the Jekyll docs. --- docs/_docs/navigation.md | 570 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 570 insertions(+) create mode 100644 docs/_docs/navigation.md diff --git a/docs/_docs/navigation.md b/docs/_docs/navigation.md new file mode 100644 index 00000000..1dc79dfa --- /dev/null +++ b/docs/_docs/navigation.md @@ -0,0 +1,570 @@ +--- +layout: docs +title: Navigation +permalink: /docs/navigation +--- + + + +If your Jekyll site has a lot of pages, you might want to create navigation for the pages. Instead of hard-coding navigation links, you can programmatically retrieve a list of pages to build the navigation for your site. + +There are two primary ways of retrieving pages on a Jekyll site: + +* **Retrieve pages listed in a YAML data source**. Store the page data in a YAML (or JSON or CSV) file in the `_data` folder, loop through the YAML properties, and insert the values into your theme. +* **Retrieve pages by looping through the page front matter**. Look through the front matter of your pages to identify certain properties, return those pages, and insert the pages' front matter values into your theme. + +The examples that follow start with a basic navigation scenario and add more sophisticated elements to demonstrate different ways of returning the pages. In almost every scenario, you'll see 3 elements: + +* YAML +* Liquid +* Result + +The YAML file in the `_data` directory is called `samplelist.yml`. + +The scenarios are as follows: + +* TOC +{:toc} + +## Scenario 1: Basic List + +You want to return a basic list of pages. + +**YAML** + +```yaml +docs_list_title: Docs +docs: + +- title: Introduction + url: introduction.html + +- title: Configuration + url: configuration.html + +- title: Deployment + url: deployment.html +``` + +**Liquid** + +```liquid +{% raw %}

{{ site.data.samplelist.docs_list_title }}

+{% endraw %} +``` + +**Result** +
+

ACME Documentation

+ +
+ +When you use a `for` loop, you choose how you want to refer to the items you're looping through. The variable you choose (in this case, `item`) becomes how you access the properties of each item in the list. Dot notation is used to get a property of the item (for example, `item.url`). + +The YAML content has two main types of formats that are relevant here: + +* mapping +* list + +`docs_list_title: ACME Documentation` is a mapping. You access the value with `site.data.samplelist.docs_list_title`. + +`docs:` is a list. The list begins each item with a hyphen. Unlike with mappings, you usually don't access list properties directly as you do with mappings. If you want to access a specific item in the list, you must identify the position in the list you want, following typical array notation. For example, `site.data.samplelist.docs[0]` would access the first item in the list. However, this is rarely done. + +With lists, you usually use `for` loops to cycle through the list of items and do something with each item. With navigation menus, you usually insert each list item into `li` tags based on the navigation structure you're using in your HTML theme. + +Each hyphen (`-`) indicates another item in the list. This example just has two properties with each list item: `title` and `url`. You can include as many properties as you want for each item. The order of properties at each position in the list doesn't matter. + +## Scenario 2: Sorted list + +Suppose you wanted to sort the list by the `title`. To do this, convert the reference to the `docs` collection to a variable, and then apply Liquid's `sort` filter to the variable: + +**Liquid** + +```liquid +{% raw %}{% assign doclist = site.data.samplelist.docs | sort: 'title' %} +{% for item in doclist %} +
  • {{ item.title }}
    • +{% endfor %}{% endraw %} +``` + +**Result** + +
    +
  • Configuration
    • +
  • Deployment
    • +
  • Introduction
    • +
    + +The items now appear in alphabetical order. The `sort` property in the Liquid filter applies to the `title`, which is an actual property in the list. If `title` weren't a property, we would need to sort by another property. + +See the [Liquid array filter](https://help.shopify.com/themes/liquid/filters/array-filters) for more filter options. Note that you can't simply use this syntax: + +```liquid +{% raw %}{% for item in site.data.samplelist.docs | sort: "title" %}{% endfor %}{% endraw %} +``` + +You have to convert `site.data.samplelist.docs` to a variable first using either `assign` or `capture` tags. + +## Scenario 3: Two-level navigation list + +Suppose you want a more robust list that incorporates multiple sections of heading titles and subitems. To do this, add an additional level to each list item to store this information: + +**YAML** + +```yaml +toc: + - title: Group 1 + subfolderitems: + - page: Thing 1 + url: /thing1.html + - page: Thing 2 + url: /thing2.html + - page: Thing 3 + url: /thing3.html + - title: Group 2 + subfolderitems: + - page: Piece 1 + url: /piece1.html + - page: Piece 2 + url: /piece2.html + - page: Piece 3 + url: /piece3.html + - title: Group 3 + subfolderitems: + - page: Widget 1 + url: /widget1.html + - page: Widget 2 + url: /widget2.html + - page: Widget 3 + url: /widget3.html +``` + +**Liquid** + +```liquid +{% raw %}{% for item in site.data.samplelist.toc %} +

    {{ item.title }}

    + + {% endfor %}{% endraw %} +``` + +**Result** +
    +

    Group 1

    + + +

    Group 2

    + + +

    Group 3

    + +
    + +In this example, `Group 1` is the first list item. Within that list item, its subpages are included as a property that itself contains a list (`subfolderitems`). + +The Liquid code looks through the first level with `for item in site.data.samplelist.toc`, and then looks through the second-level property with `for entry in item.subfolderitems`. Just as `item` is an arbitrary name for the items we're looping through, so is `entry`. + +## Scenario 4: Three-level navigation list + +Building on the previous section, let's add one more level of depth (`subsubfolderitems`) to the list. The formatting will get more complex here, but the principles are the same. + +**YAML** + +```yaml +toc2: + - title: Group 1 + subfolderitems: + - page: Thing 1 + url: /thing1.html + - page: Thing 2 + url: /thing2.html + subsubfolderitems: + - page: Subthing 1 + url: /subthing1.html + - page: Subthing 2 + url: /subthing2.html + - page: Thing 3 + url: /thing3.html + - title: Group 2 + subfolderitems: + - page: Piece 1 + url: /piece1.html + - page: Piece 2 + url: /piece2.html + - page: Piece 3 + url: /piece3.html + subsubfolderitems: + - page: Subpiece 1 + url: /subpiece1.html + - page: Subpiece2 + url: /subpiece2.html + - title: Group 3 + subfolderitems: + - page: Widget 1 + url: /widget1.html + subsubfolderitems: + - page: Subwidget 1 + url: /subwidget1.html + - page: Subwidget 2 + url: /subwidget2.html + - page: Widget 2 + url: /widget2.html + - page: Widget 3 + url: /widget3.html +``` + +**Liquid** + +```liquid +{% raw %}
    +{% if site.data.samplelist.toc2[0] %} + {% for item in site.data.samplelist.toc2 %} +

    {{ item.title }}

    + {% if item.subfolderitems[0] %} + + {% endif %} + {% endfor %} +{% endif %} +
    {% endraw %} +``` + +**Result** + +
    +
    +

    Group 1

    + +

    Group 2

    + +

    Group 3

    + +
    +
    + + In this example, `if site.data.samplelist.toc2[0]` is used to ensure that the YAML level actually contains items. If there isn't anything at the `[0]` position, we can skip looking in this level. + +
    +
    ProTip: Line up for loops and if statements
    +

    To keep the code clear, line up the beginning and ending Liquid tags, such as the for loops and if statements. This way you know when the open tags have been closed. If the code will appear in a Markdown page, keep the opening and closing HTML tags flush against the left edge so that the Markdown filter won't treat the content as a code sample. If necessary, you can wrap the entire code sample in a div tag to ensure the code has HTML tags that bookend the code.

    +
    + +## Scenario 5: Using a page variable to select the YAML list + +Suppose your sidebar will differ based on various documentation sets. You might have 3 different products on your site, and so you want 3 different sidebars — each unique for that product. + +You can store the name of the sidebar list in your page front matter and then pass that value into the list dynamically. + +**Page front matter** + +```yaml +--- +title: My page +sidebar: toc +--- +``` + +**Liquid** + +```liquid +{% raw %}{% endraw %} +``` +**Result** + +
    + +
    + +In this scenario, we want to pass values from the page's front matter into a `for` loop that contains a variable. When the assigned variable isn't a string but rather a data reference, you must use brackets (instead of curly braces) to refer to the front matter's value. + +For more information, see [Expressions and Variables](https://github.com/Shopify/liquid/wiki/Liquid-for-Designers#expressions-and-variables) in Liquid's documentation. Brackets are used in places where dot notation can't be used. You can also read more details in this [Stack Overflow answer](http://stackoverflow.com/questions/4968406/javascript-property-access-dot-notation-vs-brackets/4968448#4968448). + +## Scenario 6: Applying the active class for the current page + +In addition to inserting items from the YAML data file into your list, you also usually want to highlight the current link if the user is viewing that page. You do this by inserting an `active` class for items that match the current page URL. + +**CSS** +```css +.result li.active a { + color: lightgray; + cursor: default; + } +``` +**Liquid** + +```liquid +{% raw %}{% for item in site.data.samplelist.docs %} +
  • +{{ item.title }}
    • +{% endfor %}{% endraw %} +``` + +**Result** + + + +
    +
  • Introduction
    • +
  • Configuration
    • +
  • Deployment
    • +
    + +In this case, assume `Deployment` is the current page. + +To make sure the `item.url` (stored in the YAML file) matches the `page.url`, it can be helpful to print the `{% raw %}{{ page.url }}{% endraw %}` to the page. + +## Scenario 6: Including items conditionally + +You might want to include items conditionally in your list. For example, maybe you have multiple site outputs and only want to include the sidebar item for certain outputs. You can add properties in each list item and then use those properties to conditionally include the content. + +**YAML** +```yaml +docs2_list_title: ACME Documentation +docs2: + +- title: Introduction + url: introduction.html + version: 1 + +- title: Configuration + url: configuration.html + version: 1 + +- title: Deployment + url: deployment.html + version: 2 +``` + +**Liquid** + +```liquid +{% raw %}{% endraw %} +``` + +**Result** + +
    + +
    + +The `Deployment` page is excluded because its `version` is `2`. + +## Scenario 7: Retrieving items based on front matter properties + +If you don't want to store your navigation items in a YAML file in your `_data` folder, you can use `for` loops to look through the YAML front matter of each page or collection and get the content based on properties in the front matter. + +In this scenario, suppose we have a collection called `_docs`. Collections are often better than pages because they allow you to be more specific in what you're looping through. (Try to avoid scenarios where you loop through large numbers of items, since it will increase your build time. Collections help you narrow the scope. For more information about collections, see [Collections]({% link _docs/collections.md %}).) + +In our scenario, there are 6 docs in the `docs` collection: Sample 1, Sample 2, Topic 1, Topic 2, Widget 1, and Widget 2. + +Each doc in the collection contains at least 3 properties in the front matter: + +* `title` +* `category` +* `order` + +The front matter for each page is as follows (consolidated here for brevity): + +```yaml +--- +Title: Sample 1 +category: getting-started +order: 1 +--- + +--- +Title: Sample 2 +category: getting-started +order: 2 +--- + +--- +Title: Topic 1 +category: configuration +order: 1 +--- + +--- +Title: Topic 2 +category: configuration +order: 2 +--- + +--- +Title: Widget 1 +category: deployment +order: 1 +--- + +--- +Title: Widget 2 +category: deployment +order: 2 +--- +``` + +Note that even though `category` is used in the doc front matter, `category` is not a built-in variable like it is with posts. In other words, you cannot look directly inside `category` with `site.docs.category`. + +If you wanted to simply get all docs in the collection for a specific category, you could use a `for` loop with an `if` condition to check for a specific category: + +```liquid +{% raw %}

    Getting Started

    +{% endraw %} +``` + +The result would be as follows: + +
    +

    Getting Started

    + +
    + +This might be useful if you're setting up a knowledge base and have dozens of topics in each category, with each category displaying on its own page. + +But let's say you want to sort the items by category and group them under the category name, without hard-coding the category names. To achieve this, you could use two filters: + +* `group by` +* `sort` + +Here's the code for getting lists of pages grouped under their corresponding category headers: + +**Liquid** + +```liquid +{% raw %}{% assign mydocs = site.docs | group_by: 'category' %} +{% for cat in mydocs %} +

    {{ cat.name | capitalize }}

    + +{% endfor %}{% endraw %} +``` + +**Result** + +
    +

    Getting-started

    + + +

    Configuration

    + + +

    Deployment

    + +
    + +Let's walk through the code. First, we assign a variable (`mydocs`) to the collection content (`site.docs`). + +The `group_by` filter groups the collection content by `category`. More specifically, the `group_by` filter converts `mydocs` into an array with `name`, `items`, and `size` properties, somewhat like this: + +```yaml +[ + {"name": "getting-started", "items": [Sample 1, Sample 2],"size": 2}, + {"name": "configuration", "items": [Topic 1, Topic 2], "size": 2}, + {"name": "deployment", "items": [Widget 1, Widget 2, "size": 2} +] +``` + +Using `for cat in mydocs`, we look through each item in the `mydocs` array and print the category `name`. + +After getting the category name, we assign the variable `items` for the docs and use the `sort` filter to arrange the docs by their `order` property. The dot notation `cat.items` is used because we're accessing the content in the `items` array. The `sort` filter orders the items by their numbers in ascending order. + +The `for item in items` loop looks through each `item` and gets the `title` and `url` to form the list item link. + +For more details on the `group by` filter, see [group by in Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort in Liquid's documentation](https://help.shopify.com/themes/liquid/filters/array-filters#sort). + +Whether you use properties in your doc's front matter to retrieve your pages or a YAML data file, in both cases you can programmatically build a more robust navigation for your site. From 972dc8c2dd62aa989817702f07d6c16ba9e94b5c Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 23:21:14 -0800 Subject: [PATCH 02/11] Include navigation page in doc list Include the navigation page in the sidebar doc list. --- docs/_data/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_data/docs.yml b/docs/_data/docs.yml index 4ff28ba2..071cddb6 100644 --- a/docs/_data/docs.yml +++ b/docs/_data/docs.yml @@ -25,6 +25,7 @@ - templates - permalinks - pagination + - navigation - plugins - themes - extras From 75c40edff8fc2d2c1bb1bfeb6c45e75a654f6faa Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 26 Dec 2016 23:20:13 -0800 Subject: [PATCH 03/11] Added link to new navigation page This just links to the new page I added about navigation. --- docs/_docs/datafiles.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_docs/datafiles.md b/docs/_docs/datafiles.md index 21799169..40723d2f 100644 --- a/docs/_docs/datafiles.md +++ b/docs/_docs/datafiles.md @@ -150,3 +150,5 @@ author: dave {% endraw %} ``` + +For information on how to build robust navigation for your site (especially if you have a documentation website or another type of Jekyll site with a lot of pages to organize), see [Navigation](../navigation). From 5166ead2e03b42ae80589e56a25b379d53fea709 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Wed, 4 Jan 2017 10:14:41 -0800 Subject: [PATCH 04/11] Made updates with indentation --- docs/_docs/navigation.md | 190 ++++++++++++++++++++------------------- docs/_sass/_style.scss | 8 ++ 2 files changed, 104 insertions(+), 94 deletions(-) diff --git a/docs/_docs/navigation.md b/docs/_docs/navigation.md index 1dc79dfa..bbb009c7 100644 --- a/docs/_docs/navigation.md +++ b/docs/_docs/navigation.md @@ -1,19 +1,8 @@ --- layout: docs -title: Navigation permalink: /docs/navigation --- - - If your Jekyll site has a lot of pages, you might want to create navigation for the pages. Instead of hard-coding navigation links, you can programmatically retrieve a list of pages to build the navigation for your site. There are two primary ways of retrieving pages on a Jekyll site: @@ -67,12 +56,12 @@ docs: **Result**
    -

    ACME Documentation

    - +

    ACME Documentation

    +
    When you use a `for` loop, you choose how you want to refer to the items you're looping through. The variable you choose (in this case, `item`) becomes how you access the properties of each item in the list. Dot notation is used to get a property of the item (for example, `item.url`). @@ -99,16 +88,16 @@ Suppose you wanted to sort the list by the `title`. To do this, convert the refe ```liquid {% raw %}{% assign doclist = site.data.samplelist.docs | sort: 'title' %} {% for item in doclist %} -
  • {{ item.title }}
    • +
  • {{ item.title }}
    • {% endfor %}{% endraw %} ``` **Result**
    -
  • Configuration
    • -
  • Deployment
    • -
  • Introduction
    • +
  • Configuration
    • +
  • Deployment
    • +
  • Introduction
    • The items now appear in alphabetical order. The `sort` property in the Liquid filter applies to the `title`, which is an actual property in the list. If `title` weren't a property, we would need to sort by another property. @@ -274,24 +263,39 @@ toc2: **Result**
    - -
    +
    +

    Group 1

    + +

    Group 2

    + +

    Group 3

    + +
    + In this example, `if site.data.samplelist.toc2[0]` is used to ensure that the YAML level actually contains items. If there isn't anything at the `[0]` position, we can skip looking in this level. @@ -319,19 +323,19 @@ sidebar: toc ```liquid {% raw %}
      -{% for item in site.data.samplelist[page.sidebar] %} -
    • {{ item.title }}
      • -{% endfor %} + {% for item in site.data.samplelist[page.sidebar] %} +
    • {{ item.title }}
      • + {% endfor %}
    {% endraw %} ``` **Result**
    - +
    In this scenario, we want to pass values from the page's front matter into a `for` loop that contains a variable. When the assigned variable isn't a string but rather a data reference, you must use brackets (instead of curly braces) to refer to the front matter's value. @@ -353,8 +357,8 @@ In addition to inserting items from the YAML data file into your list, you also ```liquid {% raw %}{% for item in site.data.samplelist.docs %} -
  • -{{ item.title }}
    • +
  • + {{ item.title }}
    • {% endfor %}{% endraw %} ``` @@ -368,9 +372,9 @@ In addition to inserting items from the YAML data file into your list, you also
    -
  • Introduction
    • -
  • Configuration
    • -
  • Deployment
    • +
  • Introduction
    • +
  • Configuration
    • +
  • Deployment
    • In this case, assume `Deployment` is the current page. @@ -403,21 +407,21 @@ docs2: ```liquid {% raw %}
      -{% for item in site.data.samplelist.docs2 %} -{% if item.version == 1 %} -
    • {{ item.title }}
      • -{% endif %} -{% endfor %} + {% for item in site.data.samplelist.docs2 %} + {% if item.version == 1 %} +
    • {{ item.title }}
      • + {% endif %} + {% endfor %}
    {% endraw %} ``` **Result**
    - +
    The `Deployment` page is excluded because its `version` is `2`. @@ -483,22 +487,22 @@ If you wanted to simply get all docs in the collection for a specific category, ```liquid {% raw %}

    Getting Started

      -{% for doc in site.docs %} -{% if doc.category == "getting-started" %} -
    • {{ doc.title }}
      • -{% endif %} -{% endfor %} + {% for doc in site.docs %} + {% if doc.category == "getting-started" %} +
    • {{ doc.title }}
      • + {% endif %} + {% endfor %}
    {% endraw %} ``` The result would be as follows:
    -

    Getting Started

    - +

    Getting Started

    +
    This might be useful if you're setting up a knowledge base and have dozens of topics in each category, with each category displaying on its own page. @@ -516,35 +520,33 @@ Here's the code for getting lists of pages grouped under their corresponding cat {% raw %}{% assign mydocs = site.docs | group_by: 'category' %} {% for cat in mydocs %}

    {{ cat.name | capitalize }}

    -
      -{% assign items = cat.items | sort: 'weight' %} -{% for item in items %} -
    • {{ item.title }}
      • -{% endfor %} -
    +
      + {% assign items = cat.items | sort: 'weight' %} + {% for item in items %} +
    • {{ item.title }}
      • + {% endfor %} +
    {% endfor %}{% endraw %} ``` **Result**
    -

    Getting-started

    - - -

    Configuration

    - - -

    Deployment

    - +

    Getting-started

    + +

    Configuration

    + +

    Deployment

    +
    Let's walk through the code. First, we assign a variable (`mydocs`) to the collection content (`site.docs`). diff --git a/docs/_sass/_style.scss b/docs/_sass/_style.scss index f1e3de5f..20264408 100644 --- a/docs/_sass/_style.scss +++ b/docs/_sass/_style.scss @@ -1031,3 +1031,11 @@ code.output { clip: rect(0, 0, 0, 0); border: 0; } + +.result { + border: 1px solid yellow; + padding: 10px; + margin-top: 10px; + margin-bottom: 10px; + font-size:14px; +} From 7efeb3d4af68543a9fc88fbdadfff2354c173419 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Thu, 12 Jan 2017 23:03:56 -0800 Subject: [PATCH 05/11] made updates as requested from latest review --- docs/_docs/datafiles.md | 2 + docs/_docs/navigation.md | 174 ++++++++++++++++++++------------------- docs/_sass/_style.scss | 3 - 3 files changed, 91 insertions(+), 88 deletions(-) diff --git a/docs/_docs/datafiles.md b/docs/_docs/datafiles.md index 40723d2f..59a3ef3e 100644 --- a/docs/_docs/datafiles.md +++ b/docs/_docs/datafiles.md @@ -70,6 +70,8 @@ You can now render the list of members in a template: {% endraw %} ``` +{: .note .info } +If your Jekyll site has a lot of pages, such as with documentation websites, we've got you covered with some detailed examples on [how to build robust navigation for your site](..navigation). ## Example: Organizations diff --git a/docs/_docs/navigation.md b/docs/_docs/navigation.md index bbb009c7..548013a2 100644 --- a/docs/_docs/navigation.md +++ b/docs/_docs/navigation.md @@ -49,21 +49,24 @@ docs: {% raw %}

    {{ site.data.samplelist.docs_list_title }}

    {% endraw %} ``` **Result** -
    +

    ACME Documentation

    +{: .note .info } +For the results in these samples with fictitious page references, `#` is manually substituted for the actual link value to avoid 404 errors.) + When you use a `for` loop, you choose how you want to refer to the items you're looping through. The variable you choose (in this case, `item`) becomes how you access the properties of each item in the list. Dot notation is used to get a property of the item (for example, `item.url`). The YAML content has two main types of formats that are relevant here: @@ -94,10 +97,10 @@ Suppose you wanted to sort the list by the `title`. To do this, convert the refe **Result** -
    -
  • Configuration
    • -
  • Deployment
    • -
  • Introduction
    • +
    +
  • Configuration
    • +
  • Deployment
    • +
  • Introduction
    • The items now appear in alphabetical order. The `sort` property in the Liquid filter applies to the `title`, which is an actual property in the list. If `title` weren't a property, we would need to sort by another property. @@ -158,26 +161,26 @@ toc: ``` **Result** -
    +

    Group 1

    Group 2

    Group 3

    @@ -240,64 +243,64 @@ toc2: {% raw %}
    {% if site.data.samplelist.toc2[0] %} {% for item in site.data.samplelist.toc2 %} -

    {{ item.title }}

    - {% if item.subfolderitems[0] %} -
      - {% for entry in item.subfolderitems %} -
    • {{ entry.page }}
      • - {% if entry.subsubfolderitems[0] %} - - {% endif %} - {% endfor %} -
    - {% endif %} - {% endfor %} +

    {{ item.title }}

    + {% if item.subfolderitems[0] %} +
      + {% for entry in item.subfolderitems %} +
    • {{ entry.page }}
      • + {% if entry.subsubfolderitems[0] %} + + {% endif %} + {% endfor %} +
    + {% endif %} + {% endfor %} {% endif %}
    {% endraw %} ``` **Result** -
    +
    - In this example, `if site.data.samplelist.toc2[0]` is used to ensure that the YAML level actually contains items. If there isn't anything at the `[0]` position, we can skip looking in this level. +In this example, `if site.data.samplelist.toc2[0]` is used to ensure that the YAML level actually contains items. If there isn't anything at the `[0]` position, we can skip looking in this level.
    ProTip: Line up for loops and if statements
    @@ -324,17 +327,17 @@ sidebar: toc ```liquid {% raw %}{% endraw %} ``` **Result** -
    +
    @@ -358,7 +361,8 @@ In addition to inserting items from the YAML data file into your list, you also ```liquid {% raw %}{% for item in site.data.samplelist.docs %}
  • - {{ item.title }}
    • + {{ item.title }} + {% endfor %}{% endraw %} ``` @@ -371,10 +375,10 @@ In addition to inserting items from the YAML data file into your list, you also } -
    -
  • Introduction
    • -
  • Configuration
    • -
  • Deployment
    • +
    +
  • Introduction
    • +
  • Configuration
    • +
  • Deployment
    • In this case, assume `Deployment` is the current page. @@ -408,19 +412,19 @@ docs2: ```liquid {% raw %}
      {% for item in site.data.samplelist.docs2 %} - {% if item.version == 1 %} -
    • {{ item.title }}
      • - {% endif %} + {% if item.version == 1 %} +
    • {{ item.title }}
      • + {% endif %} {% endfor %}
    {% endraw %} ``` **Result** -
    +
    @@ -488,20 +492,20 @@ If you wanted to simply get all docs in the collection for a specific category, {% raw %}

    Getting Started

      {% for doc in site.docs %} - {% if doc.category == "getting-started" %} -
    • {{ doc.title }}
      • - {% endif %} + {% if doc.category == "getting-started" %} +
    • {{ doc.title }}
      • + {% endif %} {% endfor %}
    {% endraw %} ``` The result would be as follows: -
    +

    Getting Started

    @@ -521,31 +525,31 @@ Here's the code for getting lists of pages grouped under their corresponding cat {% for cat in mydocs %}

    {{ cat.name | capitalize }}

      - {% assign items = cat.items | sort: 'weight' %} - {% for item in items %} -
    • {{ item.title }}
      • - {% endfor %} + {% assign items = cat.items | sort: 'order' %} + {% for item in items %} +
    • {{ item.title }}
      • + {% endfor %}
    {% endfor %}{% endraw %} ``` **Result** -
    +

    Getting-started

    Configuration

    Deployment

    diff --git a/docs/_sass/_style.scss b/docs/_sass/_style.scss index 20264408..3a038966 100644 --- a/docs/_sass/_style.scss +++ b/docs/_sass/_style.scss @@ -1035,7 +1035,4 @@ code.output { .result { border: 1px solid yellow; padding: 10px; - margin-top: 10px; - margin-bottom: 10px; - font-size:14px; } From 6d9633e36460d6292414eb8f8173b570ac711f38 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Thu, 12 Jan 2017 23:28:56 -0800 Subject: [PATCH 06/11] making edits from reviews --- docs/_docs/datafiles.md | 3 ++- docs/_docs/navigation.md | 10 +++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/_docs/datafiles.md b/docs/_docs/datafiles.md index 59a3ef3e..3f464476 100644 --- a/docs/_docs/datafiles.md +++ b/docs/_docs/datafiles.md @@ -70,8 +70,9 @@ You can now render the list of members in a template: {% endraw %} ``` + {: .note .info } -If your Jekyll site has a lot of pages, such as with documentation websites, we've got you covered with some detailed examples on [how to build robust navigation for your site](..navigation). +If your Jekyll site has a lot of pages, such as with documentation websites, see the detailed examples in [how to build robust navigation for your site](../navigation). ## Example: Organizations diff --git a/docs/_docs/navigation.md b/docs/_docs/navigation.md index 548013a2..bd4228e3 100644 --- a/docs/_docs/navigation.md +++ b/docs/_docs/navigation.md @@ -10,7 +10,7 @@ There are two primary ways of retrieving pages on a Jekyll site: * **Retrieve pages listed in a YAML data source**. Store the page data in a YAML (or JSON or CSV) file in the `_data` folder, loop through the YAML properties, and insert the values into your theme. * **Retrieve pages by looping through the page front matter**. Look through the front matter of your pages to identify certain properties, return those pages, and insert the pages' front matter values into your theme. -The examples that follow start with a basic navigation scenario and add more sophisticated elements to demonstrate different ways of returning the pages. In almost every scenario, you'll see 3 elements: +The examples that follow start with a basic navigation scenario and add more sophisticated elements to demonstrate different ways of returning the pages. In every scenario, you'll see 3 elements: * YAML * Liquid @@ -65,7 +65,7 @@ docs:
    {: .note .info } -For the results in these samples with fictitious page references, `#` is manually substituted for the actual link value to avoid 404 errors.) +For the results in these fictitious samples, `#` is manually substituted for the actual link value to avoid 404 errors.) When you use a `for` loop, you choose how you want to refer to the items you're looping through. The variable you choose (in this case, `item`) becomes how you access the properties of each item in the list. Dot notation is used to get a property of the item (for example, `item.url`). @@ -434,7 +434,7 @@ The `Deployment` page is excluded because its `version` is `2`. If you don't want to store your navigation items in a YAML file in your `_data` folder, you can use `for` loops to look through the YAML front matter of each page or collection and get the content based on properties in the front matter. -In this scenario, suppose we have a collection called `_docs`. Collections are often better than pages because they allow you to be more specific in what you're looping through. (Try to avoid scenarios where you loop through large numbers of items, since it will increase your build time. Collections help you narrow the scope. For more information about collections, see [Collections]({% link _docs/collections.md %}).) +In this scenario, suppose we have a collection called `_docs`. Collections are often better than pages because they allow you to narrow the list of what you're looping through. (Try to avoid scenarios where you loop through large numbers of items, since it will increase your build time. [Collections]({% link _docs/collections.md %}) help you narrow the scope.) In our scenario, there are 6 docs in the `docs` collection: Sample 1, Sample 2, Topic 1, Topic 2, Widget 1, and Widget 2. @@ -513,7 +513,7 @@ This might be useful if you're setting up a knowledge base and have dozens of to But let's say you want to sort the items by category and group them under the category name, without hard-coding the category names. To achieve this, you could use two filters: -* `group by` +* `group_by` * `sort` Here's the code for getting lists of pages grouped under their corresponding category headers: @@ -571,6 +571,6 @@ After getting the category name, we assign the variable `items` for the docs and The `for item in items` loop looks through each `item` and gets the `title` and `url` to form the list item link. -For more details on the `group by` filter, see [group by in Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort in Liquid's documentation](https://help.shopify.com/themes/liquid/filters/array-filters#sort). +For more details on the `group_by` filter, see [Jekyll's Templates documentation](https://jekyllrb.com/docs/templates/) as well as [this Siteleaf tutorial](https://www.siteleaf.com/blog/advanced-liquid-group-by/). For more details on the `sort` filter, see [sort](https://help.shopify.com/themes/liquid/filters/array-filters#sort) in Liquid's documentation. Whether you use properties in your doc's front matter to retrieve your pages or a YAML data file, in both cases you can programmatically build a more robust navigation for your site. From a05e64c9d360e8357dc9c23a76656d231f0665dd Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 24 Jan 2017 15:38:17 -0800 Subject: [PATCH 07/11] moved navigation under new collection called tutorial --- docs/{_docs => _tutorials}/navigation.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{_docs => _tutorials}/navigation.md (100%) diff --git a/docs/_docs/navigation.md b/docs/_tutorials/navigation.md similarity index 100% rename from docs/_docs/navigation.md rename to docs/_tutorials/navigation.md From 2e9a32edd2ced3626cb38fcf0ec998549e56b411 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 24 Jan 2017 22:58:04 -0800 Subject: [PATCH 08/11] Added tutorials as a new collection, similar to Docs. Also added tutorial sidebar, tutorial link in primary nav, and tutorial overview page. --- docs/.gitignore | 1 + docs/_config.yml | 2 + docs/_data/tutorials.yml | 8 ++++ docs/_includes/primary-nav-items.html | 5 ++- docs/_includes/section_nav_tutorials.html | 39 +++++++++++++++++++ docs/_includes/tutorials_contents.html | 10 +++++ docs/_includes/tutorials_contents_mobile.html | 10 +++++ docs/_includes/tutorials_option.html | 5 +++ docs/_includes/tutorials_ul.html | 7 ++++ docs/_layouts/tutorials.html | 27 +++++++++++++ docs/_tutorials/index.md | 35 +++++++++++++++++ docs/_tutorials/navigation.md | 5 ++- 12 files changed, 151 insertions(+), 3 deletions(-) create mode 100644 docs/_data/tutorials.yml create mode 100644 docs/_includes/section_nav_tutorials.html create mode 100644 docs/_includes/tutorials_contents.html create mode 100644 docs/_includes/tutorials_contents_mobile.html create mode 100644 docs/_includes/tutorials_option.html create mode 100644 docs/_includes/tutorials_ul.html create mode 100644 docs/_layouts/tutorials.html create mode 100644 docs/_tutorials/index.md diff --git a/docs/.gitignore b/docs/.gitignore index 79bd74f7..527980f3 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,3 +2,4 @@ _site/ *.swp pkg/ test/ +.idea/ \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index 6f57710a..589b042e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -16,6 +16,8 @@ collections: posts: permalink: /news/:year/:month/:day/:title/ output: true + tutorials: + output: true name: Jekyll • Simple, blog-aware, static sites description: Transform your plain text into static websites and blogs diff --git a/docs/_data/tutorials.yml b/docs/_data/tutorials.yml new file mode 100644 index 00000000..73a0184a --- /dev/null +++ b/docs/_data/tutorials.yml @@ -0,0 +1,8 @@ +- title: Tutorials + tutorials: + - home + - navigation + +#- title: Another section +# tutorials: +# - sample \ No newline at end of file diff --git a/docs/_includes/primary-nav-items.html b/docs/_includes/primary-nav-items.html index f3778a84..a431d846 100644 --- a/docs/_includes/primary-nav-items.html +++ b/docs/_includes/primary-nav-items.html @@ -5,6 +5,9 @@
  • Docs
    • +
  • + Tutorials +
  • News
    • @@ -15,6 +18,6 @@ Help
  • - View on GitHub + GitHub
    • diff --git a/docs/_includes/section_nav_tutorials.html b/docs/_includes/section_nav_tutorials.html new file mode 100644 index 00000000..30812bba --- /dev/null +++ b/docs/_includes/section_nav_tutorials.html @@ -0,0 +1,39 @@ +{% comment %} +Map grabs the tutorials sections, giving us an array of arrays. Join, flattens all +the items to a comma delimited string. Split turns it into an array again. +{% endcomment %} +{% assign tutorials = site.data.tutorials | map: 'tutorials' | join: ',' | split: ',' %} + +{% comment %} +Because this is built for every page, lets find where we are in the ordered +document list by comparing url strings. Then if there's something previous or +next, lets build a link to it. +{% endcomment %} + +{% for tutorial in tutorials %} + {% assign tutorial_url = tutorial | prepend:"/tutorials/" | append:"/" %} + {% if tutorial_url == page.url %} +
    +
    + {% if forloop.first %} + Back + {% else %} + {% assign previous = forloop.index0 | minus: 1 %} + {% assign previous_page = tutorials[previous] | prepend:"/tutorials/" | append:"/" %} + + {% endif %} +
    +
    + {% if forloop.last %} + Next + {% else %} + {% assign next = forloop.index0 | plus: 1 %} + {% assign next_page = tutorials[next] | prepend:"/tutorials/" | append:"/" %} + + {% endif %} +
    +
    +
    + {% break %} + {% endif %} +{% endfor %} \ No newline at end of file diff --git a/docs/_includes/tutorials_contents.html b/docs/_includes/tutorials_contents.html new file mode 100644 index 00000000..5c9cdc8e --- /dev/null +++ b/docs/_includes/tutorials_contents.html @@ -0,0 +1,10 @@ +
    + +
    diff --git a/docs/_includes/tutorials_contents_mobile.html b/docs/_includes/tutorials_contents_mobile.html new file mode 100644 index 00000000..901fdf5c --- /dev/null +++ b/docs/_includes/tutorials_contents_mobile.html @@ -0,0 +1,10 @@ +
    + +
    diff --git a/docs/_includes/tutorials_option.html b/docs/_includes/tutorials_option.html new file mode 100644 index 00000000..482c2143 --- /dev/null +++ b/docs/_includes/tutorials_option.html @@ -0,0 +1,5 @@ +{% for item in include.items %} + {% assign item_url = item | prepend:"/tutorials/" | append:"/" %} + {% assign tutorial = site.tutorials | where: "url", item_url | first %} + +{% endfor %} diff --git a/docs/_includes/tutorials_ul.html b/docs/_includes/tutorials_ul.html new file mode 100644 index 00000000..6604915c --- /dev/null +++ b/docs/_includes/tutorials_ul.html @@ -0,0 +1,7 @@ +
      +{% for item in include.items %} + {% assign item_url = item | prepend:"/tutorials/" | append:"/" %} + {% assign p = site.tutorials | where:"url", item_url | first %} +
    • {{ p.title }}
      • +{% endfor %} +
    diff --git a/docs/_layouts/tutorials.html b/docs/_layouts/tutorials.html new file mode 100644 index 00000000..e3f7794b --- /dev/null +++ b/docs/_layouts/tutorials.html @@ -0,0 +1,27 @@ +--- +layout: default +--- + +
    +
    + + {% include tutorials_contents_mobile.html %} + +
    +
    +
    +  Improve this page +
    +

    {{ page.title }}

    + {{ content }} + {% include section_nav_tutorials.html %} +
    +
    + + {% include tutorials_contents.html %} + +
    + +
    +
    diff --git a/docs/_tutorials/index.md b/docs/_tutorials/index.md new file mode 100644 index 00000000..b0988b09 --- /dev/null +++ b/docs/_tutorials/index.md @@ -0,0 +1,35 @@ +--- +layout: tutorials +title: Tutorials +permalink: /tutorials/home/ +redirect_from: /tutorials/index.html +--- + +In contrast to [Docs](../docs), Tutorials provide more detailed, narrative instruction that cover a variety of Jekyll topics and scenarios. Tutorials might contain the following: + +* Step-by-step processes through particular scenarios or challenges +* Full walk-throughs using sample data, showing inputs and results from the sample data +* Detailed explanation about the pros and cons for different Jekyll strategies +* End-to-end instruction in developing a complete feature on a Jekyll site +* Instruction that combines various techniques from across the docs + +In short, tutorials aren't the core reference information in docs. They walk users through processes from beginning to end. + +{: .info .note} +**Note:** The Tutorials section is new, so there aren't many tutorials yet. You can add a tutorial here to help popular this section. + +Some of these techniques might even guide you through a supporting tool, script, service, or other hack used with your Jekyll site. Feel free to include tutorials involving external services with Jekyll as well. However, note that Jekyll in no way endorses any third-party tools mentioned in tutorials. + +## How to contribute a tutorial + +We welcome your tutorial contributions. To add your tutorial: + +1. Fork the Jekyll project by clicking the **Fork** button in the upper-right corner of the [jekyll/jekyll project Github repo](https://github.com/jekyll/jekyll/). +2. Add your tutorial in the `_tutorials` collection. +3. Make sure your tutorial has the same front matter items as other tutorial items. +5. Add a reference to your tutorial filename in `_data/tutorials.yml`. This allows your tutorial to appear in the Tutorials sidebar. +6. Follow the regular git workflow to submit the pull request. + +When you submit your pull request, the Jekyll documentation team will review your contribution and either merge it or suggest edits. + + diff --git a/docs/_tutorials/navigation.md b/docs/_tutorials/navigation.md index bd4228e3..60e86369 100644 --- a/docs/_tutorials/navigation.md +++ b/docs/_tutorials/navigation.md @@ -1,6 +1,7 @@ --- -layout: docs -permalink: /docs/navigation +layout: tutorials +permalink: /tutorials/navigation/ +title: Navigation --- If your Jekyll site has a lot of pages, you might want to create navigation for the pages. Instead of hard-coding navigation links, you can programmatically retrieve a list of pages to build the navigation for your site. From c7db12bad8a8a02f206df908a9a72ce296b0bf2c Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Wed, 25 Jan 2017 06:50:23 -0800 Subject: [PATCH 09/11] fixed link in datafiles.md to point to navigation.md location in new tutorials collection --- docs/_docs/datafiles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_docs/datafiles.md b/docs/_docs/datafiles.md index 3f464476..fde34aa0 100644 --- a/docs/_docs/datafiles.md +++ b/docs/_docs/datafiles.md @@ -72,7 +72,7 @@ You can now render the list of members in a template: ``` {: .note .info } -If your Jekyll site has a lot of pages, such as with documentation websites, see the detailed examples in [how to build robust navigation for your site](../navigation). +If your Jekyll site has a lot of pages, such as with documentation websites, see the detailed examples in [how to build robust navigation for your site]({% link _tutorials/navigation.md %}). ## Example: Organizations From a6adfa835832dec060cc068740e36612e01d39d6 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Wed, 25 Jan 2017 09:49:36 -0800 Subject: [PATCH 10/11] added cross-reference to the data files topic within the navigation topic --- docs/_tutorials/navigation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/_tutorials/navigation.md b/docs/_tutorials/navigation.md index 60e86369..7d4bafa3 100644 --- a/docs/_tutorials/navigation.md +++ b/docs/_tutorials/navigation.md @@ -6,6 +6,8 @@ title: Navigation If your Jekyll site has a lot of pages, you might want to create navigation for the pages. Instead of hard-coding navigation links, you can programmatically retrieve a list of pages to build the navigation for your site. +Although there's already information about [interacting with data files]({% link _docs/datafiles.md %}) in other Jekyll docs, this tutorial dives into building more robust navigation for your site. + There are two primary ways of retrieving pages on a Jekyll site: * **Retrieve pages listed in a YAML data source**. Store the page data in a YAML (or JSON or CSV) file in the `_data` folder, loop through the YAML properties, and insert the values into your theme. From 0ecbf40d0e28a44c80db8ba2a5eaa0d8b5d0edd7 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 28 Feb 2017 10:15:20 -0800 Subject: [PATCH 11/11] fixes from parkr's review. removed yellow style line. moved tutorials link from primary nav to Help page. removed .giignore change. --- docs/_includes/primary-nav-items.html | 3 --- docs/_sass/_style.scss | 3 +-- docs/help/index.md | 4 ++++ 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_includes/primary-nav-items.html b/docs/_includes/primary-nav-items.html index a431d846..21200b3e 100644 --- a/docs/_includes/primary-nav-items.html +++ b/docs/_includes/primary-nav-items.html @@ -5,9 +5,6 @@
  • Docs
    • -
  • - Tutorials -
  • News
    • diff --git a/docs/_sass/_style.scss b/docs/_sass/_style.scss index 3a038966..d8b0bf38 100644 --- a/docs/_sass/_style.scss +++ b/docs/_sass/_style.scss @@ -1033,6 +1033,5 @@ code.output { } .result { - border: 1px solid yellow; - padding: 10px; + padding: 12px; } diff --git a/docs/help/index.md b/docs/help/index.md index 46ddcd4d..c4674a21 100644 --- a/docs/help/index.md +++ b/docs/help/index.md @@ -14,6 +14,10 @@ Known breaking changes are listed in the upgrading docs. Our guide to Jekyll covering installation, writing, customization, deployment, and more. +### [Tutorials](/tutorials/home) + +Similar to documentation, but more detailed scenario-based walk-throughs covering a variety of topics. + ### [View source](https://github.com/jekyll/jekyll/wiki/sites) Learn from the source of others' Jekyll-powered sites.