From bea516b640ea42545c77e8093ec590b758ce5391 Mon Sep 17 00:00:00 2001 From: Michael Rose Date: Mon, 18 Apr 2016 16:26:33 -0400 Subject: [PATCH] Improve nav_list helper to be used with any type of navigation list defined in navigation.yml data file - Add documentation - Close #272 --- _data/navigation.yml | 61 ++++++++++++++++++++++------------ _docs/13-helpers.md | 74 +++++++++++++++++++++++++++++++++++++++++- _includes/nav_list | 35 ++++++++++++++++---- _includes/sidebar.html | 2 +- 4 files changed, 144 insertions(+), 28 deletions(-) diff --git a/_data/navigation.yml b/_data/navigation.yml index 2e82de13..cb72e521 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -1,3 +1,24 @@ +# example navigation +foo: + - title: "Parent Link 1" + url: /parent-1-page-url/ + children: + - title: "Child Link 1" + url: /child-1-page-url/ + - title: "Child Link 2" + url: /child-2-page-url/ + + - title: "Parent Link 2" + url: /parent-2-page-url/ + children: + - title: "Child Link 1" + url: /child-1-page-url/ + - title: "Child Link 2" + url: /child-2-page-url/ + - title: "Child Link 3" + url: /child-3-page-url/ + + # main links links main: - title: "Quick-Start Guide" @@ -18,54 +39,54 @@ docs: - title: Getting Started children: - title: "Quick-Start Guide" - path: quick-start-guide + url: /docs/quick-start-guide/ - title: "Structure" - path: structure + url: /docs/structure/ - title: "Installation" - path: installation + url: /docs/installation/ - title: "Upgrading" - path: upgrading + url: /docs/upgrading/ - title: Customization children: - title: "Configuration" - path: configuration + url: /docs/configuration/ - title: "Navigation" - path: navigation + url: /docs/navigation/ - title: "UI Text" - path: ui-text + url: /docs/ui-text/ - title: "Authors" - path: authors + url: /docs/authors/ - title: "Layouts" - path: layouts + url: /docs/layouts/ - title: Content children: - title: "Working with Posts" - path: posts + url: /docs/posts/ - title: "Working with Pages" - path: pages + url: /docs/pages/ - title: "Working with Collections" - path: collections + url: /docs/collections/ - title: "Helpers" - path: helpers + url: /docs/helpers/ - title: "Utility Classes" - path: utility-classes + url: /docs/utility-classes/ - title: Extras children: - title: "Stylesheets" - path: stylesheets + url: /docs/stylesheets/ - title: "JavaScript" - path: javascript + url: /docs/javascript/ - title: Meta children: - title: "History" - path: history + url: /docs/history/ - title: "Contributing" - path: contributing + url: /docs/contributing/ - title: "Old 2.2 Docs" - path: docs-2-2 + url: /docs/docs-2-2/ - title: "License" - path: license \ No newline at end of file + url: /docs/license/ \ No newline at end of file diff --git a/_docs/13-helpers.md b/_docs/13-helpers.md index 6a1a5b02..e837c617 100644 --- a/_docs/13-helpers.md +++ b/_docs/13-helpers.md @@ -173,4 +173,76 @@ To include an [auto-generated table of contents](http://kramdown.rubyforge.org/c ```liquid {% raw %}{% include toc icon="gears" title="My Table of Contents" %}{% endraw %} -``` \ No newline at end of file +``` + +## Navigation List + +Include an unordered list of links to be used as sidebar navigation with the `nav_list` helper. + +**1.** Start by adding a set of titles and URLs to `_data/navigation.yml` in the same way the [`main` navigation]({{ base_path }}/docs/navigation/) is built. + +`foo` navigation example: + +```yaml +# _data/navigation.yml +foo: + - title: "Link 1 Title" + url: /link-1-page-url/ + + - title: "Link 2 Title" + url: http://external-link.com + + - title: "Link 3 Title" + url: /link-3-page-url/ + + - title: "Link 4 Title" + url: /link-4-page-url/ +``` + +For a navigation list that has child pages you'd structure the YAML like this: + +```yaml +# _data/navigation.yml +foo: + - title: "Parent Link 1" + url: /parent-1-page-url/ + children: + - title: "Child Link 1" + url: /child-1-page-url/ + - title: "Child Link 2" + url: /child-2-page-url/ + + - title: "Parent Link 2" + url: /parent-2-page-url/ + children: + - title: "Child Link 1" + url: /child-1-page-url/ + - title: "Child Link 2" + url: /child-2-page-url/ + - title: "Child Link 3" + url: /child-3-page-url/ +``` + +**2:** On the page(s) you'd like the `foo` sidebar nav add the following YAML Front Matter, referencing the same key name. + +```yaml +sidebar: + nav: "foo" +``` + +**ProTip:** If you're applying the same navigation list to several pages setting it as a [Front Matter default](https://jekyllrb.com/docs/configuration/#front-matter-defaults) is the better option. +{: .notice--info} + +The theme's documentation is built with the `nav_list` helper so if you'd like an example to dissect take a look at `navigation.yml`, `_config.yml` and `_doc/` in the [`gh-pages` branch]({{ site.gh_repo }}/gh-pages/) of this repo. + +To add a navigation list to a post or page's main content instead of the sidebar use the include this way: + +```liquid +{% raw %}{% include nav_list nav="foo" %}{% endraw %} +``` + +{% include nav_list nav="foo" %} + +| Parameter | Required | Description | +| --------- | -------- | ----------- | +| items | **Required** | Name of the links array found in `_data/navigation.yml`. | \ No newline at end of file diff --git a/_includes/nav_list b/_includes/nav_list index 352856f7..60399880 100644 --- a/_includes/nav_list +++ b/_includes/nav_list @@ -1,25 +1,48 @@ {% include base_path %} -{% assign navigation = site.data.navigation[page.sidebar.nav] %} +{% assign navigation = site.data.navigation[include.nav] %} \ No newline at end of file + + + diff --git a/_includes/sidebar.html b/_includes/sidebar.html index 072ffca7..dbb7aae4 100644 --- a/_includes/sidebar.html +++ b/_includes/sidebar.html @@ -18,7 +18,7 @@ {% if s.text %}{{ s.text | markdownify }}{% endif %} {% endfor %} {% if page.sidebar.nav %} - {% include nav_list items=page.sidebar.nav %} + {% include nav_list nav=page.sidebar.nav %} {% endif %} {% endif %}