content updates

_includes/custom/doc/links_doc.html

@@ -1,4 +1,4 @@
-{% comment %} leave this end_i capture here, since many rely on it. {% endcomment %}
+{% comment %} leave this end_i capture here, since all links with _i rely on it. {% endcomment %}
 {% capture end_i %}</a>{% endcapture %}
 
 {% capture doc_about %}<a href="about.html">About this theme</a>{% endcapture %}
@@ -122,4 +122,8 @@
 {% capture doc_iterm_profiles_i %}<a href="doc_iterm_profiles.html">{% endcapture %}
 
 {% capture doc_webstorm_text_editor %}<a href="doc_webstorm_text_editor.html">WebStorm Text Editor</a>{% endcapture %}
-{% capture doc_webstorm_text_editor %}<a href="doc_webstorm_text_editor.html">{% endcapture %}
+{% capture doc_webstorm_text_editor_i %}<a href="doc_webstorm_text_editor.html">{% endcapture %}
+
+{% capture doc_seriesdemo1_1 %}<a href="doc_seriesdemo1_1.html">Series demo</a>{% endcapture %}
+{% capture doc_seriesdemo1_1_i %}<a href="doc_seriesdemo1_1.html">{% endcapture %}
+

_layouts/default.html

@@ -10,12 +10,12 @@
       $('[data-toggle="tooltip"]').tooltip()
   })
 </script>
-{% if page.video == true %}
+{% if page.video == true and site.print == false %}
 <link href="https://vjs.zencdn.net/4.12/video-js.css" rel="stylesheet">
 <script src="https://vjs.zencdn.net/4.12/video.js"></script>
 {% endif %}
 
-{% if page.datatable == true %}
+{% if page.datatable == true and site.print == false %}
 <link rel="stylesheet" type="text/css" href="https://cdn.datatables.net/1.10.5/css/jquery.dataTables.css">
 <script type="text/javascript" charset="utf8" src="https://cdn.datatables.net/1.10.5/js/jquery.dataTables.js"></script>
 <script>

css/customstyles.css

@@ -779,10 +779,6 @@ pre {
     margin: 25px 0px;
 }
 
-.video-js {
-    margin: 30px 0px;
-}
-
 p.dataType {display: block; font-color: gray; font-size: 80%;}
 
 dd {margin-left:20px;}

css/lavish-bootstrap.css

