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

content updates

Browse Source
This commit is contained in:
Tom Johnson
2015-08-12 10:52:05 -07:00
parent 655e02f773
commit 860da7c786
10 changed files with 110 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
_includes/custom/doc/links_doc.html
View File

@ -118,3 +118,6 @@
{% capture doc_video_embeds %}<a href="doc_video_embeds.html">Video embeds</a>{% endcapture %}
{% capture doc_video_embeds_i %}<a href="doc_video_embeds.html">{% endcapture %}
{% capture doc_iterm_profiles %}<a href="doc_iterm_profiles.html">iTerm profiles</a>{% endcapture %}
{% capture doc_iterm_profiles_i %}<a href="doc_iterm_profiles.html">{% endcapture %}

2
configs/config_designers.yml
View File

@ -4,7 +4,7 @@ audience: designers
product: all
platform: all
version: all
destination: /Applications/XAMPP/xamppfiles/htdocs/jekyll-documentation-theme/designers
destination: ../designers
topnav_title: Jekyll Documentation Theme
homepage_title: Jekyll Documentation Theme &mdash; Designers
site_title: Jekyll Documentation Theme &mdash; Designers

2
configs/config_writers.yml
View File

@ -4,7 +4,7 @@ audience: writers
product: all
platform: all
version: all
destination: /Applications/XAMPP/xamppfiles/htdocs/jekyll-documentation-theme/writers
destination: ../writers
topnav_title: Jekyll Documentation Theme
homepage_title: Jekyll Documentation Theme &mdash; Writers
site_title: Jekyll Documentation Theme &mdash; Writers

6
css/lavish-bootstrap.css
View File

