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 11:28:19 -07:00
parent a0ccf6bde4
commit a44149986a
6 changed files with 143 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
.idea/workspace.xml generated
View File

@ -157,8 +157,8 @@
<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="0.21314387">
<caret line="8" column="0" selection-start-line="8" selection-start-column="0" selection-end-line="8" selection-end-column="0" />
<state vertical-scroll-proportion="0.77264655">
<caret line="95" column="284" selection-start-line="95" selection-start-column="284" selection-end-line="95" selection-end-column="284" />
<folding />
</state>
</provider>
@ -167,11 +167,34 @@
</provider>
</entry>
</file>
<file leaf-file-name="linkrefs.html" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/_includes/linkrefs.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-5.0">
<caret line="8" column="101" selection-start-line="8" selection-start-column="101" selection-end-line="8" selection-end-column="101" />
<folding />
</state>
</provider>
</entry>
</file>
<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.462963">
<caret line="38" column="39" selection-start-line="38" selection-start-column="39" selection-end-line="38" selection-end-column="39" />
<state vertical-scroll-proportion="-5.240741">
<caret line="48" column="1" selection-start-line="48" selection-start-column="1" selection-end-line="48" selection-end-column="1" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
</file>
<file leaf-file-name="use_git_to_download_theme.md" pinned="false" current-in-tab="false">
<entry file="file://$PROJECT_DIR$/_drafts/use_git_to_download_theme.md">
<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="0" />
<folding />
</state>
</provider>
@ -195,8 +218,6 @@
<component name="IdeDocumentHistory">
<option name="CHANGED_PATHS">
<list>
<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" />
<option value="$PROJECT_DIR$/buildfiles/config_resolve_customer.yml" />
<option value="$PROJECT_DIR$/buildfiles/config_resolve_customer_print.yml" />
@ -244,8 +265,10 @@
<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$/_includes/linkrefs.html" />
<option value="$PROJECT_DIR$/pages/overview/troubleshooting.md" />
<option value="$PROJECT_DIR$/_drafts/2015-02-05-troubleshooting.md" />
<option value="$PROJECT_DIR$/pages/overview/getting_started.md" />
</list>
</option>
</component>
@ -492,6 +515,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="_drafts" />
<option name="myItemType" value="com.intellij.ide.projectView.impl.nodes.PsiDirectoryNode" />
</PATH_ELEMENT>
</PATH>
<PATH>
<PATH_ELEMENT>
<option name="myItemId" value="resolve" />
@ -661,14 +698,6 @@
<watches-manager />
</component>
<component name="editorHistoryManager">
<entry file="file://$PROJECT_DIR$/css/customstyles.css">
<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="0" />
<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="0.0">
@ -828,13 +857,6 @@
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/linkrefs.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-15.0">
<caret line="25" column="106" selection-start-line="25" selection-start-column="106" selection-end-line="25" selection-end-column="106" />
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/titlepage.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-4.2083335">
@ -1060,10 +1082,29 @@
</state>
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_includes/linkrefs.html">
<provider selected="true" editor-type-id="text-editor">
<state vertical-scroll-proportion="-5.0">
<caret line="8" column="101" selection-start-line="8" selection-start-column="101" selection-end-line="8" selection-end-column="101" />
<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" />
<state vertical-scroll-proportion="-5.240741">
<caret line="48" column="1" selection-start-line="48" selection-start-column="1" selection-end-line="48" selection-end-column="1" />
<folding />
</state>
</provider>
<provider editor-type-id="MarkdownPreviewEditor">
<state />
</provider>
</entry>
<entry file="file://$PROJECT_DIR$/_drafts/use_git_to_download_theme.md">
<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="0" />
<folding />
</state>
</provider>
@ -1073,8 +1114,8 @@
</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" />
<state vertical-scroll-proportion="0.77264655">
<caret line="95" column="284" selection-start-line="95" selection-start-column="284" selection-end-line="95" selection-end-column="284" />
<folding />
</state>
</provider>

6
_drafts/2015-02-05-troubleshooting.md
View File