@@ -4183,9 +4183,7 @@ textarea.input-group-sm > .input-group-btn > .btn {
 .label:empty {
   display: none;
 }
-.label-default {
-  background-color: #f9faf9;
-}
+
 .label-default[href]:hover,
 .label-default[href]:focus {
   background-color: #dde3dd;

doc_alerts.md

@@ -88,3 +88,7 @@ The following demonstrate the formatting for each callout.
 
 If you want to blast a warning to users on every page, add the alert or callout to the layouts/page.html page right below the frontmatter. Every page using the page layout (all, by defaut) will show this message.
 
+## Using Markdown inside of notes
+
+You can't use Markdown formatting inside notes.
+

doc_build_arguments.md

@@ -22,30 +22,44 @@ To build the site and view it in a live server so that Jekyll rebuilds that site
 jekyll serve
 ```
 
-By default, the _config.yml will be used, Jekyll will scan the current directory for files, and the folder _site will be used as the output. You can customize these build commands.
+By default, the _config.yml in the root directory will be used, Jekyll will scan the current directory for files, and the folder `_site` will be used as the output. You can customize these build commands like this:
 
 ```
-jekyll serve --config configs/config_writer.yml --destination /users/tjohnson/projects/documentation-theme-jekyll-builds/writer
+jekyll serve --config configs/config_writers.yml --destination /users/tjohnson/projects/documentation-theme-jekyll-builds/writer
 ```
 
-Here the configs/config_writer.yml file is used instead of _config.yml. The destination directory is /users/tjohnson/projects/documentation-theme-jekyll-builds/writer.
+Here the `configs/config_writers.yml` file is used instead of `_config.yml`. The destination directory is `../doc_writers`.
 
 ## Shortcuts for the build arguments
 
 If you don't want to enter the long Jekyll argument every time, with all your configuration details, you can create a shell script and then just run the script. This theme shows an example with the doc_multibuild_web.sh file in the root directory.
 
-My preference is to add the scripts to profiles in iTerm. See {{doc_setting_up_iterm_profiles}} for more details.
+My preference is to add the scripts to profiles in iTerm. See {{doc_iterm_profiles}} for more details.
 
 ## Stop a server
 
-When you're doing with the preview server, press `Ctrl+C` to exit out of it. If you exit Terminal without shutting down the server, the next time you build your site, or if you build multiple sites with the same port, you may get a server-already-in-use message.
+When you're done with the preview server, press **Ctrl+C** to exit out of it. If you exit iTerm or Terminal without shutting down the server, the next time you build your site, or if you build multiple sites with the same port, you may get a server-already-in-use message.
 
 You can kill the server process using these commands:
 
-`ps aux | grep jekyll`
+```
+ps aux | grep jekyll
+```
 
 Find the PID (for example, it  looks like "22298").
 
 Then type `kill -9 22298` where "22298" is the PID.
 
+To kill all Jekyll instances, use this:
+
+```
+kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
+```
+
+I created 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)
+
+
+
 

doc_collections.md

@@ -20,14 +20,14 @@ collections:
     output: true
 ```
 
-In this example, tooltips is the name of the collection.
+In this example, "tooltips"" is the name of the collection.
 
 ## Interacting with collections
 
-You can interact with collections by using the `site.collection_namespace` path, where `collection_namespace` is what you've configured. In this case, if I wanted to loop through all tooltips, I would use `site.tooltips` instead of `site.pages` or `site.posts`. 
+You can interact with collections by using the `site.collectionname` namespace, where `collectionname` is what you've configured. In this case, if I wanted to loop through all tooltips, I would use `site.tooltips` instead of `site.pages` or `site.posts`.
 
 See [Collections in the Jekyll documentation](http://jekyllrb.com/docs/collections/) for more information.
 
 ## How to use collections
 
-I haven't found a huge use for collections in normal documentation. However, I did find a use for collections in generating a tooltip file that would be used for delivering tooltips to a user interface from text files in the documentation.
+I haven't found a huge use for collections in normal documentation. However, I did find a use for collections in generating a tooltip file that would be used for delivering tooltips to a user interface from text files in the documentation. See {{doc_help_api}} for details.

doc_conditional_logic.md

@@ -10,7 +10,7 @@ summary:
 
 If you want to create different outputs for different audiences, you can do all of this using a combination of Jekyll's Liquid markup and values in your configuration file.
 
-{{tip}} Definitely check out [Liquid's documentation](http://docs.shopify.com/themes/liquid-documentation/basics) for more details about how to use operators and other liquid markup. The notes here are a small, somewhat superficial sample from the site.{{end}}
+{{tip}} Definitely check out <a href="http://docs.shopify.com/themes/liquid-documentation/basics">Liquid's documentation</a> for more details about how to use operators and other liquid markup. The notes here are a small, somewhat superficial sample from the site.{{end}}
 
 ## Where to store filtering values
 
@@ -28,7 +28,7 @@ This theme requires you to add the following attributes in your configuration fi
 
 If you've ever used DITA, you probably recognize these attributes, since DITA has mostly the same ones. I've found that most single-sourcing projects I work on can be sliced and diced in the ways I need using these conditional attributes.
 
-If you're not single sourcing and you find it annoying having to specify these attributes in your sidebar, you can rip out the logic from the sidebar.html file; then you wouldn't need these attributes in your configuration file.
+If you're not single sourcing and you find it annoying having to specify these attributes in your sidebar, you can rip out the logic from the sidebar.html, topnav.html file and any other places where conditions.html appears; then you wouldn't need these attributes in your configuration file.
 
 ## Conditional logic based on config file value
 
@@ -70,6 +70,8 @@ To bake a casserole:
 ```
 {% endraw %}
 
+You don't need the `elsif` or `else`. You could just use an `if` (but be sure to close it with `endif`).
+
 ## Or operator
 
 You can use more advanced Liquid markup for conditional logic, such as an `or` command. See [Shopify's Liquid documentation](http://docs.shopify.com/themes/liquid-documentation/basics/operators) for more details. 
@@ -84,13 +86,22 @@ For example, here's an example using `or`:
 {% endraw %}
 ```
 
-With conditional statements, you don't need the `elsif` or `else` options. But you do always need the `endif`.
+Note that you have to specify the full condition each time. You can't shorten the above logic to the following:
+
+```
+{% raw %}
+{% if site.audience contains "vegan" or "vegetarian" %}
+    // run this.
+{% endif %}
+{% endraw %}
+```
+
+This won't work.
 
 ## Storing conditions in the \_data folder
 
 Here's an example of using conditional logic based on a value in a data file:
 
-{% comment %}
 ```
 {% raw %}
 {% if site.data.options.output == "alpha" %}
@@ -102,29 +113,37 @@ this shows if neither of the above two if conditions are met.
 {% endif %}
 {% endraw %}
 ```
-{% endcomment %}
 
-To use this, I would need to have a \_data folder called options where the audience property is stored. 
+To use this, I would need to have a \_data folder called options where the `output` property is stored.
 
 I don't really use the \_data folder as much for project options. I store them in the configuration file because I usually want different projects to use different values for the same property. 
 
-For example, maybe a file or function name is called something different for different audiences. I currently single source the same content to both a fraud-prevention audience and an advertising technology audience. The identification technology is largely the same. 
+For example, maybe a file or function name is called something different for different audiences. I currently single source the same content to at least two audiences in different markets.
 
-For the fraud audience, the function name might be called `generate`, but for the ad tech audience, the same function is called `expand`. In my content, I'd just use `{% raw %}{{site.function}}{% endraw %}` in the configuration file and change its value appropriately for the audience.
+For the first audience, the function name might be called `generate`, but for the second audience, the same function might be called called `expand`. In my content, I'd just use `{% raw %}{{site.function}}{% endraw %}`. Then in the configuration file I change its value appropriately for the audience.
 
-## Specifying a data source
+## Specifying the location for \_data
 
-You can also specify a `data_source` for your data location in your configuration file. Then you aren't limited to simply using `\_data` to store your data. 
+You can also specify a `data_source` for your data location in your configuration file. Then you aren't limited to simply using `_data` to store your data files.
 
 For example, suppose you have 2 projects: alpha and beta. You might store all the data files for alpha inside data_alpha, and all the data files for beta inside data_beta.
 
-In your configuration file, specify the data source like this:
+In your alpha configuration file, specify the data source like this:
 
 ```
 data_source: data_alpha
 ```
 
-Then create a folder called data_alpha.
+Then create a folder called \_data_alpha.
+
+For your beta configuratoin file, specify the data source like this:
+
+```
+data_source: data_beta
+```
+
+Then create a folder called \_data_beta.
+
 
 ## Conditional logic based on page namespace
 
@@ -145,7 +164,7 @@ Now you can run logic based on the conditional property in that page's front mat
 
 ```liquid
 {% raw %}
-{% if page.user_plan` == "full" %}
+{% if page.user_plan == "full" %}
 // run this code
 {% endif %}
 {% endraw %}

doc_content_reuse.md

@@ -18,7 +18,7 @@ You can embed content from one file inside another using includes. Put the file
 
 With content in your \_includes folder, you don't add any frontmatter to these pages because they will be included on other pages already containing frontmatter.
 
-Also, when you include a file, all of the file's contents get included. You can't specify that you only want a specific part of the file included. However, you can use parameters with includes. See Jekyll's documentation for more information on that.
+Also, when you include a file, all of the file's contents get included. You can't specify that you only want a specific part of the file included. However, you can use parameters with includes. See []Jekyll's documentation](http://stackoverflow.com/questions/21976330/passing-parameters-to-inclusion-in-liquid-templates) for more information on that.
 
 ## Page-level variables
 

doc_generating_pdfs.md

@@ -9,7 +9,7 @@ summary:
 {% include linkrefs.html %} 
 
 ## Overview 
-This process for creating a PDF relies on Prince to transform the HTML content into PDF. Prince costs about $500 per license. That might seem like a lot, but if you're creating a PDF, you're probably working for a company that sells a product, so you likely have access to some resources.
+This process for creating a PDF relies on Prince XML to transform the HTML content into PDF. Prince costs about $500 per license. That might seem like a lot, but if you're creating a PDF, you're probably working for a company that sells a product, so you likely have access to some resources.
 
 The basic approach is to generate a list of all pages that need to be added to the PDF, and then add leverage Prince to package them up into a PDF.
 
@@ -31,7 +31,7 @@ You can see an example of the finished product here:
 
 ## 1. Set up Prince
 
-Download and install [Prince](http://www.princexml.com/).
+Download and install [Prince](http://www.princexml.com/doc/installing/).
 
 You can install a fully functional trial version. The only difference is that the title page will have a small Prince PDF watermark.
 
@@ -40,12 +40,12 @@ You can install a fully functional trial version. The only difference is that th
 The PDF configuration file will build on the settings in the regular configuration file but will some additional fields. Here's the configuration file for the config_designers.yml file for this theme:
 
 ```
-destination: /Applications/XAMPP/xamppfiles/htdocs/jekyll-documentation-theme/designers
+destination: ../doc_designers-pdf
 url: "http://127.0.0.1:4002"
-baseurl: "/designers/"
+baseurl: "/doc_designers"
 port: 4002
 print: true
-print_title: Jekyll Documentation Theme for Writers
+print_title: Jekyll Documentation Theme for Designers
 print_subtitle: version 3.0
 defaults:
   -
@@ -58,9 +58,9 @@ defaults:
       search: true
 ```
 
-{{note}} Although you're creating a PDF, you must still build a web target before running Prince. Prince will pull from the HTML files and from the file-list for the TOC. Prince won't be able to find files if they simply have relative paths, such as /sample.html. The must have full URLs it can access — hence the url and baseurl. {{end}}
+{{note}} Although you're creating a PDF, you must still build a web target before running Prince. Prince will pull from the HTML files and from the file-list for the TOC. Prince won't be able to find files if they simply have relative paths, such as /sample.html. The must have full URLs it can access &mdash; hence the <code>url</code> and <code>baseurl</code>. {{end}}
 
-Unlike the other configuration files, the PDF configuration files require a url and baseurl. This is because the Prince utility needs to access the pages in a specific place. While you could probably set up locations via file folders, it's easier just to provide the locations here as url and baseurl.
+Unlike the other configuration files, the PDF configuration files require a `url` and `baseurl`. This is because the Prince utility needs to access the pages in a specific place. While you could probably set up locations via absolute paths to file folders, it's easier just to provide the locations here as `url` and `baseurl`.
 
 Also note that the default page layout is `page_print`. This layout strips out all the sections that shouldn't appear in the print PDF, such as the sidebar and top navigation bar.
 
@@ -70,7 +70,7 @@ In the configuration file, customize the values for the `print_title` and `print
      
 ## 3. Make sure your sidebar_doc.yml file has a titlepage.html and tocpage.html
 
-There are two template pages in the root directory that are critical to PDFs:
+There are two template pages in the root directory that are critical to the PDF:
 
 * titlepage.html
 * tocpage.html
@@ -105,16 +105,17 @@ entries:
            web: false
 ```
 
-Leave these pages here in your sidebar. (The `web: false` property means they won't appear in your online TOC because the conditional logic of the sidebar.html checks whether `web` is equal to `false` or not.)
+Leave these pages here in your sidebar. (The `web: false` property means they won't appear in your online TOC because the conditional logic of the sidebar.html checks whether `web` is equal to `false` or not before including the item in the web version of the content.)
 
-The code in the tocpage.html is nearly identical to that of the sidebar.html page except that it includes the baseurl for the URLs. This is essential for Prince to create the page numbers correctly with cross references.
+The code in the tocpage.html is nearly identical to that of the sidebar.html page except that it includes the `site` and `baseurl` for the URLs. This is essential for Prince to create the page numbers correctly with cross references.
 
-There's another file (in the root directory of the theme) that is critical to the PDF generation process: prince-file-list.txt. This file simply iterates through the items in your sidebar and creates a list of links. Prince will consume the list of links from this file and create a running PDF that contains all of the pages listed, with appropriate cross references and styling for them all.
+There's another file (in the root directory of the theme) that is critical to the PDF generation process: prince-file-list.txt. This file simply iterates through the items in your sidebar and creates a list of links. Prince will consume the list of links from prince-file-list.txt and create a running PDF that contains all of the pages listed, with appropriate cross references and styling for them all.
 
 ## 4. Customize your headers and footers
 
 Open up the css/printstyles.css file and customize what you want for the headers and footers. At the very least, customize the email address that appears in the bottom left.
-{% if site.audience == "designers" %}e
+
+{% if site.audience == "designers" %}
 Exactly how the print styling works here is pretty cool. You don't need to understand the rest of the content in this section unless you want to customize your PDFs to look different from what I've configured. 
 
 This style creates a page reference for a link:
@@ -145,7 +146,7 @@ a[href^="http:"]::after, a[href^="https:"]::after {
 
 This style sets your page margins:
 
-```
+```css
 @page {
     margin: 60pt 90pt 60pt 90pt;
     font-family: sans-serif;
@@ -183,13 +184,15 @@ type: first_page
 
 The default_print.html layout will change the class of the `body` element based on the type value in the page's frontmatter:
 
-```
+```liquid
+{% raw %}
 <body class="{% if page.type == "title"%}title{% elsif page.type == "frontmatter" %}frontmatter{% elsif page.type == "first_page" %}first_page{% endif %} print">
+{% endraw %}
 ```
 
 Now in the css/printstyles.css file, you can assign a page name based on a specific class:
 
-```
+```css
 body.title { page: title }
 ```
 
@@ -271,7 +274,7 @@ h1 { string-set: doctitle content() }
 
 You'll see some other items in there such as `prince-script`. This means we're using JavaScript to run some functions to dynamically generate that content. These JavaScript functions are located in the \_includes/head_print.html:
 
-```
+```js
 <script>
     Prince.addScriptFunc("datestamp", function() {
         return "PDF last generated: {{ site.time | date: '%B %d, %Y' }}";
@@ -321,43 +324,59 @@ echo "Serving Designers PDF"
 jekyll serve --detach --config configs/config_designers.yml,configs/config_designers_pdf.yml
 ```
 
-Note that the first part kills all Jekyll instances. This way you won't try to server Jekyll at a port that is already occupied. 
+Note that the first part kills all Jekyll instances. This way you won't try to server Jekyll at a port that is already occupied.
+
+The `jekyll serve` command serves up the PDF configurations for our two projects. This web version is where Prince will go to get its content.
 
 ## 6. Configure the Prince scripts
 
 Open up doc_multibuild_pdf.sh and look at the Prince commands:
 
 ```
-echo "Building the Writers PDF..."
-prince --javascript --input-list=/Applications/XAMPP/xamppfiles/htdocs/documentation-theme-jekyll/writers-pdf/prince-file-list.txt -o /Users/tjohnson/projects/documentation-theme-jekyll/files/doc/documentation_theme_jekyll_writers_pdf.pdf;
+prince --javascript --input-list=../doc_designers-pdf/prince-file-list.txt -o /Users/tjohnson/projects/documentation-theme-jekyll/doc_designers_pdf.pdf;
 ```
 
-This script issues a command to the Prince utility. JavaScript is enabled (`--javascript`), and we tell it exactly where to find the list of files (`--input-list`) &mdash; just point to the prince-file-list.txt file. Then we tell it what to output and where (`-o`).
-
-Make sure that the path to the prince-file-list.txt is correct. For the output directory, I like to output the PDF file into my project's source. Then when I build the web output, the PDF is included. 
+This script issues a command to the Prince utility. JavaScript is enabled (`--javascript`), and we tell it exactly where to find the list of files (`--input-list`) &mdash; just point to the prince-file-list.txt file. Then we tell it where and what to output (`-o`).
 
+Make sure that the path to the prince-file-list.txt is correct. For the output directory, I like to output the PDF file into my project's source. Then when I build the web output, the PDF is included and something I can refer to.
 
 ## 7. Add a download button for the PDF
 
-You can add a download button using some Bootstrap button code:
+You can add a download button for your PDF using some Bootstrap button code:
 
 ```html
 <a target="_blank" class="noCrossRef" href="doc_designers_pdf.pdf"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> Designers PDF Download</button></a>
 ```
 
+Here's what that looks like:
+
+{% if site.audience == "designers" %}
+<a target="_blank" class="noCrossRef" href="doc_designers_pdf.pdf"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> Designers PDF Download</button></a>
+{% endif %}
+
+{% if site.audience == "writers" %}
+<a target="_blank" class="noCrossRef" href="doc_writers_pdf.pdf"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> Writers PDF Download</button></a>
+{% endif %}
+
 ## 8. Run the scripts
 
 To generate the PDF, you just run several scripts that have the commands packaged up:
 
 1. First run doc_multiserve_pdf.sh to serve up the PDF sites. The commands will detach the site from the preview server so that you can serve up multiple Jekyll sites in the same command terminal.
 2. Then run doc_multibuild_pdf.sh to build the PDF files. 
-3. There are commands to kill all Jekyll preview servers before this runs. 
+3. Now run doc_multibuild_web.sh to build the web version that includes the generated PDF files.
 
 {{note}} If you don't like the style of the PDFs, just adjust the styles in the printstyles.css file.{{end}}
 
 ## JavaScript conflicts
 
-I've noticed that when I have JavaScript in my pages, sometimes Prince doesn't like this, as it tries to process the JavaScript. It's better to conditionalize out any JavaScript from your PDF output before building your PDFs. If Prince encounters JavaScript on a page, it will give you this error:
+I've noticed that when I have JavaScript in my pages, sometimes Prince doesn't like this, as it tries to process the JavaScript. As a result, it will create an error like this in Terminal:
+
+```
+error: TypeError: value is not an object
+```
+
+It's better to conditionalize out any JavaScript from your PDF output before building your PDFs. If Prince encounters JavaScript on a page, it will give you this error:
 
 ```
 prince: http://127.0.0.1:4002/designers/doc_shuffle.html:2: error: TypeError: value is not an object
@@ -365,3 +384,11 @@ prince: http://127.0.0.1:4002/designers/doc_shuffle.html:2: error: TypeError: va
 
 However, the PDF will still build.
 
+If you encounter this error, surround the JavaScript with conditional tags like this:
+
+```
+{% raw %}
+{% unless site.print == false %}  javascript content here ... {% endunless %}
+{% endraw %}
+```
+

doc_icons.md

@@ -8,11 +8,11 @@ summary:
 ---
 {% include linkrefs.html %} 
 
-The theme has two font icon sets integrated: Font Awesome and Glyphicons Halflings. The latter is part of Bootstrap, while the former is independent. 
+The theme has two font icon sets integrated: Font Awesome and Glyphicons Halflings. The latter is part of Bootstrap, while the former is independent. Font icons allow you to insert icons drawn as vectors from a CDN (so you don't have any local images on your own site).
 
 ## See Font Awesome icons available
 
-Go to the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/)
+Go to the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/) to see the available icons.
 
 The Font Awesome icons allow you to adjust their size by simply adding `fa-2x`, `fa-3x` and so forth as a class to the icon to adjust their size to two times or three times the original size. As vector icons, they scale crisply at any size.
 
@@ -46,7 +46,7 @@ Here's the result:
 
 <div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle fa-lg"></i> This is a special warning message.</div>
 
-Some of the Bootstrap styles are pre-coded with Font Awesome and stored in the linkrefs.html file in `capture` tags. That file includes the following:
+The notes, tips, warnings, etc., are pre-coded with Font Awesome and stored in the linkrefs.html file in `capture` tags. That file includes the following:
 
 {% raw %}
 ```html
@@ -76,17 +76,19 @@ Here's the result:
 
 {{warning}} If you overlook this, you may die. {{end}}
 
+The color scheme is the default colors from Bootstrap. You can modify the icons or colors as needed.
+
 ## Creating your own combinations
 
-You can innovate with your own combinations. Here's a similar approach with a check square:
+You can innovate with your own combinations. Here's a similar approach with a file download icon:
 
 ```html
-<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o fa-lg"></i> This is a special success message.</div>
+<div class="alert alert-success" role="alert"><i class="fa fa-download fa-lg"></i> This is a special tip about some file to download....</div>
 ```
 
 And the result:
 
-<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o fa-lg"></i> This is a special success message.</div>
+<div class="alert alert-success" role="alert"><i class="fa fa-download fa-lg"></i> This is a special tip about some file to download....</div>
 
 
 Grab the right class name from the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/) and then implement it by following the pattern shown previously.
@@ -185,4 +187,5 @@ You can use any of the following:
 ```
 {% endraw %}
 
+Callouts are explained in a bit more detail here: {{doc_alerts}}.
 

doc_images.md

@@ -10,7 +10,6 @@ summary:
 
 You embed an image the same way you embed other files or assets: you put the file into a folder, and then link to that file. 
 
-## Images
 Put images inside the `images` folder in your root directory. You can create subdirectories inside this directory. Although you could use Markdown syntax for images, the HTML syntax is probably easier:
 
 {% raw %}
@@ -19,13 +18,24 @@ Put images inside the `images` folder in your root directory. You can create sub
 ```
 {% endraw %}
 
-Here's a sample:
+And the result:
 
 <img title="my sample image" src="images/jekyll.png">
 
+Here's the same Markdown syntax:
+
+```
+![My sample page](images/jekyll.png)
+```
+
+And the result:
+
+![My sample page](images/jekyll.png)
+
+
 ## SVG Images
 
-You can also embed SVG graphics. Here's a sample embed:
+You can also embed SVG graphics. If you use SVG, you need to use the HTML syntax so that you can define a width/container for the graphic. Here's a sample embed:
 
 ```html
 <img src="images/helpapi.svg" style="width: 650px;"/>

doc_iterm_profiles.md

@@ -17,11 +17,11 @@ When you're working with tech docs, a lot of times you're single sourcing multip
 3. Click the + button in the lower-left corner to create a new profile.
 4. In the **Name** field, type a name describing the output, such as `Doc theme -- designers`.
 5. In the **Send text at start** field, type the command for the build script, such as this:
-	
-	```
-	jekyll serve --config configs/config_designers.yml
-	```
-	 Leave the Login shell option selected.
+
+    ```
+    jekyll serve --config configs/config_designers.yml
+    ```
+    Leave the Login shell option selected.
 	
 6. In the Working Directory section, select **Directory** and enter the directory for your project, such as **/Users/tjohnson/projects/documentation-theme-jekyll**.
 7. Close the profiles panel. 

doc_links.md

@@ -21,7 +21,7 @@ When linking to an external site, use Markdown formatting:
 
 If you need to use HTML, use the normal syntax:
 
-```
+```html
 <a href="http://google.com">Google</a>
 ```
 
@@ -35,17 +35,19 @@ When linking to internal pages, you could use this same syntax:
 
 OR
 
-```
+```html
 <a href="sample.html">Sample</a>
 ```
 
-However, what happens when you change the page's title or link? In my experience, coding links like this results in a lot of broken links.
+However, what happens when you change the page's title or link? Jekyll doesn't automatically pull in the page's title when you create links.
+
+In my experience, coding links like this results in a lot of broken links.
 
 ## Managed links
 
-For internal links, it's a best practice to store the link in an internal file so that you can easily update all references to the link. 
+For internal links, I've found that it's a best practice to store the link in an internal file so that I can easily update all references to the link.
 
-In this theme, the includes folder contains a links_doc.html file where the capture tags are stored:
+In this theme, the \_includes folder contains a links_doc.html file where the capture tags are stored. For each link, I create the follow pair of capture tags:
 
 ```html
 {%raw%}
@@ -54,26 +56,30 @@ In this theme, the includes folder contains a links_doc.html file where the capt
 {% endraw %}
 ```
 
-The linksref.html file includes the links_doc.html, so when you add `{% raw %}{% include linkrefs.html %}{% endraw %}` at the top of a page, it includes all of the link variables. 
+The linksref.html file includes the links_doc.html, so when you add `{% raw %}{% include linkrefs.html %}{% endraw %}` at the top of a page, it includes all of the link variables captured here.
 
 To insert a link to sample, do this:
 
-```
+```liquid
+{% raw %}
 {{sample}}
+{% endraw %}
 ```
 
 If you want to insert the link with custom anchor text, use this: 
 
-```
+```liquid
+{% raw %}
 See the {{sample_i}}sample page here{{end_i}}.
+{% endraw %}
 ```
 
-Sometimes you want to refer to the page's full title while other times you want to link running text within your sentence.
-
-Make sure that the links_doc.html file also includes this at least once:
+Make sure that the links_doc.html file also includes this capture at least once:
 
 ```
+{% raw %}
 {% capture end_i %}</a>{% endcapture %}
+{% endraw %}
 ```
 
 Otherwise, your link won't close.
@@ -86,13 +92,17 @@ Author all pages in your root directory. This greatly simplifies linking. Howeve
 
 For example, to link to a file stored in files/doc/myguide.pdf, you would use "files/doc/myguide.pdf" as the link. 
 
-Why not put pages into subfolders? If you put a page into a subfolder, then links to the stylesheets, JavaScript, and other sources will fail. On those sub-folder pages, you'd need to use ../ to move up a level in the directory. But if you have some pages in some folders, others in sub-sub-folders, and others in the root, then trying to guess which files should contain ../ and which shouldn't will be a nightmare.
+Why not put pages into subfolders? If you put a page into a subfolder, then links to the stylesheets, JavaScript, and other sources will fail. On those sub-folder pages, you'd need to use `../` to move up a level in the directory. But if you have some pages in some folders, others in sub-sub-folders, and others in the root, trying to guess which files should contain `../` or `../../` or nothing at all and which shouldn't will be a nightmare.
 
-Jekyll gets around some of this by using baseurl and including code that prepends the baseurl before a link. This converts the links into absolute rather than relative links. With absolute links, the site only displays at the baseurl you configured. This is problematic for tech docs because you usually need to move files around from one folder to another based on versions you're archiving or how you're publishing your documentation from draft to testing to production folders.
+Jekyll gets around some of this link path variation by using `baseurl` and including code that prepends the `baseurl` before a link. This converts the links into absolute rather than relative links.
+
+With absolute links, the site only displays at the `baseurl` you configured. This is problematic for tech docs because you usually need to move files around from one folder to another based on versions you're archiving or when you're moving your documentation from draft to testing to production folders.
 
 ## Limitations with links
 
 One of the shortcomings in this theme is that your links_doc.html file and your sidebar.yml file aren't generated from the same source. If you change a link title, you have to change it in both of these locations. 
 
-Another limitation is that a link to the page never gets the title of the page automatically. 
+Another limitation is that a link to the page never gets the title of the page automatically.
+
+If you have solutions for either of these issues, please let me know.
 

doc_navtabs.md

@@ -84,6 +84,7 @@ You must use HTML within the navtab content because each navtab section is surro
 
 Each tab's `href` attribute must match the `id` attribute of the tab content's `div` section. So if your tab has `href="#acme"`, then you add `acme` as the ID attribute in `<div role="tabpanel" class="tab-pane" id="acme">`.
 
+## Set an active tab
 One of the tabs needs to be set as active, depending on what tab you want to be open by default (usually the first one).
 
 ```html

doc_pages.md

@@ -13,7 +13,7 @@ Use a text editor such as Sublime Text, WebStorm, IntelliJ, or Atom to create pa
 
 My preference is IntelliJ/WebStorm, since it will treat all files in your project as belonging to a project. This allows you to easily search for instances of keywords, do find-and-replace operations, or do other actions that apply across the whole project.
 
-## Page names
+## Page names and excluding files from outputs
 
 By default, everything in your project is included in the output. This is problematic when you're single sourcing and need to exclude some files from an output. 
 
@@ -26,7 +26,7 @@ exclude:
 - doc_*
 - doc_writers_*
 
-These wildcards will exclude every match after the *.
+These wildcards will exclude every match after the `*`.
 
 ## Frontmatter
 Make sure each page has frontmatter at the top like this:
@@ -36,7 +36,7 @@ Make sure each page has frontmatter at the top like this:
 ---
 title: Your page title
 tags: [deployment]
-keywords: overview, deployment summary, high-level
+keywords: overview, going live, high-level
 summary: "Deploying DeviceInsight requires the following steps."
 {% endraw %}
 ---
@@ -49,19 +49,19 @@ The following table describes each of the frontmatter that you can use with this
 | Frontmatter | Required? | Description |
 |-------------|-------------|-------------|
 | **title** | Required | The title for the page |
-| **tags** | Optional | Tags for the page. Make all tags single words, with hyphens if needed. Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to \_data/tags.yml to be allowed entrance into the page.   |
+| **tags** | Optional | Tags for the page. Make all tags single words, with hyphens 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.   |
 | **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.|
-| **summary** | Recommended | 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.)  |
-| **datatable** | Optional | Boolean. If you add `true`, then scripts for the [jQuery datatables plugin](https://www.datatables.net/) appear for the page. |
-| **video** | Optional | If you add `true`, then scripts for [Video JS: The HTML5 video player](http://www.videojs.com/) appear on the page. |
+| **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.)  |
+| **datatable** | Optional | Boolean. If you add `true`, then scripts for the [jQuery datatables plugin](https://www.datatables.net/) get included on the page. |
+| **video** | Optional | If you add `true`, then scripts for [Video JS: The HTML5 video player](http://www.videojs.com/) get included on the page. |
 
-{{tip}} You can see the scripts that conditionally appear by looking in the \_layouts/default.html page. Note that these scripts are served via a CDN, so the user must be online for the scripts to work. However, if the user isn't online, the tables and video still appear — they degrade gracefully. {{end}}
+{{tip}} You can see the scripts that conditionally appear by looking in the _layouts/default.html page. Note that these scripts are served via a CDN, so the user must be online for the scripts to work. However, if the user isn't online, the tables and video still appear. In other words, they degrade gracefully. {{end}}
 
 ## What about permalinks? 
-What about permalinks? This theme isn't build using permalinks because it makes linking problematic. Permalinks generate an index file inside a folder for each file in the output. This makes it so links (to other pages as well as to resources such as styles and scripts) need to include `../` depending upon where the other assets are located. 
+What about permalinks? This theme isn't build using permalinks because it makes linking and directory structures problematic. Permalinks generate an index file inside a folder for each file in the output. This makes it so links (to other pages as well as to resources such as styles and scripts) need to include `../` depending upon where the other assets are located. But for any pages outside folders, such as the index.html page, you wouldn't use the `../` structure.
 
-Basically, permalinks complicate the linking structure significantly, so they aren't used here. As a result, page URLs have a .html extension. If you include `permalink: something` in your frontmatter, your link to the page will break (actually, you could still go to sample instead of sample.html, but none of the styles or scripts will be correctly referenced).
+Basically, permalinks complicate the linking structure significantly, so they aren't used here. As a result, page URLs have an .html extension. If you include `permalink: something` in your frontmatter, your link to the page will break (actually, you could still go to sample instead of sample.html, but none of the styles or scripts will be correctly referenced).
 
 ## Colons in page titles 
 
@@ -69,7 +69,7 @@ If you want to use a colon in your page title, you must enclose the title's valu
 
 ## Saving pages as drafts
 
-If you add `published: false` in the frontmatter, then your page won't be published. You can also move draft pages into the _drafts folder to exclude them from the build.
+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.
 
 {{tip}} You can create file templates in WebStorm that have all your common frontmatter, such as all possible tags, prepopulated. See {{doc_webstorm_text_editor}} for details. {{end}}
 
@@ -77,7 +77,7 @@ If you add `published: false` in the frontmatter, then your page won't be publis
 
 Pages can be either Markdown or HTML format (specified through either an .md or .html file extension).
  
-If you use Markdown, you can also include HTML formatting where needed. But not vice versa -- if you use HTML (as your file extension), you can't insert Markdown content. 
+If you use Markdown, you can also include HTML formatting where needed. But not vice versa — if you use HTML (as your file extension), you can't insert Markdown content.
 
 Also, if you use HTML inside a Markdown file, you cannot use Markdown inside of HTML. But you can use HTML inside of Markdown.
 
@@ -87,6 +87,8 @@ For your Markdown files, note that a space or two indent will set text off as co
 
 Store all your pages inside the root directory. This is because the site is built with relative links. There aren't any permalinks or baseurls used in the link architecture. This relative link nature of the site allows you to easily move it from one folder to another without invalidating the links.
 
+If this approach creates too many files in one long list, consider grouping files into Favorites sections using WebStorms Add to Favorites feature.
+
 ## Github-flavored Markdown
 
 You can use standard Multimarkdown syntax for tables. You can also use fenced code blocks. The configuration file shows the Markdown processor and extensiosn:
@@ -116,11 +118,13 @@ By default, a mini-TOC appears at the top of your pages and posts. If you don't
 
 If you don't want the TOC to appear for a specific page, add `toc: false` in the frontmatter of the page.
 
-This mini-TOC requires you to use the `##` syntax for headings. If you use `<h2>` elements, then you must add an ID attribute for the h2 element in order to get it to appear in the mini-TOC.
+The mini-TOC requires you to use the `##` syntax for headings. If you use `<h2>` elements, then you must add an ID attribute for the h2 element in order for it to appear in the mini-TOC.
 
 ## Specify a particular page layout
 
-The configuration file sets the default layout for pages as the page layout. You can create other layouts inside the layouts folder. You can then specify that the page use that particular layout by adding `layout: mylayout.html` in the page's frontmatter. Whatever layout you specify in the frontmatter of a page will override the layout default set in the configuration file.
+The configuration file sets the default layout for pages as the "page" layout.
+
+You can create other layouts inside the layouts folder. If you create a new layout, you can specify that your page use your new layout by adding `layout: mylayout.html` in the page's frontmatter. Whatever layout you specify in the frontmatter of a page will override the layout default set in the configuration file.
 
 ## Comments
 
@@ -131,6 +135,10 @@ Disqus, a commenting system, is integrated into the theme. In the configuration
 This theme isn't coded with any kind of posts logic. For example, if you wanted to add a blog to your project that leverages posts, you couldn't do this with the theme. However, you could easily take the post logic from another site and integrate it into this theme. I've just never had a strong need to integrate blog posts into documentation.
 
 ## Custom keyboard shortcuts
-Some of the Jekyll syntax can be slow to create. Using a utility such as [aText](https://www.trankynam.com/atext/) can make creating content a lot of faster. You get aText from the App Store on a Mac for about $5.
+Some of the Jekyll syntax can be slow to create. Using a utility such as [aText](https://www.trankynam.com/atext/) can make creating content a lot of faster.
 
-There are alternatives to aText, such as Typeitforme. But aText seems to work the best. Read more about it on [Lifehacker](http://lifehacker.com/5843903/the-best-text-expansion-app-for-mac).
+For example, when I type `jif`, aText replaces it with `{% raw %}{% if site.platform == "x" %}{% endraw %}`. When I type `jendif`, aText replaces it with `{% raw %}{% endif %}{% endraw %}`.
+
+You get aText from the App Store on a Mac for about $5.
+
+There are alternatives to aText, such as Typeitforme. But aText seems to work the best. You can read more about it on [Lifehacker](http://lifehacker.com/5843903/the-best-text-expansion-app-for-mac).

doc_scroll.html

@@ -7,7 +7,7 @@ tags: special-layouts
 {% include linkrefs.html %}
 
 <p>This page demonstrates how you the integration of a script called ScrollTo, which is used here to link definitions of a JSON code sample to a list of definitions for that particular term. The scenario here is that the JSON blocks are really long, with extensive nesting and subnesting, which makes it difficult for tables below the JSON to adequately explain the term in a usable way.</p>
-
+{% unless site.print == false %}
  <script src="{{ "/js/jquery.scrollTo.min.js" | prepend:site.baseurl }}"></script> 
     <!-- local scroll must come after scrollTo, because localScroll is based on scrollTo, which is based on jQuery -->
 <script src="{{ "/js/jquery.localScroll.min.js" | prepend:site.baseurl }}"></script>
@@ -32,6 +32,7 @@ $('#small-box-links').localScroll({
 
 });
 </script>
+{% endunless %}
 
 <!-- documentation for localScroll function: http://flesler.blogspot.com/2007/10/jquerylocalscroll-10.html -->
     <style type="text/css">

doc_series.md

@@ -67,7 +67,7 @@ Change "acme" to the name of your series.
 
 Save this in your \_includes folder as series\_acme\_next.html. 
 
-## 3. Add the right frontmatter to each of your series pages
+## 3. Add the correct frontmatter to each of your series pages
 
 Now add the following frontmatter to each page in the series:
 
@@ -78,7 +78,7 @@ weight: 1.0
 
 With weight, you could use 1, 2, 3, etc.., but Jekyll will treat 10 as coming after 1. This is why I use 1.0 and 1.1, 1.2, etc. 
 
-If you do use whole numbers, change the `plus: "0.1"` to `plus: "1". 
+If you do use whole numbers, change the `plus: "0.1"` to `plus: "1"`.
 
 ## 4. Add links to the series button and next button on each page.
 
@@ -86,6 +86,8 @@ On each series page, add a link to the series button at the top and a link to th
  
 ```html
 {% raw %}
+<!-- your frontmatter goes here -->
+
 {% include custom/doc/series_acme.html %}
 
 <!-- your page content goes here ... -->
@@ -96,4 +98,4 @@ On each series page, add a link to the series button at the top and a link to th
 
 ## Changing the series drop-down color
 
-The Bootstrap menu uses the `primary` class for styling. If you change this class in your theme, the Bootstrap menu should automatically change color as well.
+The Bootstrap menu uses the `primary` class for styling. If you change this class in your theme, the Bootstrap menu should automatically change color as well. You can also just use another Bootstrap class in your button code. Instead of `btn-primary`, use `btn-info` or `btn-warning`. See {{doc_labels}} for more Bootstrap button classes.

doc_shuffle.html

@@ -6,9 +6,10 @@ keywords:
 summary:
 ---
 {% include linkrefs.html %}
-
+{% unless site.print == false %}
 <script src="js/jquery.shuffle.min.js"></script>
 <script src="js/jquery.ba-throttle-debounce.min.js"></script>
+{% endunless %}
 
       <div class="filter-options">
       <button class="btn btn-primary" data-group="all">All</button>

doc_sidebar_navigation.md

@@ -10,11 +10,11 @@ summary: "The sidebar and top navigation bar read their values from yml files. T
 
 ## Sidebar overview
 
-To configure the sidebar, edit the values in the \_data/sidebar_doc.yml file. Follow the example here in this theme. Note that YML spacing is picky. Each new level is two spaces indented. I usually just keep a template that shows all three levels and then copy and paste from it as needed. 
+To configure the sidebar, edit the values in the \_data/sidebar_doc.yml file. Follow the example  in this theme. Note that YML spacing is picky. Each new level is two spaces indented. I usually just keep a template that shows all three levels and then copy and paste from it as needed.
 
 ## Sidebar levels
 
-You can add two levels of nesting in the sidebar nav. For example: 
+You can add three levels of nesting in the sidebar nav. For example, three levels looks like this:
 
 ```
 Introduction
@@ -25,11 +25,13 @@ Introduction
 	-> Automation
 ```
 
-You can't add more than two levels. In general, it's a best practice not to create more than two levels of navigation anyway. If you need deeper sublevels, I recommend creating different sidebars for different pages, which is logic that I haven't coded into the theme but which could probably be added fairly easily.
+You can't add more than three levels. In general, it's a best practice not to create more than three levels of navigation anyway, since it creates a paralysis of choice for the user.
+
+If you need deeper sublevels, I recommend creating different sidebars for different pages, which is logic that I haven't coded into the theme but which could probably be added fairly easily.
 
 ## External links
 
-If you want the URL to point to an external site, use `external_url` instead of `url` in the data file. Then just enter the full HTTP URL. The sidebar.html will apply this logic:
+If you want the URL to point to an external site, use `external_url` instead of `url` in the data file. Then just enter the full HTTP URL. When you use `external_url`, the sidebar.html will apply this logic:
 
 ```html
 {% raw %}
@@ -38,12 +40,13 @@ If you want the URL to point to an external site, use `external_url` instead of
 {% endraw %}
 ```             
 
+{% if site.audience == "designers" %}
 ## How it works
 The values in the sidebar_doc.yml file are coded to match the logic in includes/sidebar.html. 
 
 Each of the items in the sidebar needs to have the attributes shown here:
 
-```
+```yaml
 - title: Getting started
   url: /doc_getting_started.html
   audience: writers, designers
@@ -54,7 +57,7 @@ Each of the items in the sidebar needs to have the attributes shown here:
 
 The audience, platform, product, and version are specified in the includes/custom/conditions.html file:
 
-```
+```liquid
 {% raw %}
 {% if site.project == "doc" %}
 {% assign audience = "designers" %}
@@ -75,18 +78,19 @@ Additionally, note how some assignments are set here as well. The conditions.htm
 
 When the sidebar.html file runs the logic, it includes these statements: 
 
-```
+```liquid
 {% raw %}
 {% include custom/conditions.html %}
 
 {% for entry in sidebar %}
+...
 {% endraw %}
 ```
 
-The assignment of the `sidebar` value means this is really what's happening: 
+The assignment of the `sidebar` value through the conditions.html file means this is really what's happening:
 
 
-```
+```liquid
 {% raw %}
 {% include custom/conditions.html %}
 
@@ -122,15 +126,17 @@ $( document ).ready(function() {
 });
 ```
 
-The script says, if the height of the viewport is greater than 800px, then insert `affix` class, which makes the nav bar fixed as your scroll. If you have a lot of nav items, this fixed position may not work for you. For example, if your sidebar has a lot of items and the fixed position makes it so the user can't see all the items when expanded, you may want to adjust the height. If viewing the sidebar is ap roblem, increase the height value from `800` to `1000` or more.       
+The script says, if the height of the viewport is greater than 800px, then insert `affix` class, which makes the nav bar fixed as your scroll. If you have a lot of nav items, this fixed position may not work for you.
+
+For example, if your sidebar has a lot of items and the fixed position makes it so the user can't see all the items when expanded, you may want to adjust the height. If viewing the sidebar is ap roblem, increase the height value from `800` to `1000` or more.
 
 ## Navgoco foundation
 
 The sidebar uses the [Navgoco jQuery plugin](https://github.com/tefra/navgoco) as its basis. Why not use Bootstrap? Navgoco provides a few features that I couldn't find in Bootstrap:
 
 * Navgoco sets a cookie to remember the user's position in the sidebar. If you refresh the page, the cookie allows the plugin to remember the state.
-* Navgoco also inserts an `active` class based on the navigation option that's open. This is essential for keeping the accordion open. 
-* Navgoco also includes the expand and collapse features of a sidebar. 
+* Navgoco inserts an `active` class based on the navigation option that's open. This is essential for keeping the accordion open.
+* Navgoco includes the expand and collapse features of a sidebar.
 
 In short, the sidebar has some complex logic here. I've integrated Navgoco's features with the sidebar.html and sidebar_doc.yml to build the sidebar. It's probably the most impressive part of this theme. (Other themes usually aren't focused on creating hierarchies of pages, but this kind of hierarchy is important in a documentation site.)
 
@@ -138,31 +144,37 @@ In short, the sidebar has some complex logic here. I've integrated Navgoco's fea
 
 Here's how the highlighting of the currently viewed page works. In the sidebar.html file, you'll see this:
 
-```
+```liquid
 {% raw %}
  {% elsif page.url == item.url %}
    <li class="active"><a href="{{item.url | replace: "/",""}}">{{item.title}}</a></li>
 {% endraw %}
 ```
                    
-The `page.url` is a universal Jekyll tag that returns the end path of the page, prepended with `/`. For example, `/sample.html`. If this page URL matches the item.url specified in the sidebar_doc.yml file, then an active class gets applied. 
+The `page.url` is a universal Jekyll tag that returns the end path of the page, prepended with `/`. For example, `/sample.html`. If this `page.url` matches the `item.url` specified in the sidebar_doc.yml file, then an `active` class gets applied.
 
 Note that I've added a filter to the item.url in the sidebar.html file: 
 
-```
+```liquid
+{% raw %}
 {{item.url | replace: "/",""}}
+{% endraw %}
 ```
 
 Ideally, in the sidebar_doc.yml file, you could just write the URL you want to go to: `sample.html` instead of `/sample.html`. However, page.url always returns the forward slash before the URL. In order to match the page.url with the item.url, you have to use the forward slash before item.url in the doc_sidebar.yml file. 
 
-However, if you set up your relative link as `/sample.html` instead of `sample.html`, then the browser will go to the directory root instead of any baseurl. For example, if your site is deployed at http://mydomain.com/doc/, then going to `/sample.html` in the link will take you to http://mydomain.com/sample.html instead of http://mydomain.com/doc/sample.html. In contrast, going to `sample.html` in the link will take you to http://mydomain.com/doc/sample.html. Hence the filter to remove the forward slash in the link.
+However, if you set up your relative link as `/sample.html` instead of `sample.html`, then the browser will go to the directory root instead of any baseurl.
 
-That logic handles the highlighting of the active item, but in order for the sidebar to remain open, the parent level needs to also have the active class. To accomplish this, I inserted this script below the sidebar code in the sidebar.html file:
+For example, if your site is deployed at http://mydomain.com/doc/, then going to `/sample.html` in the link will take you to `http://mydomain.com/sample.html` instead of `http://mydomain.com/doc/sample.html`.
+
+In contrast, going to `sample.html` in the link will take you to `http://mydomain.com/doc/sample.html`. Hence the filter to remove the forward slash in the link.
+
+That logic handles the highlighting of the active item, but in order for the sidebar to remain open, the parent level needs to also have the `active` class. To accomplish this, I inserted this script below the sidebar code in the sidebar.html file:
 
 ```js
 <script>$("li.active").parents('li').toggleClass("active");</script>
 ```
 
-This script has to come *after* the sidebar code; otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.
-
+This script has to come *after* the sidebar code. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.
 
+{% endif %}

doc_supported_features.md

@@ -8,29 +8,29 @@ summary:
 ---
 {% include linkrefs.html %} 
 
-Before you get into exploring Jekyll as a potential platform for help content, you may be wondering if it supports some basic features. The following table shows what is supported in Jekyll.
+Before you get into exploring Jekyll as a potential platform for help content, you may be wondering if it supports some basic features. The following table shows what is supported in Jekyll and this theme.
 
 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 programming language that allows you do advanced things.
+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. 
-Translation | Yes | Export the pages and send them to a translation agency. Then create a new project for that language and insert the pages. Everything will be translated.
-PDF | Yes | You can generate PDFs from your Jekyll site. This theme uses PrinceXML (costs $495) to do the PDF conversion task. You basically set up a page that uses Liquid logic to get all the pages you want, and then you use PrinceXML (not part of Jekyll) to convert that page into a PDF.  
+Translation | Yes | I haven't done a translation project yet (just a pilot test). Here's the basic approach: Export the 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.
+PDF | Yes | You can generate PDFs from your Jekyll site. This theme uses Prince XML (costs $495) to do the PDF conversion task. You basically set up a page that uses Liquid logic to get all the pages you want, and then you use PrinceXML (not part of Jekyll) to convert that page into a PDF.
 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. 
+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.
 Multichannel output | Yes | This term can mean a number of things, but let's say you have 10 different sites you want to generate from the same source. Maybe you have 7 different versions of your product, and 3 different locations. You can assemble your Jekyll site with various configurations, variants, and more. Jekyll actually does all of this quite well. Just specify a different config file for each unique build.
 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.
-Blogging features | No | This theme just uses pages, not posts. I may integrate in post features in the future, but the theme really wasn't designed with posts in mind. If you want a post version of the site, you can clone my [blog theme](https://github.com/tomjohnson1492/tomjohnson1492.github.io), which is highly similar in that it's based on Bootstrap, but it uses posts to drive most of the features.
-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. 
-WYSIWYG interface | No, but ... | I use IntelliJ/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. 
+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 | No | This theme just uses pages, not posts. I may integrate in post features in the future, but the theme really wasn't designed with posts in mind. If you want a post version of the site, you can clone my [blog theme](https://github.com/tomjohnson1492/tomjohnson1492.github.io), which is highly similar in that it's based on Bootstrap, but it uses posts to drive most of the features. I wanted to keep the project files simple.
+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, but ... | As noted in the previous point, 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.
 Versioning | Yes, but... | Jekyll doesn't version your files. You upload your files to a version control system such as Git. Your files are versioned there.
-PC platform | Yes, but ... | Jekyll isn't officially supported on Windows, and since I'm on a Mac, I haven't tried using Jekyll on Windows. See this [page in Jekyllrb help](http://jekyllrb.com/docs/windows/) for details about installing and running Jekyll on a Windows machine. A couple of Windows users who have contacted me have been unsuccessful in installing Jekyll on Windows, so beware.
-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 because Github doesn't allow Ruby plugins. Instead, you can just push your output to Github. If you're not planning to use Github, 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.
+PC platform | Yes, but ... | Jekyll isn't officially supported on Windows, and since I'm on a Mac, I haven't tried using Jekyll on Windows. See this [page in Jekyllrb help](http://jekyllrb.com/docs/windows/) for details about installing and running Jekyll on a Windows machine. A couple of Windows users who have contacted me have been unsuccessful in installing Jekyll on Windows, so beware. In the configuration files, use `rouge` instead of `pygments` (which is Python-based) to avoid conflicts.
+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.
 Bootstrap integration | Yes | This theme is built on [Bootstrap](http://getbootstrap.com/). If you don't know what Bootstrap is, basically this means there are hundreds of pre-built components, styles, and other elements that you can simply drop into your site. For example, the responsive quality of the site comes about from the Bootstrap code base.
 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.
 Relative links | Yes | This theme is built entirely with relative links, which means you can easily move the files from one folder to the next and it will still display. You don't need to view the site on a web server either -- you can view it locally just clicking the files. This relative link structure facilitates scenarios where you need to archive versions of content or move the files from one directory (a test directory) to another (such as a production directory).
 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. Not that this openness comes at a price — it's easy to make changes that break the theme or otherwise cause errors.  
+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.

doc_syntax_highlighting.md

@@ -47,19 +47,19 @@ It renders the same:
 {% endhighlight %}
 
 
-The theme has syntax highlighting configured in the configuration file as follows:
+The theme has syntax highlighting specified in the configuration file as follows:
 
 ```
 highlighter: pygments
 ```
 
-You can use another highlighter such as rouge.
+You can use another highlighter such as `rouge`.
 
 The syntax highlighting is done via the css/syntax.css file.
 
 ## Available Pygments lexers
 
-The keywords you must add to specify the highlighting are called "lexers." You can search for "pygments lexers" or go directly to [Available lexers](http://pygments.org/docs/lexers/) to see what values you can use. Here are some common ones I use:
+The keywords you must add to specify the highlighting (in the previous example, `ruby`) are called "lexers." You can search for "pygments lexers" or go directly to [Available lexers](http://pygments.org/docs/lexers/) to see what values you can use. Here are some common ones I use:
 
 * js
 * html

doc_tables.md

@@ -5,8 +5,9 @@ keywords:
 datatable: true
 summary: 
 ---
-{% include linkrefs.html %} 
+{% include linkrefs.html %}
 
+{% unless site.print == true %}
 <script>
 $(document).ready(function(){
 
@@ -18,6 +19,7 @@ $(document).ready(function(){
         );
 });
 </script>
+{% endunless %}
 
 ## Multimarkdown Tables
 
@@ -39,9 +41,9 @@ cell 2a | cell 2b
 
 ## jQuery datables
 
-You also have the option of using a [jQuery datatable](https://www.datatables.net/), which gives you some more options. If you want to use a jQuery datatable, then add `datatable: true` in a page's frontmatter. This will enable the right scripts for the table on that page only (rather than loading the scripts on every page of the site.)
+You also have the option of using a [jQuery datatable](https://www.datatables.net/), which gives you some more options. If you want to use a jQuery datatable, then add `datatable: true` in a page's frontmatter. This will load the right jQuery datatable scripts for the table on that page only (rather than loading the scripts on every page of the site.)
 
-Also, add the scripts to trigger the jQuery table on your page:
+Also, you need to add this script to trigger the jQuery table on your page:
 
 ```js
 <script>
@@ -59,7 +61,7 @@ $(document).ready(function(){
 
 The available options for the datable are described in the [datatable documentation](https://www.datatables.net/manual/options), which is excellent.
 
-Additionally, you must add a class of `display` to the table. (You can change the class, but then you'll need to change the trigger above from `table.display` to whatever class you want to you. You might have different triggers with different options for different tables.)
+Additionally, you must add a class of `display` to your tables. (You can change the class, but then you'll need to change the trigger above from `table.display` to whatever class you want to you. You might have different triggers with different options for different tables.)
 
 Since Markdown doesn't allow you to add classes to tables, you'll need to use HTML for any datatables. Here's an example: 
 

doc_tags.md

@@ -18,13 +18,17 @@ tags: [formatting, single-sourcing]
 ```
 
 ## Tags overview
-{{note}} With posts, tags have a namespace that you can access with `posts.tags.tagname`, where `tagname` is the name of the tag. You can then list all posts in that tag namespace. But pages don't off this same tag namespace, so you could actually use another key instead of `tags`. Nevertheless, I'm using the same `tags` name here.{{end}}
+{% if site.audience == "designers" %}
+{{note}} With posts, tags have a namespace that you can access with <code>posts.tags.tagname</code>, where <code>tagname</code> is the name of the tag. You can then list all posts in that tag namespace. But pages don't off this same tag namespace, so you could actually use another key instead of <code>tags</code>. Nevertheless, I'm using the same <code>tags</code> name here.{{end}}
+{% endif %}
 
-To prevent tags from getting out of control and inconsistent, first make sure the tag appears in the tags_doc.yml file. If it's not there, the tag you add to a page won't be read. I added this check just to make sure you're using the same tags consistently and not adding new tags that don't have tag archive pages. 
+To prevent tags from getting out of control and inconsistent, first make sure the tag appears in the \date/tags_doc.yml file. If it's not there, the tag you add to a page won't be read. I added this check just to make sure I'm using the same tags consistently and not adding new tags that don't have tag archive pages.
 
-{{note}} Unlike with WordPress, you have to build out the functionality for tags so that clicking a tag name shows you all pages with that tag. It's much more manual.{{end}}
+{% if site.audience == "designers" %}
+{{note}} Unlike with WordPress, 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.{{end}}
+{% endif %}
 
-Additionally, you must create a tag archive page similar to the other pages named doc_tag-tagname.html folder. This theme doesn't auto-create tag archive pages. 
+Additionally, you must create a tag archive page similar to the other pages named doc_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).
 
@@ -54,8 +58,6 @@ Tags have a few components.
 	  - special-layouts
 	  - content types
 	```
-		
-3.  In the \_includes folder, there's a taglogic.html file. This file has common logic for getting the tags and listing out the pages containing the tag in a table with summaries or truncated excerpts. You don't have to do anything with the file &mdash; just leave it there because the tag archive pages reference it.
 	
 4. Create a tag archive file for each tag in your tags_doc.yml list. Name the file like this: doc_tag-getting-started.html, where doc is your project name. (Again, tags with multiple words need hyphens in them.)
 	
@@ -70,7 +72,9 @@ Tags have a few components.
     {% include taglogic.html %}
     {% endraw %}
     ```
-	
+
+		{{note}}In the \_includes folder, there's a taglogic.html file. This file (included in each tag archive file) has common logic for getting the tags and listing out the pages containing the tag in a table with summaries or truncated excerpts. You don't have to do anything with the file &mdash; just leave it there because the tag archive pages reference it.{{end}}
+
 5. Adjust button color or tag placement as desired. 
 	
 	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:
@@ -91,22 +95,22 @@ Tags have a few components.
 	{% endraw %}
 	```
 	
-	Here's what the code does:
-	<div class="tags">
-    	    {% if page.tags != null %}
-    	    <b>Tags: </b>
-    	    {% include custom/conditions.html %}
-    	    {% for tag in page.tags %}
-    	    {% if projectTags contains tag %}
-    	    <a href="{{site.project}}_tag-{{tag}}.html"><button type="button" class="btn btn-info navbar-btn cursorNorm">{{page.tagName}}{{tag}}</button></a>{% unless forloop.last %}{% endunless%}
-    	    {% endif %}
-    	    {% endfor %}
-    	    {% endif %}
-    	</div>
+	Here's an example of what the code does:
+<div class="tags">
+	{% if page.tags != null %}
+	<b>Tags: </b>
+	{% include custom/conditions.html %}
+	{% for tag in page.tags %}
+	{% if projectTags contains tag %}
+	<a href="{{site.project}}_tag-{{tag}}.html"><button type="button" class="btn btn-info navbar-btn cursorNorm">{{page.tagName}}{{tag}}</button></a>{% unless forloop.last %}{% endunless%}
+	{% endif %}
+	{% endfor %}
+	{% endif %}
+</div>
     	
-	Because this code appears on the \layouts/page.html file by default, you don't need to do anything. However, if you want to alter the placement or change the button color, you can do so.
+Because this code appears on the \_layouts/page.html file by default, you don't need to do anything. However, if you want to alter the placement or change the button color, you can do so.
 	
-	You can change the button color by changing the class on the button from `btn-info` to one of the other button classes bootstrap allows. See {{doc_labels}} for more options on button class names.
+You can change the button color by changing the class on the button from `btn-info` to one of the other button classes bootstrap provides. See {{doc_labels}} for more options on button class names.
 
 ## Retrieving pages for a specific tag
 
@@ -138,10 +142,40 @@ Getting started pages:
 <li><a href="{{page.url}}">{{page.title}}</a></li>
 {% endif %}
 {% endfor %}
-{% endfor %} 
+{% endfor %}
 </ul>
 
-Tags will be sorted in alphabetical order.
+If you want to sort the pages alphabetically, you have to apply a `sort` filter:
+
+```liquid
+{% raw %}
+Getting started pages:
+<ul>
+{% assign sorted_pages = (site.pages | sort: 'title') %}
+{% for page in sorted_pages %}
+{% for tag in page.tags %}
+{% if tag == "getting-started" %}
+<li><a href="{{page.url}}">{{page.title}}</a></li>
+{% endif %}
+{% endfor %}
+{% endfor %} 
+</ul>
+{% endraw %}
+```
+
+Here's how that code renders:
+
+Getting started pages:
+<ul>
+{% assign sorted_pages = (site.pages | sort: 'title') %}
+{% for page in sorted_pages %}
+{% for tag in page.tags %}
+{% if tag == "getting-started" %}
+<li><a href="{{page.url}}">{{page.title}}</a></li>
+{% endif %}
+{% endfor %}
+{% endfor %}
+</ul>
 
 ## Efficiency
 Although the tag approach here uses `for` loops, these are somewhat inefficient on a large site. Most of my tech doc projects don't have hundreds of pages (like my blog does). If your project does have hundreds of pages, this `for` loop approach with tags is going to slow down your build times. 
@@ -159,11 +193,11 @@ If your page shows "tags:" at the bottom without any value, it could mean a coup
 * You're using a tag that isn't specified in your allowed tags list in your doc_tags.yml file.
 * You have an empty `tags: []` property in your frontmatter.
 
-If you don't want tags to appear at all on your page, then should remove the tags property from your frontmatter.
+If you don't want tags to appear at all on your page, remove the tags property from your frontmatter.
 
 ## Remembering the right tags
 
 Since you may have many tags and find it difficult to remember what tags are allowed, I recommend creating a template that prepopulates all your frontmatter with all possible tags. Then just remove the tags that don't apply. 
 
-You can easily create templates in IntelliJ and WebStorm. Right-click the file area, then choose **New > Edit File Templates**.
+See {{doc_webstorm_text_editor}} for tips on creating file templates in WebStorm.
 

doc_top_navigation.md

@@ -10,10 +10,10 @@ summary: "The top navigation provides either single links or a drop-down menu. T
 
 ## Changing the top navigation
 
-The top navigation reads from the \_data/topnav_doc.yml file. There are two sections:
+The top navigation reads from the \_data/topnav_doc.yml file. There are two *separate* sections:
 
-* topnav
-* topnav_dropdowns
+* `topnav``
+* `topnav_dropdowns``
 
 Items in the `topnav` section are rendered as single links. In contrast, items in the `topnav_dropdowns` section are rendered as a drop-down menu.
 
@@ -37,18 +37,22 @@ Included in the topnav.html file is an include to /doc/customMenu.html. The code
 
 The current doc site is highlighted. If you select another doc site, the site switches to that doc site and goes to the same page on that doc site. This way, if you have a task such as "Configuring the license" in several different programming languages, users can switch to other programming languages to see the same page.
 
+You need to have both the designers and writers sites deployed on a web server to see this in action. Go to the following link: <a href="http://idratherbetellingstories.com/documentation-theme-jekyll/doc_designers/" target="_blank">idratherbetellingstories.com/documentation-theme-jekyll/doc_designers/</a>.
+
+Browse to any page in the navigation. Then go to the **Custom Menu** and select the **Writers** site. You'll go to the exact same page but on the Writers site.
+
 If your current page doesn't have an equivalent in your other outputs, then put this in the frontmatter of the page:
 
 ```
 switch: false
 ```
 
-This little menu may not be something you want, and if so, just remove the include from the sidebar.html file. But if you're outputting multiple sites, it may be something valuable.
+This Custom Menu may not be something you want, and if so, just remove the include from the sidebar.html file. But if you're outputting multiple sites, it may be something valuable.
 
 ## Pop-out link
 
 The top navigation bar also has an include to frameescape.html. If the site is embedded inside a frame, a link on the top navigation bar appears that says Pop-out, and it will open the site in a new window. 
 
-In most cases, you'll want to simply remove this include. I added this because some of my doc sites are delivered through Salesforce and are embedded inside another page in a small area. This pop-out link is a way of liberating the site from these embedded page scenarios. If your site isn't embedded in an iframe, the Pop-out link is removed.
+In most cases, you'll want to simply remove this include. I added this because some of my doc sites are delivered through a Salesforce Community and are embedded inside another page in a small area. This pop-out link is a way of liberating the site from these embedded page scenarios. If your site isn't embedded in an iframe, the Pop-out link is removed.
 
 

doc_video_embeds.md

@@ -12,36 +12,34 @@ video: true
 The theme has the [video.js](http://www.videojs.com/) player integrated. But the scripts only appear on a page or post if you have certain frontmatter in that page or post. If you want to embed a video in a page and use the Video JS player, add `video: true` in your frontmatter of a page or post, and then add code like this where you want the video to appear:
 
 ```html
-<video id="scenario-1" class="video-js vjs-default-skin vjs-big-play-centered" controls
+<p><video id="scenario-1" class="video-js vjs-default-skin vjs-big-play-centered" controls
  preload="auto" width="640" height="480" data-setup='{}'>
   <source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type='video/mp4'>
-</video>
+</video></p>
 ```
 
 Here's an example: 
 
-<video id="scenario-1" class="video-js vjs-default-skin vjs-big-play-centered" controls
+<p><video id="scenario-1" class="video-js vjs-default-skin vjs-big-play-centered" controls
  preload="auto" width="640"  height="480" data-setup='{}'>
   <source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type='video/mp4'>
-</video>
-
-You'll know it's working if the video wrapper looks like the one here: [video.js: the open source HTML5 video player](http://www.videojs.com/).
+</video></p>
 
 If you want the player button in the upper-left corner (which is the default), remove the `vjs-big-play-centered` from the video class.
 
-<video id="scenario-1" class="video-js vjs-default-skin" controls
+<p><video id="scenario-1" class="video-js vjs-default-skin" controls
  preload="auto" width="640" height="480" data-setup='{}'>
   <source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type='video/mp4'>
-</video>
+</video></p>
 
-Here are [more details on this video player](https://github.com/videojs/video.js/blob/stable/docs/guides/setup.md).
+Here are [more details on this video player from Video JS](https://github.com/videojs/video.js/blob/stable/docs/guides/setup.md).
 
-Note that if some of the js doesn't load correctly, the default fallback player is the regular HTML5 video player available via the browser. Here's an example: 
+Note that if some of the js doesn't load correctly, the default fallback player is the regular HTML5 video player available via the browser. Here's an example of the built-in browser video wrapper:
 
-<video width="640" controls>
+<p><video width="640" controls>
   <source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type="video/mp4">
 Your browser does not support the video tag.
-</video>
+</video></p>
 
 However, I don't think the built-in browser video players work very well (you can't easily scrub around the video without seeing lots of buffering and other issues). But definitely compare the two. You may find that adding the Video JS wrapper is overkill.
 

doc_webstorm_text_editor.md

@@ -22,7 +22,7 @@ Since you'll be writing in Markdown, having color coding and other support for M
 | Shift + Shift | Allows you to find a file by searching for its name. |
 | Ctrl + H | Find in whole project. (WebStorm uses the term "Find in "path".) |
 | Edit > Find > Replace in Path | Replace in whole project. (Unfortunately, I can't find a keyboard shortcut for this common operation.) |
-| Right-click > Refactor > Safe Delete | Allows you to delete a file |
+| Right-click > Refactor > Safe Delete | Allows you to delete a file. |
 | Right-click > Add to Favorites | Allows you to add files to a Favorites section, which expands below the list of files in the project pane. |
 
 ## Identifying changed files
@@ -31,15 +31,17 @@ When you have the Git and Github integration, changed files appear in blue. This
 
 ## Creating file templates
 
-Rather than insert the frontmatter by hand each time, it's much faster to simply create a Jekyll template in WebStorm (my favorite editor for Jekyll projects).
-
-To create a Jekyll template:
+Rather than insert the frontmatter by hand each time, it's much faster to simply create a Jekyll template. To create a Jekyll template in WebStorm:
 
 1. Right-click a file in the list of project files, and select **New > Edit File Templates**.
 
-   If you don't see this option, you may need to create a file template first. Go to **File > Default Settings > Editor > File and Code Templates**. Create a new file template with an md extension, and then close and restart WebStorm. Then repeat this step and you will see the File Templates option appear in the right context menu.
+    If you don't see the Edit File Templates option, you may need to create a file template first. Go to **File > Default Settings > Editor > File and Code Templates**. Create a new file template with an md extension, and then close and restart WebStorm. Then repeat this step and you will see the File Templates option appear in the right context menu.
 
 2. In the upper-left corner of the dialog box that appears, click the **+** button to create a new template.
-3. Name it Jekyll. Insert the frontmatter you want, and save it.
+3. Name it something like Jekyll page. Insert the frontmatter you want, and save it.
 
-To use the Jekyll template, when you create a new file in your WebStorm project, you can select your Jekyll file template.
+    To use the Jekyll template, when you create a new file in your WebStorm project, you can select your Jekyll file template.
+
+## Disable pair quotes
+
+By default, each time you type `'`, WebStorm will pair the quote. You can disable this by going to **WebStorm > Preferences > Editor > Smartkeys**. Clear the **Insert pair quotes** check box.