content update

This commit is contained in:
Tom Johnson
2015-08-12 09:38:23 -07:00
parent 0655e5323d
commit 655e02f773
5 changed files with 30 additions and 33 deletions

View File

@ -56,8 +56,8 @@ entries:
product: all
version: all
- title: Customizing the theme
url: /doc_customize_the_theme.html
- title: Theme customization
url: /doc_theme_customization.html
audience: writers, designers
platform: all
product: all

View File

@ -2,7 +2,7 @@
## Overview
This site provides documentation, training, and other notes for the Jekyll Documentation theme. There's a lot of information about how to do a variety of things here, and it's not all unique to this theme. But by and large, understanding how to do things in Jekyll depends on how your theme is coded. Out of the box, Jekyll's theme is pretty basic.
This site provides documentation, training, and other notes for the Jekyll Documentation theme. There's a lot of information about how to do a variety of things here, and it's not all unique to this theme. But by and large, understanding how to do things in Jekyll depends on how your theme is coded.
## Survey of features
@ -10,15 +10,16 @@ Some of the more prominent features of this theme include the following:
* Bootstrap framework
* Sidebar with page hierarchy
* PDF generation
* PDF generation (with Prince XML utility)
* Notes, tips, and warning information notes
* Tags
* Single sourcing
* Single sourced outputs
* Emphasis on pages, not posts
* Relative (rather than absolute) link structure
I'm using this theme for my documentation projects, building about 15 different outputs for various products, versions, languages, and audiences from the same set of files. This single sourcing requirement has influenced how I constructed this theme.
For more discussion about the available featuers, see {{doc_supported_features}}.
For more discussion about the available features, see {{doc_supported_features}}.
## Getting started
@ -26,13 +27,11 @@ To get started, see these three topics:
1. {{doc_getting_started}}
2. {{doc_configuration_settings}}
3. {{doc_customize_the_theme}}
After that, the topics aren't in any particular order.
3. {{doc_theme_customization}}
## PDF Download
If you would like to download this help file as a PDF, you can do so here. The PDF is comprehensive of all the content in the online help.
If you would like to download this help file as a PDF, you can do so here. The PDF most of the same content as the online help, except that some elements (such as video or special layouts) don't translate the the print medium, so they're excluded.
<a target="_blank" class="noCrossRef" href="doc_{{site.audience}}_pdf.pdf"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>

View File

@ -26,8 +26,8 @@
{% capture doc_content_reuse_i %}<a href="doc_content_reuse.html">{% endcapture %}
{% capture doc_customize_the_theme %}<a href="doc_customize_the_theme.html">Customizing the theme</a>{% endcapture %}
{% capture doc_customize_the_theme_i %}<a href="doc_customize_the_theme.html">{% endcapture %}
{% capture doc_theme_customization %}<a href="doc_theme_customization.html">Customizing the theme</a>{% endcapture %}
{% capture doc_theme_customization_i %}<a href="doc_theme_customization.html">{% endcapture %}
{% capture doc_excluding_files %}<a href="doc_excluding_files.html">Excluding files</a>{% endcapture %}
{% capture doc_excluding_files_i %}<a href="doc_excluding_files.html">{% endcapture %}

View File