@ -1,6 +0,0 @@
---
title: "Knowledgebase Article"
tags: troubleshooting
---
This post is a placeholder for troubleshooting content and knowledge-base style articles. These kinds of articles will appear here.

10
_drafts/use_git_to_download_theme.md Normal file
View File

@ -0,0 +1,10 @@
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.
```
cd projects
mkdir acme
cd acme
```
2. Once you're inside the folder for your project (for example, acme), type `git clone https://github.com/tomjohnson1492/documentation-theme-jekyll.git .` (The ` .` means to clone the github repo into the current directory. Make sure the directory is empty before cloning the theme in there.)
3. In your new project folder, remove the .git folder, because no doubt you'll be customizing this project's content and committing it to another revision control repository.

2
_includes/linkrefs.html
View File

@ -6,6 +6,8 @@
{% comment %}<!-- OVERVIEW --> {% endcomment %}
{% capture getting_started %}<a href="{{"/getting_started" | prepend: site.baseurl}}">Getting Started</a>{% endcapture %}
{% capture supported_features %}<a href="{{"/supported_features" | prepend: site.baseurl}}">Supported Features</a>{% endcapture %}
{% capture troubleshooting %}<a href="{{"/troubleshooting" | prepend: site.baseurl}}">Troubleshooting</a>{% endcapture %}
{% comment %}<!-- FORMATTING --> {% endcomment %}
{% capture pages %}<a href="{{"/pages" | prepend: site.baseurl}}">Pages</a>{% endcapture %}

102
pages/overview/getting_started.md
View File

