content updates

_data/sidebar_doc.yml

@@ -85,6 +85,13 @@ entries:
           product: all
           version: all
 
+        - title: WebStorm Text Editor
+          url: /doc_webstorm_text_editor.html
+          audience: writers, designers
+          platform: all
+          product: all
+          version: all
+
         - title: Series
           url: /doc_series.html
           audience: writers, designers
@@ -99,6 +106,7 @@ entries:
           product: all
           version: all
 
+
     - title: Navigation
       audience: writers, designers
       platform: all

_includes/custom/doc/customMenu.html

@@ -3,9 +3,9 @@
 <li class="dropdown">
     <a href="#" class="dropdown-toggle otherProgLangs" data-toggle="dropdown">Custom Menu<b class="caret"></b></a>
     <ul class="dropdown-menu">
-        <li {% if site.audience == "writers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../writers/{{site.suffix}}">Writer docs</a> {% else %} ../writers{{page.url}}">Writer docs</a>{% endif %}</li>
+        <li {% if site.audience == "writers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_writers/{{site.suffix}}">Writer docs</a> {% else %} ../doc_writers{{page.url}}">Writer docs</a>{% endif %}</li>
 
-<li {% if site.audience == "designers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../designers/{{site.suffix}}">Designer doc</a> {% else %} ../designers{{page.url}}">Designer docs</a>{% endif %}</li>
+<li {% if site.audience == "designers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_designers/{{site.suffix}}">Designer doc</a> {% else %} ../doc_designers{{page.url}}">Designer docs</a>{% endif %}</li>
 
 </ul>
 </li>

_includes/custom/doc/links_doc.html

@@ -121,3 +121,5 @@
 {% capture doc_iterm_profiles %}<a href="doc_iterm_profiles.html">iTerm profiles</a>{% endcapture %}
 {% 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 %}

configs/config_designers.yml

@@ -4,7 +4,7 @@ audience: designers
 product: all
 platform: all
 version: all
-destination: ../designers
+destination: ../doc_designers
 topnav_title: Jekyll Documentation Theme
 homepage_title: Jekyll Documentation Theme — Designers
 site_title: Jekyll Documentation Theme — Designers

configs/config_designers_pdf.yml

@@ -1,6 +1,6 @@
-destination: /Applications/XAMPP/xamppfiles/htdocs/documentation-theme-jekyll/designers-pdf
+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 Designers

configs/config_writers.yml

@@ -4,7 +4,7 @@ audience: writers
 product: all
 platform: all
 version: all
-destination: ../writers
+destination: ../doc_writers
 topnav_title: Jekyll Documentation Theme
 homepage_title: Jekyll Documentation Theme — Writers
 site_title: Jekyll Documentation Theme — Writers

configs/config_writers_pdf.yml

@@ -1,6 +1,6 @@
-destination: /Applications/XAMPP/xamppfiles/htdocs/documentation-theme-jekyll/writers-pdf
+destination: ../doc_writers-pdf
 url: "http://127.0.0.1:4004"
-baseurl: "/writers"
+baseurl: "/doc_writers"
 port: 4004
 print: true
 print_title: Jekyll Documentation Theme for Writers

doc_configuration_settings.md

@@ -20,11 +20,10 @@ Some of the options you can set in the configuration file determine theme settin
 
 Note that you can define arbitrary key-value pairs in the configuration file, and then you can access them through `site.yourkey`, where `yourkey` is the name of the key. However, the values in these tables are used to control different aspects of the theme and are not arbitrary key-value pairs.
 
-## Configuration settings
+## Configuration settings for web outputs
 
 | Field | Required? | Description |
 |-------|-----------|-----------|
- |
 | **project** | Required| A unique name for the project. The \_includes/custom/{project}/conditions.html file will use this project name to determine what sidebar and top nav data files to use. Make this value unique. |
 | **audience** | Required | The audience for the output. Each entry in \_data/sidebar_doc.yml and  \_data/topnav_doc.yml needs to have an audience attribute that matches the value here in order for the sidebar or topnav item to be included.|
 | **platform** | Required | The platform for the output. See additional information in audience.
@@ -88,6 +87,37 @@ The file in \_includes/custom/doc/conditions.html contains a project setting and
 
 It's a little complicated to describe, but it works. Once you configure your project correctly, you don't even think about how the theme is processing all of this on the backend.
 
+## Configuration settings for PDF output
+
+The PDF configuration files build on all the settings in the web configuration files, but they add a few more options. 
+
+When you build the PDF output (such as for the writers output), the command will look like this:
+
+```
+jekyll serve --detach --config configs/config_writers.yml,configs/config_writers_pdf.yml
+```
+
+First Jekyll will read the config_writers.yml file, and then Jekyll will read the config_writers_pdf.yml file.
+ 
+More detail about generating PDFs is provided in {{doc_generating_pdfs}}, but the configuration settings used for the PDFs are described here.
+
+The process for creating PDFs relies on two steps:
+
+1. First you build a printer-friendly web version of the content. 
+2. Then you run PrinceXML to get all the printer-friendly web pages and package them into a PDF.
+
+Thus, you actually build a web version for the PDF first before generating the PDF. (You might be able to remove this first step by doing more coding, but I found it easier just to strip out components I didn't want included and make other adjustments.)
+
+| Field | Required? | Description |
+|-------|-----------|-----------|
+| destination | Where the PDF web version should be served so that Prince XML can find it. By default, this is in ../doc_designers-pdf, so just one level above where your project is.  |
+| url | The URL where the files can be viewed. This is `http://127.0.0.1:4002` in the sample theme files for the designers output. Prince XML requires a URL to access the file. (My attempts to use local file paths didn't work.) |
+| baseurl | The subdirectory after the url where the content is stored. In the sample theme files for the designers output, this is `/designers`. | 
+| port | The port required by the preview server. |
+| print | A boolean so that you can construct conditional statements in your content to check whether print is true or not. This setting can help you filter out content that doesn't fit well into a PDF (such as dynamic web elements). |
+| print_title | The title for the PDF. In the sample theme files for designers output, the print title is "Jekyll Documentation Theme for Designers"|
+| print_subtitle | The subtitle for the PDF. In the sample theme files, the subtitle is "version 3.0." |
+| defaults | See the sample settings in the config_designers_pdf.yml file. The only difference between this file and config_designers.yml is that the layout used for pages is `page_print` instead of `page`. The `page_print` layout also used `head_print` instead of `head`. This layout strips out components such as the sidebar and top navigation. It also leverages printstyles.css and includes some JavaScript for Prince XML. |
 
 
 

doc_getting_started.md

@@ -67,7 +67,7 @@ Before you start customizing the theme, make sure you can build the theme with t
 	. doc_multibuild_web.sh
 	```
 	
-	The themes build in the ../designers and ../writers folders. Use finder and browse to one level above where you installed the project (probably username/projects). 
+	The themes build in the ../doc_designers and ../doc_writers folders. Use finder and browse to one level above where you installed the project (probably username/projects). 
 	
 	Open the writers and designers folders and click the index.html file. The themes should launch and appear similar to their appearance in the preview folder. This is because the themes are build using a relative link structure, so you can move the theme to any folder you want without breaking the links. 
 	

doc_multibuild_pdf.sh

@@ -1,10 +1,10 @@
 # Writers PDF
 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/doc_writers_pdf.pdf;
+prince --javascript --input-list=../doc_writers-pdf/prince-file-list.txt -o /Users/tjohnson/projects/documentation-theme-jekyll/doc_writers_pdf.pdf;
 
 # Designers PDF
 echo "Building the Designers PDF ..."
-prince --javascript --input-list=/Applications/XAMPP/xamppfiles/htdocs/documentation-theme-jekyll/designers-pdf/prince-file-list.txt -o /Users/tjohnson/projects/documentation-theme-jekyll/doc_designers_pdf.pdf;
+prince --javascript --input-list=../doc_designers-pdf/prince-file-list.txt -o /Users/tjohnson/projects/documentation-theme-jekyll/doc_designers_pdf.pdf;
 
 # All done.
 # Now run . doc_multiweb_pdf.sh

doc_multiserve_pdf.sh

@@ -12,5 +12,5 @@ jekyll serve --detach --config configs/config_writers.yml,configs/config_writers
 echo "Serving Designers PDF"
 jekyll serve --detach --config configs/config_designers.yml,configs/config_designers_pdf.yml
 
-# All done.
-# Now run . doc_multibuild_pdf.sh
+echo "All done."
+echo "Now run . doc_multibuild_pdf.sh"

doc_pages.md

@@ -71,17 +71,7 @@ If you want to use a colon in your page title, you must enclose the title's valu
 
 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.
 
-## Creating a Jekyll template in WebStorm
-
-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:
-
-1. Right-click a file in the list of project files, and select **New > Edit File Templates**.
-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.
-
-To use the Jekyll template, when you create a new file in your WebStorm project, you can select your Jekyll file template.
+{{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}}
 
 ## Markdown or HTML format
 

doc_theme_customization.md

@@ -12,11 +12,11 @@ summary:
 
 The theme shows two build outputs: one for designers, and one for writers. The dual outputs is an example of the single sourcing nature of the theme. The designers output is comprehensive, whereas the writers output is a subset of the information. Follow these steps to customize the theme with your own content.
 
-{{important}} In these instructions, I'll assume your project's name is "acme." I'll also assume you have two audiences you're building your acme project for: developers and marketers. {{end}}
+{{important}} In these instructions, I'll assume your project's name is "acme." I'll also assume you have two audiences you're building your acme project for: marketers and developers. {{end}}
 
 To customize the theme:
 
-1. In the theme's root directory, rename config_writer.yml to config_marketer.yml and customize all the values inside that file based on the instructions {{config_setup}}. Do the same with config_designer.yml (changing it to config_developer.yml) and continue to clone and customize the config file for other audiences you need.
+1. In the theme's root directory, rename config_writer.yml to config_marketer.yml and customize all the values inside that file based on the instructions in {{doc_configuration_settings}}. Do the same with config_designer.yml (changing it to config_developer.yml) and continue to clone and customize the config file for other audiences you need.
     
     In this theme, each output requires a separate config file. If you have 10 audiences and you want separate sites for each, then then you'll have 10 config files in this directory. 
 
@@ -26,21 +26,27 @@ To customize the theme:
     
 5. In the \_includes/custom directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with  `developer`, and `designer` with `marketer`.) 
     
-    The conditions.html file is used to apply different requirements to the sidebar and other files. The conditions.html file is included in various parts of the theme — the sidebar.html, the topnav.html, and some of the print files. It's sort of the brains of the theme.
+    The conditions.html file is used to apply different requirements to the sidebar and other files. The conditions.html file is included in various parts of the theme — the sidebar.html, the topnav.html, and some of the print files. *conditions.html is sort of the brains of the theme.* If you don't have a specific value for audience, version, platform, or product, just put `all`.
     
 6. Remove the pages that begin with "doc_" in the root directory, and then add your own pages here. Leave all the files flat in the root directory. 
 	
 	If you nest files inside folders, you'll create problems for the links and the theme will break. Yes, this will result in a lot of files in the root directory, but you can get around this issue with some viewing strategies in your text editor.
+	
+	For example, with WebStorm, if you press **Shift** twice and type the file name you want, the editor finds it. I usually have the preview mode open in another browser and navigate the content that way. When I want to edit a specific file, I copy the filename path from the preview browser, press **Shift** twice, and then it opens. You can also create a favorites section that just shows files you've added to Favorites (an option in the context menu).
+
 7. Inside \_data, open sidebar_doc.yml and topnav_doc.yml and customize the navigation. 
     
-    {{warning}} Don't mess up the spacing or change any of the YML level names or the site or sidebar won't build. Each new YML level is indented with two spaces. Sometimes getting this spacing right is tricky. I recommend saving the sample template here that shows the various levels, and then just copy and paste the levels where you need them.{{end}}
+    {{warning}} Don't mess up the spacing or change any of the YML level names or the site or sidebar won't appear. Each new YML level is indented with two spaces. Sometimes getting this spacing right is tricky. I recommend you save the sample template here that shows the various levels, and then just copy and paste the levels where you need them. YML is very picky and it can be frustrating sorting out spacing and level issues. {{end}}
     
-9. In the root directory, customize the index.md file. This file will be the homepage for all of your projects. Use conditional tags (for example, `if site.project == "acme-writer" ...`) to change the content for different builds of your site. Store the content of the homepage in your \_includes/custom/{project_name} folder. See {{conditional_logic}} for more information on applying conditions.
-10. For each of your pages where you want to insert a note or callout, add {%raw%}`{% include linkrefs.html %}`{%endraw%}  directly below the frontmatter.
+9. In the root directory, customize the index.md file. This file will be the homepage for all of your projects.
 
-    {{tip}} If you're using WebStorm, you can create a Jekyll template so that the frontmatter is auto-populated when you create a new Jekyll file. {{end}}
+    Use conditional tags (for example, `{% raw %}{% if site.project == "writers" %} ... {% endif %}{% endraw %}`) to change the content for different builds of your site. Store the content of the homepage in your \_includes/custom/{project_name} folder. See {{conditional_logic}} for more information on applying conditions.
+
+10. For each of your pages where you want to insert a note or callout, add `{%raw%}{% include linkrefs.html %}{%endraw%}` directly below the frontmatter.
+    
+    {{tip}} If you're using WebStorm, you can create a Jekyll template so that the frontmatter is auto-populated when you create a new Jekyll file. Ctrl + click the file area and choose <b>New > Edit File Templates</b>. {{end}}
     
 12. In the \_includes folder, open footer.html and customize the content (namely the footer image). If you have different footers for different outputs, use conditional tags as you did with index.md.
-11. Build your site with the `jekyll serve --config configs/config_writers.yml` etc., and preview it at the URLs provided.
+11. Build your site with a command such as `jekyll serve --config configs/config_writers.yml` etc., and preview it at the URLs provided.
 
-{{callout_info}}<b>Publishing to web hosts:</b> If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other web host.{{end}}
+{{callout_info}}<b>Publishing to web hosts:</b> If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other web host. See {{doc_push_build_to_server}} for more information.{{end}}

doc_top_navigation.md

@@ -30,9 +30,9 @@ It's common to publish multiple sites. If you want to link them together, you co
 Included in the topnav.html file is an include to /doc/customMenu.html. The code there is as follows:
 
 ```
-  <li {% if site.audience == "writers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../writers/{{site.suffix}}">Writer docs</a> {% else %} ../writers{{page.url}}">Writer docs</a>{% endif %}</li>
+  <li {% if site.audience == "writers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_writers/{{site.suffix}}">Writer docs</a> {% else %} ../doc_writers{{page.url}}">Writer docs</a>{% endif %}</li>
 
-<li {% if site.audience == "designers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../designers/{{site.suffix}}">Designer doc</a> {% else %} ../designers{{page.url}}">Designer docs</a>{% endif %}</li>
+<li {% if site.audience == "designers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_designers/{{site.suffix}}">Designer doc</a> {% else %} ../doc_designers{{page.url}}">Designer docs</a>{% endif %}</li>
 ```
 
 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.

doc_webstorm_text_editor.md

@@ -0,0 +1,45 @@
+---
+title: WebStorm Text editor
+summary:
+---
+
+There are a variety of text editors available, but I like WebStorm the best because it groups files into projects, which makes it easy to find all instances of a text string, to do find and replace operations across the project, and more.
+
+If you decide to use WebStorm, here are a few tips on configuring the editor.
+
+## Remove unnecessary plugins
+
+By default, WebStorm comes packaged with a lot more functionality than you probably need. You can lighten the editor by removing some of the plugins. Go to **WebStorm > Preferences > Plugins** and clear the check boxes of plugins you don't need.
+
+## Add the Markdown Support plugin
+
+Since you'll be writing in Markdown, having color coding and other support for Markdown is key. Install the Markdown Support plugin by going to **WebStorm > Preferences > Plugins** and clicking **Install JetBrains Plugin**. Search for **Markdown Support**.
+
+## Learn a few key commands
+
+|Command | Shortcuts |
+|-------|--------|
+| 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 > 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
+
+When you have the Git and Github integration, changed files appear in blue. This lets you know what needs to be committed to your repository.
+
+## 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:
+
+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.
+
+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.
+
+To use the Jekyll template, when you create a new file in your WebStorm project, you can select your Jekyll file template.