diff --git a/_data/sidebars/mydoc_sidebar.yml b/_data/sidebars/mydoc_sidebar.yml index 7eb8441..0f4118c 100644 --- a/_data/sidebars/mydoc_sidebar.yml +++ b/_data/sidebars/mydoc_sidebar.yml @@ -11,11 +11,11 @@ entries: type: frontmatter folderitems: - title: - url: /titlepage.html + url: /titlepage output: pdf type: frontmatter - title: - url: /tocpage.html + url: /tocpage output: pdf type: frontmatter diff --git a/_data/sidebars/product1_sidebar.yml b/_data/sidebars/product1_sidebar.yml index 4a04389..42fd47d 100644 --- a/_data/sidebars/product1_sidebar.yml +++ b/_data/sidebars/product1_sidebar.yml @@ -12,11 +12,11 @@ entries: type: frontmatter folderitems: - title: - url: /titlepage.html + url: /titlepage output: pdf type: frontmatter - title: - url: /tocpage.html + url: /tocpage output: pdf type: frontmatter diff --git a/_data/sidebars/product2_sidebar.yml b/_data/sidebars/product2_sidebar.yml index ca80dbb..08cd712 100644 --- a/_data/sidebars/product2_sidebar.yml +++ b/_data/sidebars/product2_sidebar.yml @@ -11,11 +11,11 @@ entries: type: frontmatter folderitems: - title: - url: /titlepage.html + url: /titlepage output: pdf type: frontmatter - title: - url: /tocpage.html + url: /tocpage output: pdf type: frontmatter diff --git a/_includes/topnav.html b/_includes/topnav.html index a30288f..8748605 100644 --- a/_includes/topnav.html +++ b/_includes/topnav.html @@ -59,7 +59,7 @@ SimpleJekyllSearch.init({ searchInput: document.getElementById('search-input'), resultsContainer: document.getElementById('results-container'), - dataSource: '{{ "../search.json" }}', + dataSource: '{{ "search.json" }}', searchResultTemplate: '
  • {title}
    • ', noResultsText: '{{site.data.strings.search_no_results_text}}', limit: 10, diff --git a/_layouts/post.html b/_layouts/post.html index 065f1f2..d1ba8f1 100644 --- a/_layouts/post.html +++ b/_layouts/post.html @@ -9,7 +9,7 @@ layout: default {% assign projectTags = site.data.tags.allowed-tags %} {% for tag in page.tags %} {% if projectTags contains tag %} - {{tag}}{% unless forloop.last %}, {% endunless%} + {{tag}}{% unless forloop.last %}, {% endunless%} {% endif %} {% endfor %} {% endif %} diff --git a/feed.xml b/feed.xml index f3b6721..d8d6ac9 100644 --- a/feed.xml +++ b/feed.xml @@ -8,8 +8,8 @@ layout: none {{ site.title | xml_escape }} {{ site.description | xml_escape }} - {{ site.url }}{{ site.baseurl }}/ - + {{ site.url }}/ + {{ site.time | date_to_rfc822 }} {{ site.time | date_to_rfc822 }} Jekyll v{{ jekyll.version }} @@ -18,8 +18,8 @@ layout: none {{ post.title | xml_escape }} {{ post.content | xml_escape }} {{ post.date | date_to_rfc822 }} - {{ post.url | prepend: site.baseurl | prepend: site.url }} - {{ post.url | prepend: site.baseurl | prepend: site.url }} + {{ post.url | prepend: site.url }} + {{ post.url | prepend: site.url }} {% for tag in post.tags %} {{ tag | xml_escape }} {% endfor %} diff --git a/index.md b/index.md index 2169da1..dbe25a8 100644 --- a/index.md +++ b/index.md @@ -10,7 +10,7 @@ summary: These brief instructions will help you get started quickly with the the ## Download or clone the theme -First download or clone the theme from the [Github repo](https://github.com/tomjohnson1492/documentation-theme-jekyll). Most likely you won't be pulling in updates once you start customizing the theme, so downloading theme probably makes the most sense. +First download or clone the theme from the [Github repo](https://github.com/tomjohnson1492/documentation-theme-jekyll). Most likely you won't be pulling in updates once you start customizing the theme, so downloading the theme (instead of cloning it) probably makes the most sense. ## Build this theme @@ -21,7 +21,9 @@ If you're used to running Jekyll sites, you can type the normal jekyll command, ## Customize the Gemfile -Open the Gemfile (in any text editor) in the Jekyll doc theme project: +The Gemfile is how project dependencies are managed. This project doesn't have any dependencies beyond core Jekyll. + +Open the Gemfile (in any text editor) in the Jekyll doc theme project with the following command: ``` open Gemfile @@ -58,7 +60,7 @@ There are several products in this theme. Each product uses a different sidebar. 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. +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: @@ -84,17 +86,17 @@ The sidebarconfigs.html file uses simple `if elsif` logic to set a variable that 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: -```yaml +
     ---
 title: Alerts
 tags: [formatting]
 keywords: notes, tips, cautions, warnings, admonitions
 last_updated: July 3, 2016
 summary: "You can insert notes, tips, warnings, and important alerts in your content. These notes are stored as shortcodes made available through the linksrefs.hmtl include."
-sidebar: mydoc_sidebar
+sidebar: mydoc_sidebar
 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). @@ -102,7 +104,7 @@ If no sidebar assignment is found in the page frontmatter, the default sidebar ( 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. -Additionally, 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. +{% 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." %} For more detail on the sidebar, see [Sidebar navigation][mydoc_sidebar_navigation]. @@ -186,9 +188,7 @@ For more detail on the sidebar, see [Sidebar navigation][mydoc_sidebar_navigatio This theme uses relative links throughout so that you can view the site offline and not worry about which server or directory you're hosting it. It's common with tech docs to push content to an internal server for review prior to pushing the content to an external server for publication. Because of the need for seamless transferrence from one host to another, the site has to use relative links. -To view pages locally on your machine, they need to have the `.html` extension. However, if you prefer not to have this extension, you can simply remove the `.html` from the sidebar entries, and the pages will still work when you view content on a preview server or web server. - -The `permalink` property in the page's frontmatter combined with the `include: ['pages']` property in the configuration file is what pushes the files into the root directory when the site builds. +To view pages locally on your machine (without the Jekyll preview server), they need to have the `.html` extension. The `permalink` property in the page's frontmatter (without surrounding slashes) is what pushes the files into the root directory when the site builds. ## Page frontmatter @@ -201,22 +201,22 @@ tags: [sample1, sample2] keywords: keyword1, keyword2, keyword3 last_updated: Month day, year summary: "optional summary here" -sidebar: sidebar name -permalink: filename +sidebar: sidebarname +permalink: filename.html --- ``` (You will customize the values for each of these properties, of course.) -For titles, surrounding the title in quotes is optional, but if you have a colon in the title, you must surround the title with quotation marks. If you have a quotation mark within the title, escape it first with a backlash `\`. +For titles, surrounding the title in quotes is optional, but if you have a colon in the title, you must surround the title with quotation marks. If you have a quotation mark inside the title, escape it first with a backlash `\`. Values for `keywords` get populated into the metadata of the page for SEO. -Values for `tags` must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.) +Values for `tags` must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll won't auto-create these tag files.) If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: false` in the frontmatter. -The `permalink` value should be the same as your filename but without the file extension. +The `permalink` value should be the same as your filename and include the ".html" file extension. For more detail, see [Pages][mydoc_pages]. @@ -232,7 +232,7 @@ For more information, see [Pages][mydoc_pages] and [Posts][mydoc_posts]. The top navigation bar's menu items are set through the \_data/topnav.yml file. Use the top navigation bar to provide links for navigating from one product to another, or to navigate to external resources. -For external URLs, use `external_url` in the item property, as shown in the example topnav.yml file. For internal links, use `url` as usual. +For external URLs, use `external_url` in the item property, as shown in the example topnav.yml file. For internal links, use `url` the same was you do in the sidebar data files. Note that the topnav has two sections: `topnav` and `topnav_dropdowns`. The topnav section contains single links, while the `topnav_dropdowns` section contains dropdown menus. The two sections are independent of each other. diff --git a/pages/mydoc/mydoc_build_arguments.md b/pages/mydoc/mydoc_build_arguments.md index 8f1736a..6b5593b 100644 --- a/pages/mydoc/mydoc_build_arguments.md +++ b/pages/mydoc/mydoc_build_arguments.md @@ -63,6 +63,6 @@ kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}') I recommend creating a profile in iTerm that stores this command. Here's what the iTerm settings look like: -![iTerm profile settings to kill all Jekyll]({{ "/images/killalljekyll.png" | prepend: site.baseurl }}) +{% include image.html file="killalljekyll.png" caption="iTerm profile settings to kill all Jekyll" %} {% include links.html %} diff --git a/pages/mydoc/mydoc_generating_pdfs.md b/pages/mydoc/mydoc_generating_pdfs.md index 60776ad..c4cbbfb 100644 --- a/pages/mydoc/mydoc_generating_pdfs.md +++ b/pages/mydoc/mydoc_generating_pdfs.md @@ -23,7 +23,7 @@ Also, creating a PDF this way gives you a lot more control and customization cap You can see an example of the finished product here: - + ## 1. Set up Prince @@ -348,7 +348,7 @@ You can add a download button for your PDF using some Bootstrap button code: Here's what that looks like: - + ## JavaScript conflicts diff --git a/pages/mydoc/mydoc_help_api.md b/pages/mydoc/mydoc_help_api.md index 89d4e7d..e8dfcc5 100644 --- a/pages/mydoc/mydoc_help_api.md +++ b/pages/mydoc/mydoc_help_api.md @@ -13,9 +13,9 @@ folder: mydoc You can create a help API that developers can use to pull in content. -For the full code demo, see the notes in the tooltip demo. +For the full code demo, see the notes in the [Tooltips file](tooltips.html). -In this demo, the popovers pull in and display content from the information in a tooltips.json file located in the same directory. +In this demo, the popovers pull in and display content from the information in a tooltips.json file located in the same directory. Instead of placing the JSON source in the same directory, you could also host the JSON file on another site. @@ -25,7 +25,7 @@ Additionally, instead of tooltip popovers, you could also print content directly Here's a diagram showing the basic idea of the help API: - + Is this really an API? Well, sort of. The help content is pushed out into a JSON file that other websites and applications can easily consume. The endpoints don't deliver different data based on parameters added to a URL. But the overall concept is similar to an API: you have a client requesting resources from a server. @@ -136,7 +136,7 @@ This code will loop through all pages in the tooltips collection and insert the } ``` -You can also view the same JSON file here: tooltips.json. +You can also view the same JSON file here: tooltips.json. You can add different fields depending on how you want the JSON to be structured. Here we just have to fields: `id` and `body`. And the JSON is looking just in the tooltips collection that we created. @@ -230,7 +230,7 @@ $.get( url, function( data ) { {% endraw %} ``` -View the tooltip demo for a demo. +View the tooltip demo for a demonstration. The `url` in the demo is relative, but you could equally point it to an absolute path on a remote host assuming CORS is enabled on the host. @@ -268,7 +268,7 @@ Again, see the Tooltip Demo for a dem Note that even though you reference a Bootstrap JS script, Bootstrap's popovers require you to initialize them using the above code as well — they aren't turned on by default. -View the source code of the tooltip demo for the full comments. +View the source code of the tooltip demo for the full comments. ## 8. Create easy links to embed the help in your help site diff --git a/pages/mydoc/mydoc_icons.md b/pages/mydoc/mydoc_icons.md index 18d0fc4..daf76f4 100644 --- a/pages/mydoc/mydoc_icons.md +++ b/pages/mydoc/mydoc_icons.md @@ -220,6 +220,6 @@ You can use any of the following: The only difference is the color of the left bar. -Callouts are explained in a bit more detail in Alerts. +Callouts are explained in a bit more detail in [Alerts][mydoc_alerts]. {% include links.html %} diff --git a/pages/mydoc/mydoc_images.md b/pages/mydoc/mydoc_images.md index b466d64..225d722 100644 --- a/pages/mydoc/mydoc_images.md +++ b/pages/mydoc/mydoc_images.md @@ -92,6 +92,6 @@ Also, if you're working with SVG graphics, note that Firefox does not support SV Also, remove the check box for "Use textpath element for text on a path". And select "Embed" rather than "Link." The following screenshot shows the settings I use. Your graphics will look great in Firefox. -![Essential options for SVG with Illustrator]({{ "/images/illustratoroptions.png" | prepend: site.baseurl }}) +{% include image.html file="illustratoroptions.png" caption="Essential options for SVG with Illustrator" %} {% include links.html %} diff --git a/pages/mydoc/mydoc_introduction.md b/pages/mydoc/mydoc_introduction.md index 85a25a2..a944095 100644 --- a/pages/mydoc/mydoc_introduction.md +++ b/pages/mydoc/mydoc_introduction.md @@ -25,6 +25,6 @@ Some of the more prominent features of this theme include the following: ## Getting started -To get started, see [Getting Started][home]. +To get started, see [Getting Started][index]. {% include links.html %} diff --git a/pages/mydoc/mydoc_iterm_profiles.md b/pages/mydoc/mydoc_iterm_profiles.md index 2784a66..5116d30 100644 --- a/pages/mydoc/mydoc_iterm_profiles.md +++ b/pages/mydoc/mydoc_iterm_profiles.md @@ -31,7 +31,7 @@ When you're working with tech docs, a lot of times you have builds that push fil Here's an example: -![iTerm profile example]({{ "/images/itermexample.png" | prepend: site.baseurl }}) +{% include image.html file="itermexample.png" caption="iTerm profile example" %} ## Launching a profile diff --git a/pages/mydoc/mydoc_kb_layout.md b/pages/mydoc/mydoc_kb_layout.md index 886833e..813e4af 100644 --- a/pages/mydoc/mydoc_kb_layout.md +++ b/pages/mydoc/mydoc_kb_layout.md @@ -27,7 +27,7 @@ Here's the sample knowledge-base style layout:

    Getting started

    Lorem ipsum dolor sit amet, consectetur adipisicing elit.

    - Learn More + Learn More
    @@ -42,7 +42,7 @@ Here's the sample knowledge-base style layout:

    Navigation

    Lorem ipsum dolor sit amet, consectetur adipisicing elit.

    - Learn More + Learn More
    @@ -57,7 +57,7 @@ Here's the sample knowledge-base style layout:

    Single sourcing

    Lorem ipsum dolor sit amet, consectetur adipisicing elit.

    - Learn More + Learn More
    @@ -72,7 +72,7 @@ Here's the sample knowledge-base style layout:

    Formatting

    Lorem ipsum dolor sit amet, consectetur adipisicing elit.

    - Learn More + Learn More
    @@ -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_search_configuration.md b/pages/mydoc/mydoc_search_configuration.md index 51e5f60..5540f92 100644 --- a/pages/mydoc/mydoc_search_configuration.md +++ b/pages/mydoc/mydoc_search_configuration.md @@ -81,7 +81,8 @@ search: exclude {% unless forloop.last %},{% endunless %} {% endfor %} -]{% endraw %} +] +{% endraw %} ``` The \_includes/topnav.html file then makes use of these values: @@ -93,12 +94,12 @@ The \_includes/topnav.html file then makes use of these values:
      - +