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

content update

Browse Source
This commit is contained in:
Tom Johnson
2015-04-20 16:59:09 -07:00
parent 5b5bf8858e
commit 503d452ea5
3 changed files with 37 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
_includes/conditions.html
View File

@ -10,6 +10,6 @@
{% assign sidebar = site.data.sidebar.entries %}
{% assign topnav = site.data.topnav.topnav %}
{% assign topnav_dropdowns = site.data.topnav.topnav_dropdowns %}
{% assign fileName = "designer_guide %}
{% assign fileName = "designer_guide" %}
{% endif %}

23
index.md
View File

@ -6,30 +6,28 @@ tags: overview
{% include linkrefs.html %}
{% if site.audience == "writer" %}
{{note}} This is the version of the documentation designed for writers.{{end}}
{{note}} This is the version of the documentation designed for writers. It has a subset of topics from the designers output.{{end}}
{% endif %}
{% if site.audience == "designer" %}
{{note}} This is the version of the documentation designed for designers.{{end}}
{{note}} This is the version of the documentation designed for designers. The set of topics included here is comprehensive.{{end}}
{% endif %}
This is a Jekyll theme intended for documentation projects. What makes this theme unique is the approach in using Jekyll for single sourcing, that is, producing multiple outputs from the same theme. For example, you might have 3 different help systems that you're generating from the same Jekyll files. More than anything, this Jekyll theme shows you how to use Jekyll for documentation projects from the perspective of a technical writer.
{{note}} I'm using this theme for my own technical writing projects, so this is an evolving project.{{end}}
Note that I'm using this theme for my own technical writing projects, so this is an evolving project.
## Intended audience
Although this theme could be used for any website, I'm assuming that my main audience involves technical writers. Very few technical writers are even aware of Jekyll as a platform, let alone how to use it for tech comm scenarios. The instructions for this theme, therefore, are extensive because they discuss a lot of Jekyll basics as well. I'm not going to assume that you're already familiar with Jekyll, or that you're a UX guru, or that you know how to do backflips in Liquid. I'll try to hold your hand as much as possible.
## Supported tech comm features with Jekyll
## Supported features
As far as I can tell, Jekyll supports most of the features a technical writer needs to author and publish content. See {{supported_features}} for an extensive list. Most importantly, using Jekyll allows you to take full advantage of a modern web development platform.
As far as I can tell, Jekyll supports most of the features a technical writer needs to author and publish content. Most importantly, using Jekyll allows you to take full advantage of a modern web development platform.
## Theme features
This theme specifically provides the following:
As a quick overview, this theme specifically provides the following:
* Bootstrap framework with responsive design
* Integrated search
@ -37,6 +35,8 @@ This theme specifically provides the following:
* Font Awesome
* Options for creating multiple builds for different audiences
See {{supported_features}} for an extensive list.
## Getting started
To get started, see {{getting_started}}. It explains how to create a new project.
@ -46,10 +46,3 @@ To get started, see {{getting_started}}. It explains how to create a new project
Feel free to ask me a question if there's something I haven't addressed here.
Tom Johnson <br /><a href="mailto:">tomjohnson1492@gmail.com</a>

38
pages/getting_started.md → pages/overview/getting_started.md
View File

@ -44,22 +44,40 @@ chmod +x build_writer.sh
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."
1. Using iTerm, go to 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.
2. git clone `https://github.com/tomjohnson1492/documentation-theme-jekyll.git .`
3. Rename the documentation-theme-jekyll folder to acme.
4. In the theme's configs directory, rename config_writer.yml to config_acme.yml and customize all the values based on the instructions in that file. Do the same with config_designer.yml if you have additional outputs.
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.)
5. Add your pages inside the pages folder. (Using subfolders and sub-subfolders inside pages is all right -- you don't have to worry about folder paths in links.)
5. Inside _data, open sidebar.yml and topnav.yml and customize the navigation. (Don't mess up the spacing or change any of the level names or the site won't build.)
6. In the root directory, rename build_writer.sh to build_acme.sh (same with build_designer.sh for additional outputs). In the file's contents, change the build parameters to point to the configuration file and destination/output directory that you want.
6. Build your site with `. build_writer.sh` and preview it at the URL provided.
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
```
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 the config file for other audiences.
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.
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.)
6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside pages 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 destination/output directory that you want. The `--config` parameter specifies the directory where the build reads the configuration file, and the `-o` parameter specifies the directory where the PDF is built.
{{note}} See <a href="{{ /create_pdf | prepend: site.baseurl }}">Creating a PDF</a> for more details on creating PDF documents. 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 each of your projects. Use conditional tags 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. In t he _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags.
11. Build your site with `. build_writer.sh` and preview it at the URL provided.
If you have 10 different outputs, you'll have 10 separate configuration files in your configs directory, and probably 10 different shell scripts containing build arguments for each configuration.
{{callout_info}}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 host.{{end}}
{{callout_info}}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).