@ -14,55 +14,53 @@ summary:
Before you start installing the theme, make sure you have all of these prerequisites in place.
* **Mac computer (recommended)**. If you have a PC, you need to see [Jekyll on Windows](http://jekyllrb.com/docs/windows/). Make sure you can get Jekyll working on Windows before proceeding.
* **[Ruby](https://www.ruby-lang.org/en/)**. This should already be installed. Type `which ruby` to confirm.
* **[Ruby](https://www.ruby-lang.org/en/)**. This should already be installed. Open your Terminal and type `which ruby` to confirm.
* **[Rubygems](https://rubygems.org/pages/download)**. This is a package manager for Ruby (gems). Type `which gem` to confirm.
* **[Jekyllrb](http://jekyllrb.com/)**. To install: `gem install jekyll`. Type `which jekyll` to confirm.
* **[Git](http://git-scm.com/download/mac)**. Type `which git` to see if you already have it installed.
* **Text editor** (some examples: Sublime Text, Atom, WebStorm)
* **[Jekyllrb](http://jekyllrb.com/)**. To install: `gem install jekyll`. Type `which jekyll` to confirm that Jekyll is installed.
* **Text editor** (some examples: Sublime Text, Atom, WebStorm, IntelliJ)
* **[iTerm](http://iterm.sourceforge.net/)** - Optional but recommended instead of Terminal.
* **[pygments](http://pygments.org/download/)** - Pygments handles syntax highlighting. In my experiments, the Pygments highlighter seemed better than the default rouge highlighter. To install Pygments, you will need Python installed. (If you don't install pygments, you'll get an error when you build the theme.) To check if Python is installed, type `which python`. To install Pygments: `gem install pygments.rb`. If you want to use `rouge` instead, change `pygments` to `rouge` in the configuration files.
{{warning}} These instructions are designed for users on Macs. Jekyllrb supposedly works on Windows but is not officially supported on that platform. See <a href="Jekyll on Windows">http://jekyllrb.com/docs/windows/</a> for more details. {{end}}
{{warning}} These instructions are designed for users on Macs. Jekyllrb supposedly works on Windows but is not officially supported on that platform. See <a href="http://jekyllrb.com/docs/windows/">Jekyll on Windows"</a> for more details about getting Jekyll working on Windows. {{end}}
## Step 2: Build the theme
Before you start customizing the theme, make sure you can build the theme with the default content and settings first.
1. Make sure you satisfy all the prerequisites as listed in the previous section, "Prerequisites."
2. Download the theme from the [documentation-theme-jekyll Github repository](https://github.com/tomjohnson1492/documentation-theme-jekyll) and unzip it into your ~username/projects folder.
1. Download the theme from the [documentation-theme-jekyll Github repository](https://github.com/tomjohnson1492/documentation-theme-jekyll) and unzip it into your ~username/projects folder.
You can either download the theme files directly by clicking the **Download Zip** button on the right of the repo, or use git to clone the repository to your local machine. Note, however, that you won't be using the pull command to update the theme since you'll be customizing it with your own content and won't want to overwrite those customizations, so there isn't a need to clone it.
3. After downloading the theme, note some unique aspects of the file structure:
* There isn't a \_config.yml file in the root directory because this theme is set up to single source multiple site outputs, not just one version.
* In the configs directory, there's a separate configuration file for each unique output you're building.
* Each configuration file has a different preview port.
* Although there's a \_config.yml file in the root directory, it's there only so that Github Pages will build the theme. Because the theme is set up for single sourcing, there's a separate configuration file for each unique output you're building.
* All the configuration files are stored in the configs directory. Each configuration file has a different preview port.
* Each configuration file specifies a different project and potentially a different audience, product, platform, and version. By setting unique values for these properties in the includes/custom/conditions.html file, you determine how the sidebar and top navigation is constructed.
* You can build all the outputs in your configs directory by running the doc_multibuild_web.sh file in the root directory.
{{tip}} The main goal of this theme is to enable single sourcing. With single sourcing, you build multiple outputs from the same source, with somewhat different content in each site based on the particular product, platform, version, and audience. You don't have to use this theme for single sourcing, but most tech writing projects involve this requirement.{{end}}
In general, you build the sites by using build commands that specify the configuration file, like this:
The doc_multibuild_web.sh file just contains build commands that refer to specific configuration files. Here's how you build the "writers" output:
```
jekyll serve --config configs/config_writer.yml
jekyll serve --config configs/config_writers.yml
```
The `--config` parameter specifies the location of the configuration file to be used in the build. The configuration file itself contains the destination location for where the site gets built.
There are two configuration files in this project: config_writer.yml and config_developer.yml. The idea is that there's an output specific to writers, and an output specific to developers.
There are two configuration files in this project: config_writer.yml and config_designer.yml. The idea is that there's an output specific to writers, and an output specific to developers.
3. In the root directory, you'll find a script called multibuild_web.sh that builds (with `jekyll build`, not `jekyll serve`) both projects with the same command.
4. Open a new tab in iTerm and build an additional output:
In reality, both of these outputs are pretty much the same (except for a theme difference). However, for the writers output, I've conditionally excluded more lengthy explanations about how the theme works. The idea is that writers just want to create and publish content; in contrast, designers want to understand and modify the theme itself.
4. Open a new tab in Terminal and build the designers output:
```
jekyll serve --config configs/config_designer.yml
jekyll serve --config configs/config_designers.yml
```
Open a new tab in your browser and preview the site at the preview URL shown. Notice how the themes differ.
Open a new tab in your browser and preview the site at the preview URL shown. Notice how the themes differ (designers is blue, writers is green).
If the theme builds both outputs successfully, great. You can move on to the other sections. If you run into errors building the basic theme, you must solve them before moving on. See {{troubleshooting}} for more information.
If the theme builds both outputs successfully, great. You can move on to the other sections. If you run into errors building the basic theme, try to solve them before moving on. See {{doc_troubleshooting}} for more information.
{{tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{iterm_profiles}} for details. {{end}}
{{tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{doc_iterm_profiles}} for details. {{end}}
## Questions

View File

@ -1,5 +1,5 @@
---
title: Customizing the theme
title: Theme customization
tags: getting-started
audience: writer, designer
keywords: