HPCE/gitea-pages
HPCE/gitea-pages
0
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Activity

improving instructions

Browse Source
This commit is contained in:
Tom Johnson 2015-04-24 09:58:41 -07:00
parent a149eca341
commit a0ccf6bde4
7 changed files with 157 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

255
.idea/workspace.xml generated
View File

@ -144,51 +144,21 @@
</component>
<component name="FileEditorManager">
<leaf>
<file leaf-file-name="config_writer.yml" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/configs/config_writer.yml">
<file leaf-file-name="build_writer.sh" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/build_writer.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="31" column="30" selection-start-line="31" selection-start-column="30" selection-end-line="31" selection-end-column="30" />
<caret line="2" column="0" selection-start-line="2" selection-start-column="0" selection-end-line="2" selection-end-column="0" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="config_writer_pdf.yml" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/configs/config_writer_pdf.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="28" column="21" selection-start-line="28" selection-start-column="21" selection-end-line="28" selection-end-column="21" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="config_designer_pdf.yml" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/configs/config_designer_pdf.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="29" column="21" selection-start-line="29" selection-start-column="21" selection-end-line="29" selection-end-column="21" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="config_designer.yml" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/configs/config_designer.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="38" column="21" selection-start-line="38" selection-start-column="21" selection-end-line="38" selection-end-column="21" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="getting_started.md" pinned="false" current-in-tab="false">
<file leaf-file-name="getting_started.md" pinned="false" current-in-tab="true">
<entry file="file://$PROJECT_DIR$/pages/overview/getting_started.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-10.862069">
<caret line="21" column="0" selection-start-line="21" selection-start-column="0" selection-end-line="21" selection-end-column="0" />
<state vertical-scroll-proportion="0.21314387">
<caret line="8" column="0" selection-start-line="8" selection-start-column="0" selection-end-line="8" selection-end-column="0" />
<folding />
</state>
</provider>
@ -197,11 +167,11 @@
</provider>
</entry>
</file>
<file leaf-file-name="adding_tooltips.md" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/pages/formatting/adding_tooltips.md">
<file leaf-file-name="troubleshooting.md" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/pages/overview/troubleshooting.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-7.7586207">
<caret line="15" column="0" selection-start-line="15" selection-start-column="0" selection-end-line="15" selection-end-column="0" />
<state vertical-scroll-proportion="-7.462963">
<caret line="38" column="39" selection-start-line="38" selection-start-column="39" selection-end-line="38" selection-end-column="39" />
<folding />
</state>
</provider>
@ -210,41 +180,11 @@
</provider>
</entry>
</file>
<file leaf-file-name="sidebar.yml" pinned="false" current-in-tab="true">
<entry file="file://$PROJECT_DIR$/_data/sidebar.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.9127907">
<caret line="89" column="31" selection-start-line="89" selection-start-column="31" selection-end-line="89" selection-end-column="31" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="customstyles.css" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/css/customstyles.css">
<file leaf-file-name="build_designer.sh" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/build_designer.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="579" column="1" selection-start-line="579" selection-start-column="1" selection-end-line="579" selection-end-column="1" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="glossary.yml" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/_data/glossary.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="0" column="15" selection-start-line="0" selection-start-column="15" selection-end-line="0" selection-end-column="15" />
<folding />
</state>
</provider>
</entry>
</file>
<file leaf-file-name="customscripts.js" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/js/customscripts.js">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="54" column="0" selection-start-line="54" selection-start-column="0" selection-end-line="54" selection-end-column="0" />
<caret line="0" column="0" selection-start-line="0" selection-start-column="0" selection-end-line="0" selection-end-column="109" />
<folding />
</state>
</provider>
@ -255,7 +195,6 @@
<component name="IdeDocumentHistory">
<option name="CHANGED_PATHS">
<list>
<option value="$PROJECT_DIR$/pages/reports/viewing_reports.md" />
<option value="$PROJECT_DIR$/pages/profile_matching/matching_overview.md" />
<option value="$PROJECT_DIR$/printtoc.html" />
<option value="$PROJECT_DIR$/buildfiles/config_resolve_fe.yml" />
@ -286,8 +225,6 @@
<option value="$PROJECT_DIR$/pages/publishing/help_api.md" />
<option value="$PROJECT_DIR$/css/print-header-designer.css" />
<option value="$PROJECT_DIR$/css/print-header-writer.css" />
<option value="$PROJECT_DIR$/pages/overview/troubleshooting.md" />
<option value="$PROJECT_DIR$/pages/publishing/create_pdf.md" />
<option value="$PROJECT_DIR$/pages/formatting/icons.md" />
<option value="$PROJECT_DIR$/pages/special-layouts/kb_layout.md" />
<option value="$PROJECT_DIR$/build_writer.sh" />
@ -300,12 +237,15 @@
<option value="$PROJECT_DIR$/configs/config_writer_pdf.yml" />
<option value="$PROJECT_DIR$/configs/config_designer_pdf.yml" />
<option value="$PROJECT_DIR$/configs/config_designer.yml" />
<option value="$PROJECT_DIR$/pages/overview/getting_started.md" />
<option value="$PROJECT_DIR$/js/customscripts.js" />
<option value="$PROJECT_DIR$/_data/glossary.yml" />
<option value="$PROJECT_DIR$/css/customstyles.css" />
<option value="$PROJECT_DIR$/multibuild.sh" />
<option value="$PROJECT_DIR$/pages/formatting/adding_tooltips.md" />
<option value="$PROJECT_DIR$/_data/sidebar.yml" />
<option value="$PROJECT_DIR$/pages/publishing/create_pdf.md" />
<option value="$PROJECT_DIR$/pages/overview/getting_started.md" />
<option value="$PROJECT_DIR$/pages/overview/troubleshooting.md" />
</list>
</option>
</component>
@ -318,8 +258,8 @@
</component>
<component name="ProjectFrameBounds">
<option name="y" value="23" />
<option name="width" value="1430" />
<option name="height" value="1176" />
<option name="width" value="1280" />
<option name="height" value="736" />
</component>
<component name="ProjectLevelVcsManager" settingsEditedManually="false">
<OptionsSetting value="true" id="Add" />
@ -510,6 +450,20 @@
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.ProjectViewProjectNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="documentation-theme-jekyll" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
<PATH_ELEMENT>
<option name="myItemId" value="_tooltips" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
@ -645,10 +599,10 @@
<servers />
</component>
<component name="ToolWindowManager">
<frame x="0" y="23" width="1430" height="1176" extended-state="0" />
<frame x="0" y="23" width="1280" height="736" extended-state="6" />
<editor active="true" />
<layout>
<window_info id="Project" active="false" anchor="left" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="true" weight="0.17672108" sideWeight="0.5" order="0" side_tool="false" content_ui="combo" />
<window_info id="Project" active="false" anchor="left" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="true" weight="0.19777602" sideWeight="0.5" order="0" side_tool="false" content_ui="combo" />
<window_info id="TODO" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.33" sideWeight="0.5" order="6" side_tool="false" content_ui="tabs" />
<window_info id="Event Log" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.32928678" sideWeight="0.5" order="7" side_tool="true" content_ui="tabs" />
<window_info id="Application Servers" active="false" anchor="bottom" auto_hide="false" internal_type="DOCKED" type="DOCKED" visible="false" weight="0.33" sideWeight="0.5" order="10" side_tool="false" content_ui="tabs" />
@ -707,16 +661,6 @@
<watches-manager />
</component>
<component name="editorHistoryManager">
<entry file="file://$PROJECT_DIR$/pages/special-layouts/kb_layout.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="10" column="136" selection-start-line="10" selection-start-column="136" selection-end-line="10" selection-end-column="136" />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/css/customstyles.css">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
@ -864,13 +808,6 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/sidebar.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="36" column="6" selection-start-line="36" selection-start-column="6" selection-end-line="36" selection-end-column="6" />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/formatting/links.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-0.13729508">
@ -929,16 +866,6 @@
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/publishing/create_pdf.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.8760246">
<caret line="43" column="0" selection-start-line="43" selection-start-column="0" selection-end-line="43" selection-end-column="0" />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_layouts/default_print.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.7033639">
@ -953,16 +880,6 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/overview/troubleshooting.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.09221312">
<caret line="6" column="0" selection-start-line="6" selection-start-column="0" selection-end-line="6" selection-end-column="0" />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/special-layouts/kb_layout.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.14492753">
@ -1009,14 +926,6 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/build_writer.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="0" column="65" selection-start-line="0" selection-start-column="65" selection-end-line="0" selection-end-column="65" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/build_designer_prince.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
@ -1033,14 +942,6 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/build_designer.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="0" column="67" selection-start-line="0" selection-start-column="67" selection-end-line="0" selection-end-column="67" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/configs/config_writer.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
@ -1073,17 +974,6 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/overview/getting_started.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-10.862069">
<caret line="21" column="0" selection-start-line="21" selection-start-column="0" selection-end-line="21" selection-end-column="0" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/js/customscripts.js">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
@ -1108,10 +998,10 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/formatting/adding_tooltips.md">
<entry file="file://$PROJECT_DIR$/pages/publishing/create_pdf.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-7.7586207">
<caret line="15" column="0" selection-start-line="15" selection-start-column="0" selection-end-line="15" selection-end-column="0" />
<state vertical-scroll-proportion="0.9585492">
<caret line="30" column="330" selection-start-line="30" selection-start-column="330" selection-end-line="30" selection-end-column="330" />
<folding />
</state>
</provider>
@ -1121,11 +1011,76 @@
</entry>
<entry file="file://$PROJECT_DIR$/_data/sidebar.yml">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.9127907">
<caret line="89" column="31" selection-start-line="89" selection-start-column="31" selection-end-line="89" selection-end-column="31" />
<state vertical-scroll-proportion="1.4170616">
<caret line="88" column="16" selection-start-line="88" selection-start-column="16" selection-end-line="88" selection-end-column="16" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/sidebar.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.29064038">
<caret line="36" column="6" selection-start-line="36" selection-start-column="6" selection-end-line="36" selection-end-column="6" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/formatting/adding_tooltips.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.29801324">
<caret line="11" column="105" selection-start-line="11" selection-start-column="105" selection-end-line="11" selection-end-column="105" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/multibuild.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.023696683">
<caret line="1" column="73" selection-start-line="1" selection-start-column="73" selection-end-line="1" selection-end-column="73" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/build_writer.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="2" column="0" selection-start-line="2" selection-start-column="0" selection-end-line="2" selection-end-column="0" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/build_designer.sh">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.0">
<caret line="0" column="0" selection-start-line="0" selection-start-column="0" selection-end-line="0" selection-end-column="109" />
<folding />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/overview/troubleshooting.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-7.462963">
<caret line="38" column="39" selection-start-line="38" selection-start-column="39" selection-end-line="38" selection-end-column="39" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/pages/overview/getting_started.md">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="0.21314387">
<caret line="8" column="0" selection-start-line="8" selection-start-column="0" selection-end-line="8" selection-end-column="0" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
</component>
</project>

