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

6
_data/topnav.yml
View File

@ -3,6 +3,8 @@
topnav:
- title: Topnav
items:
- title: GitHub
external_url: https://github.com/tomjohnson1492/documentation-theme-jekyll
- title: News
url: /news
@ -10,10 +12,8 @@ topnav:
topnav_dropdowns:
- title: Topnav dropdowns
folders:
- title: Jekyll Resources
- title: Jekyll Help
folderitems:
- title: Github Repo
external_url: https://github.com/tomjohnson1492/documentation-theme-jekyll
- title: Jekyll Talk
external_url: https://talk.jekyllrb.com
- title: Jekyll documentation

2
_includes/topnav.html
View File

@ -19,7 +19,7 @@
{% assign topnav = site.data[page.topnav] %}
{% assign topnav_dropdowns = site.data[page.topnav].topnav_dropdowns %}
{% for entry in topnav %}
{% for entry in topnav.topnav %}
{% for item in entry.items %}
{% if item.external_url %}
<li><a href="{{item.external_url}}" target="_blank">{{item.title}}</a></li>

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

9
pages/mydoc/mydoc_pages.md
View File

@ -46,7 +46,8 @@ The following table describes each of the frontmatter that you can use with this
| **title** | Required | The title for the page |
| **tags** | Optional | Tags for the page. Make all tags single words, with underscores if needed (rather than spaces). Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to \_data/tags_doc.yml to be allowed entrance into the page. This prevents tags from becoming somewhat random and unstructured. You must create a tag page for each one of your tags following the pattern shown in the tags folder. (Tag pages aren't automatically created.) |
| **keywords** | Optional | Synonyms and other keywords for the page. This information gets stuffed into the page's metadata to increase SEO. The user won't see the keywords, but if you search for one of the keywords, it will be picked up by the search engine. |
| **last_updated** | Optional | The date the page was last updated. This information could helpful for readers trying to evaluate how current and authoritative information is. If included, the last_updated date appears in the footer of the page in rather small font.|
| **last_updated** | Optional | The date the page was last updated. This information could helpful for readers trying to evaluate how current and authoritative information is. If included, the last_updated date appears in the footer of the page in small font.|
| **sidebar** | Required | Refers to the sidebar data file for this page. Don't include the ".yml" file extension for the sidebar &mdash; just provide the file name. If no sidebar is specified, this value will inherit the `default` property set in your \_config.yml file for the page's frontmatter. |
| **summary** | Optional | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) The only drawback with summaries is that you can't use variables in them. |
| **permalink**| Required | The permalink *must* match the filename in order for automated links to work. Additionally, you must include the ".html" in the filename. Do not put forward slashes around the permalink (this makes Jekyll put the file inside a folder in the output). When Jekyll builds the site, it will put the page into the root directory rather than leaving it in a subdirectory or putting it inside a folder and naming the file index.html. Having all files flattened in the root directory is essential for relative linking to work and for all paths to JS and CSS files to be valid. |
| **datatable** | Optional | 'true'. If you add `datatable: true` in the frontmatter, scripts for the [jQuery Datatables plugin](https://www.datatables.net/) get included on the page. You can see the scripts that conditionally appear by looking in the \_layouts/default.html page. |
@ -126,7 +127,7 @@ Use pound signs before the heading title to designate the level. Note that kramd
## Second-level heading
```
**Result:**
**Result:**
## Second-level heading
@ -135,7 +136,7 @@ Use pound signs before the heading title to designate the level. Note that kramd
```
### Third-level heading
```
**Result:**
**Result:**
### Third-level heading
@ -145,7 +146,7 @@ Use pound signs before the heading title to designate the level. Note that kramd
#### Fourth-level heading
```
**Result:**
**Result:**
#### Fourth-level heading

12
pages/mydoc/mydoc_posts.md
View File

@ -9,8 +9,6 @@ permalink: mydoc_posts.html
folder: mydoc
---
hello there.
## About posts
Posts are typically used for blogs or other news information because they contain a date and are sorted in reverse chronological order.
@ -25,23 +23,25 @@ The news.html file in the root directory shows a reverse chronological listing o
The frontmatter you can use with posts is as follows:
```yaml
---
title: My sample post
tags: content_types
keywords: pages, authoring, exclusion, frontmatter
summary: "This is some summary frontmatter for my sample post."
sidebar: mydoc_sidebar
permalink: mydoc_pages.html
tags: content_types
summary: "This is some summary frontmatter for my sample post."
---
```
| Frontmatter | Required? | Description |
|-------------|-------------|-------------|
| **title** | Required | The title for the page |
| **tags** | Optional | Tags for the page. Make all tags single words, with underscores if needed. Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to \_data/tags_doc.yml to be allowed entrance into the page. This prevents tags from becoming somewhat random and unstructured. You must create a tag page for each one of your tags following the sample pattern in the tabs folder. (Tag pages aren't automatically created.) |
| **keywords** | Optional | Synonyms and other keywords for the page. This information gets stuffed into the page's metadata to increase SEO. The user won't see the keywords, but if you search for one of the keywords, it will be picked up by the search engine. |
| **summary** | Optional | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) The only drawback with summaries is that you can't use variables in them. |
| **sidebar** | Required | Refers to the sidebar data file for this page. Don't include the ".yml" file extension for the sidebar &mdash; just provide the file name. If no sidebar is specified, this value will inherit the `default` property set in your \_config.yml file for the page's frontmatter. |
| **permalink**| Required | This theme uses permalinks to facilitate the linking. You specify the permalink want for the page, and the \_site output will put the page into the root directory when you publish. Follow the same convention here as you do with page permalinks -- list the file name followed by the .html extension. |
| **summary** | Optional | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) The only drawback with summaries is that you can't use variables in them. |
{% include links.html %}

