updates for 6.1 - removed sidebarconfigs, added topnav flexibility, removed scroll layout, updated docs, removed lavish-bootstrap, replaced with normal bootstrap, added styles to compensate

This commit is contained in:
Tom Johnson
2017-06-05 06:10:01 -07:00
parent c6038b7ede
commit 361d9f960e
29 changed files with 197 additions and 6572 deletions

View File

@ -90,31 +90,7 @@ This is perhaps the easiest way to see how your site would actually look.
There are several products in this theme. Each product uses a different sidebar. This is the essence of what makes this theme unique -- different sidebars for different product documentation. The idea is that when users are reading documentation for a specific product, the sidebar navigation should be specific to that product. (You can read more of my thoughts on why multiple sidebars are important in this [blog post](http://idratherbewriting.com/2016/03/23/release-of-documentation-theme-for-jekyll-50/).)
The top navigation remains the same, because it allows users to navigate across products. But the sidebar navigation adapts to the product.
Because each product uses a different sidebar, you'll need to set up your sidebars. There's a file inside \_includes/custom called "sidebarconfigs.html." This file controls which sidebar gets associated with which product. Open up this file to see its contents.
The sidebarconfigs.html file uses simple `if elsif` logic to set a variable that the sidebar.html file uses to read the sidebar data file. The code in sidebarconfigs.html looks like this:
{% raw %}
```liquid
{% if page.sidebar == "home_sidebar" %}
{% assign sidebar = site.data.sidebars.home_sidebar.entries %}
{% elsif page.sidebar == "product1_sidebar" %}
{% assign sidebar = site.data.sidebars.product1_sidebar.entries %}
{% elsif page.sidebar == "product2_sidebar" %}
{% assign sidebar = site.data.sidebars.product2_sidebar.entries %}
{% elsif page.sidebar == "mydoc_sidebar" %}
{% assign sidebar = site.data.sidebars.mydoc_sidebar.entries %}
{% else %}
{% assign sidebar = site.data.sidebars.home_sidebar.entries %}
{% endif %}
```
{% endraw %}
The top navigation usually remains the same, because it allows users to navigate across products. But the sidebar navigation adapts to the product.
In each page's frontmatter, you must specify the sidebar you want that page to use. Here's an example of the page frontmatter showing the sidebar property:
@ -132,16 +108,71 @@ permalink: mydoc_alerts
The `sidebar: mydoc_sidebar` refers to the \_data/sidebars/mydoc_sidebar.yml file (meaning, the mydoc_sidebar.yml file inside the sidebars subfolder inside the \data folder).
If no sidebar assignment is found in the page frontmatter, the default sidebar (specified by the `else` statement) will be shown: `site.data.sidebars.home_sidebar.entries`.
Note that your sidebar can only have 2 levels. Given that each product has its own sidebar, this depth should be sufficient (it's really like 3 levels). Deeper nesting goes against usability recommendations.
{% include note.html content="Note that each level must have at least one topic before the next level starts. You can't have a second level that contains multiple third levels without having at least one standalone topic in the second level." %}
You can optionally turn off the sidebar on any page (e.g. landing pages). To turn off the sidebar for a page, you should set the page frontmatter tag as `hide_sidebar: true`.
If you don't declare a sidebar, the `home_sidebar` file gets used as the default. This is the default specified in the config file:
```
-
scope:
path: ""
type: "pages"
values:
layout: "page"
comments: true
search: true
sidebar: home_sidebar
topnav: topnav
```
If you wanted to load different sidebars based on how pages are organized, you could specify that like this:
```
-
scope:
path: "pages/mydoc"
type: "pages"
values:
layout: "page"
comments: true
search: true
sidebar: mydoc_sidebar
topnav: topnav
```
This would load the `mydoc_sidebar` for each file in pages/mydoc.
For more detail on the sidebar, see [Sidebar navigation][mydoc_sidebar_navigation].
## Top navigation
The top navigation works just like the sidebar. You can specify which topnav data file should load by adding a `topnav` property in your page, like this:
```
topnav: topnav
```
Here the topnav refers to the \_data/topnav.yml file.
Because most topnav options will be the same, the \_config.yml file specifies this as a default:
```
-
scope:
path: ""
type: "pages"
values:
layout: "page"
comments: true
search: true
sidebar: home_sidebar
topnav: topnav
```
## Sidebar syntax
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown in the theme. For example: