From fad29f113b88773f18fc99a2a4e746e5ca950a1b Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Mon, 5 Jun 2017 09:27:03 -0700 Subject: [PATCH] improved doc around sidebars, fixed bug with topnav code for single items, improved other doc with supported features --- _data/topnav.yml | 6 +- _includes/topnav.html | 2 +- index.md | 105 ++++++++++++++++++------ pages/mydoc/mydoc_pages.md | 9 +- pages/mydoc/mydoc_posts.md | 12 +-- pages/mydoc/mydoc_support.md | 1 + pages/mydoc/mydoc_supported_features.md | 20 ++--- 7 files changed, 106 insertions(+), 49 deletions(-) diff --git a/_data/topnav.yml b/_data/topnav.yml index 8bd1397..d2e23a1 100644 --- a/_data/topnav.yml +++ b/_data/topnav.yml @@ -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 diff --git a/_includes/topnav.html b/_includes/topnav.html index 0182f0d..315125f 100644 --- a/_includes/topnav.html +++ b/_includes/topnav.html @@ -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 %}
  • {{item.title}}
    • diff --git a/index.md b/index.md index b753d64..bfa5581 100644 --- a/index.md +++ b/index.md @@ -106,17 +106,15 @@ 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). +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 diff --git a/pages/mydoc/mydoc_pages.md b/pages/mydoc/mydoc_pages.md index 35bc4b0..d2b91a8 100644 --- a/pages/mydoc/mydoc_pages.md +++ b/pages/mydoc/mydoc_pages.md @@ -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 — 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 diff --git a/pages/mydoc/mydoc_posts.md b/pages/mydoc/mydoc_posts.md index 4edcb32..835e18c 100644 --- a/pages/mydoc/mydoc_posts.md +++ b/pages/mydoc/mydoc_posts.md @@ -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 — 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 %} diff --git a/pages/mydoc/mydoc_support.md b/pages/mydoc/mydoc_support.md index 5ab18f7..1e878c0 100644 --- a/pages/mydoc/mydoc_support.md +++ b/pages/mydoc/mydoc_support.md @@ -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 tomjohnson1492@gmail.com. You can also [create issues directly within the Github repository here](https://github.com/tomjohnson1492/jekyll-doc/issues). diff --git a/pages/mydoc/mydoc_supported_features.md b/pages/mydoc/mydoc_supported_features.md index bbd1953..619ed02 100644 --- a/pages/mydoc/mydoc_supported_features.md +++ b/pages/mydoc/mydoc_supported_features.md @@ -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.