made some fixes in the docs and to the relative links with posts and news pages

Author: tomjoht

_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
 

_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
 

_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
 

_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: '<li><a href="{url}" title="{{page.title | replace: "'", "\"}}">{title}</a></li>',
                     noResultsText: '{{site.data.strings.search_no_results_text}}',
                             limit: 10,

_layouts/post.html

@@ -9,7 +9,7 @@ <h1 class="post-title" itemprop="name headline">{{ page.title }}</h1>
             {% assign projectTags = site.data.tags.allowed-tags %}
             {% for tag in page.tags %}
             {% if projectTags contains tag %}
-            <a href="{{ "../tag_" | append: tag }}">{{tag}}</a>{% unless forloop.last %}, {% endunless%}
+            <a href="{{ "../tag_" | append: tag | append: ".html" }}">{{tag}}</a>{% unless forloop.last %}, {% endunless%}
             {% endif %}
             {% endfor %}
             {% endif %}

feed.xml

@@ -8,8 +8,8 @@ layout: none
     <channel>
         <title>{{ site.title | xml_escape }}</title>
         <description>{{ site.description | xml_escape }}</description>
-        <link>{{ site.url }}{{ site.baseurl }}/</link>
-        <atom:link href="{{ "/feed.xml" | prepend: site.baseurl | prepend: site.url }}" rel="self" type="application/rss+xml"/>
+        <link>{{ site.url }}/</link>
+        <atom:link href="{{ "/feed.xml" | prepend: site.url }}" rel="self" type="application/rss+xml"/>
         <pubDate>{{ site.time | date_to_rfc822 }}</pubDate>
         <lastBuildDate>{{ site.time | date_to_rfc822 }}</lastBuildDate>
         <generator>Jekyll v{{ jekyll.version }}</generator>
@@ -18,8 +18,8 @@ layout: none
             <title>{{ post.title | xml_escape }}</title>
             <description>{{ post.content | xml_escape }}</description>
             <pubDate>{{ post.date | date_to_rfc822 }}</pubDate>
-            <link>{{ post.url | prepend: site.baseurl | prepend: site.url }}</link>
-            <guid isPermaLink="true">{{ post.url | prepend: site.baseurl | prepend: site.url }}</guid>
+            <link>{{ post.url | prepend: site.url }}</link>
+            <guid isPermaLink="true">{{ post.url | prepend: site.url }}</guid>
             {% for tag in post.tags %}
             <category>{{ tag | xml_escape }}</category>
             {% endfor %}

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,25 +86,25 @@ 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
+<pre>
 ---
 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
+<span class="red">sidebar: mydoc_sidebar</span>
 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).
 
 If no sidebar assignment is found in the page frontmatter, the default sidebar (specified by the `else` statement) will be shown: `site.data.sidebars.home_sidebar.entries`.
 
 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.
 

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 %}

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:
 
-<a target="_blank" class="noCrossRef" href="{{ "/pdf/mydoc.pdf" | prepend: site.baseurl }}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
+<a target="_blank" class="noCrossRef" href="{{ "pdf/mydoc.pdf"}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
 
 ## 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:
 
-<a target="_blank" class="noCrossRef" href={{ "/pdf/mydoc.pdf" | prepend: site.baseurl}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
+<a target="_blank" class="noCrossRef" href={{ "pdf/mydoc.pdf"}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
 
 ## JavaScript conflicts
 

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 <a target="_blank" href="{{ "/tooltips" | prepend: site.baseurl}}" class="noCrossRef">tooltip demo</a>.
+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 <a target="_blank" href="{{ "/tooltips.json" | prepend: site.baseurl}}">tooltips.json</a> file located in the same directory.
+In this demo, the popovers pull in and display content from the information in a <a target="_blank" href="tooltips.json">tooltips.json</a> 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:
 
-<img src="{{ "/images/helpapi.svg" | prepend: site.baseurl }}" style="width: 650px;"/>
+<img src="images/helpapi.svg" style="width: 650px;"/>
 
 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: <a target="_blank" href="{{ "/tooltips.json" | prepend: site.baseurl}}">tooltips.json</a>.
+You can also view the same JSON file here: <a target="_blank" href="tooltips.json">tooltips.json</a>.
 
 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 ) {
 </script>{% endraw %}
 ```
 
-View the <a target="_blank" href="{{ "/tooltips" | prepend: site.baseurl}}" class="noCrossRef">tooltip demo</a> for a demo.
+View the <a target="_blank" href="tooltips.html" class="noCrossRef">tooltip demo</a> 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 <a class="noCrossRef" href="/tooltips">Tooltip Demo</a> 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 &mdash; they aren't turned on by default.
 
-View the source code of the <a target="_blank" href="{{ "/tooltips" | prepend: site.baseurl}}" class="noCrossRef">tooltip demo</a> for the full comments.
+View the source code of the <a target="_blank" href="tooltips.html" class="noCrossRef">tooltip demo</a> for the full comments.
 
 ## 8. Create easy links to embed the help in your help site