HPCE/gitea-pages
0
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Activity

improved doc around sidebars, fixed bug with topnav code for single items, improved other doc with supported features

Browse Source
This commit is contained in:
Tom Johnson
2017-06-05 09:27:03 -07:00
parent 361d9f960e
commit fad29f113b
7 changed files with 106 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

105
index.md
View File

@ -106,17 +106,15 @@ permalink: mydoc_alerts
---
</pre>
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).
The `sidebar: mydoc_sidebar` refers to the \_data/sidebars/mydoc_sidebar.yml file.
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." %}
Note that your sidebar can only have 2 levels (expand the **Tag archives** option to see an example of the second level). 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.
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:
If you don't declare a sidebar, the `home_sidebar` file gets used as the default because this is the default specified in the config file:
```
```yaml
-
scope:
path: ""
@ -129,7 +127,7 @@ If you don't declare a sidebar, the `home_sidebar` file gets used as the default
topnav: topnav
```
If you wanted to load different sidebars based on how pages are organized, you could specify that like this:
If you want to set different sidebar defaults based on different folders for your pages, specify your defaults like this:
```
-
@ -144,7 +142,7 @@ If you wanted to load different sidebars based on how pages are organized, you c
topnav: topnav
```
This would load the `mydoc_sidebar` for each file in pages/mydoc.
This would load the `mydoc_sidebar` for each file in **pages/mydoc**. You could set different defaults for different path scopes.
For more detail on the sidebar, see [Sidebar navigation][mydoc_sidebar_navigation].
@ -152,15 +150,15 @@ For more detail on the sidebar, see [Sidebar navigation][mydoc_sidebar_navigatio
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:
```
```yaml
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:
Because most topnav options will be the same, the \_config.yml file specifies the topnav file as a default:
```
```yaml
-
scope:
path: ""
@ -175,7 +173,7 @@ Because most topnav options will be the same, the \_config.yml file specifies th
## 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:
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown in the theme, specically looking at mydoc_sidebar.yml as an example: Here's a code sample showing all levels:
```yaml
entries:
@ -183,7 +181,6 @@ entries:
product: Jekyll Doc Theme
version: 6.0
folders:
- title: Overview
output: web, pdf
folderitems:
@ -191,23 +188,12 @@ entries:
- title: Get started
url: /index.html
output: web, pdf
type: homepage
- title: Introduction
url: /mydoc_introduction.html
output: web, pdf
- title: Supported features
url: /mydoc_supported_features.html
output: web, pdf
- title: About the theme author
url: /mydoc_about.html
output: web, pdf
- title: Support
url: /mydoc_support.html
output: web, pdf
- title: Release Notes
output: web, pdf
folderitems:
@ -220,6 +206,30 @@ entries:
url: /mydoc_release_notes_50.html
output: web, pdf
- title: Tag archives
output: web
folderitems:
- title: Tag archives overview
url: /mydoc_tag_archives_overview.html
output: web
subfolders:
- title: Tag archive pages
output: web
subfolderitems:
- title: Formatting pages
url: /tag_formatting.html
output: web
- title: Navigation pages
url: /tag_navigation.html
output: web
- title: Content types pages
url: /tag_content_types.html
output: web
```
Each `folder` or `subfolder` must contain a `title` and `output` property. Each `folderitem` or `subfolderitem` must contain a `title`, `url`, and `output` property.
@ -228,6 +238,51 @@ The two outputs available are `web` and `pdf`. (Even if you aren't publishing PD
The YAML syntax depends on exact spacing, so make sure you follow the pattern shown in the sample sidebars. See my [YAML tutorial](mydoc_yaml_tutorial) for more details about how YAML works.
{% include note.html content="If you have just one character of spacing off, Jekyll won't build due to the YAML syntax error. You'll see an error message in your console that says \"Error ... did not find expected key while parsing a block mapping at line 22 column 5. Error: Run jekyll build --trace for more information.\" If you encounter this, it usually refers to incorrect indentation or spacing in the YAML file. See the example mydoc_sidebar.yml file to see where your formatting went wrong." %}
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. If you need a hierarchy that has a folder that contains other folders and no loose topics, use a blank `-` item like this:
```yamll
entries:
- title: sidebar
product: Jekyll Doc Theme
version: 6.0
folders:
- title: Overview
output: web, pdf
folderitems:
-
- title: Release Notes
output: web, pdf
folderitems:
- title: 6.0 Release notes
url: /mydoc_release_notes_60.html
output: web, pdf
- title: 5.0 Release notes
url: /mydoc_release_notes_50.html
output: web, pdf
- title: Installation
output: web, pdf
folderitems:
- title: About Ruby, Gems, Bundler, etc.
url: /mydoc_about_ruby_gems_etc.html
output: web, pdf
- title: Install Jekyll on Mac
url: /mydoc_install_jekyll_on_mac.html
output: web, pdf
- title: Install Jekyll on Windows
url: /mydoc_install_jekyll_on_windows.html
output: web, pdf
```
To accommodate the title page and table of contents in PDF outputs, each product sidebar must list these pages before any other:
```yaml