From a0ccf6bde4f3bb0f636f032bf4546af91f0bdef5 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Fri, 24 Apr 2015 09:58:41 -0700 Subject: [PATCH] improving instructions --- .idea/workspace.xml | 255 ++++++++++++---------------- _data/sidebar.yml | 4 +- multibuild.sh | 2 + pages/formatting/adding_tooltips.md | 7 +- pages/overview/getting_started.md | 37 ++-- pages/overview/troubleshooting.md | 24 ++- pages/publishing/create_pdf.md | 3 +- 7 files changed, 157 insertions(+), 175 deletions(-) create mode 100644 multibuild.sh diff --git a/.idea/workspace.xml b/.idea/workspace.xml index f0405c4..46a309d 100644 --- a/.idea/workspace.xml +++ b/.idea/workspace.xml @@ -144,51 +144,21 @@ - - + + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - + + @@ -197,11 +167,11 @@ - - + + - - + + @@ -210,41 +180,11 @@ - - - - - - - - - - - - + + - - - - - - - - - - - - - - - - - - - - - + @@ -255,7 +195,6 @@ @@ -318,8 +258,8 @@ @@ -510,6 +450,20 @@ - + - + @@ -707,16 +661,6 @@ - - - - - - - - - - @@ -864,13 +808,6 @@ - - - - - - - @@ -929,16 +866,6 @@ - - - - - - - - - - @@ -953,16 +880,6 @@ - - - - - - - - - - @@ -1009,14 +926,6 @@ - - - - - - - - @@ -1033,14 +942,6 @@ - - - - - - - - @@ -1073,17 +974,6 @@ - - - - - - - - - - - @@ -1108,10 +998,10 @@ - + - - + + @@ -1121,11 +1011,76 @@ - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/_data/sidebar.yml b/_data/sidebar.yml index d1e69c5..9bf6fe7 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -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 diff --git a/multibuild.sh b/multibuild.sh new file mode 100644 index 0000000..3a7b91b --- /dev/null +++ b/multibuild.sh @@ -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 \ No newline at end of file diff --git a/pages/formatting/adding_tooltips.md b/pages/formatting/adding_tooltips.md index 0fe91d3..3d9ebcc 100644 --- a/pages/formatting/adding_tooltips.md +++ b/pages/formatting/adding_tooltips.md @@ -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 -Jekyll is my favorite tool for building websites. +Jekyll is my favorite tool for building websites. ``` +{% endraw %} This renders to the following: -Jekyll is my favorite tool for building websites. +Jekyll is my favorite tool for building websites. diff --git a/pages/overview/getting_started.md b/pages/overview/getting_started.md index f72c2e1..24c5243 100644 --- a/pages/overview/getting_started.md +++ b/pages/overview/getting_started.md @@ -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 http://jekyllrb.com/docs/windows/ 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. - -You build the sites by using more specific build commands, like this: +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. + + In general, you build the sites by using more specific build commands, like this: + ``` +jekyll serve --config configs/config_writer.yml --destination ../documentation-theme-jekyll-builds/writer ``` -jekyll serve --config configs/config_writer.yml --destination /users/tjohnson/projects/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. diff --git a/pages/overview/troubleshooting.md b/pages/overview/troubleshooting.md index f130a4e..243db91 100644 --- a/pages/overview/troubleshooting.md +++ b/pages/overview/troubleshooting.md @@ -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 - 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 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 + + diff --git a/pages/publishing/create_pdf.md b/pages/publishing/create_pdf.md index 4e82a30..5ee4c13 100644 --- a/pages/publishing/create_pdf.md +++ b/pages/publishing/create_pdf.md @@ -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.