@ -5,7 +5,9 @@ tags: getting-started
audience: writer, designer
---
{% include linkrefs.html %}
## Prerequisites
## Step 1: Install all the prerequisites
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.
@ -13,79 +15,85 @@ audience: writer, designer
* [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 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.)
* [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`.
{{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
## Step 2: Build the theme
{{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}}
{{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, and there isn't one there.{{end}}
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.
1. Make sure you satisfy all the prerequisites as listed in the previous section, "Prerequisites."
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 huge need to clone or fork it.
2. After downloading the theme, note some unique aspects of the file structure: *Inside the configs folder, there's a separate config file for each unique output you're building.* Each config file has a different preview port and build destination. Each config file also specifies a different audience. The whole point of this theme is to enable single sourcing, which allows you to build multiple outputs from the same source. That's why there are separate config files for each output.
In general, you build the sites by using more specific build commands, like this:
In general, you build the sites by using build commands that specify the config file and destination , like this:
```
jekyll serve --config configs/config_writer.yml --destination ../documentation-theme-jekyll-builds/writer
```
The `--config` parameter specifies the location of the configuration file to be used in the build, and the `--destination` parameter specifies where you want the site to be built.
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:
3. In the root directory, you'll find build_writer.sh, which is a simple shell script containing 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. 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. 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.
```
cd projects
mkdir acme
cd acme
. build_writer.sh
```
2. Once you're inside the folder for your project (for example, acme), type `git clone https://github.com/tomjohnson1492/documentation-theme-jekyll.git .` (The ` .` means to clone the github repo into the current directory. Make sure the directory is empty before cloning the theme in there.)
3. In your new project folder, remove the .git folder, because no doubt you'll be customizing this project's content and committing it to another revision control repository.
4. In the theme's configs directory, rename config_writer.yml to config_[your audience].yml and customize all the values inside that file based on the instructions in that file. Do the same with config_designer.yml and continue to clone and customize the config file for other audiences.
Preview the site at the preview URL shown.
In this theme, each output requires an individual config file. Each print output requires a separate config file. If you have 10 audiences and you want both web and PDF outputs for each audience, then you'll have 20 config files in this directory.
4. Open a new tab in iTerm and build an additional output:
5. In the _includes directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with your audience, and `designer` with another audience.) The conditions.html file is used to apply different audience requirements to the sidebar and other files.
6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside the pages folder is all right -- you don't have to worry about folder paths in links.)
7. Inside _data, open sidebar.yml and topnav.yml and customize the navigation. (Don't mess up the spacing or change any of the YML level names or the site or sidebar won't build.)
8. In the root directory, rename build_writer.sh to build_[your audience].sh (same with build_designer.sh for additional outputs). In the files' contents, change the build parameters to point to the configuration file and output directory that you want.
```
. build_designer.sh
```
Open a new tab in your browser and preview the site at the preview URL shown.
{{note}} When you're just starting out, don't worry about setting up the PDF builds. This workflow is more complicated and somewhat touchy. See {{create_pdf}} for more details. You will need to set up Prince in order for the PDF build to work. {{end}}
If the theme builds both outputs 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.
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.audience == "writer" ...`) to change the content for different builds of your site. See {{conditional_logic}} for more information.
## Step 3: Customize the theme
{{note}} Before you start customizing the theme, make sure you can build the theme by following the instructions in the previous section, "Step 2: Build the theme." {{end}}
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}}
1. If you haven't already downloaded the theme, see the previous section, "Step 2: Build the theme." Press Ctrl+C to stop the previews.
1. In the theme's configs directory, rename config_writer.yml to config_developer.yml and customize all the values inside that file based on the instructions in that file. Do the same with config_designer.yml (changing it to config_marketer.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.
{{tip}} As you customize the config files, make the port values unique so that you don't run into "Address already in use" issues when you build multiple sites and want to preview them at the same time.{{end}}
5. In the _includes directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with your developer, and `designer` with another marketer.)
The conditions.html file is used to apply different audience 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.
6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside the pages folder is fine -- you won't have to worry about folder paths in links.)
7. Inside _data, open sidebar.yml and topnav.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.) {{end}}
8. In the root directory, rename build_writer.sh to build_developer.sh (same with build_designer.sh; change it to build_marketer.sh). In the content of each of these files, change the build parameters to point to the configuration file and output directory that you want.
{{note}} When you're just starting out, don't worry about setting up the PDF builds. This workflow for PDFs is more complicated and somewhat touchy. See {{create_pdf}} for more details. You will need to set up Prince in order for the PDF build to work. {{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.audience == "developer" ...`) to change the content for different builds of your site. See {{conditional_logic}} for more information.
10. In the _includes folder, open linkrefs.html and add capture tags for all the pages in your site following the sample format shown. This will make it easy to link to each of the topics. (Don't remove the capture tags for the alerts and callouts.)
11. For each of your pages where you want to insert a link, note, or callout, add {%raw%}`{% include linkrefs.html %}`{%endraw%} directly below the frontmatter.
12. In the _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags as you did on index.md.
12. In the layouts folder, open page.html and customize the values in the `site.show_audience_label` section. These are labels that appear on the page based on the audience attributes in the frontmatter for that page. If you want these shown, make sure you have `true` set for the `site.show_audience_label` property in your config file.
11. Build your site with `. build_acme.sh` and preview it at the URL provided.
12. In the _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags as you did with index.md.
12. In the layouts folder, open page.html and customize the values in the `site.show_audience_label` section. These are labels that appear on the page based on the audience attributes in the frontmatter for that page. If you want audiencd tags shown, make sure you have `true` set for the `site.show_audience_label` property in your config file. Each of your pages will need an audience property in the frontmatter.
11. Build your site with `. build_developer.sh` and `. build_marketer.sh` 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}}
## Questions
If you have questions, contact me at tomjohnson1492@gmail.com. My regular site is [http://idratherbewriting.com](idratherbewriting.com).
If you have questions, contact me at tomjohnson1492@gmail.com. My regular site is [http://idratherbewriting.com](idratherbewriting.com). I'm eager to make these installation instructions as clear as possible, so please let me know if there are areas of confusion that need clarifying.

9
pages/overview/troubleshooting.md
View File

@ -22,6 +22,14 @@ Find the PID (for example, it looks like "22298").
Then type `kill -9 22298` where "22298" is the PID.
### build_writer.sh file not executable
If you run into permissions errors trying to run the build_writer.sh file, you may need to change the file permissions to make the sh file executable. Browse to the directory containing build_writer.sh and run the following:
```
chmod +x build_writer.sh
```
### 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`.
@ -39,5 +47,6 @@ The config file requires pygments for the highlighter. You must [download and in
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