@ -1878,8 +1878,6 @@ fieldset[disabled] .btn-default.active {
}
.btn-primary {
color: #ffffff;
background-color: #74ab50;
border-color: #689a48;
}
.btn-primary:hover,
.btn-primary:focus,
@ -1887,8 +1885,6 @@ fieldset[disabled] .btn-default.active {
.btn-primary.active,
.open .dropdown-toggle.btn-primary {
color: #ffffff;
background-color: #618f43;
border-color: #4c7034;
}
.btn-primary:active,
.btn-primary.active,
@ -1910,8 +1906,6 @@ fieldset[disabled] .btn-primary:active,
.btn-primary.disabled.active,
.btn-primary[disabled].active,
fieldset[disabled] .btn-primary.active {
background-color: #74ab50;
border-color: #689a48;
}
.btn-warning {
color: #ffffff;

9
css/theme-blue.css
View File

@ -54,6 +54,15 @@ a[data-toggle="tooltip"] {
border-color: #347DBE;
}
.btn-primary:hover,
.btn-primary:focus,
.btn-primary:active,
.btn-primary.active,
.open .dropdown-toggle.btn-primary {
background-color: #248ec2;
border-color: #347DBE;
}
.printTitle {
color: #015CAE !important;
}

9
css/theme-green.css
View File

@ -53,6 +53,15 @@ a[data-toggle="tooltip"] {
border-color: #5b893c;
}
.btn-primary:hover,
.btn-primary:focus,
.btn-primary:active,
.btn-primary.active,
.open .dropdown-toggle.btn-primary {
background-color: #72ac4a;
border-color: #5b893c;
}
.printTitle {
color: #5b893c !important;
}

84
doc_configuration_settings.md
View File

@ -6,35 +6,19 @@ summary: "The configuration file contains important settings for your project. S
---
{% include linkrefs.html %}
## Importance of Configuration File
The configuration file serves important functions with single sourcing. For each site output, you create a unique configuration file for that output.
The configuration file contains all the settings and other details unique to that site output, such as variables, titles, output directories, build folders, and more.
{{warning}} This theme is coded to look for specific values set by the configuration file. If something isn't working correctly, check to make sure that you have the configuration values that are defined here properly configured.{{end}}
{{warning}} This theme is coded to look for specific values set by the configuration file. If something isn't working correctly, check to make sure that you have the configuration values that are defined here.{{end}}
## Configuration file options
Some of the options you can set in the configuration file determine theme settings.
Note that you can arbitrary key value pairs in the configuration file, and then you can access them through `site.yourkey`. However, the values in these tables are used to control different aspects of the theme and are not arbitrary key-value pairs.
## Cascading configuration files
When you build or serve Jekyll, you specify the configuration file that you want Jekyll to use. If you have multiple sites you're building, you can put all the common configuration values into a base configuration file. For the unique configuration files, you put them into another configuration file. Jekyll will read multiple configuration files.
The build command needs to look like this:
```
jekyll serve --config config_base.yml,config_designer.yml
```
Later configuration files will override settings in earlier configuration files.
{{warning}} You cannot use a space after the period.{{end}}
Note that you can define arbitrary key-value pairs in the configuration file, and then you can access them through `site.yourkey`, where `yourkey` is the name of the key. However, the values in these tables are used to control different aspects of the theme and are not arbitrary key-value pairs.
## Configuration settings
@ -42,27 +26,25 @@ Later configuration files will override settings in earlier configuration files.
|-------|-----------|-----------|
|
| **project** | Required| A unique name for the project. The \_includes/custom/{project}/conditions.html file will use this project name to determine what sidebar and top nav data files to use. Make this value unique. |
| **audience** | Required | The audience for the output. Each sidebar entry in the \_data/sidebar.yml files needs to have an audience attribute that matches the value here in order for the sidebar item to be included.|
| **platform** | Required | The platform for the output. The function is the same as audience -- the sidebar file matches up with attributes defined in the configuration file to determine what sidebar items are included in the build.|
| **product** | Required | Same function as audience, platform, and version.
| **version** | Required | Same function as audience, platform, and product.
| **audience** | Required | The audience for the output. Each entry in \_data/sidebar_doc.yml and \_data/topnav_doc.yml needs to have an audience attribute that matches the value here in order for the sidebar or topnav item to be included.|
| **platform** | Required | The platform for the output. See additional information in audience.
| **product** | Required | The product for the output. See additional information in audience.
| **version** | Required | The version for the output. See additional information in audience.
| **destination** | Required | The folder where the site is built. If you put this into your same folder as your other files, Jekyll may start building and rebuilding in an infinite loop because it detects more files in the project folder. Make sure you specify a folder outside your project folder, by using `../` or by specifying the absolute path, such as /Applications/XAMPP/xamppfiles/htdocs/myfolder. |
| **sidebar_tagline** | Optional | Appears above the sidebar. Usually you put some tag related to the site specific build, such as the audience.|
| **sidebar_version** | Optional | Appears below the sidebar_tagline in a smaller font. Usually specifying the version of the documentation. |
| **topnav_title** | Required | Appears next to the home button in the top nav bar.|
| **homepage_title**| Required | You set the title for your homepage via this setting. This is because multiple files are being displayed on the index.md page depending on the project. Because index.md has `homepage: true` in the frontmatter, then the page layout will use the `homepage_title` property from the configuration file instead of the traditional title in the frontmatter.|
| **site_title**| Appears in the webpage title area (on the browser tab, not in the page viewing area). |
| **port** | Required | The port used in the preview mode. This is only for the live preview and doesn't affect the published output. If you serve multiple outputs simultaneously, the port must be unique. |
| **sidebar_tagline** | Optional | Appears above the sidebar. Usually you put some term related to the site specific build, such as the audience. In the sample theme files, the taglines are "writers" and "designers."|
| **sidebar_version** | Optional | Appears below the sidebar_tagline in a smaller font, usually specifying the version of the documentation. In the sample theme files, the version is "3.0."|
| **topnav_title** | Required | Appears next to the home button in the top nav bar. In the sample theme files, the topnav_title is "Jekyll Documentation Theme." |
| **homepage_title**| Required | You set the title for your homepage via this setting. This is because multiple projects are all using the same index.md as their homepage. Because index.md has `homepage: true` in the frontmatter, the "page" layout will use the `homepage_title` property from the configuration file instead of the traditional title in the frontmatter. In the sample theme files, the homepage title is "Jekyll Documentation Theme -- {audience}." |
| **site_title**| Appears in the webpage title area (on the browser tab, not in the page viewing area). In the sample theme files, the site title is the "page name | homepage title." |
| **port** | Required | The port used in the preview mode. This is only for the live preview and doesn't affect the published output. If you serve multiple outputs simultaneously, the port must be unique. |
| **feedback_email** | Gets configured as the email address in the Send Feedback button in the top navigation bar.|
| **sidebar_accordion** | Optional | Boolean. Whether you want the navigation sidebar to use the accordion effect or not. The accordion effect means when you expand a section, the other sections auto-collapse. If you put false, then you can expand multiple sections at once. At the bottom of the navigation sidebar, two links will appear: Collapse All and Expand All. The default is true.|
| **disqus_shortname** | Optional | The disqus site shortname, which is used for comments. If you don't want comment forms via disqus, leave this blank or omit it altogether. |
| **sidebar_accordion** | Optional | Boolean. The default value is true. Whether you want the navigation sidebar to use the accordion effect or not. The accordion effect means when you expand a section, the other sections automatically collapse. If you put `false`, then you can expand multiple sections at once. At the bottom of the navigation sidebar, two links will appear: Collapse All and Expand All. |
| **disqus_shortname** | Optional | The disqus site shortname, which is used for comments. If you don't want comment forms via disqus, leave this blank or omit it altogether and Disqus won't appear. |
| **markdown** | Required | The processor to use for Markdown. This is a Jekyll-specific setting. |
| **redcarpet** | Required | Extensions used with redcarpet. You can read more about them by searching for redcarpet extensions online. |
| **highlighter** | Optional | The syntax highlighter used. Rouge is also an option. I think Pygments does a better job. You will need to [install Pygments](http://pygments.org/download/) on your machine or else you will see an error. |
| **exclude** | Optional | A list of files and directories that you want excluded from the build. By default, all the content in your project is included in the output. |
| **permalink** | Required | The structure used for the link URLs. To read more about permalinks, see [Permalinks](http://jekyllrb.com/docs/permalinks/). |
| **highlighter** | Optional | The syntax highlighter used. `rouge` is also an option. I think Pygments does a better job. You will need to [install Pygments](http://pygments.org/download/) on your machine or else you will see an error. |
| **exclude** | Optional | A list of files and directories that you want excluded from the build. By default, all the content in your project is included in the output. |
| **defaults** | Optional | Here you can set default values for frontmatter based on the content type (page, post, or collection). |
| **sass** | Required | The directory for sass files. This is a Jekyll-specific settings. Sass isn't customized in this theme. |
| **collections** | Optional | Any specific collections (custom content types that extend beyond pages or posts) that you want to define. This theme defines a collection called tooltips. You access this collection by using site.tooltips instead of site.pages or site.posts. Put the tooltip content types inside a folder in your project called \_tooltips. |
| **print** | Optional | Boolean. Whether this build is a print build or not. This setting allows you to run conditions in your content such as {% raw %} {% if site.print == true %} do this... {% endif %} {% endraw %}. |
| **suffix** | Optional | If you publish on Salesforce's site.com, you have to add index.html to the permalink or else the page won't render. If you add `suffix: index.html` in your config file, this suffix will be appended in the homepage URL. If you're not publishing to Salesforce, don't add this property to your configuration file.|
@ -71,6 +53,40 @@ Later configuration files will override settings in earlier configuration files.
In this theme, the configuration files are listed in the configs directory. There are some build scripts in the root directory that simply reference the configuration files.
## The conditional attributes
Each configuration file must specify values for the conditional attributes:
* project
* product
* platform
* audience
* version
The sidebar.html and topnav.html files apply conditional logic based on the values for these conditional attributes.
For example, you will see this kind of logic in the sidebar and topnav files:
```
{% raw %}
{% if item.audience contains audience and item.product contains product and item.platform contains platform and item.version contains version and item.web != false %}
{% endraw %}
```
If all of these conditions are met, then the item will qualify to be included in the sidebar or top navigation file. That is why each item in the sidebar_doc.yml or topnav_doc.yml file includes similar properties to match:
```
- title: Pages
url: /doc_pages.html
audience: writers, designers
platform: all
product: all
version: all
```
The file in \_includes/custom/doc/conditions.html contains a project setting and also assigns general names for each of these specific values. This way the same theme files can be used interchangeably depending on the assignments, whose values are specified in the configuration file.
It's a little complicated to describe, but it works. Once you configure your project correctly, you don't even think about how the theme is processing all of this on the backend.

47
doc_getting_started.md
View File

@ -14,15 +14,13 @@ summary:
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. Open your Terminal and type `which ruby` to confirm.
* **[Rubygems](https://rubygems.org/pages/download)**. This is a package manager for Ruby (gems). Type `which gem` to confirm.
* **[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.
* **[Jekyllrb](http://jekyllrb.com/)**. To install: `gem install jekyll`. Type `which jekyll` to confirm that Jekyll is installed.
* **Text editor** (some examples: Sublime Text, Atom, WebStorm, IntelliJ)
* **[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`. If you want to use `rouge` instead, change `pygments` to `rouge` in the configuration files.
{{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="http://jekyllrb.com/docs/windows/">Jekyll on Windows"</a> for more details about getting Jekyll working on Windows. {{end}}
## Step 2: Build the theme
Before you start customizing the theme, make sure you can build the theme with the default content and settings first.
@ -31,40 +29,57 @@ Before you start customizing the theme, make sure you can build the theme with t
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 need to clone it.
3. After downloading the theme, note some unique aspects of the file structure:
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.
* 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 is constructed.
* 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.
* You can build all the outputs in your configs directory by running the doc_multibuild_web.sh file in the root directory.
{{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 site 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 involve this requirement.{{end}}
The doc_multibuild_web.sh file just contains build commands that refer to specific configuration files. Here's how you build the "writers" output:
There are four configuration files in this project: config_writer.yml and config_designer.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. However, for the writers output, I've conditionally excluded more lengthy explanations about how the theme works. The idea is that writers just want to create and publish content; in contrast, designers want to understand and modify the theme itself. Also, the configuration files use different themes.
3. Build the writer's output:
```
jekyll serve --config configs/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.
There are two configuration files in this project: config_writer.yml and config_designer.yml. The idea is that there's an output specific to writers, and an output specific to developers.
In reality, both of these outputs are pretty much the same (except for a theme difference). However, for the writers output, I've conditionally excluded more lengthy explanations about how the theme works. The idea is that writers just want to create and publish content; in contrast, designers want to understand and modify the theme itself.
Open a new tab in your browser and preview the site at the preview URL shown.
4. Press **Ctrl+C** in Terminal to shut down the writer's output.
5. Build the designers output:
4. Open a new tab in Terminal and build the designers output:
```
jekyll serve --config configs/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).
If the theme builds both outputs successfully, great. You can move on to the other sections. If you run into errors building the basic theme, try to solve them before moving on. See {{doc_troubleshooting}} for more information.
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).
5. Press **Ctrl+C** in Terminal to shut down the designer's output.
6. Build both themes by running the following command:
```
. doc_multibuild_web.sh
```
The themes build in the ../designers and ../writers folders. Use finder and browse to one level above where you installed the project (probably username/projects).
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 build 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, try to solve them before moving on. See {{doc_troubleshooting}} for more information.
{{tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{doc_iterm_profiles}} for details. {{end}}
More information about building the PDF versions is provided in {{doc_generating_pdfs}}.
## Questions
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.
If you have questions, contact me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. 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.

0
iterm_profiles.md → doc_iterm_profiles.md
View File

6
update.sh Normal file
View File

@ -0,0 +1,6 @@
# this file is for convenience in updating this content in Github pages
git add --all
git status
git commit -m "content updates"
git push