4
_data/sidebar.yml
View File

@ -86,9 +86,9 @@ entries:
audience: writer, designer
print: true
- title: Adding Tooltips
- title: Tooltips
url: /adding_tooltips/
add: writer, designer
audience: writer, designer
print: true

2
multibuild.sh Normal file
View File

@ -0,0 +1,2 @@
jekyll build --config configs/config_writer.yml --destination ../documentation-theme-jekyll-builds/writer
jekyll build --config configs/config_designer.yml --destination ../documentation-theme-jekyll-builds/designer

7
pages/formatting/adding_tooltips.md
View File

@ -7,12 +7,13 @@ You can add tooltips to your content. Because this theme is built on Bootstrap,
Suppose you have a glossary.yml file inside your _data folder. You could pull in that glossary definition like this:
{% raw %}
```html
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll is my favorite tool for building websites.</a>
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.</a>
```
{% endraw %}
This renders to the following:
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll is my favorite tool for building websites.</a>
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.</a>

27
pages/overview/getting_started.md
View File

@ -9,41 +9,48 @@ audience: writer, designer
* 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.
* [Rubygems](https://rubygems.org/pages/download). This is a package manager for Ruby (gems).
* [Jekyllrb](http://jekyllrb.com/). To install: `gem install jekyll`
* [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)
* [iTerm](http://iterm.sourceforge.net/) - optional but recommended instead of Terminal.
* [pygments](http://pygments.org/download/) - Pygments handles syntax highlighting. In my experiments, the highlighting seemed better than the default rouge. To install Pygments, you will need Python installed. (If you don't install pygments, you'll get an error when you build the theme.)
* [pygments](http://pygments.org/download/) - Pygments handles syntax highlighting. In my experiments, the highlighting 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.)
{{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}}
## Build the theme
Because this theme is intended to build multiple outputs from the same project, it doesn't use the default _config.yml file like other Jekyll themes. Instead, each different output has its own config file in the configs directory.
{{important}} Because this theme is intended to build multiple outputs from the same project, it doesn't use the default _config.yml file like other Jekyll themes. Instead, each different output has its own config file in the configs directory. As a result, you can't type `jekyll serve` to build the theme, since this command looks for the _config.yml file in your project directory.{{end}}
Each config file has a different preview port and build destination. It also specifies a different audience.
1. Download the theme from the [documentation-theme-jekyll Github repository](https://github.com/tomjohnson1492/documentation-theme-jekyll).
You can either download it directly by clicking the **Download Zip** button on the right, 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.
2. Note some unique aspects of this theme: *There's a separate config file for each unique output you're building.* Each config file has a different preview port and build destination. It also specifies a different audience.
You build the sites by using more specific build commands, like this:
In general, you build the sites by using more specific 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_writer.yml --destination ../documentation-theme-jekyll-builds/writer
```
Because these commands are long and bulky, it's easier to store them in a small shell script and then run the script. In the root directory, you'll find build_writer.sh, which simply contains this build argument. Instead of running the command above, run the following:
Because these commands are long and bulky, it's easier to store them in a small shell script and then run the script.
3. In the root directory, you'll find build_writer.sh, which simply contains this build argument. Instead of running the command above, run the following:
```
. build_writer.sh
```
If you run into permissions errors trying to run the .sh file, you may need to change the file permissions to make the sh file executable. To do that, browse to the directory containing build_writer.sh and run the following:
If you run into permissions errors trying to run the .sh file, you may need to change the file permissions to make the sh file executable. If you find you need to make the file writable (because iTerm won't execute it), browse to the directory containing build_writer.sh and run the following:
```
chmod +x build_writer.sh
```
If the theme builds successfully, great. You can move on to the next section: Customizing the theme. If you run into errors building the basic theme, you must solve them before moving on. See {{troubleshooting}} for more information.
## Customizing the theme
The theme shows two build outputs: one for designers, and one for writers. Here's how you would customize the theme. In these instructions, I'll assume your project's name is "acme."
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. Here's how you would customize the theme.
{{important}} In these instructions, I'll assume your project's name is "acme."{{end}}
1. Using iTerm, create the directory where you want to install the project. I like using ~[username]/projects, because ~[username] is the default directory that appears when you open iTerm on a Mac.

24
pages/overview/troubleshooting.md
View File

@ -3,9 +3,11 @@ title: Troubleshooting
permalink: /troubleshooting/
---
## Address already in use
## Issues building the site
When you try to build the site, you get this error:
### Address already in use
When you try to build the site, you get this error in iTerm:
```
jekyll 2.5.3 | Error: Address already in use - bind(2)
@ -20,8 +22,22 @@ Find the PID (for example, it looks like "22298").
Then type `kill -9 22298` where "22298" is the PID.
## "page 0" cross references in the PDF
### Pygments not installed
The config file requires pygments for the highlighter. You must [download and install Pygments]([pygments](http://pygments.org/download/)), which requires Python, in order to use this syntax highlighter. If you don't want to bother with Pygments, open the configuration file and change `pygments` to `rouge`.
## PDF issues
### "page 0" cross references in the PDF
If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build.
If it's not a page but rather a file, you need to add a class to the file so that your print stylesheet excludes the counter from it. Try adding `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class.
### The PDF is blank
Check the prince-file-list.txt file in the output to see if it contains links. If not, you have something wrong with the logic in the prince-file-list.txt file. Check the conditions.html file in your _includes to see if the audience specified in your configuration file aligns with the buildAudience in the conditions.html file
If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build. If it's not a page but rather a file, you need to add a class to the file so that your print stylesheet excludes the counter from it. Try adding `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class.

3
pages/publishing/create_pdf.md
View File

@ -3,7 +3,7 @@ title: Create PDF
permalink: /create_pdf/
tags: publishing
---
{% include linkrefs.html %}
{% comment %}
remaining tasks:
@ -28,6 +28,7 @@ This process for creating a PDF relies on Prince to transform the HTML content i
3. In the css folder, open the print-header-writer.css and print-header-designer.css files. Change the filenames to your audiences. Customize what appears in each of the page margins.
4. In the default_print.html file in the layout folder, customize the conditional logic to match your audience with the stylesheets you created in the previous step.
5. In the _data folder, open sidebar.yml and add `print: true` for each page that you want to appear in the print version. (The pages in the topnav aren't pushed to PDF, so if you need some of the pages there, add them to the sidebar and add a `web: false` property to each of them (in addition to a `print: true` property).)
{{note}} In addition to adding the right audience to the page, you must also add the audience to the section's audience attribute. This is because the theme logic first checks whether the section contains the right audience attribute, and then checks whether the items in that section have the right audience attribute.{{end}}
6. In the project's root directory, the logic in the prince-file-list.txt will pull all files from the sidebar.yml file to be included in the PDF. You can adjust any of the logic there as needed, but you shouldn't need to do anything to the file.
5. In the root directory, rename the build_writer_pdf.sh file and customize its contents to point to the right paths on your computer.
5. In the root directory, rename the build_writer_prince.sh file and customize the input and output directories. The input should point to where this project builds, so the script can find the processed prince-file-list.txt file and so it knows where to build the output.