Improve nav_list helper to be used with any type of navigation list defined in navigation.yml data file
- Add documentation - Close #272
This commit is contained in:
Michael Rose
parent
1579805e3d
commit
bea516b640
@ -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
|
||||
url: /docs/license/
|
||||
@ -174,3 +174,75 @@ 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 %}
|
||||
```
|
||||
|
||||
## 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`. |
|
||||
@ -1,21 +1,42 @@
|
||||
{% include base_path %}
|
||||
{% assign navigation = site.data.navigation[page.sidebar.nav] %}
|
||||
{% assign navigation = site.data.navigation[include.nav] %}
|
||||
|
||||
<nav class="nav__list">
|
||||
{% if page.sidebar.title %}<header><h4 class="nav__title" style="padding: 0;">{{ page.sidebar.title }}</h4></header>{% endif %}
|
||||
<ul>
|
||||
{% for nav in navigation %}
|
||||
<li><span class="nav__sub-title">{{ nav.title }}</span>
|
||||
<li>
|
||||
{% if nav.url %}
|
||||
{% comment %}internal/external URL check{% endcomment %}
|
||||
{% if nav.url contains "http" %}
|
||||
{% assign domain = "" %}
|
||||
{% else %}
|
||||
{% assign domain = base_path %}
|
||||
{% endif %}
|
||||
|
||||
<a href="{{ domain }}{{ nav.url }}"><span class="nav__sub-title">{{ nav.title }}</span></a>
|
||||
{% else %}
|
||||
<span class="nav__sub-title">{{ nav.title }}</span>
|
||||
{% endif %}
|
||||
|
||||
{% if nav.children != null %}
|
||||
<ul>
|
||||
{% for child in nav.children %}
|
||||
{% assign nav_url = child.path | prepend: "/" | prepend: page.sidebar.nav | prepend: "/" | append: "/" %}
|
||||
{% if nav_url == page.url %}
|
||||
{% comment %}internal/external URL check{% endcomment %}
|
||||
{% if child.url contains "http" %}
|
||||
{% assign domain = "" %}
|
||||
{% else %}
|
||||
{% assign domain = base_path %}
|
||||
{% endif %}
|
||||
|
||||
{% comment %}set "active" class on current page{% endcomment %}
|
||||
{% if child.url == page.url %}
|
||||
{% assign active = "active" %}
|
||||
{% else %}
|
||||
{% assign active = "" %}
|
||||
{% endif %}
|
||||
<li><a href="{{ nav_url | prepend: base_path }}" class="{{ active }}">{{ child.title }}</a></li>
|
||||
|
||||
<li><a href="{{ domain }}{{ child.url }}" class="{{ active }}">{{ child.title }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endif %}
|
||||
@ -23,3 +44,5 @@
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
|
||||
|
||||
@ -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 %}
|
||||
</div>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user