From dfb63aecbc73a9dfc019a58f5267bd3b0b03cd38 Mon Sep 17 00:00:00 2001 From: tomjohnson1492 Date: Mon, 11 Jul 2016 07:10:32 -0700 Subject: [PATCH] fixing docs, also fixing link paths in various places. --- _config.yml | 3 ++ _includes/custom/getting_started_series.html | 2 +- .../custom/getting_started_series_next.html | 2 +- _includes/custom/series_acme.html | 2 +- _includes/custom/series_acme_next.html | 2 +- _layouts/page.html | 22 ++++----- pages/mydoc/mydoc_content_reuse.md | 2 +- pages/mydoc/{mydoc_faq.html => mydoc_faq.md} | 0 pages/mydoc/mydoc_images.md | 4 +- pages/mydoc/mydoc_kb_layout.md | 4 +- pages/mydoc/mydoc_pages.md | 38 ++++++++-------- pages/mydoc/mydoc_release_notes_60.md | 3 ++ pages/mydoc/mydoc_search_configuration.md | 4 +- pages/mydoc/mydoc_series.md | 4 +- pages/mydoc/mydoc_sidebar_navigation.md | 11 +++-- pages/mydoc/mydoc_supported_features.md | 3 +- pages/mydoc/mydoc_tags.md | 45 +++++++++---------- search.json | 2 +- 18 files changed, 80 insertions(+), 73 deletions(-) rename pages/mydoc/{mydoc_faq.html => mydoc_faq.md} (100%) diff --git a/_config.yml b/_config.yml index a3e6bbb..21aaff5 100644 --- a/_config.yml +++ b/_config.yml @@ -97,3 +97,6 @@ sidebars: description: "Intended as a documentation theme based on Jekyll for technical writers documenting software and other technical products, this theme has all the elements you would need to handle multiple products with both multi-level sidebar navigation, tags, and other documentation features." # the description is used in the feed.xml file + +# needed for sitemap.xml file only +url: diff --git a/_includes/custom/getting_started_series.html b/_includes/custom/getting_started_series.html index 464479f..fef578b 100644 --- a/_includes/custom/getting_started_series.html +++ b/_includes/custom/getting_started_series.html @@ -9,7 +9,7 @@
  • → {{p.title}}
    • {% else %}
  • - {{p.title}} + {{p.title}}
    • {% endif %} {% endif %} diff --git a/_includes/custom/getting_started_series_next.html b/_includes/custom/getting_started_series_next.html index 0a7bbd9..247e0cb 100644 --- a/_includes/custom/getting_started_series_next.html +++ b/_includes/custom/getting_started_series_next.html @@ -4,7 +4,7 @@ {% if p.series == "Getting Started" %} {% assign nextTopic = page.weight | plus: "1" %} {% if p.weight == nextTopic %} - + {% endif %} {% endif %} {% endfor %} diff --git a/_includes/custom/series_acme.html b/_includes/custom/series_acme.html index 6b51f6f..adeb76f 100644 --- a/_includes/custom/series_acme.html +++ b/_includes/custom/series_acme.html @@ -9,7 +9,7 @@
  • → {{p.weight}}. {{p.title}}
    • {% else %}
  • - {{p.weight}}. {{p.title}} + {{p.weight}}. {{p.title}}
    • {% endif %} {% endif %} diff --git a/_includes/custom/series_acme_next.html b/_includes/custom/series_acme_next.html index c789a6a..abd345b 100644 --- a/_includes/custom/series_acme_next.html +++ b/_includes/custom/series_acme_next.html @@ -3,7 +3,7 @@ {% if p.series == "ACME series" %} {% assign nextTopic = page.weight | plus: "1" %} {% if p.weight == nextTopic %} - + {% endif %} {% endif %} {% endfor %} diff --git a/_layouts/page.html b/_layouts/page.html index 5ac7435..ca15833 100644 --- a/_layouts/page.html +++ b/_layouts/page.html @@ -49,17 +49,17 @@ layout: default {{content}} -
    - {% if page.tags != null %} - Tags: - {% assign projectTags = site.data.tags.allowed-tags %} - {% for tag in page.tags %} - {% if projectTags contains tag %} - {{page.tagName}}{{tag}} - {% endif %} - {% endfor %} - {% endif %} -
    +
    + {% if page.tags != null %} + Tags: + {% assign projectTags = site.data.tags.allowed-tags %} + {% for tag in page.tags %} + {% if projectTags contains tag %} + {{page.tagName}}{{tag}} + {% endif %} + {% endfor %} + {% endif %} +
    {% if site.disqus %} {% include disqus.html %} diff --git a/pages/mydoc/mydoc_content_reuse.md b/pages/mydoc/mydoc_content_reuse.md index 3586816..e543bdd 100644 --- a/pages/mydoc/mydoc_content_reuse.md +++ b/pages/mydoc/mydoc_content_reuse.md @@ -10,7 +10,7 @@ folder: mydoc --- ## About content reuse -You can embed content from one file inside another using includes. Put the file containing content you want to reuse (e.g., mypage.html) inside the \_includes/custom folder and then use a tag like this: +You can embed content from one file inside another using includes. Put the file containing content you want to reuse (e.g., mypage.html) inside the \_includes/custom folder and then use a tag like this: {% raw %} ``` diff --git a/pages/mydoc/mydoc_faq.html b/pages/mydoc/mydoc_faq.md similarity index 100% rename from pages/mydoc/mydoc_faq.html rename to pages/mydoc/mydoc_faq.md diff --git a/pages/mydoc/mydoc_images.md b/pages/mydoc/mydoc_images.md index 225d722..084ad23 100644 --- a/pages/mydoc/mydoc_images.md +++ b/pages/mydoc/mydoc_images.md @@ -23,7 +23,7 @@ The available include properties are as follows: | Property | description | |-------|--------| -| file | The name of the file. Store it in the /images folder. | +| file | The name of the file. Store it in the /images folder. If you want to organize your images in subfolders, reference the subfolder path here, like this: `mysubfolder/jekyllrb.png` | | url | Whether to link the image to a URL | | alt | Alternative image text for accessibility and SEO | | caption | A caption for the image | @@ -35,6 +35,8 @@ Here's the result: {% include image.html file="jekyll.png" url="http://jekyllrb.com" alt="Jekyll" caption="This is a sample caption" %} + + ## Inline image includes For inline images, such as with a button that you want to appear inline with text, use the inline_image.html include, like this: diff --git a/pages/mydoc/mydoc_kb_layout.md b/pages/mydoc/mydoc_kb_layout.md index 813e4af..63b4869 100644 --- a/pages/mydoc/mydoc_kb_layout.md +++ b/pages/mydoc/mydoc_kb_layout.md @@ -90,7 +90,7 @@ If you don't want to link to a tag archive index, but instead want to list all p {% for page in sorted_pages %} {% for tag in page.tags %} {% if tag == "getting_started" %} -
  • {{page.title}}
    • +
  • {{page.title}}
    • {% endif %} {% endfor %} {% endfor %} @@ -106,7 +106,7 @@ Getting started pages: {% for page in sorted_pages %} {% for tag in page.tags %} {% if tag == "getting_started" %} -
  • {{page.title}}
    • +
  • {{page.title}}
    • {% endif %} {% endfor %} {% endfor %} diff --git a/pages/mydoc/mydoc_pages.md b/pages/mydoc/mydoc_pages.md index add2931..373f272 100644 --- a/pages/mydoc/mydoc_pages.md +++ b/pages/mydoc/mydoc_pages.md @@ -12,21 +12,11 @@ folder: mydoc ## Where to author content Use a text editor such as Sublime Text, WebStorm, IntelliJ, or Atom to create pages. Atom is recommended because it's created by Github, which is driving some of the Jekyll development through Github Pages. -## Page names and excluding files from outputs +## Where to save pages -By default, everything in your project is included in the output. You can exclude all files that don't belong to that project by specifying the file name, the folder name, or by using wildcards in your configuration file: +You can store your pages in any folder structures you want, with any level of folder nesting. The site output will pull all of those pages out of their folders and put them into the root directory. Check out the \_site folder, which is where Jekyll is generated, to see the difference between your project's structure and the resulting site output. -```yaml -exclude: - -- filename.md -- subfolder_name/ -- mydoc_* -- gitignore -``` - - -Wildcards will exclude every match after the `*`. +The listing of all pages in the root directory (which happens when you add a permalink property to the pages) is what allows the relative linking and offline viewing of the site to work. ## Frontmatter @@ -60,12 +50,27 @@ The following table describes each of the frontmatter that you can use with this | **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. | -| toc | Optional | If you specify `toc: false` in the frontmatter, the page won't have the table of contents that appears below the title. The toc refers to the list of jump links below the page title, not the sidebar navigation. You probably want to hide the TOC on the homepage and product landing pages.| +| **toc** | Optional | If you specify `toc: false` in the frontmatter, the page won't have the table of contents that appears below the title. The toc refers to the list of jump links below the page title, not the sidebar navigation. You probably want to hide the TOC on the homepage and product landing pages.| ## Colons in page titles If you want to use a colon in your page title, you must enclose the title's value in quotation marks. +## Page names and excluding files from outputs + +By default, everything in your project is included in the output. You can exclude all files that don't belong to that project by specifying the file name, the folder name, or by using wildcards in your configuration file: + +```yaml +exclude: + +- filename.md +- subfolder_name/ +- mydoc_* +- gitignore +``` + +Wildcards will exclude every match after the `*`. + ## Saving pages as drafts If you add `published: false` in the frontmatter, your page won't be published. You can also move draft pages into the \_drafts folder to exclude them from the build. With posts, you can also keep them as drafts by omitting the date in the title. @@ -84,11 +89,6 @@ For your Markdown files, note that a space or two indent will set text off as co If you have a lot of HTML, as long as the top and bottom tags of the HTML are flush left in a Markdown file, all the tags inside those bookend HTML tags will render as HTML, regardless of their indentation. (This can be especially useful for tables.) -## Where to save pages - -You can store your pages in any folder structures you want, with any level of folder nesting. The site output will pull all of those pages out of their folders and put them into the root directory. Check out the \_site folder, which is where Jekyll is generated, to see the difference between your project's structure and the resulting site output. - -The listing of all pages in the root directory is what allows the relative linking and offline viewing of the site to work. ## Page names diff --git a/pages/mydoc/mydoc_release_notes_60.md b/pages/mydoc/mydoc_release_notes_60.md index 5584953..54ade7c 100644 --- a/pages/mydoc/mydoc_release_notes_60.md +++ b/pages/mydoc/mydoc_release_notes_60.md @@ -33,5 +33,8 @@ Instead of using YAML references to handle links, I've switched to a Markdown re If you want to display a workflow map for a process, you can do so by adding some properties in your frontmatter. The workflow map helps guide users through a process. Both simple and complex workflow maps are available. For more details, see [Workflow maps][mydoc_workflow_maps]. +## Upgrading + +If you want to upgrade from an earlier version of the theme, I recommend that you download the new theme and copy of your Markdown files into the new theme. You'll then need to make adjustments to your page frontmatter, to the sidebar table of contents, links, image references, and alert references. In short, there's no easy upgrade path. But all of this won't take too long if you don't have mountains of content. {% include links.html %} diff --git a/pages/mydoc/mydoc_search_configuration.md b/pages/mydoc/mydoc_search_configuration.md index 5540f92..99a512e 100644 --- a/pages/mydoc/mydoc_search_configuration.md +++ b/pages/mydoc/mydoc_search_configuration.md @@ -63,7 +63,7 @@ search: exclude "title": "{{ page.title | escape }}", "tags": "{{ page.tags }}", "keywords": "{{page.keywords}}", -"url": "{{ page.url | prepend: site.baseurl }}", +"url": "{{ page.url | remove: "/"}}", "summary": "{{page.summary | strip }}" }, {% endunless %} @@ -75,7 +75,7 @@ search: exclude "title": "{{ post.title | escape }}", "tags": "{{ post.tags }}", "keywords": "{{post.keywords}}", -"url": "{{ post.url | prepend: site.baseurl }}", +"url": "{{ post.url }}", "summary": "{{post.summary | strip }}" } {% unless forloop.last %},{% endunless %} diff --git a/pages/mydoc/mydoc_series.md b/pages/mydoc/mydoc_series.md index a6042e2..7efc836 100644 --- a/pages/mydoc/mydoc_series.md +++ b/pages/mydoc/mydoc_series.md @@ -30,7 +30,7 @@ First create an include that contains your series button:
  • → {{p.weight}}. {{p.title}}
    • {% else %}
  • - {{p.weight}}. {{p.title}} + {{p.weight}}. {{p.title}}
    • {% endif %} {% endif %} @@ -58,7 +58,7 @@ Now create another include for the Next button at the bottom of the page. Copy t {% if p.series == "ACME series" %} {% assign nextTopic = page.weight | plus: "1" %} {% if p.weight == nextTopic %} - + {% endif %} {% endif %} {% endfor %} diff --git a/pages/mydoc/mydoc_sidebar_navigation.md b/pages/mydoc/mydoc_sidebar_navigation.md index 8a1b538..a03b03d 100644 --- a/pages/mydoc/mydoc_sidebar_navigation.md +++ b/pages/mydoc/mydoc_sidebar_navigation.md @@ -45,9 +45,8 @@ For example, the sidebar.html file contains the following code: {% raw %} ```liquid - {% if subfolderitem.external_url %} -
  • {{deeplevel.title}}
    • -``` +{% if folderitem.external_url %} +
  • {{folderitem.title}}
    • ``` {% endraw %} You can see that the `external_url` is a condition that applies a different formatting. Although this feature is available, I recommend putting any external navigation links in the top navigation bar instead of the side navigation bar. @@ -60,8 +59,8 @@ For example, the sidebar.html file contains the following code: {% raw %} ```liquid -{% elsif page.url == subfolderitem.url %} -
  • {{subfolderitem.title}}
    • +{% elsif page.url == folderitem.url %} +
  • {{folderitem.title}}
    • ``` {% endraw %} @@ -73,7 +72,7 @@ This is why the `url` value in the sidebar data file looks something like this: ```yaml - title: Understanding how the sidebar works - url: /mydoc_understand_sidebar/ + permalink: mydoc_understand_sidebar.html output: web, pdf ``` diff --git a/pages/mydoc/mydoc_supported_features.md b/pages/mydoc/mydoc_supported_features.md index 4cfe232..82ed0db 100644 --- a/pages/mydoc/mydoc_supported_features.md +++ b/pages/mydoc/mydoc_supported_features.md @@ -34,6 +34,7 @@ Bootstrap integration | Yes | This theme is built on [Bootstrap](http://getboots Fast-loading pages| Yes | This is one of the Jekyll's strengths. Because the files are static, they loading extremely fast, approximately 0.5 seconds per page. You can't beat this for performance. (A typically database-driven site like WordPress averages about 2.5 + seconds loading time per page.) Because the pages are all static, it means they are also extremely secure. You won't get hacked like you might with a WordPress site. Themes | Yes | You can have different themes for different outputs. If you know CSS, theming both the web and print outputs is pretty easy. Open source | Yes | This theme is entirely open source. Every piece of code is open, viewable, and editable. Note that this openness comes at a price — it's easy to make changes that break the theme or otherwise cause errors. +Offline viewing | Yes | This theme uses relative linking throughout, so you can view the content offline and on any webserver without configuring urls and baseurls in your configuration file. ## Features not available @@ -44,7 +45,7 @@ Features | Supported | Notes --------|-----------|----------- CMS interface | No | Unlike with WordPress, you don't log into an interface and navigate to your files. You work with text files and preview the site dynamically in your browser. Don't worry -- this is part of the simplicy that makes Jekyll awesome. I recommend using WebStorm as your text editor. WYSIWYG interface | No | I use WebStorm to author content, because I like working in text file formats. But you can use any Markdown editor you want (e.g., Lightpaper for Mac, Marked) to author your content. -Different outputs | No | This theme provides a single website output that contains documentation for multiple products. Unlike previous iterations of the theme, it's not intended to support different outputs from the same content. +Different outputs | No | This theme provides a single website output that contains documentation for multiple products. Unlike previous iterations of the theme, it's not intended to support different outputs from the same content. However, you can easily set things up to do this by simply creating multiple configuration files and running different builds for each configuration file. Robust search | No | The search feature is a simplistic JSON search. For more robust search, you should integrate Swiftype or Algolia. However, those services aren't currently integrated into the theme. Standardized templates | No | You can create pages with any structure you want. The theme does not enforce topic types such as a task or concept as the DITA specification does. Integration with Swagger | No | You can link to a SwaggerUI output, but there is no built-in integration of SwaggerUI into this documentation theme. diff --git a/pages/mydoc/mydoc_tags.md b/pages/mydoc/mydoc_tags.md index 7bca464..110217b 100644 --- a/pages/mydoc/mydoc_tags.md +++ b/pages/mydoc/mydoc_tags.md @@ -15,8 +15,8 @@ You can add tags to pages by adding `tags` in the frontmatter with values inside ``` --- -title: 2.0 Release Notes -permalink: release_notes_2_0/ +title: 5.0 Release Notes +permalink: release_notes_5_0.html tags: [formatting, single_sourcing] --- ``` @@ -31,7 +31,6 @@ To prevent tags from getting out of control and inconsistent, first make sure th {% include note.html content="In contrast to WordPress, with Jekyll to get tags on pages you have to build out the functionality for tags so that clicking a tag name shows you all pages with that tag. Tags in Jekyll are much more manual." %} - Additionally, you must create a tag archive page similar to the other pages named tag_{tagname}.html folder. This theme doesn't auto-create tag archive pages. For simplicity, make all your tags single words (connect them with hyphens if necessary). @@ -63,7 +62,7 @@ Tags have a few components. title: "Collaboration pages" tagName: collaboration search: exclude -permalink: tag_collaboration/ +permalink: tag_collaboration.html sidebar: mydoc_sidebar --- {% include taglogic.html %} @@ -76,21 +75,21 @@ sidebar: mydoc_sidebar By default, the \_layouts/page.html file will look for any tags on a page and insert them at the bottom of the page using this code: - {% raw %} - ``` -
    - {% if page.tags != null %} - Tags: - {% assign projectTags = site.data.tags.allowed-tags %} - {% for tag in page.tags %} - {% if projectTags contains tag %} - {{page.tagName}}{{tag}} - {% endif %} - {% endfor %} - {% endif %} -
    - ``` - {% endraw %} + +```liquid +{% raw %}
    +{% if page.tags != null %} +Tags: +{% assign projectTags = site.data.tags.allowed-tags %} +{% for tag in page.tags %} +{% if projectTags contains tag %} +{{page.tagName}}{{tag}} +{% endif %} +{% endfor %} +{% endif %} +
    {% endraw %} +``` + Because this code appears on the \_layouts/page.html file by default, you don't need to do anything in your page to get the tags to appear. However, if you want to alter the placement or change the button color, you can do so within the \_includes/taglogic.html file. @@ -107,7 +106,7 @@ Getting started pages: {% for page in site.pages %} {% for tag in page.tags %} {% if tag == "getting_started" %} -
  • {{page.title}}
    • +
  • {{page.title}}
    • {% endif %} {% endfor %} {% endfor %} @@ -122,7 +121,7 @@ Getting started pages: {% for page in site.pages %} {% for tag in page.tags %} {% if tag == "getting_started" %} -
  • {{page.title}}
    • +
  • {{page.title}}
    • {% endif %} {% endfor %} {% endfor %} @@ -138,7 +137,7 @@ Getting started pages: {% for page in sorted_pages %} {% for tag in page.tags %} {% if tag == "getting_started" %} -
  • {{page.title}}
    • +
  • {{page.title}}
    • {% endif %} {% endfor %} {% endfor %} @@ -154,7 +153,7 @@ Getting started pages: {% for page in sorted_pages %} {% for tag in page.tags %} {% if tag == "getting_started" %} -
  • {{page.title}}
    • +
  • {{page.title}}
    • {% endif %} {% endfor %} {% endfor %} diff --git a/search.json b/search.json index aa6e13a..348c498 100644 --- a/search.json +++ b/search.json @@ -11,7 +11,7 @@ search: exclude "title": "{{ page.title | escape }}", "tags": "{{ page.tags }}", "keywords": "{{page.keywords}}", -"url": "{{ page.url }}", +"url": "{{ page.url | remove: "/"}}", "summary": "{{page.summary | strip }}" }, {% endunless %}