1
pages/mydoc/mydoc_support.md
View File

@ -7,6 +7,7 @@ summary: "Contact me for any support issues."
sidebar: mydoc_sidebar
permalink: mydoc_support.html
folder: mydoc
topnav: topnav
---
Let me know about any bugs or other issues that you find. Just email me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. You can also [create issues directly within the Github repository here](https://github.com/tomjohnson1492/jekyll-doc/issues).

20
pages/mydoc/mydoc_supported_features.md
View File

@ -17,16 +17,16 @@ Before you get into exploring Jekyll as a potential platform for help content, y
Features | Supported | Notes
--------|-----------|-----------
Content re-use | Yes | Supports re-use through Liquid. You can re-use variables, snippets of code, entire pages, and more. In DITA speak, this includes conref and keyref.
Markdown | Yes | You can author content using Markdown syntax. This is a wiki-like syntax for HTML that you can probably pick up in 10 minutes. Where Markdown falls short, you can use HTML. Where HTML falls short, you use Liquid, which is a scripting that allows you to incorporate more advanced logic.
Responsive design | Yes | Uses Bootstrap framework for responsive design.
Translation | Yes | I haven't done a translation project yet (just a pilot test). Here's the basic approach: Export the HTML pages and send them to a translation agency. Then create a new project for that language and insert the translated pages. Everything will be translated.
Collaboration | Yes | You collaborate with Jekyll projects the same way that developers collaborate with software projects. (You don't need a CMS.) Because you're working with text file formats, you can use any version control software (Git, Mercurial, Perforce, Bitbucket, etc.) as a CMS for your files.
Scalability | Yes | Your site can scale to any size. It's up to you to determine how you will design the information architecture for your thousands of pages. You can choose what you display at first, second, third, fourth, and more levels, etc. Note that when your project has thousands of pages, the build time will be longer (maybe 1 minute per thousand pages?). It really depends on how many for loops you have iterating through the pages.
Lightweight architecture | Yes | You don't need a LAMP stack (Linux, Apache, MySQL, PHP) architecture to get your site running. All of the building is done on your own machine, and you then push the static HTML files onto a server.
Skinnability | Yes | You can skin your Jekyll site to look identical to pretty much any other site online. If you have a UX team, they can really skin and design the site using all the tools familiar to the modern designer -- JavaScript, HTML5, CSS, jQuery, and more. Jekyll is built on the modern web development stack rather than the XML stack (XSLT, XPath, XQuery).
Support | Yes | The community for your Jekyll site isn't so much other tech writers (as is the case with DITA) but rather the wider web development community. [Jekyll Talk](http://talk.jekyllrb.com) is a great resource. So is Stack Overflow.
Blogging features | Yes | There is a simple blogging feature. This appears as "news" and is intended to promote news that applies across products.
Content re-use | Yes | Supports re-use through Liquid. You can re-use variables, snippets of code, entire pages, and more. In DITA speak, this includes conref and keyref. See [Content reuse][mydoc_content_reuse] for more details.|
Markdown | Yes | You can author content using Markdown syntax, specifically [kramdown](https://kramdown.gettalong.org/). This is a wiki-like syntax for HTML that you can probably pick up in 10 minutes. Where Markdown falls short, you can use HTML. Where HTML falls short, you use Liquid, which is a scripting that allows you to incorporate more advanced logic.|
Responsive design | Yes | Uses [Bootstrap framework](http://getbootstrap.com/) for responsive design.
Translation | Yes | To translate content, send the generated HTML to your translation group. You can translate the Markdown source if your translator accepts the format, but usually Markdown is problematic. Note that this theme isn't structured well to accommodate translation projects.|
Collaboration | Yes | You collaborate with Jekyll projects the same way that developers collaborate with software projects. (You don't need a CMS.) Because you're working with text file formats, you can use any version control software (Git, Mercurial, Perforce, Bitbucket, etc.) as a CMS for your files.|
Scalability | Yes | Your site can scale to any size. It's up to you to determine how you will design the information architecture for your pages. You can choose what you display at first, second, third, fourth, and more levels, etc. Note that when your project has thousands of pages, the build time will be longer (maybe 1 minute per thousand pages?). It really depends on how many for loops you have iterating through the pages. I recommend that you use [smaller repos](http://idratherbewriting.com/2017/05/26/big-repos-versus-small-repos/) in your content architecture. |
Lightweight architecture | Yes | You don't need a LAMP stack (Linux, Apache, MySQL, PHP) architecture to get your site running. All of the building is done on your own machine, and you then push the static HTML files onto a server.|
Skinnability | Yes | You can skin your Jekyll site to look identical to pretty much any other site online. If you have a UX team, they can really skin and design the site using all the tools familiar to the modern designer -- JavaScript, HTML5, CSS, jQuery, and more. Jekyll is built on the modern web development stack rather than the XML stack (XSLT, XPath, XQuery). See [this tutorial](http://jekyllrb.com/tutorials/convert-site-to-jekyll/) for details on how to create your own Jekyll theme. |
Support | Yes | The community for your Jekyll site isn't so much other tech writers (as is the case with DITA) but rather the wider web development community. [Jekyll Talk](http://talk.jekyllrb.com) is a great resource. So is [Stack Overflow](https://stackoverflow.com/questions/tagged/jekyll). See the [Getting Help](http://jekyllrb.com/help/) section of Jekyll. |
Blogging features | Yes | There is a simple blogging feature. This appears as [news](news.html) and is intended to promote news that applies across products.|
Versioning | Yes | Jekyll doesn't version your files. You upload your files to a version control system such as Github. Your files are versioned there.
PC platform | Yes | Jekyll runs on Windows. Although the experience working on the command line is better on a Mac, Windows also works, especially now that Jekyll 3.0 dropped dependencies on Python, which wasn't available by default on Windows.
jQuery plugins | Yes | You can use any jQuery plugins you and other JavaScript, CMS, or templating tools. However, note that if you use Ruby plugins, you can't directly host the source files on Github Pages because Github Pages doesn't allow Ruby plugins. Instead, you can just push your output to any web server. If you're not planning to use Github Pages, there are no restrictions on any plugins of any sort. Jekyll makes it super easy to integrate every kind of plugin imaginable. This theme doesn't actually use any plugins, so you can publish on Github if you want.