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

committing new version of jekyll doc theme -- 5.0, with some refinements to come with the documentation

Browse Source
This commit is contained in:
tomjohnson1492
2016-03-19 00:13:09 -07:00
parent e267cce513
commit 7a869d7cd4
206 changed files with 16935 additions and 37629 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
mydoc/mydoc_getting_started.md
View File

@ -1,96 +1,175 @@
---
title: 1. Build the default project
title: Getting started
tags: [getting_started]
keywords: start, introduction, begin, install, build, hello world,
last_updated: November 30, 2015
summary: "To get started with this theme, first make sure you have all the prerequisites in place; then build the theme following the sample build commands. Because this theme is set up for single sourcing projects, it doesn't follow the same pattern as most Jekyll projects (which have just a _config.yml file in the root directory)."
last_updated: March 20, 2016
summary: "To get started with this theme, first make sure you have all the prerequisites in place; then build the theme following the sample build commands."
series: "Getting Started"
weight: 1
sidebar: mydoc_sidebar
permalink: /mydoc_getting_started/
---
{% include custom/mydoc/getting_started_series.html %}
## Set up the prerequisites
## Getting up and running
Before you start installing the theme, make sure you have all of these prerequisites in place.
To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/).
* **Mac computer**. If you have a Windows machine, make sure you can get a vanilla Jekyll site working before proceeding. You'll probably need Ruby and Ruby Dev Kit installed first. Also note that the shell scripts (.sh files) in this theme for automating the builds work only on a Mac. To run them on Windows, you need to convert them to BAT.
* **[Ruby](https://www.ruby-lang.org/en/)**. On a Mac, 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. Type `which gem` to confirm.
* **Text editor**: My recommendations is WebStorm (or IntelliJ). You can use another text editor. However, there are certain shortcuts and efficiencies in WebStorm (such as using Find and Replace across the project, or Markdown syntax highlighting) that I'll be noting in this documentation.
If you're in Windows, you might want to [install Jekyll using Chocolately](https://www.google.com/search?q=install+jekyll+using+chocolately).
I added a page called {{site.data.mydoc.mydoc_urls.mydoc_install_dependencies.link}} that explains how to install any necessary RubyGem dependencies in case you run into errors.
After ensuring you can run Jekyll on your machine, you can build this site using the usual Jekyll command: `jekyll serve`.
## Build the default project
## Configuring the theme
Before you start customizing the theme, make sure you can build the theme with the default content and settings first.
There are several products in this theme. Each product uses a different sidebar. This is the essence of what makes this theme unique -- different sidebars for different product documentation. The idea is that when users are reading documentation for a specific product, the sidebar navigation should be specific to that product. The top navigation remains the same, because it allows users to navigate across products. But the sidebar navigation adapts to the product.
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.
2. After downloading the theme, note some unique aspects of the file structure:
* 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. If you want, you can build and preview all your outputs simultaneously in different preview servers.
* 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 get constructed.
* A variety of shell scripts (.sh files) in the project's root directory automate the building and publishing of both the web and PDF files. After you configure the scripts, you can execute all the scripts through the master shell script, mydoc_all.sh.
* "mydoc" is the name of the documentation project. You can leave the mydoc content in the theme. It won't affect the other projects you add to the theme.
{{site.data.alerts.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 output 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 require this. If you're not a technical writer or not creating documentation, this theme is probably not for you. It doesn't have any post features coded, just pages.{{site.data.alerts.end}}
There are four configuration files in this project: config_writers.yml and config_designers.yml as well as their PDF equivalents. The idea is that there's an output specific to writers, and an output specific to designers.
In reality, both of these outputs are pretty much the same. I mainly incorporated two outputs here mainly to demonstrate how the single sourcing works.
## Where to store your documentation topics
3. Unless you're planning to publish on Github Pages, you can delete the Gemfile. The Gemfile is only in this project to allow publishing on Github Pages.
The theme is not using a Gemfile to manage project dependencies. Although theoretically the Gemfile should make things easier, I've found that it tends to give users more errors than they need. Add to this the incompatibility of Github Pages with Jekyll 3.0 and the Gemfile becomes even more problematic.
Store your files for each product inside subfolders following the pattern shown in the theme. For example, product1, product2, etc. You can store your topics inside sub-subfolders to your heart's content. When Jekyll builds your site, it will pull the topics into the root directory and use the permalink for the URL.
4. Install the [Jekyll](https://rubygems.org/gems/jekyll), [redcarpet](https://rubygems.org/gems/redcarpet), and [pygments](https://rubygems.org/gems/pygments.rb) gems.
These gems are the only ones the project uses. Go to the [Rubygems site](https://rubygems.org) for each of these gems (based on the links above). In the right column, click the "INSTALL" command and paste the copied command into your terminal. If your computer gives you permissions errors, add `sudo` before the command.
5. In your terminal, browse to the documentation-theme-jekyll folder that you downloaded.
6. Build the writer's output:
```
jekyll serve --config configs/mydoc/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.
Open a new tab in your browser and preview the site at the preview URL shown.
7. Press **Ctrl+C** in Terminal to shut down the writer's preview server.
8. Build the designers output:
```
jekyll serve --config configs/mydoc/config_designers.yml
```
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).
## Configuring the sidebar
9. Press **Ctrl+C** in Terminal to shut down the designer's preview server.
10. Build both themes by running the following command:
Because each product uses a different sidebar, you'll need to set up your sidebars. There's a file inside \_includes/custom called "sidebarconfigs.html". This file controls which sidebar gets associated with which product.
```
. mydoc_3_multibuild_web.sh
```
The themes build in the `../doc_outputs/mydoc/mydoc_designers` and `../doc_outputs/mydoc/mydoc_writers` folders. Browse to these directories to view the output.
Open the writers and designers folders and click the index.html file. The themes should launch and appear similar to their appearance in the preview folder. This is because the themes are built using a relative link structure, so you can move the theme to any folder you want without breaking the links.
If the theme builds both outputs successfully, great. You can move on to the other sections. If you run into errors building the themes, solve them before moving on. See {{site.data.mydoc.mydoc_urls.mydoc_troubleshooting.link}} for more information.
{{site.data.alerts.tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{site.data.mydoc.mydoc_urls.mydoc_iterm_profiles.link}} for details. {{site.data.alerts.end}}
More information about building the PDF versions is provided in {{site.data.mydoc.mydoc_urls.mydoc_generating_pdfs.link}}.
The sidebarconfigs.html file uses simple `if elsif` logic to set a variable that the sidebar.html file uses to read the sidebar data file. The code in sidebarconfigs.html looks like this:
## Questions
{% raw %}
```liquid
{% if page.sidebar == "home_sidebar" %}
{% assign sidebar = site.data.sidebars.home_sidebar.entries %}
If you have questions, contact me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. My regular site is [idratherbewriting.com](http://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.
{% elsif page.sidebar == "product1_sidebar" %}
{% assign sidebar = site.data.sidebars.product1_sidebar.entries %}
{% elsif page.sidebar == "product2_sidebar" %}
{% assign sidebar = site.data.sidebars.product2_sidebar.entries %}
{% elsif page.sidebar == "mydoc_sidebar" %}
{% assign sidebar = site.data.sidebars.mydoc_sidebar.entries %}
{% elsif page.sidebar == "tags_sidebar" %}
{% assign sidebar = site.data.sidebars.tags_sidebar.entries %}
{% else %}
{% assign sidebar = site.data.sidebars.home_sidebar.entries %}
{% endif %}
```
{% endraw %}
In each page's frontmatter, you must specify the sidebar you want that page to use. Here's an example of the page frontmatter showing the sidebar property:
```
---
title: Alerts
tags: [formatting]
keywords: notes, tips, cautions, warnings, admonitions
last_updated: March 20, 2016
summary: "You can insert notes, tips, warnings, and important alerts in your content. These notes are stored as shortcodes made available through the linksrefs.hmtl include."
sidebar: mydoc_sidebar
permalink: /mydoc_alerts/
---
```
The `sidebar: mydoc_sidebar` refers to the \_data/sidebars/mydoc_sidebar.yml file.
If no sidebar assignment is found in the page frontmatter, the default sidebar (specified by the `else` statement) will be shown: `site.data.sidebars.home_sidebar.entries`.
Note that your sidebar can only have 2 levels. Given that each product has its own sidebar, this depth should be sufficient. Deeper nesting goes against usability recommendations.
## Sidebar syntax
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown:
```yaml
- title: Overview
output: web, pdf
items:
- title: Mydoc home
url: /mydoc_landing_page/
output: web
```
Each heading must contain a title and output property. Each item must contain a title, url, and output property.
The two outputs available are web and pdf. (Even if you aren't publishing PDF, you still need to specify `output: web`).
The YAML syntax depends on exact spacing, so make sure you follow the pattern shown in the sample sidebars. See my [YAML tutorial](mydoc_yaml_tutorial) for more details about how YAML works.
To accommodate the title page and table of contents in PDF outputs, each product sidebar must list these pages before any other:
```yaml
- title:
output: pdf
type: frontmatter
items:
- title:
url: /titlepage/
output: pdf
type: frontmatter
- title:
url: /tocpage/
output: pdf
type: frontmatter
```
Leave the output as `output: pdf` so that they don't appear in the web output.
## Page frontmatter
When you write pages, include this same frontmatter in each page:
```yaml
---
title: "Some title"
tags: [sample1, sample2]
keywords: keyword1, keyword2, keyword3
last_updated: Month day, year
summary: "optional summary here"
sidebar: sidebar name
permalink: /yoururl/
---
```
(If you're using Webstorm, you can set up a template to auto-populate this code when you create a new file.)
For titles, surrounding the title in quotes is optional, but if you have a colon in the title, you must surround the title with quotation marks.
Keywords get populated into the metadata of the page for SEO.
Tags must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.)
```
If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: none` in the frontmatter.
## Configure the top navigation
The top navigation bar's menu items are set through the _data/topnav.yml file. Use the top navigation bar to provide links for navigating from one product to another, or to navigate to external resources.
For external URLs, use `external_url` in the item property, as shown in the example topnav.yml file. For internal links, use `url` as usual.
Note that the topnav has two sections: topnav and topnav_dropdowns. The topnav section contains single links, while the topnav_dropdowns section contains dropdown menus. The two sections are independent of each other.
## Generating PDF
If you want to generate PDF, you'll need a license for [Prince XML](http://www.princexml.com/). You will also need to [install Prince](http://www.princexml.com/doc/installing/). You can generate PDFs by product (but not for every product on the site combined together into one massive PDF). Prince will work even without a license, but it will imprint a small Prince image on the first page.
Open up the css/printstyles.css file and customize the email address (`youremail@domain.com`) that is listed there. This email address appears in the bottom left footer of the PDF output. You'll also need to create a PDF configuration file following the examples shown in the pdfconfigs folder, and also customize some build scripts following the same pattern shown in the root: pdf-product1.sh
See the section on [generating PDFs](mydoc_generating_pdfs) for more details about setting the theme up for this output.
## Blogs / News
For blog posts, create your markdown files in the \_posts folder following the sample formats. Post file names always begin with the date (YYYY-MM-DD-title).
The news/news.html file displays the posts, and the news_archive.html file shows a yearly history of posts. In documentation, you might use the news to highlight product features outside of your documentation, or to provide release notes and other updates.
## Markdown
This theme uses Kramdown markdown. Kramdown is similar to Github-flavored Markdown, except that when you have text that intercepts list items, the spacing of the intercepting text must align with the spacing of the first character after the space of a numbered list item.
## Other instructions
For other details in working with the theme, see the various sections in the sidebar.
{% include custom/mydoc/getting_started_series_next.html %}