committing new version of jekyll doc theme -- 5.0, with some refinements to come with the documentation
This commit is contained in:
tomjohnson1492
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Introduction
|
||||
tags: [getting_started]
|
||||
audience: field engineers, clients
|
||||
type: first_page
|
||||
homepage: true
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This site provides documentation, training, and other notes for the Jekyll Documentation theme. There's a lot of information about how to do a variety of things here, and it's not all unique to this theme. But by and large, understanding how to do things in Jekyll depends on how your theme is coded. As a result, these additional details are provided.
|
||||
|
||||
The instructions here are geared towards technical writers working on documentation. You may have a team of one or more technical writers working on documentation for multiple projects. You can use this same theme to author all of your documentation for each of your products. The theme is set up to push out documentation for multiple projects all from the same source. You can also share content across projects.
|
||||
|
||||
## Survey of features
|
||||
|
||||
Some of the more prominent features of this theme include the following:
|
||||
|
||||
* Bootstrap framework
|
||||
* Sidebar for table of contents
|
||||
* Top navigation bar with drop-down menus
|
||||
* PDF generation (through Prince XML utility)
|
||||
* Build scripts to automate the workflow
|
||||
* Notes, tips, and warning information notes
|
||||
* A nifty system for creating links to different pages
|
||||
* Tags for alternative nativation
|
||||
* Content sharing across projects
|
||||
* Emphasis on pages, not posts
|
||||
* Relative (rather than absolute) link structure, so you can push the outputs anywhere and easily view them
|
||||
|
||||
I'm using this theme for my documentation projects, building about 20 different outputs for various products, versions, languages, and audiences from the same set of files. This single sourcing requirement has influenced how I constructed this theme.
|
||||
|
||||
For more discussion about the available features, see {{site.data.mydoc.mydoc_urls.mydoc_supported_features.link}}.
|
||||
|
||||
## Getting started
|
||||
|
||||
To get started, see these three topics:
|
||||
|
||||
1. {{site.data.mydoc.mydoc_urls.mydoc_getting_started.link}}
|
||||
2. {{site.data.mydoc.mydoc_urls.mydoc_configuration_settings.link}}
|
||||
3. {{site.data.mydoc.mydoc_urls.mydoc_adding_new_projects.link}}
|
||||
|
||||
## PDF Download Option for Help Material
|
||||
|
||||
If you would like to download this help file as a PDF, you can do so here. The PDF is comprehensive of all the content in the online help.
|
||||
|
||||
<a target="_blank" class="noCrossRef" href="files/{{site.pdf_file_name}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
|
||||
The PDF contains a timestamp in the header indicating when it was last generated.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 75 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 90 KiB |
File diff suppressed because it is too large
Load Diff
|
Before Width: | Height: | Size: 126 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 115 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 5.2 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 65 KiB |
@ -1,14 +1,16 @@
|
||||
---
|
||||
title: About the theme author
|
||||
keywords: documentation theme, jekyll, technical writers, help authoring tools, hat replacements
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
tags: [getting_started]
|
||||
summary: "I use this theme for sophisticated single_sourcing projects that I work on as a professional technical writer."
|
||||
summary: "I have used this theme for projects that I've worked on as a professional technical writer."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_about/
|
||||
---
|
||||
|
||||
My name is Tom Johnson, and I'm a technical writer, blogger, and podcaster based in San Jose, California. My blog is here: [http://idratherbewriting.com](http://idratherbewriting.com). I write several posts there a week. See [my blog's about page](http://idratherbewriting.com/aboutme/) for more details about me.
|
||||
|
||||
I'm using this theme for my documentation projects. This theme has undergone several major iterations, and now it's fairly stable and full of all the features that I need. You are welcome to use it for your documentation projects for free.
|
||||
I have used this theme and variations of it for various documentation projects. This theme has undergone several major iterations, and now it's fairly stable and full of all the features that I need. You are welcome to use it for your documentation projects for free.
|
||||
|
||||
I think this theme does pretty much everything that you can do with something like OxygenXML, but without the constraints of structured authoring. Everything is completely open and changeable, so if you start tinkering around with the theme's files, you can break things. But it's completely empowering as well!
|
||||
|
||||
|
||||
@ -1,76 +0,0 @@
|
||||
---
|
||||
title: 2. Add a new project
|
||||
tags: [getting_started]
|
||||
last_updated: November 30, 2015
|
||||
keywords: getting started, customization, beginning steps, modifying the theme, modification
|
||||
summary: "You add a new project essentially by duplicating all the mydoc project files in the _data, _includes, configs, and other folders. You can add as many projects as you want in this theme."
|
||||
series: "Getting Started"
|
||||
weight: 2
|
||||
---
|
||||
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
|
||||
## About 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. The designers output is comprehensive, whereas the writers output is a subset of the information. However, the outputs are mostly the same. I just created the separate output to demonstrate how the single sourcing aspect works.
|
||||
|
||||
You can add as many documentation projects as you want to the same Jekyll project. Some doc projects have multiple outputs, as is the case with the designers and writers outputs for the mydoc project.
|
||||
|
||||
## Add a new project
|
||||
Follow these steps to add additional projects.
|
||||
|
||||
{{site.data.alerts.important}} In these instructions, I'll assume your project's name is "acme." Replace "acme" with the real name of your project. {{site.data.alerts.end}}
|
||||
|
||||
### 1. Copy and customize the mydoc folder in _data
|
||||
|
||||
Inside the \_data folder, copy the mydoc folder and its contents. Rename it to acme, and then rename each of the YML files inside the folder with the acme prefix.
|
||||
|
||||
The files in data control how the side and top nav bar get populated. Here is also where URLs, definitions, and other settings are stored.
|
||||
|
||||
### 2. Copy and customize the mydoc folder in configs
|
||||
|
||||
In the configs folder, copy the mydoc folder and its contents. Rename it to acme, and then rename each of the config_ files to the outputs you need for your acme project.
|
||||
|
||||
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.
|
||||
|
||||
Change the file names from config_writers.yml and so forth to whatever file names best represent the audiences for your outputs.
|
||||
|
||||
More details about customizing the settings in the configuration files will be explained later. For now you're just duplicating the necessary project files for your new project.
|
||||
|
||||
### 3. Create a new folder inside \_includes/custom
|
||||
|
||||
In the _includes/custom directory, add a new folder there called "acme." This folder should sit parallel to the mydoc folder. This is where you can store includes for your project.
|
||||
|
||||
### 4. Add a new folder in the root directory
|
||||
|
||||
In the root directory, add a folder for your pages called acme (similar to the mydoc folder). Include two subfolders inside acme: files and images.
|
||||
|
||||
Inside the mydoc folder, copy the home.md file and add it to the acme folder. (With most Jekyll projects, they open up on the index.html file in the root directory. However, because the pages for each project are stored in subfolders, it was necessary to create a redirect from the index page to the home.md page.)
|
||||
|
||||
This acme directory is where you'll store all your pages.
|
||||
|
||||
Note that you cannot create subfolders in this acme directory. All of your pages have to be flat in this directory. This is because the references to the resources (stylesheets, javascript, etc.) are relative, and creating additional directory levels will break the relative paths.
|
||||
|
||||
### 5. Copy and customize the mydoc shell scripts in the root directory
|
||||
|
||||
In the root directory, duplicate the shell scripts (the file extension is .sh) and rename the prefix to "acme_". The following files are the shell scripts that need to be duplicated:
|
||||
|
||||
* mydoc_1_multiserve_pdf.sh
|
||||
* mydoc_2_multibuild_pdf.sh
|
||||
* mydoc_3_multibuild_web.sh
|
||||
* mydoc_4_publish.sh
|
||||
* mydoc_all.sh
|
||||
|
||||
### 6. Copy the URL generator text file
|
||||
|
||||
In the root directory, copy urls_mydoc.txt and duplicate it. Change the suffix to urls_acme.txt.
|
||||
|
||||
{{site.data.alerts.tip}} In this step, you're just duplicating project files. In later steps, you'll actually customize all of the settings. {{site.data.alerts.end}}
|
||||
|
||||
{% include custom/mydoc/getting_started_series_next.html %}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Tooltips
|
||||
tags: [formatting]
|
||||
keywords: popovers, tooltips, user interface text, glossaries, definitions
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can add tooltips to any word, such as an acronym or specialized term. Tooltips work well for glossary definitions, because you don't have to keep repeating the definition, nor do you assume the reader already knows the word's meaning."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_adding_tooltips/
|
||||
---
|
||||
|
||||
## Creating tooltips
|
||||
@ -19,4 +21,4 @@ Suppose you have a glossary.yml file inside your \_data folder. You could pull i
|
||||
|
||||
This renders to the following:
|
||||
|
||||
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.</a>
|
||||
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.
|
||||
@ -2,10 +2,11 @@
|
||||
title: Alerts
|
||||
tags: [formatting]
|
||||
keywords: notes, tips, cautions, warnings, admonitions
|
||||
last_updated: November 30, 2015
|
||||
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."
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can insert notes, tips, warnings, and important alerts in your content. These notes make use of Bootstrap styling and are available through data references such as site.data.alerts.note."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_alerts/
|
||||
---
|
||||
{% comment %} comment 4 by saphira {% endcomment %}
|
||||
|
||||
## About alerts
|
||||
Alerts are little warnings, info, or other messages that you have called out in special formatting. In order to use these alerts or callouts, just reference the appropriate value stored in the alerts.yml file as described in the following sections.
|
||||
@ -80,5 +81,5 @@ If you want to blast a warning to users on every page, add the alert or callout
|
||||
|
||||
## Using Markdown inside of notes
|
||||
|
||||
You can't use Markdown formatting inside alerts. This is because the alerts leverage HTML, and you can't use Markdown inside of HTML tags.
|
||||
You can't use Markdown formatting inside alerts. This is because the alerts leverage HTML, and you can't use Markdown inside of HTML tags. It's very easy to forget this, which is why I recommend using HTML formatting for links in every case. This way you're less likely to forget to switch into HTML mode when you're writing content in a tip. You must remember, however, to avoid Markdown with code and bold formatting inside of notes.
|
||||
|
||||
|
||||
@ -1,10 +0,0 @@
|
||||
---
|
||||
title: Algolia search
|
||||
tags: [formatting]
|
||||
keywords: search
|
||||
summary: "This page demonstrates an integration of Algolia search."
|
||||
---
|
||||
|
||||
## algolia:
|
||||
|
||||
{% include algolia.html %}
|
||||
@ -2,8 +2,10 @@
|
||||
title: Build arguments
|
||||
tags: [publishing]
|
||||
keywords: building, serving, serve, build
|
||||
last_updated: November 30, 2015
|
||||
summary: "When you have a single sourcing project, you use more advanced arguments when you're building or serving your Jekyll sites. These arguments specify a particular configuration file and may build on other configuration files."
|
||||
last_updated: March 20, 2016
|
||||
summary: "You use various build arguments with your Jekyll project. You can also create shell scripts to act as shortcuts for long build commands. You can store the commands in iTerm as profiles as well."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_build_arguments/
|
||||
---
|
||||
|
||||
## How to build Jekyll sites
|
||||
@ -23,16 +25,20 @@ jekyll serve
|
||||
By default, the _config.yml in the root directory will be used, Jekyll will scan the current directory for files, and the folder `_site` will be used as the output. You can customize these build commands like this:
|
||||
|
||||
```
|
||||
jekyll serve --config configs/config_writers.yml --destination /users/tjohnson/projects/documentation-theme-jekyll-builds/writer
|
||||
jekyll serve --config configs/myspecialconfig.yml --destination ../doc_outputs
|
||||
```
|
||||
|
||||
Here the `configs/config_writers.yml` file is used instead of `_config.yml`. The destination directory is `../mydoc_writers`.
|
||||
Here the `configs/myspecialconfig.yml` file is used instead of `_config.yml`. The destination directory is `../doc_outputs`, which would be one level up from your current directory.
|
||||
|
||||
## Shortcuts for the build arguments
|
||||
|
||||
If you don't want to enter the long Jekyll argument every time, with all your configuration details, you can create a shell script and then just run the script. This theme shows an example with the mydoc_multibuild_web.sh file in the root directory.
|
||||
If you have a long build argument and don't want to enter it every time in Jekyll, noting all your configuration details, you can create a shell script and then just run the script. Simply put the build argument into a text file and save it with the .sh extension (for Mac) or .bat extension (for Windows). Then run it like this:
|
||||
|
||||
My preference is to add the scripts to profiles in iTerm. See {{site.data.mydoc.mydoc_urls.mydoc_iterm_profiles.link}} for more details.
|
||||
```
|
||||
. myscript.sh
|
||||
```
|
||||
|
||||
My preference is to add the scripts to profiles in iTerm. See {{site.data.urls.mydoc_iterm_profiles.link}} for more details.
|
||||
|
||||
## Stop a server
|
||||
|
||||
@ -54,9 +60,9 @@ To kill all Jekyll instances, use this:
|
||||
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
|
||||
```
|
||||
|
||||
I created a profile in iTerm that stores this command. Here's what the iTerm settings look like:
|
||||
I recommend creating a profile in iTerm that stores this command. Here's what the iTerm settings look like:
|
||||
|
||||
|
||||
![iTerm profile settings to kill all Jekyll]({{ "/images/killalljekyll.png" | prepend: site.baseurl }})
|
||||
|
||||
|
||||
|
||||
|
||||
@ -3,13 +3,15 @@ title: 10. Configure the build scripts
|
||||
tags:
|
||||
- publishing
|
||||
keywords: "build scripts, generating outputs, building, publishing"
|
||||
last_updated: "November 30, 2015"
|
||||
last_updated: "November 30, 2016"
|
||||
summary: "You need to customize the build scripts. These script automate the publishing of your PDFs and web outputs through shell scripts on the command line."
|
||||
series: "Getting Started"
|
||||
weight: 10
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_build_scripts/
|
||||
---
|
||||
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
{% include custom/getting_started_series.html %}
|
||||
|
||||
## About the build scripts
|
||||
|
||||
@ -23,16 +25,16 @@ To set up your projects:
|
||||
|
||||
1. Set up your Jekyll theme in a folder called "docs." All of the source files for every project the team is working on should live in this directory. Most likely you already either downloaded or cloned the jekyll-documentation-theme. Just rename the folder to "docs" and move it into the projects folder as shown here.
|
||||
2. In the same root directory where the docs folder is, create another directory parallel to docs called doc_outputs.
|
||||
|
||||
Thus, your folder structure should be something like this:
|
||||
|
||||
```
|
||||
projects
|
||||
- docs
|
||||
- doc_outputs
|
||||
```
|
||||
|
||||
The docs folder contains the source of all your files, while the doc_outputs contains the site outputs.
|
||||
|
||||
Thus, your folder structure should be something like this:
|
||||
|
||||
```
|
||||
projects
|
||||
- docs
|
||||
- doc_outputs
|
||||
```
|
||||
|
||||
The docs folder contains the source of all your files, while the doc_outputs contains the site outputs.
|
||||
|
||||
## Configure the Build Scripts
|
||||
|
||||
@ -148,7 +150,7 @@ This script first removes the project folder on /var/www/html/yourpublishingdire
|
||||
|
||||
Note that the delete part of the script (`rm -rf`) works really well. It annihilates a folder in a heartbeat and doesn't give you any warning prompts, so make sure you have it set up correctly.
|
||||
|
||||
Also, in case you haven't set up the SSH publishing without a password, see {{site.data.mydoc.mydoc_no_password_prompts_scp.link}}. Otherwise the script will stop and ping you to enter your password for each directory it transfers.
|
||||
Also, in case you haven't set up the SSH publishing without a password, see {{site.data.mydoc_no_password_prompts_scp.link}}. Otherwise the script will stop and ping you to enter your password for each directory it transfers.
|
||||
|
||||
### (Optional) Push to repositories
|
||||
|
||||
@ -188,4 +190,4 @@ After you've configured all the scripts, you can run them all by running `. mydo
|
||||
## Test out the scripts
|
||||
|
||||
After setting up and customizing the build scripts, run a few tests to make sure everything is generating correctly. Getting this part right is somewhat difficult and may likely require you to tinker around with the scripts a while before it works flawlessly.
|
||||
{% include custom/mydoc/getting_started_series_next.html %}
|
||||
{% include custom/getting_started_series_next.html %}
|
||||
@ -2,13 +2,14 @@
|
||||
title: Collections
|
||||
tags: [content-types]
|
||||
keywords: groups, api, structure
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "Collections are useful if you want to loop through a special folder of pages that you make available in a content API. You could also use collections if you have a set of articles that you want to treat differently from the other content, with a different layout or format."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_collections/
|
||||
---
|
||||
|
||||
|
||||
## What are collections
|
||||
Collections are custom content types different from pages and posts. You might create a collection if you want to treat a specific set of articles in a unique way, such as with a custom layout or listing. For more detail on collections, see [Ben Balter's explanation of collections here](http://ben.balter.com/2015/02/20/jekyll-collections/).
|
||||
Collections are custom content types different from pages and posts. You might create a collection if you want to treat a specific set of articles in a unique way, such as with a custom layout or listing. For more detail on collections, see [Ben Balter's explanation of collections here](http://ben.balter.com/2016/02/20/jekyll-collections/).
|
||||
|
||||
## Create a collection
|
||||
To create a collection, add the following in your configuration file:
|
||||
@ -29,4 +30,8 @@ See [Collections in the Jekyll documentation](http://jekyllrb.com/docs/collectio
|
||||
|
||||
## How to use collections
|
||||
|
||||
I haven't found a huge use for collections in normal documentation. However, I did find a use for collections in generating a tooltip file that would be used for delivering tooltips to a user interface from text files in the documentation. See {{site.data.mydoc.mydoc_urls.mydoc_help_api.link}} for details.
|
||||
I haven't found a huge use for collections in normal documentation. However, I did find a use for collections in generating a tooltip file that would be used for delivering tooltips to a user interface from text files in the documentation. See {{site.data.mydoc_urls.mydoc_help_api.link}} for details.
|
||||
|
||||
## Video tutorial on collections
|
||||
|
||||
See this [video tutorial on Jekyll.tips](http://jekyll.tips/jekyll-casts/introduction-to-collections/) for more details on collections.
|
||||
@ -3,9 +3,10 @@ title: Commenting on files
|
||||
tags:
|
||||
- navigation
|
||||
keywords: "annotations, comments, feedback"
|
||||
last_updated: "November 30, 2015"
|
||||
summary: "You can add a button to your pages that allows people to add comments. Prose.io is an overlay on Github that would allow people to make comments in an easier interface."
|
||||
published: true
|
||||
last_updated: "November 30, 2016"
|
||||
summary: "You can add a button to your pages that allows people to add comments."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_commenting_on_files/
|
||||
---
|
||||
|
||||
## About the review process
|
||||
@ -18,32 +19,29 @@ Here's the code for that button on the page.html layout:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% if site.github_editme_path %}
|
||||
<a href="https://github.com/{{site.github_editme_path}}{{page.url | replace: '.html', '.md'}}" class="btn btn-default " role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>
|
||||
{% endif %}
|
||||
{% unless jekyll.environment == "production" %}
|
||||
|
||||
{% if site.github_editme_path %}
|
||||
|
||||
<a target="_blank" href="https://github.com/{{site.github_editme_path}}{% unless page.url contains "html" %}{{page.url | replace: '.html', '.md'}}{% endunless %}{% if page.url contains "html" %}{{page.url }}{% endif %}" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>
|
||||
{% endif %}
|
||||
|
||||
{% endunless %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You could also make it so the Github button appears only when you're working in a development environment.
|
||||
This code is only active if you're publishing in a development environment, which is the default.
|
||||
|
||||
To activate the production environment, add the [production environment flag](http://jekyllrb.com/docs/configuration/) in your build command:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% if jekyll.environment == "development" %}
|
||||
{% if site.github_editme_path %}
|
||||
<a target="_blank" href="https://github.com/{{site.github_editme_path}}{{page.url | replace: '.html', '.md'}}" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>
|
||||
{% endif %}
|
||||
JEKYLL_ENV=production jekyll serve
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
To activate the development environment, add the [environment flag](http://jekyllrb.com/docs/configuration/) in your build command:
|
||||
In your configuration file, edit the value for `github_editme_path`. For example, you might create a branch called "reviews" on your Github repo. Then you would add something like this in your configuration file for the 'github_editme_path': tomjohnson1492/documentation-theme-jekyll/edit/reviews. Here "tomjohnson1492" is my github account name. The repo name is "documentation-theme-jekyll". The "reviews" name is the branch.
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
JEKYLL_ENV=development jekyll serve
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The default environment is production.
|
||||
|
||||
## Add reviewers as collaborators
|
||||
|
||||
@ -54,3 +52,16 @@ If you don't want to allow anyone to commit to your Github branch, don't add the
|
||||
{{site.data.alerts.note}} When you process pull requests, you have to accept everything or nothing. You can't pick and choose which changes you'll merge. Therefore you'll probably want to edit the branch you're planning to merge or ask the contributor to make some changes to the fork before processing the pull request.{{site.data.alerts.end}}
|
||||
|
||||
|
||||
## Workflow
|
||||
|
||||
Users will make edits in your "reviews" branch (or whatever you want to call it). You can then commit those edits as you make updates.
|
||||
|
||||
When you're finished making all updates in the branch, you can merge the branch into the master.
|
||||
|
||||
Note that if you're making updates online, those updates will be out of sync with any local edits.
|
||||
|
||||
{{site.data.alerts.warning}} Don't make edits both online using Github's browser-based interface AND offline on your local machine using your local tools. When you try to push from your local, you'll likely get a merge conflict error. Instead, make sure you do a pull and update on your local after making any edits online.{{site.data.alerts.end}}
|
||||
|
||||
## Prose.io
|
||||
|
||||
Prose.io is an overlay on Github that would allow people to make comments in an easier interface. If you simply go to [prose.io](http://prose.io), it asks to authorize your Github account, and so it will read files directly from Github but in the Prose.io interface.
|
||||
@ -2,55 +2,45 @@
|
||||
title: Conditional logic
|
||||
tags: [single_sourcing]
|
||||
keywords: if else logic, conditions, conditional attributes, conditional filtering
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can implement advanced conditional logic that includes if statements, or statements, unless, and more. This conditional logic facilitates single sourcing scenarios in which you're outputting the same content for different audiences."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_conditional_logic/
|
||||
---
|
||||
|
||||
## About Liquid and conditional statements
|
||||
If you want to create different outputs for different audiences, you can do all of this using a combination of Jekyll's Liquid markup and values in your configuration file.
|
||||
If you want to create different outputs for different audiences, you can do all of this using a combination of Jekyll's Liquid markup and values in your configuration file. This is how I previously configured the theme. I had different configuration files for each output. Each configuration file specified different values for product, audience, version, and so on. Then I had different build processes that would leverage the different configuration files. It seemed like a perfect implementation of DITA-like techniques with Jekyll.
|
||||
|
||||
You can then incorporate conditional statements that check the values in the configuration files.
|
||||
But I soon found that having lots of separate outputs for a project was undesirable. If you have 10 different outputs that have different nuances for different audiences, it's hard to manage and maintain. In this latest version of the theme, I consolidated all information into the same output to explicitly do away with the multi-output approach.
|
||||
|
||||
As such, the conditional logic won't have as much play as it previously did. Instead of conditions, you'll probably want to incorporate [navtabs](mydoc_navtabs) to split up the information.
|
||||
|
||||
However, you can still of course use conditional logic as needed.
|
||||
|
||||
{{site.data.alerts.tip}} Definitely check out <a href="http://docs.shopify.com/themes/liquid-documentation/basics">Liquid's documentation</a> for more details about how to use operators and other liquid markup. The notes here are a small, somewhat superficial sample from the site.{{site.data.alerts.end}}
|
||||
|
||||
## Where to store filtering values
|
||||
|
||||
You can filter content based on values that you have set either in your config file or in a file in your \_data folder. If you set the attribute in your config file, you need to restart the Jekyll server to see the changes. If you set the value in a file in your \_data folder, you don't need to restart the server when you make changes.
|
||||
|
||||
## Required conditional attributes
|
||||
|
||||
This theme requires you to add the following attributes in your configuration file:
|
||||
|
||||
* project
|
||||
* audience
|
||||
* product
|
||||
* platform
|
||||
* version
|
||||
|
||||
If you've ever used DITA, you probably recognize these attributes, since DITA has mostly the same ones. I've found that most single_sourcing projects I work on can be sliced and diced in the ways I need using these conditional attributes.
|
||||
|
||||
If you're not single sourcing and you find it annoying having to specify these attributes in your sidebar, you can rip out the logic from the sidebar.html, topnav.html file and any other places where conditions.html appears; then you wouldn't need these attributes in your configuration file.
|
||||
You can filter content based on values that you have set either in your page's frontmatter, a config file, or in a file in your \_data folder. If you set the attribute in your config file, you need to restart the Jekyll server to see the changes. If you set the value in a file in your \_data folder or page frontmatter, you don't need to restart the server when you make changes.
|
||||
|
||||
## Conditional logic based on config file value
|
||||
|
||||
Here's an example of conditional logic based on a value in the configs/config_writer.yml file. In my config_writer.yml file, I have the following:
|
||||
Here's an example of conditional logic based on a value in the page's frontmatter. Suppose you have the following in your frontmatter:
|
||||
|
||||
```
|
||||
audience: writers
|
||||
platform: mac
|
||||
```
|
||||
|
||||
On a page in my site (it can be HTML or markdown), I can conditionalize content using the following:
|
||||
On a page in my site (it can be HTML or markdown), you can conditionalize content using the following:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```liquid
|
||||
{% if site.audience == "writers" %}
|
||||
The writer audience should see this...
|
||||
{% elsif site.audience == "designers" %}
|
||||
The designer audience should see this ...
|
||||
{% if page.platform == "mac" %}
|
||||
Here's some info about the Mac.
|
||||
{% elsif page.platform == "windows" %}
|
||||
Here's some info about Windows ...
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
This uses simple `if-elsif` logic to determine what is shown (note the spelling of `elsif`). The `else` statement handles all other conditions not handled by the `if` statements.
|
||||
@ -62,9 +52,9 @@ Here's an example of `if-else` logic inside a list:
|
||||
To bake a casserole:
|
||||
|
||||
1. Gather the ingredients.
|
||||
{% if site.audience == "writer" %}
|
||||
{% if page.audience == "writer" %}
|
||||
2. Add in a pound of meat.
|
||||
{% elsif site.audience == "designer" %}
|
||||
{% elsif page.audience == "designer" %}
|
||||
3. Add in an extra can of beans.
|
||||
{% endif %}
|
||||
3. Bake in oven for 45 min.
|
||||
@ -81,8 +71,8 @@ For example, here's an example using `or`:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if site.audience contains "vegan" or site.audience == "vegetarian" %}
|
||||
// run this.
|
||||
{% if page.audience contains "vegan" or page.audience == "vegetarian" %}
|
||||
Then run this...
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
@ -91,7 +81,7 @@ Note that you have to specify the full condition each time. You can't shorten th
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if site.audience contains "vegan" or "vegetarian" %}
|
||||
{% if page.audience contains "vegan" or "vegetarian" %}
|
||||
// run this.
|
||||
{% endif %}
|
||||
```
|
||||
@ -106,16 +96,14 @@ You can also use `unless` in your logic, like this:
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% unless site.output == "pdf" %}
|
||||
...
|
||||
...do this
|
||||
{% endunless %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
When figuring out this logic, read it like this: "Run the code here *unless* this condition is satisfied." Or "If this condition is satisfied, don't run this code."
|
||||
When figuring out this logic, read it like this: "Run the code here *unless* this condition is satisfied."."
|
||||
|
||||
Don't read it the other way around or you'll get confused. (It's not executing the code only if the condition is satisfied.)
|
||||
|
||||
In this situation, if `site.print == true`, then the code will *not* be run here.
|
||||
Don't read it the other way around or you'll get confused. (It's *not* executing the code only if the condition is satisfied.)
|
||||
|
||||
## Storing conditions in the \_data folder
|
||||
|
||||
@ -135,12 +123,6 @@ this shows if neither of the above two if conditions are met.
|
||||
|
||||
To use this, I would need to have a \_data folder called options where the `output` property is stored.
|
||||
|
||||
I don't really use the \_data folder as much for project options. I store them in the configuration file because I usually want different projects to use different values for the same property.
|
||||
|
||||
For example, maybe a file or function name is called something different for different audiences. I currently single source the same content to at least two audiences in different markets.
|
||||
|
||||
For the first audience, the function name might be called `generate`, but for the second audience, the same function might be called called `expand`. In my content, I'd just use {% raw %}`{{site.function}}`{% endraw %}. Then in the configuration file I change its value appropriately for the audience.
|
||||
|
||||
## Specifying the location for \_data
|
||||
|
||||
You can also specify a `data_source` for your data location in your configuration file. Then you aren't limited to simply using `_data` to store your data files.
|
||||
@ -150,7 +132,7 @@ For example, suppose you have 2 projects: alpha and beta. You might store all th
|
||||
In your alpha configuration file, specify the data source like this:
|
||||
|
||||
```
|
||||
data_source: data_alpha
|
||||
data_source: data_amydoc_content_reuselpha
|
||||
```
|
||||
|
||||
Then create a folder called \_data_alpha.
|
||||
@ -164,29 +146,6 @@ data_source: data_beta
|
||||
Then create a folder called \_data_beta.
|
||||
|
||||
|
||||
## Conditional logic based on page namespace
|
||||
|
||||
You can also create conditional logic based on the page namespace. For example, create a page with front matter as follows:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
layout: page
|
||||
user_plan: full
|
||||
---
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Now you can run logic based on the conditional property in that page's front matter:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if page.user_plan == "full" %}
|
||||
// run this code
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Conditions versus includes
|
||||
|
||||
If you have a lot of conditions in your text, it can get confusing. As a best practice, whenever you insert an `if` condition, add the `endif` at the same time. This will reduce the chances of forgetting to close the if statement. Jekyll won't build if there are problems with the liquid logic.
|
||||
|
||||
@ -1,49 +0,0 @@
|
||||
---
|
||||
title: 5. Customize the conditions file
|
||||
tags:
|
||||
- navigation
|
||||
keywords: "single sourcing, conditions, filtering, attributes, logic"
|
||||
last_updated: "November 30, 2015"
|
||||
summary: "The conditions file is included in various parts of the theme. Its purpose is to set attributes as variables that affect how the theme is constructed. The settings in this file are essential for single sourcing."
|
||||
series: "Getting Started"
|
||||
weight: 7
|
||||
---
|
||||
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
|
||||
## About the conditions.html file
|
||||
The conditions file is a critical file that sets certain variables used in constructing the theme. You already set some of these values in the configuration file, but you need to duplicate some of the settings here. In this file, the settings are variable assignments.
|
||||
|
||||
This file is used as include in certain files. When used as an include, it sets variables that are used to configure your theme. Because you're single sourcing your Jekyll content, you need this file.
|
||||
|
||||
## Customize the conditions file
|
||||
|
||||
In the \_includes/custom directory, open the conditions.html file. Duplicate one of the project settings blocks like this:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% if site.project == "mydoc_writers" %}
|
||||
{% assign audience = "writers" %}
|
||||
{% assign sidebar = site.data.mydoc.mydoc_sidebar.entries %}
|
||||
{% assign topnav = site.data.mydoc.mydoc_topnav.topnav %}
|
||||
{% assign topnav_dropdowns = site.data.mydoc.mydoc_topnav.topnav_dropdowns %}
|
||||
{% assign version = "all" %}
|
||||
{% assign product = "all" %}
|
||||
{% assign platform = "all" %}
|
||||
{% assign projectTags = site.data.mydoc.mydoc_tags.allowed-tags %}
|
||||
{% assign projectFolder = "mydoc" %}
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You need to duplicate this block for each output you have.
|
||||
|
||||
Once you've duplicated the block, make a few customizations:
|
||||
|
||||
* In each place that "mydoc" appears, change "mydoc" to "acme".
|
||||
* Use the same attributes for project, audience, version, product, and platform that you used in your configuration file. (If you don't have a specific attribute value that you need, just put "all".) The values here have to exactly match those in the configuration file.
|
||||
|
||||
{{site.data.alerts.tip}} If you want to create signposts in the code as shown in the conditions.html file, install a utility called [figlets](http://www.figlet.org/) on your Mac. The figlets just make scanning long code blocks easier. If you have 15+ configuration groupings in your conditions file, the figlets make it easy to scan.{{site.data.alerts.end}}
|
||||
|
||||
{% include custom/mydoc/getting_started_series_next.html %}
|
||||
|
||||
@ -1,115 +0,0 @@
|
||||
---
|
||||
title: 4. Set the configuration options
|
||||
tags: [single_sourcing, publishing]
|
||||
keywords: configuration, config, publishing options, outputs, projects
|
||||
last_updated: November 30, 2015
|
||||
summary: "The configuration file contains important settings for your project. Some of the values you set here affect the display and functionality of the theme — especially the product, platform, audience, and version."
|
||||
series: "Getting Started"
|
||||
weight: 4
|
||||
---
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
|
||||
## Importance of the 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 most of the settings and other details unique to that site output, such as variables, titles, output directories, build folders, and more.
|
||||
|
||||
## Change the project name within the config file
|
||||
|
||||
By default, the config file contains the project name, such as mydoc, in numerous places. You can do a find and replace in each of the configuration files to replace "mydoc" with your new project's name. You can also fine tune the configuration settings by looking at what each of them does (as described in the following sections).
|
||||
|
||||
## Update the exclude list
|
||||
|
||||
By default, all the files in the Jekyll project are included in the output. You have two manually tell Jekyll which files and folders you want to exclude from the output. In each configuration file there is an `exclude` property that takes a list of items that should be excluded from the build.
|
||||
|
||||
In the new configuration file that you created, exclude the mydoc folder and any other mydoc files that you don't want to be output. Similarly, update the mydoc configuration files to exclude the new project that you added.
|
||||
|
||||
Manually excluding files from the output is one of pain points in Jekyll that I could never solve. Jekyll was not designed for multiple output publishing but was conceived as a way to manage files for a single website.
|
||||
|
||||
## Configuration file variables
|
||||
|
||||
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, some of the options you set in the configuration file determine theme settings. These options are required for this theme to work. The required settings are defined in the following tables.
|
||||
|
||||
## Configuration settings for web outputs
|
||||
|
||||
The values in the following tables are used to control different aspects of the theme and are not arbitrary key-value pairs. As you set up your project, enter the appropriate values for each of these keys in the configuration file.
|
||||
|
||||
If you're unsure how or where the project setting affects the theme, just search for the project setting in the theme (for example, `site.sidebar_version`) and you'll see the files involved.
|
||||
|
||||
The order of the settings doesn't matter.
|
||||
|
||||
| Field | Required? | Description |
|
||||
|-------|-----------|-----------|
|
||||
| **project** | Required| A unique name for the project. The \_includes/custom/conditions.html file will use this project name to determine what sidebar and top nav data files to use. Make this value unique. Note that the project name also determines what conditions are set in the conditions.html file. It's critical that the project name you specify in the configuration file matches the project names in the conditions.html file. Otherwise, the conditions.html file won't be able to set the right variables needed for single sourcing. (Admittedly, the settings for these attributes are somewhat duplicated between the conditions.html and configuration file.)|
|
||||
| **audience** | Required | The audience for the output. This value is also set in the \_includes/custom/conditions.html file. Each entry in \_data/sidebar_doc.yml and \_data/topnav_doc.yml needs to have an audience attribute that matches the correct audience value in order for the sidebar or topnav item to be included.|
|
||||
| **platform** | Required | The platform for the output. The same matching logic applies as with audience.
|
||||
| **product** | Required | The product for the output. The same matching logic applies as with audience.
|
||||
| **version** | Required | The version for the output. The same matching logic applies as with 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. The recommended output folder is `../doc_outputs`. The PDF configuration files will look in that directory for the outputs needed to build the PDF outputs.|
|
||||
| **sidebar_tagline** | Optional | Appears above the sidebar. Usually you put some term related to the site specific build, such as the audience name. In the sample theme files, the taglines are "writers" and "designers." Keep these short — there's not much room. Six or seven letters is perfect.|
|
||||
| **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 "4.0."|
|
||||
| **topnav_title** | Required | Appears next to the home icon 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 — writers" or "Jekyll Documentation Theme — designers." |
|
||||
| **site_title**| Required | 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 rendered as {% raw %}`{{ page.title }}{% endif %} | {{ site.site_title }}`{% endraw %} (these values get dynamically replaced depending on the page name and 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** | Required | Gets configured as the email address in the Send Feedback button in the top navigation bar.|
|
||||
| **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 used to convert Markdown to HTML. This is a Jekyll-specific setting. Use `redcarpet`. Another option is `kramdown`. However, my examples will follow redcarpet. |
|
||||
| **redcarpet** | Required | Extensions used with redcarpet. You can read more about the Red Carpet extensions [here](https://github.com/vmg/redcarpet). |
|
||||
| **highlighter** | Required | The syntax highlighter used. Use `rouge` because it has fewer dependencies on your operating system (it doesn't require Python). However, you can also use `pygments`. If so, you may need need to [install Pygments](http://pygments.org/download/). |
|
||||
| **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. If you don't want to include a file or directory, list it here. It's helpful to name your files with a prefix such as product_audience_filename.md, so that you can exclude using wildcards such as "product*" or product_audience*". For more information about excluding files, see {{site.data.mydoc.mydoc_urls.mydoc_excluding_files.link}}. |
|
||||
| **defaults** | Optional | Here you can set default values for frontmatter based on the content type (page, post, or collection). |
|
||||
| **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. Tooltips are useful for creating UI content. For more information about creating tooltips for UI text, see {{site.data.mydoc.mydoc_urls.mydoc_help_api.link}}. |
|
||||
| **output** | Optional | Boolean. Whether this build is `web` or `pdf`. This setting allows you to run conditions in your content such as {% raw %} `{% if site.output == pdf %}` do this... `{% endif %}` {% endraw %}. Limit the options to just `web` or `pdf` for this setting. |
|
||||
| **github_editme_path** | Optional | A path to configure the Github Edit Me button. Put the path to the branch on Github where you want to edit the theme. Here's a sample: `tomjohnson1492/documentation-theme-jekyll/edit/reviews`. In this case, "reviews" is the name of the branch where I want people to make edits. I can then merge the "reviews" branch with the "gh-pages" branch (which is the default branch). See the "page" layout (inside the \_layouts folder) for how this path gets inserted into the rest of the HTML.|
|
||||
| **company_name** | Optional | Used in the footer to brand your site.|
|
||||
| **footer_image_location** | Optional | The image used in the footer to brand your site. Store this image in the common_images folder so that it's not excluded by a particular project. Example: ../common_images/company_logo.png|
|
||||
| **theme_file** | Optional | The theme used for the output. Currently there are two options: theme-green.css or theme-blue.css. These themes cover both web and PDF output. The themes have the same style and layout. They only differ in the accent color for the top nav bar, buttons, hyperlinks, and other small details. |
|
||||
| **pdf_file_name** | Optional | The name of the PDF file generated by Prince. This is helpful for the code on the home.md page that allows users to download a PDF of the material. If you have 5 different PDFs, you don't want to use `if` statements to render different PDF buttons. Instead, this theme uses the same PDF code but swaps out the PDF file name with a variable here. |
|
||||
|
||||
## Where to store configuration files
|
||||
|
||||
In this theme, all the configuration files are listed in the configs directory. There are some build scripts in the root directory that reference the configuration files in this configs folder.
|
||||
|
||||
There's also a \_config.yml file in the root directory. This is simply copied from the configs directory and used to accommodate publishing with Github Pages.
|
||||
|
||||
## Configuration settings for PDF output
|
||||
|
||||
The PDF configuration files build on all the settings in the web configuration files, but they add a few more options.
|
||||
|
||||
When you build the PDF output (such as for the writers output), the command will look like this:
|
||||
|
||||
```
|
||||
jekyll serve --detach --config configs/config_writers.yml,configs/config_writers_pdf.yml
|
||||
```
|
||||
|
||||
First Jekyll will read the config_writers.yml file, and then Jekyll will read the config_writers_pdf.yml file. Values from both configuration files will be used, but the later configuration file (on the right) will overwrite any values set in the previous configuration file (on the left).
|
||||
|
||||
(Previously people running Windows reported problems with cascading the configuration files like this. If you're on Windows, for PDF outputs, you may need to combine the settings from the web configuration file into the PDF configuration file.)
|
||||
|
||||
More detail about generating PDFs is provided in {{site.data.mydoc.mydoc_urls.mydoc_generating_pdfs.link}}, but the configuration settings used for the PDFs are described here.
|
||||
|
||||
The process for creating PDFs relies on two steps:
|
||||
|
||||
1. First you build a printer-friendly web version of the content.
|
||||
2. Then you run PrinceXML to get all the printer-friendly web pages and package them into a PDF.
|
||||
|
||||
Thus, you actually build a web version for the PDF first before generating the PDF.
|
||||
|
||||
The following table describes the settings in the PDF configuration file.
|
||||
|
||||
| Field | Required? | Description |
|
||||
|-------|-----------|-----------|
|
||||
| **destination** | Where the PDF web version should be served so that Prince XML can find it. By default, this is in `../mydoc_designers-pdf`, which is just one level above where your project is. |
|
||||
| **url** | The URL where the files can be viewed. This is `http://127.0.0.1:4002` in the sample theme files for the designers output. Prince XML requires a URL to access the file. |
|
||||
| **baseurl** | The subdirectory after the url where the content is stored. In the sample theme files for the designers output, this is `/designers`. |
|
||||
| **port** | The port required by the preview server. |
|
||||
| **output** | `web` or `pdf`. This setting allows you to construct conditional statements in your content to check whether output is web or pdf. This setting can help you filter out content that doesn't fit well into a PDF (such as dynamic web elements). In particular, the Prince XML script conflicts with any JavaScript on the page, so you want to filter out the JavaScript from the PDF-friendly HTML output that Prince consumes.|
|
||||
| **print_title** | The title for the PDF. In the sample theme files for designers output, the print title is "Jekyll Documentation Theme for Designers"|
|
||||
| **print_subtitle** | The subtitle for the PDF. In the sample theme files, the subtitle is "version 4.0." |
|
||||
| **defaults** | See the sample settings in the config_designers_pdf.yml file. The only difference between this file and config_designers.yml is that the layout used for pages is `page_print` instead of `page`. The `page_print` layout also used `head_print` instead of `head`. This layout strips out components such as the sidebar and top navigation. It also leverages printstyles.css and includes some JavaScript for Prince XML. |
|
||||
|
||||
{% include custom/mydoc/getting_started_series_next.html %}
|
||||
@ -1,146 +0,0 @@
|
||||
---
|
||||
title: 6. Configure the sidebar
|
||||
tags: [getting_started]
|
||||
last_updated: November 30, 2015
|
||||
keywords: sidebar, accordion, yaml, iteration, for loop, navigation, attributes, conditional filtering
|
||||
summary: "The sidebar and top navigation bar read their values from yml files. The navigation components are one of the most unique parts of this theme, since the navigation components are only included if they meet all of the product, audience, version, etc., values as specified in the project settings. Understanding how the sidebar works is critical to successfully using this theme."
|
||||
series: "Getting Started"
|
||||
weight: 6
|
||||
---
|
||||
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
|
||||
## Understand how the sidebar works
|
||||
|
||||
In the \_data folder, the mydoc_sidebar.yml files contains the sidebar items for the theme. These list items (which are in YAML format) form your main navigation, and all pages in your project must appear here to be included in the PDF or the URL generator. Both the PDF and the URL generator (mydoc_urls.txt) iterate over the pages listed in the mydoc_sidebar.yml file to produce their output.
|
||||
|
||||
As a best practice, do the following with the sidebar:
|
||||
|
||||
* List all pages in your project somewhere in the sidebar.
|
||||
* As soon as you create a new page, add it to your sidebar (so you don't forget about the page).
|
||||
* Copy and paste the existing YAML chunks (then customize them) to get the formatting right.
|
||||
|
||||
YAML is a markup that uses spacing and hyphens instead of tags. YAML is a superset of JSON, so you can convert from YAML to JSON and vice versa equivalently.
|
||||
|
||||
There are certain values in the sidebar file coded to match the theme's code. These values include the main level names (`entries`, `subcategories`, `items`, `thirdlevel`, and `thirdlevelitems`). If you change these values in the sidebar file, the navigation won't display. (As long as you follow the sample with mydoc_sidebar.yml, you should be fine.)
|
||||
|
||||
At a high level, the sidebar data structure looks like this:
|
||||
|
||||
```yaml
|
||||
entries
|
||||
subcategories
|
||||
items
|
||||
thirdlevel
|
||||
thirdlevelitems
|
||||
```
|
||||
|
||||
Within these levels, you add your content. You can only have two levels in the sidebar. Here's an example:
|
||||
|
||||
```
|
||||
Introduction
|
||||
-> Getting started
|
||||
-> Features
|
||||
-> Configuration
|
||||
-> Options
|
||||
-> Automation
|
||||
```
|
||||
|
||||
"Introduction" is a heading — it's the first level. Beneath it are Getting started and Features — these sub-items for the first level.
|
||||
|
||||
Configuration is a heading announcing a second level. Below it are Options and Automation — these are on the second level.
|
||||
|
||||
You can't add more than two levels. In general, it's a best practice not to create more than two levels of navigation anyway, since it creates a paralysis of choice for the user.
|
||||
|
||||
(If you need deeper sublevels, I recommend creating different sidebars for different pages, which is logic that I haven't coded into the theme but which could probably be added fairly easily. Additionally, if you wanted to create a third level, you could do so by following the same pattern as the second level and customizing a few things. However, the theme is not coded to support additional levels.)
|
||||
|
||||
The code in the theme's sidebar.html file (in the \_includes folder) iterates through the items in the mydoc_sidebar.yml file using a Liquid `for` loop and inserts the items into HTML. Iterating over a list in a data file to populate HTML is a common technique with static site generators.
|
||||
|
||||
What I've added in this theme is some special logic that checks if the sidebar items meet the right attribute conditions. As a result, the sidebar.html file has code that looks like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% include custom/conditions.html %}
|
||||
{% for entry in sidebar %}
|
||||
{% for subcategory in entry.subcategories %}
|
||||
{% if subcategory.audience contains audience and subcategory.product contains product and subcategory.platform contains platform and subcategory.version contains version and subcategory.output contains "web" %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Only if the sidebar item contains the right `audience`, `product`, `platform`, `version`, and `output` attributes does the item get included in the sidebar navigation.
|
||||
|
||||
This means you will have just one sidebar data file for all the outputs in a single project. Different projects will use different sidebar data files, but all outputs for a single project will use the same sidebar data file. (This allows you to do single sourcing.)
|
||||
|
||||
If you look at the code above, you'll see that `audience`, `product`, `platform`, and `version` are defined generally. In sidebar.html, there are lines like `subcategory.audience contains audience`.
|
||||
|
||||
This is where the conditions.html file (inside \_includes) comes into play. `audience` is a variable defined in the conditions.html file. If you open up conditions.html, you'll see something like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if site.project == "mydoc_writers" %}
|
||||
{% assign audience = "writers" %}
|
||||
{% assign sidebar = site.data.mydoc.mydoc_sidebar.entries %}
|
||||
{% assign topnav = site.data.mydoc.mydoc_topnav.topnav %}
|
||||
{% assign topnav_dropdowns = site.data.mydoc.mydoc_topnav.topnav_dropdowns %}
|
||||
{% assign version = "all" %}
|
||||
{% assign product = "all" %}
|
||||
{% assign platform = "all" %}
|
||||
{% assign projectTags = site.data.mydoc.mydoc_tags.allowed-tags %}
|
||||
{% assign projectFolder = "mydoc" %}
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
`audience` is a variable set to `writers` for the mydoc_writers project. Therefore anywhere `audience` appears, `writers` gets inserted in its place.
|
||||
|
||||
When the sidebar.html code runs `subcategory.audience contains audience`, it's saying that the subcategory item must have an attribute called `audience`, and the value for audience must contain `writers`.
|
||||
|
||||
All of the attributes (which are defined in the conditions.html file) must be met in order to display in the navigation. The attributes must be present on both the heading and items under that heading.
|
||||
|
||||
However, note that the `output` attribute is a bit different. With this attribute, you just list whether you want a `web` or `pdf` output (or both, usually). For both, you just write `web, pdf`.
|
||||
|
||||
The logic in the sidebar is multi-step and somewhat complex, but you're also doing something truly sophisticated. You're instructing a static site generator to conditionally include certain information while using the same source files (not just the same sidebar data file, but the same sidebar.html file).
|
||||
|
||||
Fortunately, once you set it up, you don't need to think about the underlying logic that's processing. You just make sure you're putting the right attributes on your sidebar items.
|
||||
|
||||
## Recognize the frontmatter in the sidebar
|
||||
|
||||
The first section in the sidebar subcategory list is a special frontmatter section that you should pretty much leave alone (except for changing the attribute values). It looks like this:
|
||||
|
||||
```yaml
|
||||
- title:
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
product: all
|
||||
version: all
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
items:
|
||||
- title:
|
||||
url: /titlepage.html
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
product: all
|
||||
version: all
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
- title:
|
||||
url: /tocpage.html
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
product: all
|
||||
version: all
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
|
||||
```
|
||||
|
||||
The only values you should change here are the values for the `audience`, `platform`, `product,` and `version`.
|
||||
|
||||
These frontmatter pages are used in producing the PDF. This part will grab the titlepage.html and tocpage.html content in the theme's root directory. (If you're not publishing PDF, you can remove this section.)
|
||||
|
||||
Note that the output is `pdf` only for these frontmatter pages. They are specific to the PDF output only.
|
||||
|
||||
|
||||
To learn more about the sidebar, see {{site.data.mydoc.mydoc_urls.mydoc_sidebar_navigation.link}}.
|
||||
|
||||
{% include custom/mydoc/getting_started_series_next.html %}
|
||||
@ -2,30 +2,24 @@
|
||||
title: Content reuse
|
||||
tags: [single_sourcing]
|
||||
keywords: includes, conref, dita, transclusion, transclude, inclusion, reference
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can reuse chunks of content by storing these files in the includes folder. You then choose to include the file where you need it. This works similar to conref in DITA, except that you can include the file in any content type."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_content_reuse/
|
||||
---
|
||||
|
||||
## About content reuse
|
||||
You can embed content from one file inside another using includes. Put the file containing content you want to reuse (e.g., mypage.html) inside the \_includes/mydoc folder (replacing "mydoc" with your project's name), and then use a tag like this:
|
||||
You can embed content from one file inside another using includes. Put the file containing content you want to reuse (e.g., mypage.html) inside the \_includes/custom folder and then use a tag like this:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% include mydoc/mypage.html %}
|
||||
{% include custom/mypage.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
With content in your \_includes folder, you don't add any frontmatter to these pages because they will be included on other pages already containing frontmatter.
|
||||
|
||||
Also, when you include a file, all of the file's contents get included. You can't specify that you only want a specific part of the file included. However, you can use parameters with includes. See [Jekyll's documentation](http://stackoverflow.com/questions/21976330/passing-parameters-to-inclusion-in-liquid-templates) for more information on that.
|
||||
|
||||
## Re-using content across projects
|
||||
|
||||
When you want to re-use a topic across projects, store the content in the \includes folder (it can be in any project's subfolder). Any folder that begins with an underscore (`_`) isn't included in the site output.
|
||||
|
||||
Also be sure to put any images in the common_images folder. None of the assets in the common_images folder should be excluded in the configuration files. This means every project's output will include the resources from the common_images folder.
|
||||
|
||||
However, each project will likely exclude content from the specific folders where the pages are stored. This is why reuse across projects requires you to use the \_includes folder and the common_images folder. (Unfortunately you can't include an image from the \_includes folder.)
|
||||
Also, when you include a file, all of the file's contents get included. You can't specify that you only want a specific part of the file included. However, you can use parameters with includes. See [Jekyll's documentation](http://stackoverflow.com/questions/21976330/passing-parameters-to-inclusion-in-liquid-templates) for more information.
|
||||
|
||||
## Page-level variables
|
||||
|
||||
@ -51,7 +45,6 @@ thing2: {{page.thing2}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
I haven't found a use case for page-level variables, but it's nice to know they're available.
|
||||
|
||||
I use includes all the time. Most of the includes in the \_includes directory are pulled into the theme layouts. For those includes that change, I put them inside custom and then inside a specific project folder.
|
||||
|
||||
|
||||
@ -1,29 +0,0 @@
|
||||
---
|
||||
title: 3. Decide on your project's attributes
|
||||
tags: [getting_started]
|
||||
last_updated: November 30, 2015
|
||||
keywords: attributes, conditional filtering, audience, platform, product, version, output, DITA, variables
|
||||
summary: "Each project has attributes that define the audience, platform, product, version, and output. These attributes are used in generating the outputs. The attributes function as filtering conditions that determine what content gets included in the navigation."
|
||||
series: "Getting Started"
|
||||
weight: 3
|
||||
---
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
|
||||
## Your attribute values
|
||||
Before you can customize your project's settings, you have to make some decisions about the following:
|
||||
|
||||
* `audience`
|
||||
* `platform`
|
||||
* `product`
|
||||
* `version`
|
||||
* `output` (web, pdf)
|
||||
|
||||
Every project uses a value for these settings, so even if the attribute doesn't apply to your project, you will need to put some value for `audience`, `platform`, `product`, and `version` (a value such as `all` will work fine).
|
||||
|
||||
The `audience`, `platform`, `product`, and `version` settings derive from the same filtering attributes as in DITA. You can usually create any kind of filtered output by combining these attributes in different ways.
|
||||
|
||||
For example, you might have different product lines (lite versus pro), different versions (1.0 versus 2.0), different platforms (such as Java versus C++), and different audiences (administrators versus analysts) and so on. You'll need to know the values you want to use for each attribute in order to configure the project successfully to build the different outputs.
|
||||
|
||||
If you aren't sure of your outputs, just put `all` for the `audience`, `platform`, `product`, and `version`. For the `output` value, the options are fixed to either `web` or `pdf` (or both — `web, pdf` — separated by a comma).
|
||||
|
||||
{% include custom/mydoc/getting_started_series_next.html %}
|
||||
@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Excluding files
|
||||
tags: [single_sourcing]
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
keywords: exclusion, separating outputs, removing files from outputs
|
||||
summary: "By default, all the files in your Jekyll project are included in the output (this differs from DITA projects, which don't include files unless noted on the map). If you're single sourcing, you'll need to exclude the files that shouldn't be included in the output. The sidebar doesn't control inclusion or exclusion."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_exluding_files/
|
||||
---
|
||||
|
||||
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: FAQ layout
|
||||
tags: [special_layouts]
|
||||
keywords: frequently asked questions, FAQ, question and answer, collapsible sections, expand, collapse
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can use an accordion-layout that takes advantage of Bootstrap styling. This is useful for an FAQ page."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_faq/
|
||||
---
|
||||
|
||||
If you want to use an FAQ format, use the syntax shown on the faq.html page. Rather than including code samples here (which are bulky with a lot of nested <code>div</code> tags), just look at the source in the mydoc_faq.html theme file.
|
||||
|
||||
@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Generating PDFs
|
||||
permalink: /mydoc_generating_pdfs/
|
||||
tags: [publishing, single_sourcing, content-types]
|
||||
keywords: PDF, prince, prince XML, ant, xsl fo
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can generate a PDF from your Jekyll project. You do this by creating a web version of your project that is printer friendly. You then use utility called Prince to iterate through the pages and create a PDF from them. It works quite well and gives you complete control to customize the PDF output through CSS, including page directives and dynamic tags from Prince."
|
||||
sidebar: mydoc_sidebar
|
||||
---
|
||||
|
||||
|
||||
@ -18,9 +20,9 @@ Also, creating a PDF this way gives you a lot more control and customization cap
|
||||
|
||||
## Demo
|
||||
|
||||
You can see an example of the finished product here:
|
||||
You can see an example of the finished product here:
|
||||
|
||||
<a target="_blank" class="noCrossRef" href="files/{{pdf_file_name}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
<a target="_blank" class="noCrossRef" href="{{ "/pdf/mydoc.pdf" | prepend: site.baseurl }}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
|
||||
## 1. Set up Prince
|
||||
|
||||
@ -30,16 +32,17 @@ You can install a fully functional trial version. The only difference is that th
|
||||
|
||||
## 2. Create a new configuration file for each of your PDF targets
|
||||
|
||||
The PDF configuration file will build on the settings in the regular configuration file but will some additional fields. Here's the configuration file for the config_designers.yml file for this theme:
|
||||
The PDF configuration file will build on the settings in the regular configuration file but will some additional fields. Here's the configuration file for the mydoc product within this theme. This configuration file is located in the pdfconfigs folder.
|
||||
|
||||
```
|
||||
destination: ../doc_outputs/mydoc/designers-pdf
|
||||
destination: _site/
|
||||
url: "http://127.0.0.1:4010"
|
||||
baseurl: "/mydoc/designers-pdf"
|
||||
baseurl: "/mydoc-pdf"
|
||||
port: 4010
|
||||
output: pdf
|
||||
print_title: Jekyll theme for documentation — designers
|
||||
print_subtitle: version 4.0
|
||||
product: mydoc
|
||||
print_title: Jekyll theme for documentation — mydoc product
|
||||
print_subtitle: version 5.0
|
||||
output: pdf
|
||||
defaults:
|
||||
-
|
||||
@ -52,14 +55,14 @@ defaults:
|
||||
search: true
|
||||
```
|
||||
|
||||
{{site.data.alerts.note}} Although you're creating a PDF, you must still build an HTML web target before running Prince. Prince will pull from the HTML files and from the file-list for the TOC. Prince won't be able to find files if they simply have relative paths, such as /sample.html. The must have full URLs it can access — hence the <code>url</code> and <code>baseurl</code>. {{site.data.alerts.end}}
|
||||
{{site.data.alerts.note}} Although you're creating a PDF, you must still build an HTML web target before running Prince. Prince will pull from the HTML files and from the file-list for the TOC. {{site.data.alerts.end}}
|
||||
|
||||
Also note that the default page layout is `page_print`. This layout strips out all the sections that shouldn't appear in the print PDF, such as the sidebar and top navigation bar.
|
||||
Note that the default page layout specified by this configuration file is `page_print`. This layout strips out all the sections that shouldn't appear in the print PDF, such as the sidebar and top navigation bar.
|
||||
|
||||
Finally, note that there's a `output: pdf` toggle in case you want to make some of your content unique to PDF output. For example, you could add conditional logic that checks whether `site.output` is `pdf` or `web`. If it's `pdf`, then include information only for the PDF, and so on.
|
||||
Also note that there's a `output: pdf` toggle in case you want to make some of your content unique to PDF output. For example, you could add conditional logic that checks whether `site.output` is `pdf` or `web`. If it's `pdf`, then include information only for the PDF, and so on. If you're using nav tabs, you'll definitely want to create an alternative experience in the PDF.
|
||||
|
||||
In the configuration file, customize the values for the `print_title` and `print_subtitle` that you want. These will appear on the title page of the PDF.
|
||||
|
||||
|
||||
## 3. Make sure your sidebar_doc.yml file has a titlepage.html and tocpage.html
|
||||
|
||||
There are two template pages in the root directory that are critical to the PDF:
|
||||
@ -67,51 +70,40 @@ There are two template pages in the root directory that are critical to the PDF:
|
||||
* titlepage.html
|
||||
* tocpage.html
|
||||
|
||||
These pages should appear in your sidebar YML file (in this theme, sidebar_doc.yml):
|
||||
These pages should appear in your sidebar YML file (in this product, mydoc_sidebar.yml):
|
||||
|
||||
```json
|
||||
- title:
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
product: all
|
||||
version: all
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
items:
|
||||
- title:
|
||||
url: /titlepage.html
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
product: all
|
||||
version: all
|
||||
url: /titlepage/
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
- title:
|
||||
url: /tocpage.html
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
product: all
|
||||
version: all
|
||||
url: /tocpage/
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
```
|
||||
|
||||
Leave these pages here in your sidebar. (The `output: pdf` property means they won't appear in your online TOC because the conditional logic of the sidebar.html checks whether `web` is equal to `pdf` or not before including the item in the web version of the content.)
|
||||
|
||||
The code in the tocpage.html is nearly identical to that of the sidebar.html page except that it includes the `site` and `baseurl` for the URLs. This is essential for Prince to create the page numbers correctly with cross references.
|
||||
The code in the tocpage.html is mostly identical to that of the sidebar.html page. This is essential for Prince to create the page numbers correctly with cross references.
|
||||
|
||||
There's another file (in the root directory of the theme) that is critical to the PDF generation process: prince-file-list.txt. This file simply iterates through the items in your sidebar and creates a list of links. Prince will consume the list of links from prince-file-list.txt and create a running PDF that contains all of the pages listed, with appropriate cross references and styling for them all.
|
||||
There's another file (in the root directory of the theme) that is critical to the PDF generation process: prince-list.txt. This file simply iterates through the items in your sidebar and creates a list of links. Prince will consume the list of links from prince-list.txt and create a running PDF that contains all of the pages listed, with appropriate cross references and styling for them all.
|
||||
|
||||
{{site.data.alerts.note}} If you have any files that you do not want to appear in the PDF, add <code>output: web</code> (rather than <code>output: pdf</code>) in the list of attributes in your sidebar. The prince-file-list.txt file that loops through the mydoc_sidebar.yml file to grab the URLs of each page that should appear in the PDF will skip over any items that do not list <code>output: pdf</code> in the item attributes. For example, you might not want your tag archives to appear in the PDF, but you probably will want to list them in the online help navigation. {{site.data.alerts.end}}
|
||||
{{site.data.alerts.note}} If you have any files that you do not want to appear in the PDF, add <code>output: web</code> (rather than <code>output: pdf</code>) in the list of attributes in your sidebar. The prince-list.txt file that loops through the mydoc_sidebar.yml file to grab the URLs of each page that should appear in the PDF will skip over any items that do not list <code>output: pdf</code> in the item attributes. For example, you might not want your tag archives to appear in the PDF, but you probably will want to list them in the online help navigation. {{site.data.alerts.end}}
|
||||
|
||||
## 4. Customize your headers and footers
|
||||
|
||||
Open up the css/printstyles.css file and customize what you want for the headers and footers. At the very least, customize the email address (`youremail@domain.com`) that appears in the bottom left.
|
||||
|
||||
Exactly how the print styling works here is pretty cool. You don't need to understand the rest of the content in this section unless you want to customize your PDFs to look different from what I've configured.
|
||||
Exactly how the print styling works here is pretty nifty. You don't need to understand the rest of the content in this section unless you want to customize your PDFs to look different from what I've configured. But I'm adding this information here in case you want to understand how to customize the look and feel of the PDF output.
|
||||
|
||||
This style creates a page reference for a link:
|
||||
|
||||
{% raw %}
|
||||
```css
|
||||
a[href]::after {
|
||||
content: " (page " target-counter(attr(href), page) ")"
|
||||
@ -125,10 +117,11 @@ a[href*="mailto"]::after, a[data-toggle="tooltip"]::after, a[href].noCrossRef::a
|
||||
content: "";
|
||||
}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{{site.data.alerts.tip}} If you have a link to a file download, or some other link that shouldn't have a cross reference (such as link used in JavaScript for navtabs or collapsible sections, for example, add `noCrossRef` as a class to the link to avoid having it say "page 0" in the cross reference.{{site.data.alerts.end}}
|
||||
|
||||
This style specifies that following links to web resources, the URL should be inserted instead of the page number:
|
||||
This style specifies that after links to web resources, the URL should be inserted instead of the page number:
|
||||
|
||||
```css
|
||||
a[href^="http:"]::after, a[href^="https:"]::after {
|
||||
@ -148,7 +141,7 @@ This style sets the page margins:
|
||||
}
|
||||
```
|
||||
|
||||
To set a specific style property for a particular page, you have to name the page. This allows Prince to identify the page.
|
||||
To set a specific style property for a particular page, you have to name the page. This allows Prince to identify the page.
|
||||
|
||||
First you add frontmatter to the page that specifies the type. For the titlepage.html, here's the frontmatter:
|
||||
|
||||
@ -190,7 +183,7 @@ body.title { page: title }
|
||||
|
||||
This means that for content inside of `body class="title"`, we can style this page in our stylesheet using `@page title`.
|
||||
|
||||
Here's how that title page is styled:
|
||||
Here's how that title page is styled:
|
||||
|
||||
```css
|
||||
@page title {
|
||||
@ -211,7 +204,7 @@ Here's how that title page is styled:
|
||||
|
||||
As you can see, we don't have any header or footer content, because it's the title page.
|
||||
|
||||
For the tocpage.html, which has the `type: frontmatter`, this is specified in the stylesheet:
|
||||
For the tocpage.html, which has the `type: frontmatter`, this is specified in the stylesheet:
|
||||
|
||||
```css
|
||||
body.frontmatter { page: frontmatter }
|
||||
@ -235,7 +228,7 @@ body.frontmatter {counter-reset: page 1}
|
||||
|
||||
With `counter(page, lower-roman)`, we reset the page count to 1 so that the title page doesn't start the count. Then we also add some header and footer info. The page numbers start counting in lower-roman numerals.
|
||||
|
||||
Finally, for the first page (which doesn't have a specific name), we restart the counting to 1 again and this time use regular numbers.
|
||||
Finally, for the first page (which doesn't have a specific name), we restart the counting to 1 again and this time use regular numbers.
|
||||
|
||||
```css
|
||||
body.first_page {counter-reset: page 1}
|
||||
@ -286,7 +279,7 @@ There are a couple of Prince functions that are default functions from Prince. T
|
||||
content: string(doctitle);
|
||||
```
|
||||
|
||||
This gets the current page:
|
||||
This gets the current page:
|
||||
|
||||
```js
|
||||
content: "Page " counter(page);
|
||||
@ -296,65 +289,70 @@ Because the theme uses JavaScript in the CSS, you have to add the `--javascript`
|
||||
|
||||
## 5. Customize the PDF script
|
||||
|
||||
Open the mydoc_1_multiserve_pdf.sh file in the root directory and customize it for your specific configuration files.
|
||||
Duplicate the pdf-mydocf.sh file in the root directory and customize it for your specific configuration files.
|
||||
|
||||
```
|
||||
echo 'Killing all Jekyll instances'
|
||||
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
|
||||
clear
|
||||
|
||||
echo "Building PDF-friendly HTML site for Mydoc Writers ..."
|
||||
jekyll serve --detach --config configs/mydoc/config_writers.yml,configs/mydoc/config_writers_pdf.yml
|
||||
echo "done"
|
||||
echo "Building PDF-friendly HTML site for Mydoc ...";
|
||||
jekyll serve --detach --config _config.yml,pdfconfigs/config_mydoc_pdf.yml;
|
||||
echo "done";
|
||||
|
||||
echo "Building PDF-friendly HTML site for Mydoc Designers ..."
|
||||
jekyll serve --detach --config configs/mydoc/config_designers.yml,configs/mydoc/config_designers_pdf.yml
|
||||
echo "done"
|
||||
echo "Building the PDF ...";
|
||||
prince --javascript --input-list=_site/pdfconfigs/prince-list.txt -o _pdf/mydoc.pdf;
|
||||
echo "done";
|
||||
```
|
||||
|
||||
echo "All done serving up the PDF-friendly sites. Now let's generate the PDF files from these sites."
|
||||
echo "Now run . mydoc_2_multibuild_pdf.sh"
|
||||
|
||||
Note that the first part kills all Jekyll instances. This way you won't try to server Jekyll at a port that is already occupied.
|
||||
Note that the first part kills all Jekyll instances. This way you won't try to serve Jekyll at a port that is already occupied.
|
||||
|
||||
The `jekyll serve` command serves up the HTML-friendly PDF configurations for our two projects. This web version is where Prince will go to get its content.
|
||||
|
||||
## 6. Configure the Prince scripts
|
||||
The prince script issues a command to the Prince utility. JavaScript is enabled (`--javascript`), and we tell it exactly where to find the list of files (`--input-list`) — just point to the prince-list.txt file. Then we tell it where and what to output (`-o`).
|
||||
|
||||
Open up mydoc_2_multibuild_pdf.sh and look at the Prince commands:
|
||||
Make sure that the path to the prince-list.txt is correct. For the output directory, I like to output the PDF file into my project's source (into the files folder). Then when I build the web output, the PDF is included and something I can refer to.
|
||||
|
||||
{{site.data.alerts.note}} You might not want to include the PDF in your project files, since you're likely committing the PDF to Github and as a result saving the changes from one PDF version to another with each save. {{site.data.alerts.end}}
|
||||
|
||||
## 6. Add conditions for your new builds in the sidebarconfigs.html file
|
||||
|
||||
In the \_includes/custom/sidebarconfigs.html file, there's a section that looks like this:
|
||||
|
||||
```
|
||||
# Doc Writers
|
||||
echo "Building the Mydoc Writers PDF ..."
|
||||
prince --javascript --input-list=../doc_outputs/mydoc/writers-pdf/prince-file-list.txt -o mydoc/files/mydoc_writers_pdf.pdf;
|
||||
echo "done"
|
||||
|
||||
# Doc Designers
|
||||
echo "Building Mydoc Designers PDF ..."
|
||||
prince --javascript --input-list=../doc_outputs/mydoc/designers-pdf/prince-file-list.txt -o mydoc/files/mydoc_designers_pdf.pdf;
|
||||
echo "done"
|
||||
{% comment %}
|
||||
sidebar configuration for print files
|
||||
{% endcomment %}
|
||||
|
||||
echo "All done building the PDFs!"
|
||||
echo "Now build the web outputs: . mydoc_3_multibuild_web.sh"
|
||||
{% if site.product == "mydoc" %}
|
||||
{% assign sidebar_pdf = site.data.sidebars.mydoc_sidebar.entries %}
|
||||
{% endif %}
|
||||
|
||||
{% if site.product == "product1" %}
|
||||
{% assign sidebar_pdf = site.data.sidebars.product1_sidebar.entries %}
|
||||
{% endif %}
|
||||
|
||||
{% if site.product == "product2" %}
|
||||
{% assign sidebar_pdf = site.data.sidebars.product2_sidebar.entries %}
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
This script issues a command to the Prince utility. JavaScript is enabled (`--javascript`), and we tell it exactly where to find the list of files (`--input-list`) — just point to the prince-file-list.txt file. Then we tell it where and what to output (`-o`).
|
||||
Add your own condition here that points to your sidebar.
|
||||
|
||||
Make sure that the path to the prince-file-list.txt is correct. For the output directory, I like to output the PDF file into my project's source (into the files folder). Then when I build the web output, the PDF is included and something I can refer to.
|
||||
What this does is allow the prince-list.txt and toc.html files to use a variable for the sidebar (called `sidebar_pdf`) when iterating through the sidebar. Otherwise, you would need to create a unique prince-list.txt and toc.html file for each separate PDF output you have.
|
||||
|
||||
## 7. Add a download button for the PDF
|
||||
|
||||
You can add a download button for your PDF using some Bootstrap button code:
|
||||
|
||||
```html
|
||||
<a target="_blank" class="noCrossRef" href="files/{{site.pdf_file_name}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
<a target="_blank" class="noCrossRef" href="/pdf/mydoc.pdf"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
```
|
||||
|
||||
Here's what that looks like:
|
||||
|
||||
<a target="_blank" class="noCrossRef" href="files/{{site.pdf_file_name}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
|
||||
The {% raw %}`{{site.pdf_file_name}}`{% raw %} is set in the configuration file.
|
||||
|
||||
{{site.data.alerts.note}} If you don't like the style of the PDFs, just adjust the styles in the printstyles.css file.{{site.data.alerts.end}}
|
||||
<a target="_blank" class="noCrossRef" href={{ "/pdf/mydoc.pdf" | prepend: site.baseurl}}"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
|
||||
## JavaScript conflicts
|
||||
|
||||
@ -387,7 +385,7 @@ The theme relies on Bootstrap's CSS for styling. However, for print media, Boots
|
||||
```
|
||||
@media print{*,:after,:before{color:#000!important;text-shadow:none!important;background:0 0!important;-webkit-box-shadow:none!important;box-shadow:none!important}
|
||||
```
|
||||
This is minified, but basically the `*` (asterisk) means select all, and applied the color #000 (black). As a result, the Bootstrap style strips out all color from the PDF (for Bootstrap elements).
|
||||
This is minified, but basically the `*` (asterisk) means select all, and applied the color #000 (black). As a result, the Bootstrap style strips out all color from the PDF (for Bootstrap elements).
|
||||
|
||||
This is problematic for code snippets that have syntax highlighting. I decided to remove this de-coloring from the print output. I commented out the Bootstrap style:
|
||||
|
||||
|
||||
@ -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 %}
|
||||
|
||||
|
||||
|
||||
|
||||
@ -4,6 +4,8 @@ summary: "If you're interacting with your team using Git, the notes and tips wil
|
||||
tags: collaboration
|
||||
keywords: git, github, collaboration, interaction, file sharing, push
|
||||
published: false
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_git_collaboration/
|
||||
---
|
||||
|
||||
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Glossary layout
|
||||
tags: [formatting, special_layouts]
|
||||
keywords: definitions, glossaries, terms, style guide
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "Your glossary page can take advantage of definitions stored in a data file. This gives you the ability to reuse the same definition in multiple places. Additionally, you can use Bootstrap classes to arrange your definition list horizontally."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_glossary/
|
||||
---
|
||||
|
||||
|
||||
|
||||
@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Help APIs and UI tooltips
|
||||
tags: [publishing, single_sourcing, content-types]
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
keywords: API, content API, UI text, inline help, context-sensitive help, popovers, tooltips
|
||||
summary: "You can loop through files and generate a JSON file that developers can consume like a help API. Developers can pull in values from the JSON into interface elements, styling them as popovers for user interface text, for example. The beauty of this method is that the UI text remains in the help system (or at least in a single JSON file delivered to the dev team) and isn't hard-coded into the UI."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_help_api/
|
||||
---
|
||||
|
||||
|
||||
@ -23,7 +25,7 @@ Additionally, instead of tooltip popovers, you could also print content directly
|
||||
|
||||
Here's a diagram showing the basic idea of the help API:
|
||||
|
||||
<img src="images/helpapi.svg" style="width: 650px;"/>
|
||||
<img src="{{ "/images/helpapi.svg" | prepend: site.baseurl }}" style="width: 650px;"/>
|
||||
|
||||
Is this really an API? Well, sort of. The help content is pushed out into a JSON file that other websites and applications can easily consume. The endpoints don't deliver different data based on parameters added to a URL. But the overall concept is similar to an API: you have a client requesting resources from a server.
|
||||
|
||||
@ -49,7 +51,7 @@ In Jekyll, folders that begin with an underscore ("_") aren't included in the ou
|
||||
|
||||
## 2. Create tooltip definitions in a YAML file
|
||||
|
||||
Inside \_data > mydoc create a YAML file called something like mydoc_definitions.yml. Add the definitions for each of your tooltips here like this:
|
||||
Inside \_data > mydoc create a YAML file called something like definitions.yml. Add the definitions for each of your tooltips here like this:
|
||||
|
||||
```yaml
|
||||
basketball: "Basketball is a sport involving two teams of five players each competing to put a ball through a small circular rim 10 feet above the ground. Basketball requires players to be in top physical condition, since they spend most of the game running back and forth along a 94-foot-long floor."
|
||||
@ -59,7 +61,7 @@ The definition of basketball is stored this data file so that you can re-use it
|
||||
|
||||
## 3. Create pages in your collection
|
||||
|
||||
Create pages inside your new tooltips collection (that is, inside the \_tooltips folder). Each page needs to have a unique `id` in the frontmatter as well as a `product`. Then reference the definition you created in the mydoc_definitions.yml file.
|
||||
Create pages inside your new tooltips collection (that is, inside the \_tooltips folder). Each page needs to have a unique `id` in the frontmatter as well as a `product`. Then reference the definition you created in the definitions.yml file.
|
||||
|
||||
Here's an example:
|
||||
|
||||
@ -70,7 +72,7 @@ id: basketball
|
||||
product: mydoc
|
||||
---
|
||||
|
||||
{{site.data.mydoc.mydoc_definitions.basketball}}
|
||||
{{site.data.definitions.basketball}}
|
||||
```
|
||||
{%endraw%}
|
||||
|
||||
@ -115,19 +117,19 @@ This code will loop through all pages in the tooltips collection and insert the
|
||||
"entries": [
|
||||
{
|
||||
"id": "baseball",
|
||||
"body": "{{site.data.mydoc.mydoc_definitions.baseball}}"
|
||||
"body": "{{site.data.definitions.baseball}}"
|
||||
},
|
||||
{
|
||||
"id": "basketball",
|
||||
"body": "{{site.data.mydoc.mydoc_definitions.basketball}}"
|
||||
"body": "{{site.data.definitions.basketball}}"
|
||||
},
|
||||
{
|
||||
"id": "football",
|
||||
"body": "{{site.data.mydoc.mydoc_definitions.football}}"
|
||||
"body": "{{site.data.definitions.football}}"
|
||||
},
|
||||
{
|
||||
"id": "soccer",
|
||||
"body": "{{site.data.mydoc.mydoc_definitions.soccer}}"
|
||||
"body": "{{site.data.definitions.soccer}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -220,7 +222,7 @@ $.get( url, function( data ) {
|
||||
|
||||
$.each(data.entries, function(i, page) {
|
||||
if (page.id == "basketball") {
|
||||
$( "#basketball" ).attr( "data-content", page.body );
|
||||
$( "#basketball" ).attr( "data-content", page.body );
|
||||
}
|
||||
|
||||
});
|
||||
@ -295,22 +297,22 @@ Here's how you would reuse the content:
|
||||
|
||||
<tr>
|
||||
<td>Basketball</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.basketball}}</td>
|
||||
<td>{{site.data.definitions.basketball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Baseball</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.baseball}}</td>
|
||||
<td>{{site.data.definitions.baseball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Football</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.football}}</td>
|
||||
<td>{{site.data.definitions.football}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Soccer</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.soccer}}</td>
|
||||
<td>{{site.data.definitions.soccer}}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@ -333,22 +335,22 @@ And here's the code:
|
||||
|
||||
<tr>
|
||||
<td>Basketball</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.basketball}}</td>
|
||||
<td>{{site.data.definitions.basketball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Baseball</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.baseball}}</td>
|
||||
<td>{{site.data.definitions.baseball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Football</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.football}}</td>
|
||||
<td>{{site.data.definitions.football}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Soccer</td>
|
||||
<td>{{site.data.mydoc.mydoc_definitions.soccer}}</td>
|
||||
<td>{{site.data.definitions.soccer}}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
@ -3,19 +3,15 @@ title: Links
|
||||
audience: writer, designer
|
||||
tags: [formatting, navigation]
|
||||
keywords: links, hyperlinks, cross references, related links, relationship tables
|
||||
summary: "When creating links, although you can use standard HTML or Markdown, this approach is usually susceptible to a lot of errors and broken links. There's a URL generator that will facilitate linking to other pages in ways that ensures the links won't break."
|
||||
last_updated: November 30, 2015
|
||||
summary: "When creating links, you can use standard HTML or Markdown formatting. Note that this approach is susceptible to errors and broken links, so check your outputs for broken links."
|
||||
last_updated: March 20, 2016
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_hyperlinks/
|
||||
---
|
||||
|
||||
## Link strategies
|
||||
|
||||
One of the more difficult parts of a documentation site is keeping all the internal links accurate and valid. When you're single sourcing, you usually have multiple documentation outputs that include certain pages for certain audiences. Orphan links are a common problem to avoid.
|
||||
|
||||
Although there are many ways to create links, I'll just describe what I've found to work well.
|
||||
|
||||
## Create an external link
|
||||
|
||||
When linking to an external site, use Markdown formatting:
|
||||
When linking to an external site, use Markdown formatting because it's simplest:
|
||||
|
||||
```
|
||||
[Google](http://google.com)
|
||||
@ -29,36 +25,42 @@ If you need to use HTML, use the normal syntax:
|
||||
|
||||
## Linking to internal pages
|
||||
|
||||
When linking to internal pages, you could use this same syntax:
|
||||
When linking to internal pages, you can use this same syntax:
|
||||
|
||||
```
|
||||
[Sample](sample.html)
|
||||
[Sample]({{ "/page" | prepend: site.baseurl }})
|
||||
```
|
||||
|
||||
OR
|
||||
|
||||
```html
|
||||
<a href="sample.html">Sample</a>
|
||||
<a href="{{ "/page" | prepend: site.baseurl }}">page</a>
|
||||
```
|
||||
|
||||
However, what happens when you change the page's title or link? Jekyll doesn't automatically pull in the page's title when you create links.
|
||||
I find that using the HTML formatting is easiest. Store the code in a shortcut in aText to populate it easily.
|
||||
|
||||
In my experience, coding links like this results in a lot of broken links.
|
||||
## Avoiding broken links
|
||||
|
||||
## Managed links
|
||||
In general, avoid broken links and outdated titles in links by doing the following:
|
||||
|
||||
For internal links, I've found that it's a best practice to store the link in a YAML file that is derived from the table of contents.
|
||||
* Where possible, avoid using the exact titles in link names. For example, if you write, see the <a href="{{ "/mydoc_hyperlinks/" | prepend: site.baseurl}}">Links</a> page, this title is likely to become more outdated than if you were to write, learn how to <a href="{{ "/mydoc_hyperlinks/" | prepend: site.baseurl}}">manage links</a>.
|
||||
* Use a broken link checker on your site output to see if links are broken.
|
||||
* Generate a PDF, since the PDF tends to highlight broken links more forcefully.
|
||||
|
||||
The theme has a file called urls_mydoc.txt. This file contains the same code as the table of contents (but without the conditional qualifiers). It iterates through every page listed in the table of contents sidebar (as well as the top navigation menus) and creates an output that looks like this for each link:
|
||||
## Other methods for managing links
|
||||
|
||||
You can also adopt an indirect-reference systems for managing links. This involves storing the link text in YAML syntax.
|
||||
|
||||
If you want to try this method, look in the root directory. The urls.txt file contains the same code as the table of contents (but without the conditional qualifiers), duplicated for each of the sidebars. The code iterates through every page listed in the table of contents sidebars (as well as the top navigation menus) and creates an output that looks like this for each link:
|
||||
|
||||
```yaml
|
||||
mydoc_getting_started:
|
||||
title: "Getting started with this theme"
|
||||
url: "mydoc_getting_started.html"
|
||||
link: "<a href='mydoc_getting_started.html'>Getting started with this theme</a>"
|
||||
mydoc_introduction:
|
||||
title: "Introduction"
|
||||
url: "mydoc_introduction"
|
||||
link: "<a href='/mydoc_introduction/'>Introduction</a>"
|
||||
```
|
||||
|
||||
From the site output folder (in ../doc_outputs), open urls_mydoc.txt and observe that it is properly populated (blank spaces between entries doesn't matter). Then manually copy the contents from the mydoc_urls.txt and insert it into the \_data/mydoc/mydoc_urls.yml file in your project folder.
|
||||
From the site output folder (in \_site), open urls.txt and observe that it is properly populated (blank spaces between entries doesn't matter). Then manually copy the contents from the urls.txt and insert it into the \_data/urls.yml file in your project folder.
|
||||
|
||||
Because the urls.txt is produced from the table of contents, you ensure that the same titles and URLs used in your table of contents and top navigation will also be used in your inline links.
|
||||
|
||||
@ -66,14 +68,14 @@ To create a link in a topic, just reference the appropriate value in the urls.ym
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
{{site.data.mydoc.mydoc_urls.mydoc_getting_started.link}}
|
||||
{{site.data.urls.mydoc_introduction.link}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This will insert the following into your topic:
|
||||
|
||||
```html
|
||||
<a href='mydoc_getting_started.html'>Getting started with this theme</a>
|
||||
<a href='/mydoc_getting_started/'>Getting started</a>
|
||||
```
|
||||
|
||||
You don't need to worry whether you can use Markdown syntax when inserting a link this way, because the insertion is HTML.
|
||||
@ -82,7 +84,7 @@ To insert a link in the context of a phrase, you can use this syntax:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
After downloading the theme, you can [get started in building the theme]({{site.data.mydoc.mydoc_urls.mydoc_getting_started.url}}).
|
||||
After downloading the theme, you can [get started in building the theme]({{site.data.urls.mydoc_getting_started.url}}).
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
@ -90,7 +92,7 @@ This leverages Markdown syntax. If you're in an HTML file or section, use this:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<p>After downloading the theme, you can <a href="{{site.data.mydoc.mydoc_urls.mydoc_getting_started.url}}">get started in building the theme</a>.</p>
|
||||
<p>After downloading the theme, you can <a href="{{site.data.urls.mydoc_getting_started.url}}">get started in building the theme</a>.</p>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
@ -104,15 +106,15 @@ By using this approach, you're less likely to end up with broken links.
|
||||
|
||||
## Always make sure your TOC page is accurate
|
||||
|
||||
You should treat your sidebar_doc.yml file with a lot of care. Every time you add a page to your site, make sure it's listed in your sidebar_doc.yml file (or in your top navigation). If you don't have pages listed in your sidebar_doc.yml file, they won't be included in the urls_mydoc.txt file, and as your site grows, it will be harder to recognize pages that are absent from the TOC.
|
||||
You should treat your sidebar data files (in /_data/sidebars) with a lot of care. Every time you add a page to your site, make sure it's listed in your sidebar file (or in your top navigation). If you don't have pages listed in your sidebar file, they won't be included in the urls.txt file, and as your site grows, it will be harder to recognize pages that are absent from the TOC.
|
||||
|
||||
Because all the pages are stored in the root directory, the list of files can grow really long. I typically find pages by navigating to the page in the preview server, copying the page name (e.g., mydoc_hyperlinks), and then pressing **Shift + Shift** in WebStorm to locate the page.
|
||||
|
||||
This is the only sane way to locate your pages when you have hundreds of pages in your root directory. If the page isn't listed in your TOC, it will be difficult to navigate to it and find it.
|
||||
This is the only sane way to locate your pages when you have hundreds of pages in your root directory. If the page isn't listed in your TOC, it will be difficult to navigate to it and find it.
|
||||
|
||||
## Checking for broken links
|
||||
|
||||
Another way to ensure you don't have any broken links in your output is to [generate a PDF]({{site.data.mydoc.mydoc_urls.mydoc_generating_pdfs.url}}). When you generate a PDF, look for the following two problems in the output:
|
||||
Another way to ensure you don't have any broken links in your output is to [generate a PDF]({{site.data.urls.mydoc_generating_pdfs.url}}). When you generate a PDF, look for the following two problems in the output:
|
||||
|
||||
* page 0
|
||||
* see .
|
||||
@ -122,21 +124,3 @@ Both instances indicate a broken link. The "page 0" indicates that Prince XML co
|
||||
If you see "see ." it means that the reference (for example, {% raw %}`{{mylink...}}`{% endraw %} doesn't actually refer to anything. As a result, it's simply blank in the output.
|
||||
|
||||
{{site.data.alerts.note}} To keep Prince XML from trying to insert a cross reference into a link, add <code>class="noCrossRef"</code> to the link. {{site.data.alerts.end}}
|
||||
|
||||
## Relative link paths
|
||||
|
||||
The site is coded with relative links. There aren't any permalinks, urls, or baseurls. The folder structure you see in the project directory is the same folder directory that gets built in the site output.
|
||||
|
||||
Author all pages in your root directory. This greatly simplifies linking. However, when you're linking to images, files, or other content, you can put these assets into subfolders.
|
||||
|
||||
For example, to link to a file stored in files/doc/whitepaper.pdf, you would use "files/doc/whitepaper.pdf" as the link.
|
||||
|
||||
Why not put pages too into subfolders? If you put a page into a subfolder, then links to the stylesheets, JavaScript, and other sources will fail. On those sub-folder pages, you'd need to use `../` to move up a level in the directory to access the stylesheets, JavaScript, etc. But if you have some pages in folders on one level, others in sub-sub-folders, and others in the root, trying to guess which files should contain `../` or `../../` or nothing at all and which shouldn't will be a nightmare.
|
||||
|
||||
Jekyll gets around some of this link path variation by using `baseurl` and including code that prepends the `baseurl` before a link. This converts the links into absolute rather than relative links.
|
||||
|
||||
With absolute links, the site only displays at the `baseurl` you configured. This is problematic for tech docs because you usually need to move files around from one folder to another based on versions you're archiving or when you're moving your documentation from draft to testing to production folders.
|
||||
|
||||
## Limitations with links
|
||||
|
||||
One of the shortcomings in this theme is that the link titles in the sidebar and inline links don't necessarily have to match the titles specified on each page. You have to manually keep the page titles in sync with the titles listed in the sidebar and top navigation. Although I could potentially get rid of the titles key in the article topic, it would make it more difficult to know what page you're editing.
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Icons
|
||||
tags: [formatting]
|
||||
keywords: font icons, buttons, images, vectors, font awesome, glyphicons
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can integrate font icons through the Font Awesome and Glyphical Halflings libraries. These libraries allow you to embed icons through their libraries delivered as a link reference. You don't need any image libraries downloaded in your project."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_icons/
|
||||
---
|
||||
|
||||
## Font icon options
|
||||
@ -67,7 +69,7 @@ hr_shaded: '<hr class="shaded"/>'
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This means you can insert a tip, note, warning, or important alert simply by using these tags:
|
||||
This means you can insert a tip, note, warning, or important alert simply by using these tags.
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
@ -75,6 +77,24 @@ This means you can insert a tip, note, warning, or important alert simply by usi
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{site.data.alerts.tip}} Add your tip here. {{site.data.alerts.end}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{site.data.alerts.important}} Add your important info here. {{site.data.alerts.end}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{site.data.alerts.warning}} Add your warning here. {{site.data.alerts.end}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Here's the result:
|
||||
|
||||
{{site.data.alerts.note}} Add your note here. {{site.data.alerts.end}}
|
||||
@ -180,14 +200,17 @@ And here's the shortcode:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{{site.data.alerts.callout_info}}<div class="bs-callout bs-callout-info">{{site.data.alerts.end}}
|
||||
{{site.data.alerts.callout_info}This is a special callout information message. {{site.data.alerts.end}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
{{site.data.alerts.callout_info}}This is a special callout information message. {{site.data.alerts.end}}
|
||||
|
||||
You can use any of the following:
|
||||
{% raw %}
|
||||
```
|
||||
{{callout_danger}}
|
||||
{{site.data.alerts.callout_default}}
|
||||
{{site.data.alerts.callout_primary}}
|
||||
{{site.data.alerts.callout_success}}
|
||||
@ -196,5 +219,7 @@ You can use any of the following:
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Callouts are explained in a bit more detail here: {{site.data.mydoc.mydoc_urls.mydoc_alerts.link}}.
|
||||
The only difference is the color of the left bar.
|
||||
|
||||
Callouts are explained in a bit more detail in <a href="{{ "/mydoc_alerts" | prepend: site.baseurl }}">Alerts</a>.
|
||||
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Images
|
||||
tags: [formatting]
|
||||
keywords: images, screenshots, vectors, svg, markdown syntax
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You embed images using traditional HTML or Markdown syntax for images. Unlike pages, you can store images in subfolders (in this theme). This is because when pages reference the images, the references are always as subpaths, never requiring the reference to move up directories."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_images/
|
||||
---
|
||||
|
||||
You embed an image the same way you embed other files or assets: you put the file into a folder, and then link to that file.
|
||||
@ -12,44 +14,82 @@ Put images inside the `images` folder in your root directory. You can create sub
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<img title="my sample page" src="images/jekyll.png" />
|
||||
<img title="my sample page" src="{{ "/images/jekyll.png" | prepend: site.baseurl }}" />
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
And the result:
|
||||
|
||||
<img title="my sample image" src="images/jekyll.png">
|
||||
<img title="my sample image" src="{{ "/images/jekyll.png" | prepend: site.baseurl }}">
|
||||
|
||||
Here's the same Markdown syntax:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
|
||||
![My sample page]({{ "/images/jekyll.png" | prepend: site.baseurl }})
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
And the result:
|
||||
|
||||
|
||||
![My sample page]({{ "/images/jekyll.png" | prepend: site.baseurl }})
|
||||
|
||||
{{site.data.alerts.tip}} I recommend storing this format into a shortcut editor such as aText. This way when you want to insert an image, just type something like jimg and the shortcut editor will automatically type the code.{{site.data.alerts.end}}
|
||||
|
||||
## Figure captions
|
||||
|
||||
If you want to add a figure caption, you can do so using standard `figure` HTML tags:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<figure><img title="my sample page" src="{{ "/images/jekyll.png" | prepend: site.baseurl }}" /><figcaption>Your caption</figcaption></figure>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Here's the result:
|
||||
|
||||
<img title="my sample page" src="{{ "/images/jekyll.png" | prepend: site.baseurl }}" />
|
||||
<figcaption>Your caption</figcaption></figure>
|
||||
|
||||
## SVG Images
|
||||
|
||||
You can also embed SVG graphics. If you use SVG, you need to use the HTML syntax so that you can define a width/container for the graphic. Here's a sample embed:
|
||||
|
||||
```html
|
||||
<img src="images/dicloud_architecture.svg" style="max-width: 700px;" />
|
||||
<img src="{{ "/images/helpapi.svg" | prepend: site.baseurl }}" style="max-width: 600px;" />
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
<img src="images/helpapi.svg" style="max-width: 700px;" />
|
||||
<img src="{{ "/images/helpapi.svg" | prepend: site.baseurl }}" style="max-width: 600px;" />
|
||||
|
||||
SVG images will expand to the size of their artboard, so you can either set the artboard the right size when you create the graphic in Illustrator, or you can set an inline style that confines the size to a certain width as shown in the code above.
|
||||
SVG images will expand to the size of their container, so you have to specify it here. The previous syntax isn't well supported in IE, so you would be better off using the `object` element like this:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<div style="max-width:600px;"><object type="image/svg+xml" data="{{ "/images/helpapi.svg" | prepend: site.baseurl }}">Your browser does not support SVG</object>
|
||||
</div>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Here's the same code with `figure` elements:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<div style="max-width:600px;"><figure><object type="image/svg+xml" data="{{ "/images/helpapi.svg" | prepend: site.baseurl }}">Your browser does not support SVG</object><figcaption>This is your caption</figcaption></figure>
|
||||
</div>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
And the result:
|
||||
|
||||
<div style="max-width:400px;"><figure><object type="image/svg+xml" data="{{ "/images/helpapi.svg" | prepend: site.baseurl }}">Your browser does not support SVG</object><figcaption>This is your caption</figcaption></figure></div>
|
||||
|
||||
Also, if you're working with SVG graphics, note that Firefox does not support SVG fonts. In Illustrator, when you do a Save As with your AI file and choose SVG, to preserve your fonts, in the Font section, select "Convert to outline" as the Type (don't choose SVG in the Font section).
|
||||
|
||||
Also, remove the check box for "Use textpath element for text on a path". And select "Embed" rather than "Link." The following screenshot shows the settings I use. Your graphics will look great in Firefox.
|
||||
|
||||
|
||||
![Essential options for SVG with Illustrator]({{ "/images/illustratoroptions.png" | prepend: site.baseurl }})
|
||||
|
||||
|
||||
|
||||
|
||||
@ -1,120 +0,0 @@
|
||||
---
|
||||
title: Inner Workings...
|
||||
tags: [formatting]
|
||||
keywords: images, screenshots, vectors, svg, markdown syntax
|
||||
last_updated: November 30, 2015
|
||||
summary: ""
|
||||
published: false
|
||||
---
|
||||
|
||||
In this page, I'm going to explain some of the inner workings of Jekyll, including some weaknesses of the theme that could be addressed. These points aren't in any particular order.
|
||||
|
||||
Location of build scripts
|
||||
The build scripts (ending in ".sh") in the root directory are in the root directory rather than a subdirectory because for some reason, when I put them in a subdirectory, they didn't work. Things only seemed to work in the root directory, but maybe with some finagling or path adjustment the build scripts could be moved to a subfolder.
|
||||
Grouping of projects
|
||||
At one time in my architecting of the Jekyll theme, I tried to group all of the assets for each project into their own folders...the includes, the images, files, stylesheets, the data sources, and more. But in trying to make it work, it just didn't. Jekyll likes things distributed into different folders like this.
|
||||
Redirect on home page
|
||||
In order to allow different product doc sets within the same jekyll project, I created a series of subfolders that correlate with each project. This change required quite a bit of updates.
|
||||
With posts, Jekyll automatically extracts them from subfolders and puts them into the root folder. It's not the case with pages. Pages remain in the subfolders.
|
||||
With the relative linking strategy, having different pages in different subfolders created some serious challenges with links. You can't have a set of links that works when you keep jumping different levels of nesting. For example, if you're on the homepage the link to the CSS file is ../css/customstyles.css, but once you drill into a subfolder the same link becomes ../../css/customstyles.css.
|
||||
I could have solved this issue a number of ways. One way would be to put an attribute on the homepage that referenced a different layout. For example, the homepage could have linked to default_home.html while all project pages could link to default.html's layout. That probably wouldn't be a bad approach, except for the way it duplicated content. Additionally, when you searched for something from the home page versus searching from a content page, the links would be messed up, as well as tags on the homepage versus a content page, and so on.
|
||||
I decided to keep everything at the same level. When you go to the index.html file in the project, this is what appears:
|
||||
|
||||
{% raw %}
|
||||
{% include custom/conditions.html %}
|
||||
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en-US">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta http-equiv="refresh" content="0;url={{projectFolder}}/home.html">
|
||||
<script type="text/javascript">
|
||||
window.location.href = "{{projectFolder}}/home.html"
|
||||
</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
The conditions.html file assigns the variable for projectFolder:
|
||||
{% assign projectFolder = "resolve" %}
|
||||
This makes the preceding block read like this:
|
||||
{% include custom/conditions.html %}
|
||||
|
||||
|
||||
|
||||
<!DOCTYPE HTML>
|
||||
<html lang="en-US">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta http-equiv="refresh" content="0;url={{projectFolder}}/home.html">
|
||||
<script type="text/javascript">
|
||||
window.location.href = "resolve/home.html"
|
||||
</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
{% endraw %}
|
||||
The code here is standard code for an HTTP redirect. When a browser sees this code, it automatically changes the location to resolve/home.html.
|
||||
This is how the same index.html file can route to the right home.html file among different project folders.
|
||||
The only downside of this approach is that it lengthens the URL. Now you have http://docs.the41.internal/resolve/fe/resolve/home.html instead of just http://docs.the41.internal/resolve/fe/index.html. However, it makes it so that all the paths for all pages in the project are all at the same level.
|
||||
|
||||
Relative paths
|
||||
Jekyll is really designed to use an absolute link structure rather than relative links. However, the absolute link structure ties you to a specific domain, which doesn't work for tech docs when we're pushing content out to a number of different domains.
|
||||
After some hacking, I converted the absolute or permalink structure to relative links. These link paths affect everything from the TOC links, inline links in a page, links in the top navigation, links from tags, links from search results, and so on.
|
||||
|
||||
Search
|
||||
The basic search in the Jekyll theme relies on a JSON file located in the root folder:
|
||||
---
|
||||
title: search
|
||||
layout: none
|
||||
search: exclude
|
||||
---
|
||||
{% raw %}
|
||||
[
|
||||
{% for page in site.pages %}
|
||||
{% unless page.search == "exclude" %}
|
||||
{
|
||||
"title": "{{ page.title | escape }}",
|
||||
"tags": "{{ page.tags }}",
|
||||
"keywords": "{{page.keywords}}",
|
||||
"url": "{{ page.url | prepend: '..' }}",
|
||||
"summary": "{{page.summary}}"
|
||||
},
|
||||
{% endunless %}
|
||||
|
||||
{% endfor %}
|
||||
null
|
||||
]
|
||||
{% endraw %}
|
||||
This code iterates through each page in the site.pages namespace and pushes the page into a JSON structure. This content is used by the search feature, which is a simple technique explained in Simple Search by Christian Fei.
|
||||
You'll notice that body isn't a field pushed into this search. This is because not only does a lot of the formatting in the body element tend to make the JSON invalid, including the body here makes the keyword search highlighting problematic. For example, suppose you have a keyword in the body called "configuration." But you have another topic called "Configuration." Suppose you have 10 other topics that all mention the word "configuration" before Jekyll gets down to indexing the topic that starts with "Configuration." Well, the topic that starts with "Configuration" won't actually appear in your search results! WTF!
|
||||
This is because there's no weighting of content in the JSON search index. Things are just weighted based on their occurrence in the results.
|
||||
Overall, the JSON search is pretty poor. I highly recommend integrating Algolia or Swiftype. Algolia is cheaper ($50/month) but Swifttype ($200/month) will implement search for you. Unfortunately I didn't prioritize the integration of search into the theme. The more content you include in your docs, the more search will grow in importance. Our current file model is to make every product's output separate, so it's not that big of a deal.
|
||||
Sharing content across projects
|
||||
When you share content across projects, you have to store the content in the includes folder, and you have to store any images in the common_images folder. I would have preferred storing images inside the includes folder as well, but you can only put html and md files in there, not images.
|
||||
Content in the includes folder is only included based on the include tags in your content, but the content in the common_images folder will unfortunately
|
||||
I realize they're kind of spread out...
|
||||
Misc. Weaknesses
|
||||
If you want to improve the theme, here are some of the weaknesses/challenges to work on.
|
||||
no markdown in notes. When you insert a note, tip, or caution, you have to use HTML formatting inside the curly braces. This is because these notes are just variables for some bootstrap code that provides the formatting, and you can't use markdown inside of HTML. However, I routinely put markdown inside these notes and don't realize it until looking at the output. It would be better to find an approach less prone to error.
|
||||
complex markdown formatting. When your markdown formatting gets complex, such as a list in a subbullet within an ordered list, it can be a pain to get the formatting right. Sometimes I think it might be better just to use HTML throughout the project and scrap markdown altogether. HTML is a lot more reliable. BTW, if you are using HTML, to get the syntax highlighting, you must use the more traditional syntax highlighting tags;
|
||||
Unknown macro: {% highlight js %}
|
||||
some js code...
|
||||
Unknown macro: {% endhighlight %}
|
||||
No error checking. if a link is broken, or markdown filtering doesn't work, you won't know until you see the output. We need better validity checking for broken links and broken code.
|
||||
Links in topics shared across projects. If you're sharing content from one project to another, you can't include links in there except with conditions that would filter it out. This challenge is not really specific to jekyll, though, but is rather a larger challenge in tech comm.
|
||||
More dropdown levels in TOC. At times I wanted to add another level in the TOC sidebar, but I never had a really compelling case for doing it.
|
||||
Lavish.css overlaps. I used a tool called lavish bootstrap to speed up the color customization of the bootstrap theme. I have both the bootstrap css and the lavish css in the same page, so I'm sure there are tons of styles that are redundant and overwritten between the two, but I never tried to sort out any redundancy there.
|
||||
TOC spacing is touchy. Getting the spacing right in the table of contents files can be tricky. I wish there was a better way to avoid errors there.
|
||||
Duplication of values from config files into conditions.html file. Some of the same values (product, version, platform, etc.) are duplicated between the configuration file and the conditions.html file. I wish there wasn't any duplication, but I couldn't find a way around it.
|
||||
No variables in frontmatter. You can't have variables in frontmatter. This can be a real pain if you need them, such as with the resourceDirectory / DIResource application naming.
|
||||
No ability to lock down variables. It would be nice to lock down the core variables of product, platform, audience, etc. to a restricted set of terms. This would help everyone stay on the same page.
|
||||
need to get on the same page about how we're using each of them. I think John might be using "version" different from how I'm using "version" in some of my project. I think the general usage of these variables is something to consider as a team since they impact the way content is shared across projects.
|
||||
Search is weak. The JSON-based search sucks. You should implement Algolia or Swiftype intsead.
|
||||
|
||||
@ -3,6 +3,8 @@ title: Adding all project dependencies
|
||||
tags: [getting-started]
|
||||
keywords:
|
||||
summary: ""
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_install_dependencies/
|
||||
---
|
||||
|
||||
You want to be sure that you have all the required gems and other utilities on your computer to make the project run. Jekyll runs on Ruby, and there are various plugins for Ruby that enable different functionality. These Ruby plugins are referred to as gems, and you install the gems you need for your projects.
|
||||
@ -12,7 +14,7 @@ To manage the various gems and their versions needed for your project, you can u
|
||||
|
||||
## RubyGems
|
||||
|
||||
Make sure you have RubyGems. This should be installed by default.
|
||||
Make sure you have RubyGems. This should be installed by default on Mac.
|
||||
|
||||
Open Terminal and type `which gem`. You should get a response indicating the location of Rubygems, such as `/Users/MacBookPro/.rvm/rubies/ruby-2.2.1/bin/gem`.
|
||||
|
||||
@ -89,4 +91,28 @@ Finally, you can run the following to make sure the installed gems get associate
|
||||
|
||||
```
|
||||
bundle exec jekyll serve
|
||||
```
|
||||
|
||||
## Ruby permissions errors
|
||||
|
||||
While trying to install a missing gem, you get an error message that says,
|
||||
|
||||
>ERROR: While executing gem ... (Gem::FilePermissionError)
|
||||
You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.
|
||||
|
||||
This most likely happens with El Capitan on the Mac.
|
||||
|
||||
As long as you have brew installed (see the previous section), run the following:
|
||||
|
||||
```
|
||||
brew update
|
||||
brew install ruby
|
||||
```
|
||||
|
||||
Close your terminal, and then restart a fresh session.
|
||||
|
||||
Now run the gem you're trying to install, such as the following:
|
||||
|
||||
```
|
||||
gem install kramdown
|
||||
```
|
||||
@ -1,6 +1,8 @@
|
||||
---
|
||||
title: Installing Bundler
|
||||
published: false
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_installing_bundler/
|
||||
---
|
||||
|
||||
If you get permissions errors when trying to install Bundler, follow these steps:
|
||||
|
||||
27
mydoc/mydoc_introduction.md
Normal file
27
mydoc/mydoc_introduction.md
Normal file
@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Introduction
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_introduction/
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This site provides documentation, training, and other notes for the Jekyll Documentation theme. There's a lot of information about how to do a variety of things here, and it's not all unique to this theme. But by and large, understanding how to do things in Jekyll depends on how your theme is coded. As a result, these additional details are provided.
|
||||
|
||||
The instructions here are geared towards technical writers working on documentation. You may have a team of one or more technical writers working on documentation for multiple projects. You can use this same theme to author all of your documentation for each of your products. The theme is built to accommodate documentation for multiple products on the same site.
|
||||
|
||||
## Survey of features
|
||||
|
||||
Some of the more prominent features of this theme include the following:
|
||||
|
||||
* Bootstrap framework
|
||||
* [Navgoco multi-level sidebar](http://www.komposta.net/article/navgoco) for table of contents
|
||||
* Ability to specify different sidebars for different products
|
||||
* Top navigation bar with drop-down menus
|
||||
* Notes, tips, and warning information notes
|
||||
* Tags for alternative navigation
|
||||
* Advanced landing page layouts from the [Modern Business theme](http://startbootstrap.com/template-overviews/modern-business/).
|
||||
|
||||
## Getting started
|
||||
|
||||
To get started, see <a href="{{ "/mydoc_getting_started" | prepend: site.baseurl }}">Get started</a>.
|
||||
@ -2,8 +2,10 @@
|
||||
title: iTerm profiles
|
||||
tags: [publishing]
|
||||
keywords: iterm, terminal, build shortcuts, mac
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "Set up profiles in iTerm to facilitate the build process with just a few clicks. This can make it a lot easier to quickly build multiple outputs."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_iterm_profiles/
|
||||
---
|
||||
|
||||
|
||||
@ -19,17 +21,17 @@ When you're working with tech docs, a lot of times you're single sourcing multip
|
||||
4. In the **Name** field, type a name describing the output, such as `Doc theme -- designers`.
|
||||
5. In the **Send text at start** field, type the command for the build script, such as this:
|
||||
|
||||
```
|
||||
```
|
||||
jekyll serve --config configs/config_designers.yml
|
||||
```
|
||||
```
|
||||
Leave the Login shell option selected.
|
||||
|
||||
|
||||
6. In the Working Directory section, select **Directory** and enter the directory for your project, such as **/Users/tjohnson/projects/documentation-theme-jekyll**.
|
||||
7. Close the profiles panel.
|
||||
|
||||
Here's an example:
|
||||
|
||||
|
||||
![iTerm profile example]({{ "/images/itermexample.png" | prepend: site.baseurl }})
|
||||
|
||||
## Launching a profile
|
||||
|
||||
|
||||
@ -2,21 +2,23 @@
|
||||
title: Knowledge-base layout
|
||||
tags: [special_layouts]
|
||||
keywords: knowledge base, support portal, grid, doc portal
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "This shows a sample layout for a knowledge base. Each square could link to a tag archive page. In this example, font icons from Font Awesome are enlarged to a large size. You can also add captions below each icon."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_kb_layout/
|
||||
---
|
||||
|
||||
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_getting_started.html"><i class="fa fa-file-image-o fa-8x border"></i><div class="kbCaption">Getting Started</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_navigation.html"><i class="fa fa-bar-chart-o fa-8x border"></i><div class="kbCaption">Navigation</a></div></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_single_sourcing.html"><i class="fa fa-code fa-8x border"></i><div class="kbCaption">single_sourcing</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_getting_started.html"><i class="fa fa-file-image-o fa-5x border"></i><div class="kbCaption">Getting Started</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_navigation.html"><i class="fa fa-bar-chart-o fa-5x border"></i><div class="kbCaption">Navigation</a></div></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_single_sourcing.html"><i class="fa fa-code fa-5x border"></i><div class="kbCaption">single_sourcing</div></a></div>
|
||||
</div>
|
||||
<p> </p>
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_publishing.html"><i class="fa fa-dashboard fa-8x border"></i><div class="kbCaption">Publishing</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_special_layouts.html"><i class="fa fa-desktop fa-8x border"></i><div class="kbCaption">Special layouts</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_formatting.html"><i class="fa fa-cloud fa-8x border"></i><div class="kbCaption">Formatting</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_publishing.html"><i class="fa fa-dashboard fa-5x border"></i><div class="kbCaption">Publishing</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_special_layouts.html"><i class="fa fa-desktop fa-5x border"></i><div class="kbCaption">Special layouts</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="tag_formatting.html"><i class="fa fa-cloud fa-5x border"></i><div class="kbCaption">Formatting</div></a></div>
|
||||
</div>
|
||||
|
||||
## Generating a list of all pages with a certain tag
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Labels
|
||||
tags: [formatting]
|
||||
keywords: labels, buttons, bootstrap, api methods
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "Labels are just a simple Bootstrap component that you can include in your pages as needed. They represent one of many Bootstrap options you can include in your theme."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_labels/
|
||||
---
|
||||
|
||||
|
||||
|
||||
@ -1,38 +0,0 @@
|
||||
---
|
||||
title: Link validation
|
||||
keywords: broken links, orphan links, publishing errors, validation, link validity, hyperlink issues
|
||||
tags: [publishing]
|
||||
last_updated: September 13, 2015
|
||||
summary: "Before deploying your published site, you want to ensure that you don't have any broken links. There are a few ways to check for broken links."
|
||||
---
|
||||
|
||||
## Why broken links are challenging for technical writers
|
||||
One of the challenging aspects of technical writing is avoiding broken links in your output. Consider this example. You have three outputs, with different topics included for different audiences. The topics each have inline cross references pointing to the other topics, but since some of the topics aren't included for each audience, you risk having a broken link for the output that omits that topic.
|
||||
|
||||
Additionally, technical writers frequently manage large numbers of topics, and as they make updates, they rename titles, remote some topics, combine multiple topics into the same topic, and make other edits. When you're developing content, the pages and titles in your topics and navigation are in flux. You shift things around constantly trying to find the right organization, the right titles, and more.
|
||||
|
||||
During this time, if you have inline links that point to specific pages, how do you avoid broken links in your output?
|
||||
|
||||
## Use the title checker
|
||||
|
||||
The theme has a file called title-checker.html. This file will iterate through all the pages listed in the sidebar navigation and top navigation, and compare the navigation titles against the page titles based on matching URLs. If there are inconsistencies in the titles, they get noted on the title-checker.html page.
|
||||
|
||||
To run the link checker, just build or serve your project, and go to title-checker.html in your browser (such as Chrome). If there are inconsistencies, they will be noted on the page.
|
||||
|
||||
Note that in order for the title-checker file to run correctly, it has to detect a match between the URL listed in the sidebar or top navigation with the URL for the page (based on the file name). If you have the wrong URL, it won't tell you if the page titles match. Therefore you should always click through all the topics in your navigation to make sure the URLs are accurate.
|
||||
|
||||
## Generate a PDF
|
||||
|
||||
When you generate a PDF, Prince XML will print "page 0" for any cross references it can't find. This lets you know that a particular link is bad because the page is missing.
|
||||
|
||||
If you have links in your PDF that aren't references to other topics (maybe they're links to PDF file assets, or links within a navtab or collapsible section), then you must add a class of `noCrossRef` to the link to avoid having Prince write "page 0" for the link.
|
||||
|
||||
(Note that there are still some kinks I'm working out with this. You may find that links still say "page 0" even if they have the `noCrossRef` class.)
|
||||
|
||||
## Use data references for all inline links
|
||||
|
||||
Instead of creating links to direct pages, use the data reference technique described in {{site.data.mydoc.mydoc_urls.mydoc_hyperlinks.link}}. With this method, the urls.txt file iterates through all the pages in your navigation and formats them into a YAML syntax.
|
||||
|
||||
Then you insert an inline link by referring to that YAML data. For example, the previous hyperlink is {% raw %}`{{site.data.mydoc.mydoc_urls.mydoc_hyperlinks.link}}`{% endraw %}.
|
||||
|
||||
As you go through the link validation process, make sure you copy over the content from the generated urls.txt (in the Jekyll site output) and insert it into the urls.yml file in your \_data folder.
|
||||
@ -1,250 +0,0 @@
|
||||
---
|
||||
title: Mercurial notes and tips
|
||||
summary: "If you're using Mercurial to collaborate on a project, see the tips and notes on this page."
|
||||
tags: collaboration
|
||||
keywords: mercurial, hg, collaboration, interaction, project teams
|
||||
---
|
||||
|
||||
|
||||
This is my reference notes and quick reference for using Mercurial.
|
||||
|
||||
## Terminology
|
||||
|
||||
<dl>
|
||||
|
||||
<dt>Distributed revision control</dt><dd>Mercurial is distributed revision control instead of centralized revision control. This means everyone keeps a copy of the repo on their local machine, and then they merge back the changes. With centralized revision control, team members check out a version that remains in a central repo, and it becomes locked when checked out. The latter results in more wait time to check out files, little innovation for experimentation without committing, latency, and other issues.</dd>
|
||||
|
||||
<dt>Working directory</dt> <dd>The files that Mercurial is tracking in a directory.</dd>
|
||||
|
||||
<dt>Changeset</dt> <dd>A list of the most recent changes to the repo.</dd>
|
||||
|
||||
<dt>Tip</dt> <dd>The name of the latest changeset.</dd>
|
||||
|
||||
<dt>Tags</dt> <dd>A more user-friendly way to name changesets.</dd>
|
||||
|
||||
<dt>Default</dt> <dd>The name of the main repo. This is defined in the .hg/hgrc file in the `[paths]` section. When you run `hg push` and other commands, if you don't specify another source, the default path gets used.</dd>
|
||||
|
||||
<dt>Diff</dt> <dd>A list of differences with a file.</dd>
|
||||
|
||||
<dt>Patch</dt> <dd>Synonym for diff.</dd>
|
||||
|
||||
<dt>Repo</dt> <dd>The directory where Mercurial is activated.</dd>
|
||||
|
||||
<dt>head</dt> <dd>A changeset with no child changesets. When you get two heads, it's because you pulled in changes.</dd>
|
||||
|
||||
<dt>parent</dt> <dd>The previous changeset before the latest change.</dd>
|
||||
|
||||
<dt>child</dt> <dd>Later in the changeset history. the first parent is the first changeset, and then you have a list of descendants, which are the children.</dd>
|
||||
|
||||
<dt>merge conflict scenarios</dt> <dd>Merge conflicts happen when add or modify a file that another has removed from one commit to another, you make conflicting changes to the same file from one commit to another, or Mercurial notes some other file discrepancy. When a merge conflict happens, Mercurial launches a merge program to resolve the conflict. When merge conflicts happen, Mercurial removes the problematic files from the working directory until you fix them. You have to add them again to the working directory.
|
||||
</dd>
|
||||
|
||||
<dt>bookmarks:</dt><dd>This is a way to create branches in Mercurial. First run <code>hg bookmark hell</code>. Then <code>hg checkout hell</code>. Now you're working in hell. Then run <code>hg bookmark --delete hell</code> to delete hell. </dd>
|
||||
|
||||
<dt>branches</dt><dd> You don't really work with branches in Mercurial. If you create a branch, it's considered a separate line of code. Rarely do you merge branches back in. In this regard, Mercurial differs greatly from Git. However, Mercurial's approach to branching is that you should simply clone the repository. When you want to merge your clone, you pull changes from your clone. There's really no reason to add in this new "branching" functionality when all you're doing is basically the same clone operation. </dd>.
|
||||
|
||||
</dl>
|
||||
|
||||
|
||||
## Commands
|
||||
|
||||
| Commands | Description |
|
||||
| ------ | ------ |
|
||||
| clone | copy a specific repository (can be URL or local path) |
|
||||
| init | initialize Mercurial in the existing repository |
|
||||
| outgoing | show changes committed locally but not yet pushed |
|
||||
| incoming | show changes committed to remote but not yet pulled |
|
||||
| pull | pull the latest changeset into local repo|
|
||||
| pull -u | pull the latest changeset into local repo and update working directory to that changeset |
|
||||
| fetch | pull -u + merge + commit (if merge was successful) all in one command |
|
||||
| help -v | show help in verbose mode|
|
||||
| help (command) | shows help about a specific command |
|
||||
| summary | summarizes the state of the current local working directory |
|
||||
| summary --remote | summarizes the state of the remote working directory |
|
||||
| log | show history of all change sets in the repo |
|
||||
| log -r 2 -v| show the history of changeset 2 in the repo, with verbose details |
|
||||
| log -r 2:4 | show history of change sets from ranges 2 to 4
|
||||
| log -p home.md | show log of changes (patches) for specific file|
|
||||
| log -v -p -r 2 or log -vpr2 | show a diff of what has changed in a specific changeset (2) |
|
||||
| diff (filename) | shows differences in a file|
|
||||
| status | gives you details about the repo's files that have been modified, added, or removed since the last change. The files in the response will show ? for untracked, A for added, M for modified, and R for removed.|
|
||||
| tip | show the latest changset|
|
||||
| tip -vp | show the latest changeset and list verbose details of the differences |
|
||||
| update | pull the latest changeset into the working directory. By default pull just brings in the changeset, but it doesn't change your working directory to the latest changeset. |
|
||||
| heads | Shows the heads in the repo|
|
||||
| addremove | add all files in directory, remove missing files from previous tracking. (This is the equivalent of using hg add and hg rm for all the files.)|
|
||||
| merge | After you do a merge, you have to commit the merge.|
|
||||
| commit -m 'Merged remote changes' ||
|
||||
| add | add a file to Mercurial's working directory. You can list a filename or a directory. Or " ." to select all.|
|
||||
| remove | delete the file and tell Mercurial to stop tracking it. (addremove is a way of bulk doing this.)|
|
||||
| resolve --mark ||
|
||||
| forget (filename) | tells Mercurial to stop tracking a file|
|
||||
| branches | lists the branches created for the repo |
|
||||
| bookmarks | lists the bookmarks you have set |
|
||||
| bookmark {bookmark_name} | creates a bookmark named sophia |
|
||||
| checkout {bookmark_name} | checks out the bookmark. now you're working in bookmark_name. |
|
||||
| bookmark --delete {bookmark_name | deletes the bookmark |
|
||||
| revert | go back to the way the files were at the last commit |
|
||||
|
||||
{{site.data.alerts.note}} You can add a source for all of these commands. If no source is specified, the default repo (from which the existing repo was cloned) is used. For example, pull (source) will pull from a source other than the default if specified.{{site.data.alerts.end}}
|
||||
|
||||
When you run `hg status`, there are various icons next to the files.
|
||||
|
||||
|hg status icons | Description |
|
||||
|
||||
| ! | Mercurial can't find the file. You probably deleted it manually and didn't do an hg rm filename or hg addremove.
|
||||
| ? | Mercurial doesn't know anything about this file, even though it's in the same directory as other files you're tracking.
|
||||
| M | you modified this file.
|
||||
| A | Mercurial added this file to the list of files you're tracking.
|
||||
| R | removed from tracking and the directory.
|
||||
|
||||
|
||||
## General workflow
|
||||
|
||||
As a general worfklow:
|
||||
|
||||
1. Commit
|
||||
2. Pull -u (or fetch)
|
||||
3. Merge
|
||||
4. Push
|
||||
|
||||
|
||||
## Merge conflicts
|
||||
|
||||
When a conflict happens, the default merge program configured in .hgrc launches. [P4Merge](https://www.perforce.com/product/components/perforce-visual-merge-and-diff-tools) works well.
|
||||
To configure Mercurial to use p4merge, install P4Merge, and then put this into your .hgrc file (if it's not already there).
|
||||
|
||||
```
|
||||
p4merge.executable = /Applications/p4merge.app/Contents/MacOS/p4merge
|
||||
p4merge.priority = 50
|
||||
p4merge.premerge = True
|
||||
p4merge.gui = True
|
||||
p4merge.args = $base $local $other $output
|
||||
p4merge.binary = True
|
||||
```
|
||||
|
||||
When P4Merge launches to resolve a merge conflict, you select the change you want, or add your own. Then Save. Then quit P4merge completely.
|
||||
|
||||
(I am not sure if you have to run `hg addremove` and then `hg resolve --mark` to mark the conflict as resolved.)
|
||||
|
||||
For more details, see [P4Merge](https://www.mercurial-scm.org/wiki/P4Merge).
|
||||
|
||||
## Binary files
|
||||
|
||||
P4Merge can't handle merges with binary files. However, you can run a diff to see the differences between files. You would need to clone your repository and use a different changeset for that repo. Then compare the same file in the different repos in different changesets.
|
||||
|
||||
## Ignoring certain files
|
||||
|
||||
Some files you don't want in Mercurial because they only have relevance locally. Here is the list of files to ignore to add to your .hgignore file:
|
||||
|
||||
```
|
||||
.jekyll-metadata
|
||||
_site
|
||||
.DS_Store
|
||||
.idea
|
||||
```
|
||||
|
||||
If you forget to add certain files to your ignore list, you can add them later and apply the ignore rule retroactively. See [this stackoverflow thread](http://stackoverflow.com/questions/8129912/mercurial-and-xcuserdata-ds-store-and-git) for more details. once you make the update, run `hg forget "set:hgignore()"`.
|
||||
|
||||
## Merge conflicts
|
||||
|
||||
Here's the scenario. After you do `hg pull -u`, you get this error message:
|
||||
|
||||
```
|
||||
abort: untracked files in working directory differ from files in requested revision
|
||||
```
|
||||
|
||||
The problem is that you modified files in your working directory, such as adding or removing a file. Another person added or removed the same file and committed to the repo. Now when you get the latest changeset that has a discrepancy with the added/removed files, Mercurial complains.
|
||||
|
||||
For example, Writer A removes file apple.md from his working directory. Writer B adds file apple.md to his working directory. Writer B commits. Now Writer A does a pull -u. At this point, Mercurial responds with the abort message listed above because Writer A's files don't match up with the incoming revision.
|
||||
|
||||
Theoretically, you can do an hg merge and resolve the issue. However, when I tried this, the abort message didn't go away.
|
||||
Saga continued. I'm actually unclear how to resolve this. After fruitless attempts to fix it, I moved on to the nuclear option.
|
||||
|
||||
## Exercising the Nuclear Option
|
||||
|
||||
When you run into problems with Mercurial, you should try to sort it out the best you can. However, if things just won't behave, you can always exercise the nuclear option.
|
||||
|
||||
1. Change the name of your "repo" to "repo-old".
|
||||
2. Reclone the project.
|
||||
3. Copy over the contents from repo-old into repo. (Don't copy over the .hg. idea, .DS_Store, or .hgignore files.)
|
||||
|
||||
Now follow the standard Commit and Push instructions here. It should fix the issue.
|
||||
|
||||
## Creating a Mercurial Test Playground on Your Local Machine
|
||||
|
||||
You can create some local Mercurial repos on your machine so you can play around with commits, merges, and other experiments.
|
||||
|
||||
Create a folder and initialize Mercurial in the folder:
|
||||
|
||||
```
|
||||
hg init hgrepo
|
||||
```
|
||||
|
||||
This creates a folder called hgrepo. This is your main repository.
|
||||
|
||||
Now change into hgrepo and add a file:
|
||||
|
||||
```
|
||||
cd hgrepo
|
||||
touch mytestfile.txt
|
||||
open mytestfile.txt
|
||||
```
|
||||
|
||||
Type some text and then click Ctrl + S to save it. Then Ctrl + W to close.
|
||||
|
||||
Add the file to Mercurial's tracking and make a commit:
|
||||
|
||||
```
|
||||
hg addremove
|
||||
hg commit -m "my first commit"
|
||||
```
|
||||
|
||||
Now make a couple of clones of the repo:
|
||||
|
||||
```
|
||||
cd ../
|
||||
hg clone /Users/tjohnson/projects/hgrepo hgclone1
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```
|
||||
hg clone /Users/tjohnson/projects/hgrepo hgclone2
|
||||
```
|
||||
|
||||
(Replace /Users/tjohnson/projects/hgrepo with the path to your repo.)
|
||||
|
||||
You should now have a file structure that looks like this:
|
||||
|
||||
```
|
||||
hgrepo
|
||||
- mytestfile.txt
|
||||
hgclone1
|
||||
- mytestfile.txt
|
||||
hgclone2
|
||||
- mytestfile.txt
|
||||
```
|
||||
|
||||
In iTerm, open two separate tabs and go into hgclone1 and hgclone2 on the different tabs. Now you can make changes to mytestfile.txt and commit and push it into the main repo.
|
||||
|
||||
|
||||
## Stop Tracking a File
|
||||
Sometimes you inadvertently add a file into Mercurial that you really don't want to track. One example is the .jekyll-metadata file that is included by default when you do incremental builds. This file is used locally to remember what changes have been made to your build and what haven't.
|
||||
|
||||
This file shouldn't be pushed to Mercurial because it will conflict with the content of other people's .jekyll-metadata files. You need to tell Mercurial to stop tracking the file and then add it to the ignore list.
|
||||
|
||||
To stop tracking a file:
|
||||
|
||||
```
|
||||
hg forget filename.txt
|
||||
```
|
||||
|
||||
If you run the hg addremove command, Mercurial will simply add back the file you ignored.
|
||||
|
||||
You should add this file to an ignore list.
|
||||
|
||||
1. Go to the root directory of your jekyll project.
|
||||
2. Create a file called .hgignore.
|
||||
3. Add each file you want to ignore (e.g., .jekyll-metadata) on a separate line.
|
||||
4. Now make sure that everyone else adds these files to their ignore list. If someone else commits a file that you've ignored, Mercurial will complain when you pull the latest revision.
|
||||
@ -2,8 +2,10 @@
|
||||
title: Navtabs
|
||||
tags: [formatting]
|
||||
keywords: navigation tabs, hide sections, tabbers, interface tabs
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "Navtabs provide a tab-based navagation directly in your content, allowing users to click from tab to tab to see different panels of content. Navtabs are especially helpful for showing code samples for different programming languages. The only downside to using navtabs is that you must use HTML instead of Markdown."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_navtabs/
|
||||
---
|
||||
|
||||
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
---
|
||||
title: Getting around the password prompts in SCP
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_no_password_prompts_scp/
|
||||
---
|
||||
|
||||
You can publish your docs via SSH through a Terminal window or more likely, via a shell script that you simply execute as part of the publishing process. However, you will be prompted for your password with each file transfer unless you configure passwordless SSH.
|
||||
|
||||
@ -2,28 +2,27 @@
|
||||
title: Pages
|
||||
tags: [getting_started, formatting, content-types]
|
||||
keywords: pages, authoring, exclusion, frontmatter
|
||||
last_updated: November 30, 2015
|
||||
summary: "This theme uses pages only, not posts. You need to make sure your pages have the appropriate frontmatter. One frontmatter tag your users might find helpful is the summary tag. This functions similar in purpose to the shortdesc element in DITA."
|
||||
last_updated: March 20, 2016
|
||||
summary: "This theme primarily uses pages. You need to make sure your pages have the appropriate frontmatter. One frontmatter tag your users might find helpful is the summary tag. This functions similar in purpose to the shortdesc element in DITA."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_pages/
|
||||
---
|
||||
|
||||
|
||||
## Where to author content
|
||||
Use a text editor such as Sublime Text, WebStorm, IntelliJ, or Atom to create pages.
|
||||
|
||||
My preference is IntelliJ/WebStorm, since it will treat all files in your project as belonging to a project. This allows you to easily search for instances of keywords, do find-and-replace operations, or do other actions that apply across the whole project.
|
||||
My preference is IntelliJ/WebStorm, since it will treat all files in your theme as belonging to a project. This allows you to easily search for instances of keywords, do find-and-replace operations, or do other actions that apply across the whole project.
|
||||
|
||||
## Page names and excluding files from outputs
|
||||
|
||||
By default, everything in your project is included in the output. This is problematic when you're single sourcing and need to exclude some files from an output.
|
||||
|
||||
Here's the approach I've taken. Put all files in your root directory, but put the project name first and then any special conditions. For example, mydoc_writers_intro.md.
|
||||
|
||||
In your configuration file, you can exclude all files that don't belong to that project by using wildcards such as the following:
|
||||
By default, everything in your project is included in the output. You can exclude all files that don't belong to that project by specifying the file name, the folder name, or by using wildcards in your configuration file:
|
||||
|
||||
exclude:
|
||||
|
||||
- filename.md
|
||||
- subfolder_name/
|
||||
- mydoc_*
|
||||
- mydoc_writers_*
|
||||
|
||||
|
||||
These wildcards will exclude every match after the `*`.
|
||||
|
||||
@ -33,35 +32,32 @@ Make sure each page has frontmatter at the top like this:
|
||||
{% raw %}
|
||||
```yaml
|
||||
---
|
||||
title: Your page title
|
||||
tags: [formatting, getting_started]
|
||||
keywords: overview, going live, high-level
|
||||
last_updated: November 30, 2015
|
||||
summary: "Deploying DeviceInsight requires the following steps."
|
||||
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/
|
||||
---
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Frontmatter is always formatted with three hyphens at the top and bottom. Your frontmatter must have a `title` value. All the other values are optional.
|
||||
Frontmatter is always formatted with three hyphens at the top and bottom. Your frontmatter must have a `title` value. All the other values are optional. If you omit them, the theme won't break.
|
||||
|
||||
Note that you cannot use variables in frontmatter.
|
||||
|
||||
The following table describes each of the frontmatter that you can use with this theme:
|
||||
|
||||
| Frontmatter | Required? | Description |
|
||||
|-------------|-------------|-------------|
|
||||
| **title** | Required | The title for the page |
|
||||
| **tags** | Optional | Tags for the page. Make all tags single words, with hyphens if needed. Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to \_data/tags_doc.yml to be allowed entrance into the page. |
|
||||
| **tags** | Optional | Tags for the page. Make all tags single words, with underscores if needed (rather than spaces). Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to \_data/tags_doc.yml to be allowed entrance into the page. This prevents tags from becoming somewhat random and unstructured. You must create a tag page for each one of your tags following the pattern shown in the tags folder. (Tag pages aren't automatically created.) |
|
||||
| **keywords** | Optional | Synonyms and other keywords for the page. This information gets stuffed into the page's metadata to increase SEO. The user won't see the keywords, but if you search for one of the keywords, it will be picked up by the search engine. |
|
||||
| **last_updated** | Optional | The date the page was last updated. This information could helpful for readers trying to evaluate how current and authoritative information is. If included, the last_updated date appears in the footer of the page.|
|
||||
| **summary** | Optional | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) |
|
||||
| **datatable** | Optional | Boolean. If you add `true`, then scripts for the [jQuery datatables plugin](https://www.datatables.net/) get included on the page. |
|
||||
| **video** | Optional | If you add `true`, then scripts for [Video JS: The HTML5 video player](http://www.videojs.com/) get included on the page. |
|
||||
|
||||
{{site.data.alerts.tip}} You can see the scripts that conditionally appear by looking in the _layouts/default.html page. Note that these scripts are served via a CDN, so the user must be online for the scripts to work. However, if the user isn't online, the tables and video still appear. In other words, they degrade gracefully. {{site.data.alerts.end}}
|
||||
|
||||
## What about permalinks?
|
||||
What about permalinks? This theme isn't build using permalinks because it makes linking and directory structures problematic. Permalinks generate an index file inside a folder for each file in the output. This makes it so links (to other pages as well as to resources such as styles and scripts) need to include `../` depending upon where the other assets are located. But for any pages outside folders, such as the index.html page, you wouldn't use the `../` structure.
|
||||
|
||||
Basically, permalinks complicate the linking structure significantly, so they aren't used here. As a result, page URLs have an .html extension. If you include `permalink: something` in your frontmatter, your link to the page will break (actually, you could still go to sample instead of sample.html, but none of the styles or scripts will be correctly referenced).
|
||||
| **last_updated** | Optional | The date the page was last updated. This information could helpful for readers trying to evaluate how current and authoritative information is. If included, the last_updated date appears in the footer of the page in rather small font.|
|
||||
| **summary** | Optional | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) The only drawback with summaries is that you can't use variables in them. |
|
||||
| **permalink**| Required | This theme uses permalinks to facilitate the linking. You specify the permalink want for the page, and the \_site output will put the page into the root directory when you publish. The page will appear inside a folder by the same name, with the actual page being index.html. Browsers will automatically show the index.html file inside of any folder, so permalinks avoid the .html extension with file names. Permalink names don't have to match your file names, but it might be easier to keep them in sync. If you don't use permalinks, Jekyll automatically uses the file name and folder path as the link.|
|
||||
| **datatable** | Optional | 'active'. If you add `datatable: active` in the frontmatter, scripts for the [jQuery Datatables plugin](https://www.datatables.net/) get included on the page. You can see the scripts that conditionally appear by looking in the \_layouts/default.html page. |
|
||||
| toc | Optional | If you specify `toc: none` in the frontmatter, the page won't have the table of contents that appears below the title. The toc refers to the list of jump links below the page title, not the sidebar navigation. You probably want to hide the TOC on the homepage and product landing pages.|
|
||||
|
||||
## Colons in page titles
|
||||
|
||||
@ -69,56 +65,53 @@ If you want to use a colon in your page title, you must enclose the title's valu
|
||||
|
||||
## Saving pages as drafts
|
||||
|
||||
If you add `published: false` in the frontmatter, your page won't be published. You can also move draft pages into the _drafts folder to exclude them from the build.
|
||||
If you add `published: false` in the frontmatter, your page won't be published. You can also move draft pages into the \_drafts folder to exclude them from the build. With posts, you can also keep them as drafts by omitting the date in the title.
|
||||
|
||||
{{site.data.alerts.tip}} You can create file templates in WebStorm that have all your common frontmatter, such as all possible tags, prepopulated. See {{site.data.mydoc.mydoc_urls.mydoc_webstorm_text_editor.link}} for details. {{site.data.alerts.end}}
|
||||
{{site.data.alerts.tip}} You can create file templates in WebStorm that have all your common frontmatter, such as all possible tags, prepopulated. See <a href="{{ "/mydoc_webstorm_text_editor" | prepend: site.baseurl }}">WebStorm Text Editor</a> for details. {{site.data.alerts.end}}
|
||||
|
||||
## Markdown or HTML format
|
||||
|
||||
Pages can be either Markdown or HTML format (specified through either an .md or .html file extension).
|
||||
|
||||
If you use Markdown, you can also include HTML formatting where needed. But not vice versa — if you use HTML (as your file extension), you can't insert Markdown content.
|
||||
If you use Markdown, you can also include HTML formatting where needed. But not vice versa — if you use HTML (as your file extension), you can't insert Markdown content in the file.
|
||||
|
||||
Also, if you use HTML inside a Markdown file, you cannot use Markdown inside of HTML. But you can use HTML inside of Markdown.
|
||||
|
||||
For your Markdown files, note that a space or two indent will set text off as code or blocks, so avoid spacing indents unless intentional.
|
||||
|
||||
If you have a lot of HTML, as long as the top and bottom tags of the HTML are flesh left in a Markdown file, all the tags inside those bookend HTML tags will render as HTML, regardless of their indentation.
|
||||
|
||||
## Where to save pages
|
||||
|
||||
Store all your pages inside the root directory. This is because the site is built with relative links. There aren't any permalinks or baseurls used in the link architecture. This relative link nature of the site allows you to easily move it from one folder to another without invalidating the links.
|
||||
You can store your pages in any folder structures you want, with any level of folder nesting. The site output will pull all of those pages out of their folders and put them into the root directory. Check out the \_site folder, which is where Jekyll is generated, to see the difference between your project's structure and the resulting site output.
|
||||
|
||||
## Page names
|
||||
|
||||
If this approach creates too many files in one long list, consider grouping files into Favorites sections using WebStorms Add to Favorites feature.
|
||||
I recommend prefixing your page names with the product, such as "mydoc_pages" instead of just "pages." This way if you have other products that also hae topics with generic names such as "pages," there won't be naming conflicts.
|
||||
|
||||
## Github-flavored Markdown
|
||||
Additionally, consider adding the product name in parentheses after the title, such as "Pages (Mydoc)" so that users can clearly navigate different topics for each product.
|
||||
|
||||
You can use standard Multimarkdown syntax for tables. You can also use fenced code blocks. The configuration file shows the Markdown processor and extensiosn:
|
||||
## Kramdown Markdown
|
||||
|
||||
Kramdown is the Markdown flavor used in the theme. This mostly aligns with Github-flavored Markdown, but with some differences in the indentation allowed within lists. Basically, Kramdown requires you to line up the indent between list items with the first starting character after the space in your list item numbering. See this [blog post on Kramdown and Rouge](http://idratherbewriting.com/2016/02/21/bug-with-kramdown-and-rouge-with-github-pages/) for more details.
|
||||
|
||||
You can use standard Multimarkdown syntax for tables. You can also use fenced code blocks with lexers specifying the type of code. The configuration file shows the Markdown processor and extensiosn:
|
||||
|
||||
```yaml
|
||||
highlighter: rouge
|
||||
markdown: kramdown
|
||||
kramdown:
|
||||
input: GFM
|
||||
auto_ids: true
|
||||
hard_wrap: false
|
||||
syntax_highlighter: rouge
|
||||
```
|
||||
markdown: redcarpet
|
||||
|
||||
redcarpet:
|
||||
extensions: ["no_intra_emphasis", "fenced_code_blocks", "tables", "with_toc_data"]
|
||||
```
|
||||
These extensions mean the following:
|
||||
|
||||
| Redcarpet extension | Description |
|
||||
| --------------|---------------|
|
||||
| no_intra_emphasis | don't italicize words with underscores |
|
||||
| fenced_code_blocks | allow three backticks before and after code blocks instead of `<pre>` tags |
|
||||
| tables | allow table syntax |
|
||||
| with_toc\_data | add ID tags to headings automatically |
|
||||
|
||||
You can also add "autolink" as an option if you want links such as http://google.com to automatically be converted into links.
|
||||
|
||||
{{site.data.alerts.note}} Make sure you leave the <code>with_toc_data</code> option included. This auto-creates an ID for each Markdown-formatted heading, which then gets injected into the mini-TOC. Without this auto-creation of IDs, the mini-TOC won't include the heading. If you ever use HTML formatting for headings, you need to manually add an ID attribute to the heading in order for the heading to appear in the mini-TOC. {{site.data.alerts.end}}
|
||||
|
||||
## Automatic mini-TOCs
|
||||
|
||||
By default, a mini-TOC appears at the top of your pages and posts. If you don't want this, you can remove the {% raw %}`{% include toc.html %}` {% endraw %} from the layouts/page.html file.
|
||||
By default, a TOC appears at the top of your pages and posts. If you don't want the TOC to appear for a specific page, such as for a landing page or other homepage, add `toc: none` in the frontmatter of the page.
|
||||
|
||||
If you don't want the TOC to appear for a specific page, add `toc: false` in the frontmatter of the page.
|
||||
|
||||
The mini-TOC requires you to use the `##` syntax for headings. If you use `<h2>` elements, then you must add an ID attribute for the h2 element in order for it to appear in the mini-TOC.
|
||||
The mini-TOC requires you to use the `##` Markdown syntax for headings. If you use `<h2>` elements, you must add an ID attribute for the heading element in order for it to appear in the mini-TOC (for example, `<h2 id="mysampleid">Heading</h2>`.
|
||||
|
||||
## Specify a particular page layout
|
||||
|
||||
@ -128,17 +121,13 @@ You can create other layouts inside the layouts folder. If you create a new layo
|
||||
|
||||
## Comments
|
||||
|
||||
Disqus, a commenting system, is integrated into the theme. In the configuration file, specify the Disqus code for the universal code, and Disqus will appear. If you don't add a Disqus value, the Disqus code isn't included.
|
||||
|
||||
## Posts
|
||||
|
||||
This theme isn't coded with any kind of posts logic. For example, if you wanted to add a blog to your project that leverages posts, you couldn't do this with the theme. However, you could easily take the post logic from another site and integrate it into this theme. I've just never had a strong need to integrate blog posts into documentation.
|
||||
Disqus, a commenting system, is integrated into the theme. In the configuration file, specify the Disqus code for the universal code, and Disqus will appear. If you don't add a Disqus value, the Disqus form isn't included.
|
||||
|
||||
## Custom keyboard shortcuts
|
||||
Some of the Jekyll syntax can be slow to create. Using a utility such as [aText](https://www.trankynam.com/atext/) can make creating content a lot of faster.
|
||||
|
||||
For example, when I type `jif`, aText replaces it with {% raw %}`{% if site.platform == "x" %}`{% endraw %}. When I type `jendif`, aText replaces it with {% raw %}`{% endif %}`{% endraw %}.
|
||||
For example, with my aText configuration, when I type `jlink`, aText replaces it with {% raw %}`<a href="{{ "/page" | prepend: site.baseurl }}">page</a>`{% endraw %}.
|
||||
|
||||
You get aText from the App Store on a Mac for about $5.
|
||||
You get aText from the App Store on a Mac for about $5. However, the Mac Store version of aText won't work on Mac OSX El Capitan due to sandbox security restrictions, so you need to download the app outside of the App Store to make it work.
|
||||
|
||||
There are alternatives to aText, such as Typeitforme. But aText seems to work the best. You can read more about it on [Lifehacker](http://lifehacker.com/5843903/the-best-text-expansion-app-for-mac).
|
||||
There are alternatives to aText, such as Typeitforme. But aText seems to work the best. You can read more about aText on [Lifehacker](http://lifehacker.com/5843903/the-best-text-expansion-app-for-mac).
|
||||
|
||||
44
mydoc/mydoc_posts.md
Normal file
44
mydoc/mydoc_posts.md
Normal file
@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Posts
|
||||
tags: [getting_started, formatting, content-types]
|
||||
keywords: posts, blog, news, authoring, exclusion, frontmatter
|
||||
last_updated: Feb 25, 2016
|
||||
summary: "You can use posts when you want to create blogs or news type of content."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_posts/
|
||||
---
|
||||
|
||||
## About posts
|
||||
|
||||
Posts are typically used for blogs or other news information because they contain a date and are sorted in reverse chronological order.
|
||||
|
||||
You create a post by adding a file in the \_posts folder that is named yyyy-mm-dddd-permalink.md, which might be 2016-02-25-my-latest-updates.md. You can use any number of subfolders here that you want.
|
||||
|
||||
Posts use the post.html layout in the \_layouts folder when you are viewing the post.
|
||||
|
||||
The news.html file in the root directory shows a reverse chronological listing of the 10 latest posts
|
||||
|
||||
## Allowed frontmatter
|
||||
|
||||
The frontmatter you can use with posts is as follows:
|
||||
|
||||
---
|
||||
title: My sample post
|
||||
keywords: pages, authoring, exclusion, frontmatter
|
||||
summary: "This is some summary frontmatter for my sample post."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_pages/
|
||||
tags: content_types
|
||||
---
|
||||
|
||||
|
||||
| Frontmatter | Required? | Description |
|
||||
|-------------|-------------|-------------|
|
||||
| **title** | Required | The title for the page |
|
||||
| **tags** | Optional | Tags for the page. Make all tags single words, with underscores if needed. Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to \_data/tags_doc.yml to be allowed entrance into the page. This prevents tags from becoming somewhat random and unstructured. You must create a tag page for each one of your tags following the sample pattern in the tabs folder. (Tag pages aren't automatically created.) |
|
||||
| **keywords** | Optional | Synonyms and other keywords for the page. This information gets stuffed into the page's metadata to increase SEO. The user won't see the keywords, but if you search for one of the keywords, it will be picked up by the search engine. |
|
||||
| **summary** | Optional | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) The only drawback with summaries is that you can't use variables in them. |
|
||||
| **permalink**| Required | This theme uses permalinks to facilitate the linking. You specify the permalink want for the page, and the \_site output will put the page into the root directory when you publish. The page will appear inside a folder by the same name, with the actual page being index.html. Browsers will automatically show the index.html file inside of any folder, so permalinks avoid the .html extension with file names. Permalink names don't have to match your file names, but it might be easier to keep them in sync. |
|
||||
|
||||
|
||||
|
||||
@ -1,25 +0,0 @@
|
||||
---
|
||||
title: 9. Set up Prince XML
|
||||
tags:
|
||||
- publishing
|
||||
keywords: "pdf generation, prince xml"
|
||||
last_updated: "November 30, 2015"
|
||||
summary: "Prince XML is the utility used for creating PDFs. Though not free, this utility gets a list of links and compiles them into a PDF."
|
||||
series: "Getting Started"
|
||||
weight: 9
|
||||
---
|
||||
|
||||
{{site.data.alerts.tip}} More details about generating PDFs are listed in {{site.data.mydoc.mydoc_urls.mydoc_generating_pdfs.link}}. {{site.data.alerts.end}}
|
||||
|
||||
## Install Prince XML
|
||||
|
||||
Prince XML is a utility I've decided to use to create PDFs. The Prince XML utility requires a list of web pages from which it can construct a PDF.
|
||||
|
||||
You need to install Prince. See the [instructions on the Prince website](http://www.princexml.com/doc/installing/#macosx) for installing Prince.
|
||||
|
||||
Prince will work even without a license, but it will imprint a small Prince image on the first page.
|
||||
|
||||
## Customize PDF headers and footers
|
||||
|
||||
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.
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Pushing builds to server
|
||||
tags: [publishing]
|
||||
keywords: AWS, Amazon, command line, pushing build
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can push your build to AWS using commands from the command line. By including your copy commands in commands, you can package all of the build and deploy process into executable scripts."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_push_build_to_server/
|
||||
---
|
||||
|
||||
|
||||
|
||||
@ -1,240 +0,0 @@
|
||||
---
|
||||
title: Scroll layout
|
||||
type: scroll
|
||||
keywords: json, scrolling, scrollto, jquery plugin
|
||||
tags: special_layouts
|
||||
last_updated: November 30, 2015
|
||||
summary: "This page demonstrates how you the integration of a script called ScrollTo, which is used here to link definitions of a JSON code sample to a list of definitions for that particular term. The scenario here is that the JSON blocks are really long, with extensive nesting and subnesting, which makes it difficult for tables below the JSON to adequately explain the term in a usable way."
|
||||
---
|
||||
|
||||
{% if site.output == "pdf" %}
|
||||
{{site.data.alerts.note}} The content on this page doesn't display well on PDF, but I included it anyway so you could see the problems this layout poses if you're including it in PDF. {{site.data.alerts.end}}
|
||||
{% endif %}
|
||||
|
||||
{% if site.output == "web" %}
|
||||
<script src="../js/jquery.scrollTo.min.js"></script>
|
||||
<!-- local scroll must come after scrollTo, because localScroll is based on scrollTo, which is based on jQuery -->
|
||||
<script src="../js/jquery.localScroll.min.js"></script>
|
||||
|
||||
<script>
|
||||
|
||||
$( document ).ready(function() {
|
||||
$('#small-box-links').localScroll({
|
||||
target:'#definition-box-container',
|
||||
showSpeed: 1000,
|
||||
hash: true,
|
||||
easing: 'swing',
|
||||
onAfter:function(){
|
||||
$("#definition-box-container div a").addClass("active");
|
||||
$("#definition-box-container div a").removeClass("active");
|
||||
$("#definition-box-container div").removeClass("active");
|
||||
$(window.location.hash).addClass("active");
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
});
|
||||
</script>
|
||||
|
||||
<!-- documentation for localScroll function: http://flesler.blogspot.com/2007/10/jquerylocalscroll-10.html -->
|
||||
<style type="text/css">
|
||||
|
||||
#definition-box-container {
|
||||
border: 0px solid #dedede;
|
||||
border-radius: 4px;
|
||||
max-height: 500px;
|
||||
overflow: scroll;
|
||||
padding-left:5px;
|
||||
border-radius:5px;
|
||||
}
|
||||
|
||||
#json-box-container {
|
||||
|
||||
border: 1px solid #dedede;
|
||||
border-radius: 4px;
|
||||
max-height:500px;
|
||||
overflow: scroll;
|
||||
}
|
||||
|
||||
#small-box-links {
|
||||
float: left;
|
||||
}
|
||||
|
||||
#definition-box-container .active {
|
||||
background-color: #FFFBCC;
|
||||
}
|
||||
|
||||
div#definition-box-container div {
|
||||
padding: 10px;
|
||||
}
|
||||
|
||||
@media (min-height: 700px) {
|
||||
#json-box-container {
|
||||
max-height:500px;
|
||||
}
|
||||
#definition-box-container {
|
||||
max-height: 500px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-height: 800px) {
|
||||
#json-box-container {
|
||||
max-height:600px;
|
||||
}
|
||||
#definition-box-container {
|
||||
max-height: 600px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-height: 900px) {
|
||||
#json-box-container {
|
||||
max-height:700px;
|
||||
}
|
||||
#definition-box-container {
|
||||
max-height: 700px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-height: 1000px) {
|
||||
#json-box-container {
|
||||
max-height:800px;
|
||||
}
|
||||
#definition-box-container {
|
||||
max-height: 800px;
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-height: 1100px) {
|
||||
#json-box-container {
|
||||
max-height:900px;
|
||||
}
|
||||
#definition-box-container {
|
||||
max-height: 900px;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
</style>
|
||||
|
||||
|
||||
<div class="container">
|
||||
<div class="row">
|
||||
|
||||
<div id="small-box-links">
|
||||
|
||||
<div class="col-md-6">
|
||||
<div id="json-box-container">
|
||||
<pre>
|
||||
{
|
||||
<a href="#apples">"apples"</a>: "red fruit at the store",
|
||||
<a href="#bananas">"bananas"</a>: "yellow bananas in a bunch",
|
||||
<a href="#carrots">"carrots"</a>: "orange vegetables that grow in the ground",
|
||||
<a href="#dingbats">"dingbats"</a>: "a type of character symbol on a computer",
|
||||
<a href="#eggs">"eggs"</a>: "chickens lay them, and people eat them",
|
||||
<a href="#falafel">"falafel"</a>: "a Mediterranean sandwich consisting of lots of different stuff i don't know much about",
|
||||
<a href="#giraffe">"giraffe"</a>: "tall animal, has purple tongue",
|
||||
<a href="#hippo">"hippo"</a>: "surprisingly dangerous amphibian",
|
||||
<a href="#igloo">"igloo"</a>: "an ice shelter made by eskimos",
|
||||
<a href="#jeep">"jeep</a>: "the only car that starts with a j",
|
||||
<a href="#kilt">"kilt"</a>: "something worn by scottish people, not a dress",
|
||||
<a href="#lamp">"lamp"</a>: "you use it to read by your bedside at night"
|
||||
<a href="#manifold">"manifold"</a>: "an intake mechanism on a car, like a valve, i think",
|
||||
<a href="#octopus">"octopus"</a>: "eight tentacles, shoots ink, lives in dark caves, very mysterious",
|
||||
<a href="#paranoia">"paranoia"</a>: "the constant feeling that others are out to get you, conspiring against your success",
|
||||
<a href="#qui">"qui"</a>: "a life force that runs through your body",
|
||||
<a href="#radical">"radical"</a>: "someone who opposes the status quo in major ways",
|
||||
<a href="#silly">"silly"</a>: "how I feel writing this dummy copy",
|
||||
<a href="#taffy">"taffy"</a>: "the sweets children like the most and dentists hate the worst",
|
||||
<a href="#umbrella">"umbrella"</a>: "an invention that has not had any advancements in 200 years",
|
||||
<a href="#vampire">"vampire"</a>: "a paranormal figure that is surprisingly in vogue despite its basic nature",
|
||||
<a href="#washington">"washington"</a>: "the place where tom was born",
|
||||
<a href="#xylophone">"xylophone"</a>: "some kind of pinging instrument used to sound chime-like notes",
|
||||
<a href="#yahoo">"yahoo"</a>: "an expression of exuberance, said under breath when something works right",
|
||||
<a href="#zeta">"zeta"</a>: "the way british people pronounce z",
|
||||
<a href="#alpha">"alpha"</a>: "the original letter of the alphabet, which has since come to mean the first. however, i think the original symbol of alpha is actually an ox. it is somewhat of a mystery to linquists as to the exact origin of the letter alpha, but it basically represents the dawn of the alphabet, which proved to be a huge step forward for human thought and expression.",
|
||||
<a href="#beta">"beta"</a>: "the period of time when something is finished but undergoing testing by a group of people.",
|
||||
<a href="#cappa">"cappa"</a>: "how italians refer to their baseball caps",
|
||||
<a href="#dunno">"dunno"</a>: "informal expression for 'don't know'"
|
||||
}
|
||||
|
||||
</pre>
|
||||
|
||||
</div><!-- end json-box-container-->
|
||||
</div> <!-- end col-md-6-->
|
||||
|
||||
<div class="col-md-3">
|
||||
|
||||
<div id="definition-box-container">
|
||||
|
||||
|
||||
<div id="apples"><h5>apples</h5>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer magna massa, euismod sed rutrum at, ullamcorper quis tellus. Vestibulum erat purus, aliquet sit amet pellentesque eget, tempus at ante. Nulla justo nisi, elementum nec nisi eget, consectetur varius tortor. </div>
|
||||
|
||||
<div id="bananas"><h5>bananas</h5>Curabitur quis nibh sed eros viverra tempus et quis lorem. Nulla convallis sit amet risus vitae rutrum. Nulla at faucibus lectus. Pellentesque tortor nisl, interdum ac quam non, egestas congue massa. Vestibulum non porttitor lacus. Nam tincidunt arcu lectus. Donec eget ornare neque, hendrerit ornare lectus. In ac pretium odio.</div>
|
||||
|
||||
<div id="carrots"><h5>carrots</h5>Vivamus pulvinar vestibulum pharetra. Vivamus vitae diam iaculis, posuere mi sed, dignissim massa. Nunc vitae aliquet urna. Proin sed pulvinar ex. Maecenas nisl lorem, rutrum sit amet hendrerit sed, posuere at odio. Sed consectetur semper tristique. Vivamus finibus varius felis at convallis. Fusce in dictum nunc.</div>
|
||||
|
||||
<div id="dingbats"><h5>dingbats</h5>Curabitur feugiat lorem eget elit ullamcorper tincidunt. In euismod diam aliquet tortor fermentum tempor. Fusce quam felis, commodo viverra orci vitae, scelerisque aliquet risus. </div>
|
||||
|
||||
<div id="eggs"><h5>eggs</h5>Duis est nunc, fringilla eu ligula et, varius dignissim dui. Vivamus in tellus vitae ipsum vehicula fermentum at congue tellus. Suspendisse fermentum, magna vitae aliquet sodales, tellus nisi rutrum arcu, vitae auctor dolor quam ac tellus. Cras posuere augue erat, in sagittis quam lacinia id.</div>
|
||||
|
||||
<div id="falafel"><h5>falafel</h5>Praesent auctor a enim non lacinia. Integer sodales aliquet mi vel dapibus. Donec consequat justo eget nisi lacinia, eu sodales ligula molestie. Sed sapien nulla, rhoncus at elementum a, </div>
|
||||
|
||||
<div id="giraffe"><h5>giraffe</h5>Nullam venenatis at lectus sed pharetra. Sed hendrerit ligula lectus, non pellentesque diam faucibus sit amet. Aliquam dictum hendrerit pellentesque. Cras eu nisl sagittis, faucibus velit sit amet, sagittis odio. Donec vulputate ex vitae purus</div>
|
||||
|
||||
<div id="hippo"><h5>hippo</h5>Cras nec pretium nulla. Suspendisse tempus tortor vel venenatis pulvinar. Integer varius tempor enim fringilla tincidunt. Phasellus magna turpis, auctor vitae elit eget, fringilla pellentesque est. Phasellus ut porta risus. Curabitur iaculis sapien sed venenatis auctor. Integer eu orci at lectus eleifend auctor id rutrum urna.</div>
|
||||
|
||||
<div id="igloo"><h5>igloo</h5>Suspendisse tempus tortor vel venenatis pulvinar. Integer varius tempor enim fringilla tincidunt. Phasellus magna turpis, auctor vitae elit eget, fringilla pellentesque est. Phasellus ut porta risus. </div>
|
||||
|
||||
<div id="jeep"><h5>jeep</h5>Nulla vitae metus rutrum, condimentum orci nec, maximus est. Aenean sit amet ante nec elit dignissim faucibus eget quis quam. </div>
|
||||
|
||||
<div id="kilt"><h5>kilt</h5>Morbi maximus, erat vel rhoncus sagittis, dolor purus dignissim ante, sit amet pharetra ex justo vitae ipsum. Nulla consequat interdum neque</div>
|
||||
|
||||
<div id="lamp"><h5>lamp</h5>Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Mauris aliquam dapibus blandit. Donec porta, enim hendrerit venenatis vulputate, orci diam lacinia nibh, faucibus rutrum dolor dui ut quam.</div>
|
||||
|
||||
<div id="manifold"><h5>manifold</h5>Donec finibus massa vel nisi ullamcorper, vitae ornare enim euismod. Aliquam auctor quam erat. Duis interdum rutrum orci, ac interdum urna pharetra eget.</div>
|
||||
|
||||
<div id="octopus"><h5>octopus</h5>Nulla id egestas enim. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse potenti. Curabitur eu lobortis ligula.</div>
|
||||
|
||||
<div id="paranoia"><h5>paranoia</h5>Aenean hendrerit mauris ipsum, non laoreet ipsum luctus vel. Curabitur tristique auctor elit ut pulvinar. Quisque arcu arcu, condimentum aliquam sodales nec, dignissim nec justo. Nunc tristique sem felis, pharetra euismod lorem volutpat sed. Ut porttitor metus sit amet elit rhoncus semper.</div>
|
||||
|
||||
<div id="qui"><h5>qui</h5>Quisque rhoncus cursus felis vel elementum. Vestibulum dignissim molestie tortor nec facilisis. Praesent a nibh condimentum, porta nulla egestas, auctor eros</div>
|
||||
|
||||
<div id="radical"><h5>radical</h5>Etiam hendrerit interdum tellus, at aliquet sapien egestas in. Aenean eu urna nisl. Cras vitae risus pharetra, elementum mauris nec, auctor lectus. Fusce pellentesque venenatis dictum. Proin at augue at mauris finibus semper ultricies sed eros.</div>
|
||||
|
||||
<div id="silly"><h5>silly</h5>Praesent pulvinar consequat posuere. Morbi egestas rhoncus felis, id fermentum metus lobortis in. Vestibulum nibh orci, euismod eget vestibulum nec, vehicula vitae tortor. Aenean ullamcorper enim nunc, eu auctor ligula auctor eget.</div>
|
||||
|
||||
<div id="taffy"><h5>taffy</h5>Etiam et arcu vel lacus aliquet lobortis in in massa. Nunc non mollis elit. Aenean accumsan orci quis risus aliquam, non gravida nulla molestie. Mauris pharetra libero et magna aliquam aliquam. Integer quis luctus dolor. </div>
|
||||
|
||||
<div id="umbrella"><h5>umbrella</h5>Fusce molestie finibus malesuada. Nullam ac egestas quam, id venenatis ligula. Pellentesque pulvinar elit et vestibulum fringilla. Cras volutpat sed quam ornare scelerisque. Vivamus volutpat ante pretium scelerisque tempus. Etiam venenatis tempor nisl dignissim sollicitudin. Curabitur ac risus vitae dolor pretium posuere vel vitae diam. Donec in odio arcu.</div>
|
||||
|
||||
<div id="vampire"><h5>vampire</h5>Vestibulum pretium condimentum commodo. Integer placerat leo non ipsum ultrices, ac convallis elit varius. Vestibulum ultricies, justo eu rutrum molestie, quam arcu euismod sapien, vel gravida ipsum nulla eget erat. </div>
|
||||
|
||||
<div id="washington"><h5>washington</h5>Nunc ac quam eu risus dictum sodales. Nam ac risus iaculis, aliquet sem eu, mollis mauris. Curabitur pretium facilisis orci ut lacinia. Sed fermentum leo a odio blandit rutrum. Phasellus at nibh vel odio interdum vulputate ac eget urna. Nam eu arcu dapibus, sodales ligula nec, volutpat ipsum. Suspendisse auctor tellus vitae libero euismod venenatis. </div>
|
||||
|
||||
<div id="xylophone"><h5>xylophone</h5>Sed molestie lobortis ante sit amet hendrerit. Sed pharetra nisi sed interdum pulvinar. Nunc efficitur erat non aliquam mattis. Sed id nisl mattis lacus vehicula volutpat vitae vel massa. Curabitur interdum velit odio, vitae sollicitudin nunc rutrum non. </div>
|
||||
|
||||
<div id="yahoo"><h5>yahoo</h5>Nunc commodo consectetur scelerisque. Proin fermentum ligula ac quam finibus tincidunt. Aenean venenatis nisi et semper semper. Nunc sodales velit ipsum, ac pellentesque augue placerat eu.</div>
|
||||
|
||||
<div id="zeta"><h5>zeta</h5>Nullam ac suscipit odio. Curabitur viverra arcu ut egestas sollicitudin. Fusce sodales varius lectus ut tristique. Etiam eget nunc ornare, aliquet tortor eget, consequat mauris. Integer sit amet fermentum augue. </div>
|
||||
|
||||
<div id="alpha"><h5>alpha</h5>Praesent nec neque ac tellus sodales eleifend nec vel ipsum. Cras et semper risus. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Integer mattis leo nisl, a tincidunt lectus tristique eget. Donec finibus lobortis viverra. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Vivamus egestas pulvinar odio non vehicula. Morbi malesuada leo eget nisl sagittis aliquet.</div>
|
||||
|
||||
|
||||
<div id="beta"><h5>beta</h5>Mauris a libero vel enim pharetra interdum non a quam. Sed tincidunt ut elit sed dignissim. Suspendisse vitae tellus dapibus, fermentum lacus ac, fermentum lacus. Nam ante odio, fringilla ac elementum a, mollis sed tellus.</div>
|
||||
|
||||
<div id="cappa"><h5>cappa</h5>Nam molestie semper nulla et molestie. Ut facilisis, ipsum sed convallis posuere, mi mauris bibendum erat, nec egestas ipsum est nec dolor. </div>
|
||||
|
||||
<div id="dunno"><h5>dunno</h5>Etiam et metus congue, commodo libero et, accumsan sem. Aliquam erat volutpat. Quisque tincidunt, tortor non blandit ullamcorper, orci mauris dignissim augue, eget vehicula nulla justo sed dolor. Nunc ac urna quis nisi maximus pharetra in a mauris. Proin metus mi, venenatis vitae tristique sed, fermentum at purus. Aliquam erat volutpat. Maecenas efficitur sodales nibh, ac hendrerit felis facilisis et. Interdum et malesuada fames ac ante ipsum primis in faucibus.</div>
|
||||
|
||||
|
||||
</div> <!-- end definition-box-container -->
|
||||
</div> <!-- end col-md-3-->
|
||||
</div> <!-- end small-box-links -->
|
||||
</div> <!-- end row -->
|
||||
</div> <!-- end container -->
|
||||
|
||||
|
||||
{{site.data.alerts.note}} This was mostly an experiment to see if there was a better way to document a long JSON code example. I haven't actually used this approach in my own documentation.{{site.data.alerts.end}}
|
||||
|
||||
{% endif %}
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Search configuration
|
||||
tags: [publishing, navigation]
|
||||
keywords: search, json, configuration, findability
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "The search feature uses JavaScript to look for keyword matches in a JSON file. The results show instant matches, but it doesn't provide a search results page like Google. Also, sometimes invalid formatting can break the JSON file."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_search_configuration/
|
||||
---
|
||||
|
||||
|
||||
|
||||
@ -2,13 +2,15 @@
|
||||
title: Series
|
||||
tags: [content-types]
|
||||
keywords: series, connected articles, tutorials, hello world
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can automatically link together topics belonging to the same series. This helps users know the context within a particular process."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_series/
|
||||
---
|
||||
|
||||
|
||||
## Using series for pages
|
||||
You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a <a href="mydoc_seriesdemo1_0.html" class="noCrossRef">demo</a>.
|
||||
|
||||
You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a <a href="{{ "/mydoc_seriesdemo1" | prepend: site.baseurl }}" class="noCrossRef">demo</a>.
|
||||
|
||||
## 1. Create the series button
|
||||
|
||||
@ -40,20 +42,20 @@ First create an include that contains your series button:
|
||||
|
||||
Change "ACME series" to the name of your series.
|
||||
|
||||
Save this in your \_includes/custom/mydoc folder as something like series\_acme.html.
|
||||
Save this in your \_includes/custom folder as something like series\_acme.html.
|
||||
|
||||
{{site.data.alerts.warning}} With pages, there isn't a universal namespace created from tags or categories like there is with Jekyll posts. As a result, you have to loop through all pages. If you have a lot of pages in your site (e.g., 1,000+), then this looping will create a slow build time. If this is the case, you will need to rethink the approach to looping here.{{site.data.alerts.end}}
|
||||
|
||||
## 2. Create the "next" include
|
||||
|
||||
Now create another include for the Next button at the bottom of the page. Copy the following code, changing the series name to your series'name:
|
||||
Now create another include for the Next button at the bottom of the page. Copy the following code, changing the series name to your series'name:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<p>{% assign series_pages = site.tags.series_acme %}
|
||||
{% for p in pages %}
|
||||
{% if p.series == "ACME series" %}
|
||||
{% assign nextTopic = page.weight | plus: "0.1" %}
|
||||
{% assign nextTopic = page.weight | plus: "1" %}
|
||||
{% if p.weight == nextTopic %}
|
||||
<a href="{{p.url | prepend: '..'}}"><button type="button" class="btn btn-primary">Next: {{p.weight}} {{p.title}}</button></a>
|
||||
{% endif %}
|
||||
@ -76,9 +78,7 @@ series: "ACME series"
|
||||
weight: 1.0
|
||||
```
|
||||
|
||||
With weight, you could use 1, 2, 3, etc.., but Jekyll will treat 10 as coming after 1. This is why I use 1.0 and 1.1, 1.2, etc.
|
||||
|
||||
If you do use whole numbers, change the `plus: "0.1"` to `plus: "1"`.
|
||||
With weights, Jekyll will treat 10 as coming after 1. If you have more than 10 items, consider changing `plus: "1.0"` to `plus: "0.1"`.
|
||||
|
||||
Additionally, if your page names are prefaced with numbers, such as "1. Download the code," then the {% raw %}`{{p.weight}}`{% endraw %} will create a duplicate number. In that case, just remove the {% raw %}`{{p.weight}}`{% endraw %} from both code samples here.
|
||||
|
||||
@ -90,18 +90,18 @@ On each series page, add a link to the series button at the top and a link to th
|
||||
```liquid
|
||||
<!-- your frontmatter goes here -->
|
||||
|
||||
{% include custom/mydoc/series_acme.html %}
|
||||
{% include custom/series_acme.html %}
|
||||
|
||||
<!-- your page content goes here ... -->
|
||||
|
||||
{% include custom/mydoc/series_acme_next.html %}
|
||||
{% include custom/series_acme_next.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Changing the series drop-down color
|
||||
|
||||
The Bootstrap menu uses the `primary` class for styling. If you change this class in your theme, the Bootstrap menu should automatically change color as well. You can also just use another Bootstrap class in your button code. Instead of `btn-primary`, use `btn-info` or `btn-warning`. See {{site.data.mydoc.mydoc_urls.mydoc_labels.link}} for more Bootstrap button classes.
|
||||
The Bootstrap menu uses the `primary` class for styling. If you change this class in your theme, the Bootstrap menu should automatically change color as well. You can also just use another Bootstrap class in your button code. Instead of `btn-primary`, use `btn-info` or `btn-warning`. See <a href="{{ "/mydoc_labels" | prepend: site.baseurl }}">Labels</a>for more Bootstrap button classes.
|
||||
|
||||
## Using a collection with your series
|
||||
|
||||
Instead of copying and pasting the button includes on each of your series, you could also create a collection and define a layout for the collection that has the include code. For more information on creating collections, see {{site.data.mydoc.mydoc_urls.mydoc_collections.link}}.
|
||||
Instead of copying and pasting the button includes on each of your series, you could also create a collection and define a layout for the collection that has the include code. For more information on creating collections, see <a href="{{ "/mydoc_collections" | prepend: site.baseurl }}">Collections</a>.
|
||||
@ -1,12 +1,14 @@
|
||||
---
|
||||
title: Series demo 1.0
|
||||
title: Series demo 1
|
||||
summary: "This is the first post in the series."
|
||||
series: "ACME series"
|
||||
weight: 1.0
|
||||
last_updated: November 30, 2015
|
||||
weight: 1
|
||||
last_updated: March 20, 2016
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_seriesdemo1/
|
||||
---
|
||||
|
||||
{% include custom/mydoc/series_acme.html %}
|
||||
{% include custom/series_acme.html %}
|
||||
|
||||
This is the first post in the series.
|
||||
|
||||
@ -14,6 +16,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo. Aliquam feugiat, nibh in ultrices mattis, felis ipsum venenatis metus, vel vehicula libero mauris a enim. Sed placerat est ac lectus vestibulum tempor. Quisque ut condimentum massa. Proin venenatis leo id urna cursus blandit. Vivamus sit amet hendrerit metus.
|
||||
|
||||
{% include custom/mydoc/series_acme_next.html %}
|
||||
{% include custom/series_acme_next.html %}
|
||||
|
||||
|
||||
@ -1,13 +1,15 @@
|
||||
---
|
||||
title: Series demo 1.1
|
||||
title: Series demo 2
|
||||
summary: "This is the second post in the series."
|
||||
series: "ACME series"
|
||||
weight: 1.1
|
||||
last_updated: November 30, 2015
|
||||
weight: 2
|
||||
last_updated: March 20, 2016
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_seriesdemo2/
|
||||
---
|
||||
|
||||
|
||||
{% include custom/mydoc/series_acme.html %}
|
||||
{% include custom/series_acme.html %}
|
||||
|
||||
This is the second post in the series.
|
||||
|
||||
@ -17,4 +19,4 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo.
|
||||
|
||||
{% include custom/mydoc/series_acme_next.html %}
|
||||
{% include custom/series_acme_next.html %}
|
||||
@ -1,14 +1,15 @@
|
||||
---
|
||||
title: Series demo 1.2
|
||||
last_updated: May 17, 2015
|
||||
title: Series demo 3
|
||||
last_updated: May 17, 2016
|
||||
summary: "This is the third post in the series."
|
||||
series: "ACME series"
|
||||
weight: 1.2
|
||||
last_updated: November 30, 2015
|
||||
weight: 3
|
||||
last_updated: March 20, 2016
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_seriesdemo3/
|
||||
---
|
||||
|
||||
|
||||
{% include custom/mydoc/series_acme.html %}
|
||||
{% include custom/series_acme.html %}
|
||||
|
||||
This is the third post in the series.
|
||||
|
||||
@ -18,4 +19,4 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo. Aliquam feugiat, nibh in ultrices mattis, felis ipsum venenatis metus, vel vehicula libero mauris a enim. Sed placerat est ac lectus vestibulum tempor. Quisque ut condimentum massa. Proin venenatis leo id urna cursus blandit. Vivamus sit amet hendrerit metus.
|
||||
|
||||
{% include custom/mydoc/series_acme_next.html %}
|
||||
{% include custom/series_acme_next.html %}
|
||||
@ -1,13 +1,15 @@
|
||||
---
|
||||
title: Series demo 1.3
|
||||
title: Series demo 4
|
||||
summary: "This is the fourth post in the series."
|
||||
series: "ACME series"
|
||||
weight: 1.3
|
||||
last_updated: November 30, 2015
|
||||
weight: 4
|
||||
last_updated: March 20, 2016
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_seriesdemo4/
|
||||
---
|
||||
|
||||
|
||||
{% include custom/mydoc/series_acme.html %}
|
||||
{% include custom/series_acme.html %}
|
||||
|
||||
This is the fourth post in the series.
|
||||
|
||||
@ -21,4 +23,4 @@ Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fer
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius.
|
||||
|
||||
|
||||
{% include custom/mydoc/series_acme_next.html %}
|
||||
{% include custom/series_acme_next.html %}
|
||||
@ -1,164 +0,0 @@
|
||||
---
|
||||
title: Shuffle layout
|
||||
tags: [special_layouts]
|
||||
last_updated: November 30, 2015
|
||||
keywords: shuffle, card layout, dynamic grid, doc portal, support portal
|
||||
summary: "This layout shows an example of a knowledge-base style navigation system, where there is no hierarchy, just groups of pages that have certain tags."
|
||||
---
|
||||
|
||||
|
||||
{% if site.output == "pdf" %}
|
||||
{{site.data.alerts.note}} The content on this page doesn't display well on PDF, but I included it anyway so you could see the problems this layout poses if you're including it in PDF. {{site.data.alerts.end}}
|
||||
{% endif %}
|
||||
|
||||
{% unless site.output == "pdf" %}
|
||||
<script src="../js/jquery.shuffle.min.js"></script>
|
||||
<script src="../js/jquery.ba-throttle-debounce.min.js"></script>
|
||||
{% endunless %}
|
||||
|
||||
<div class="filter-options">
|
||||
<button class="btn btn-primary" data-group="all">All</button>
|
||||
<button class="btn btn-primary" data-group="getting_started">Getting Started</button>
|
||||
<button class="btn btn-primary" data-group="formatting">Formatting</button>
|
||||
<button class="btn btn-primary" data-group="publishing">Publishing</button>
|
||||
<button class="btn btn-primary" data-group="content-types">Content types</button>
|
||||
<button class="btn btn-primary" data-group="single_sourcing">Single Sourcing</button>
|
||||
<button class="btn btn-primary" data-group="special_layouts">Special Layouts</button>
|
||||
</div>
|
||||
|
||||
<div id="grid" class="row">
|
||||
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["getting_started"]'>
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">Getting started</div>
|
||||
<div class="panel-body">
|
||||
If you're getting started with Jekyll, see the links in this section. It will take you from the beginning level to comfortable.
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "getting_started" %}
|
||||
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["content-types"]'>
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">Content types</div>
|
||||
<div class="panel-body">
|
||||
This section lists different content types and how to work with them.
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "content-types" %}
|
||||
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["formatting"]'>
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">Formatting</div>
|
||||
<div class="panel-body">
|
||||
These topics get into formatting syntax, such as images and tables, that you'll use on each of your pages:
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "formatting" %}
|
||||
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["single_sourcing"]'>
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">Single Sourcing</div>
|
||||
<div class="panel-body">These topics cover strategies for single_sourcing. Single sourcing refers to strategies for re-using the same source in different outputs for different audiences or purposes.
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "single_sourcing" %}
|
||||
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["publishing"]'>
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">Publishing</div>
|
||||
<div class="panel-body">When you're building, publishing, and deploying your Jekyll site, you might find these topics helpful.
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "publishing" %}
|
||||
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["special_layouts"]'>
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">Special Layouts</div>
|
||||
<div class="panel-body">
|
||||
These pages highlight special layouts outside of the conventional page and TOC hierarchy.
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "special_layouts" %}
|
||||
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<!-- sizer -->
|
||||
<div class="col-xs-6 col-sm-4 col-md-1 shuffle_sizer"></div>
|
||||
|
||||
|
||||
</div><!-- /#grid -->
|
||||
|
||||
{% unless site.output == "pdf" %}
|
||||
{% include initialize_shuffle.html %}
|
||||
{% endunless %}
|
||||
|
||||
{{site.data.alerts.note}} This was mostly an experiment to see if I could break away from the hierarchical TOC and provide a different way of arranging the content. However, this layout is somewhat problematic because it doesn't allow you to browse other navigation options on the side while viewing a topic.{{site.data.alerts.end}}
|
||||
|
||||
|
||||
@ -1,15 +1,13 @@
|
||||
---
|
||||
title: Sidebar Navigation
|
||||
tags: [getting_started]
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
keywords: sidebar, accordion, yaml, iteration, for loop, navigation, attributes, conditional filtering
|
||||
summary: "The sidebar navigation uses a jQuery component called Navgoco. The sidebar is a somewhat complex part of the theme that remembers your current page, highlights the active item, stays in a fixed position on the page, and more."
|
||||
summary: "The sidebar navigation uses a jQuery component called Navgoco. The sidebar is a somewhat complex part of the theme that remembers your current page, highlights the active item, stays in a fixed position on the page, and more. This page explains a bit about how the sidebar was put together."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_sidebar_navigation/
|
||||
---
|
||||
|
||||
{{site.data.alerts.note}} For basic information about configuring the sidebar navigation, see {{site.data.mydoc.mydoc_urls.mydoc_configure_sidebar.link}}. This section gets into the top sidebar navigation in more depth.{{site.data.alerts.end}}
|
||||
|
||||
When you set up your project, you configured the sidebar following the instructions in {{site.data.mydoc.mydoc_urls.mydoc_configure_sidebar.link}}. In this topic, I dive deeper into other aspects of the sidebar.
|
||||
|
||||
## Navgoco foundation
|
||||
|
||||
The sidebar uses the [Navgoco jQuery plugin](https://github.com/tefra/navgoco) as its basis. Why not use Bootstrap? Navgoco provides a few features that I couldn't find in Bootstrap:
|
||||
@ -18,11 +16,11 @@ The sidebar uses the [Navgoco jQuery plugin](https://github.com/tefra/navgoco) a
|
||||
* Navgoco inserts an `active` class based on the navigation option that's open. This is essential for keeping the accordion open.
|
||||
* Navgoco includes the expand and collapse features of a sidebar.
|
||||
|
||||
In short, the sidebar has some complex logic here. I've integrated Navgoco's features with the sidebar.html and sidebar_doc.yml to build the sidebar. It's probably the most impressive part of this theme. (Other themes usually aren't focused on creating hierarchies of pages, but this kind of hierarchy is important in a documentation site.)
|
||||
In short, the sidebar has some complex logic here. I've integrated Navgoco's features with the sidebar.html and sidebar data files to build the sidebar. It's probably the most impressive part of this theme. (Other themes usually aren't focused on creating hierarchies of pages, but this kind of hierarchy is important in a documentation site.)
|
||||
|
||||
## Accordion sidebar feature
|
||||
|
||||
As mentioned in the previous section, the theme uses the [Navgoco sidebar](http://www.komposta.net/article/navgoco). The sidebar.html file (inside the _includes folder) contains the `.navgoco` method called on the `#mysidebar` element.
|
||||
The sidebar.html file (inside the _includes folder) contains the `.navgoco` method called on the `#mysidebar` element.
|
||||
|
||||
There are some options to set within the `.navgoco` method. The only noteworthy option is `accordion`. This option makes it so when you expand a section, the other sections collapse. It's a way of keeping your navigation controls condensed.
|
||||
|
||||
@ -78,14 +76,10 @@ This is why the `url` value in the sidebar data file looks something like this:
|
||||
|
||||
```yaml
|
||||
- title: Understanding how the sidebar works
|
||||
url: /mydoc/mydoc_understand_sidebar.html
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
product: all
|
||||
version: all
|
||||
output: web, pdf
|
||||
url: /mydoc_understand_sidebar/
|
||||
output: web, pdf
|
||||
```
|
||||
|
||||
Note that the url includes the project folder where the file is stored.
|
||||
Note that the url does not include the project folder where the file is stored. This is because the site uses permalinks, which pulls the topics out of subfolders and places them into the root directory when the site builds.
|
||||
|
||||
Now the page.url and the item.url can match and the `active` class can get applied. With the `active` class applied, the sidebar section remains open.
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Special layouts overview
|
||||
tags: [special_layouts]
|
||||
keywords: layouts, information design, presentation
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "This theme has a few special layouts. Special layouts include the JS files they need directly in the page. The JavaScript for each special layout does not load by default for every page in the site."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_special_layouts/
|
||||
---
|
||||
|
||||
|
||||
@ -11,18 +13,18 @@ summary: "This theme has a few special layouts. Special layouts include the JS f
|
||||
|
||||
## FAQ layout
|
||||
|
||||
See {{site.data.mydoc.mydoc_urls.mydoc_faq.link}} for an example of the FAQ format, which follows an accordion, collapse/expand format. This code is from Bootstrap.
|
||||
See {{site.data.mydoc_urls.mydoc_faq.link}} for an example of the FAQ format, which follows an accordion, collapse/expand format. This code is from Bootstrap.
|
||||
|
||||
## Knowledgebase layout
|
||||
|
||||
See {{site.data.mydoc.mydoc_urls.mydoc_kb_layout.link}} for a possible layout for knowledge base articles. This layout looks for pages containing specific tags.
|
||||
See {{site.data.mydoc_urls.mydoc_kb_layout.link}} for a possible layout for knowledge base articles. This layout looks for pages containing specific tags.
|
||||
|
||||
## Scroll layout
|
||||
|
||||
If you have a long JSON message you're documenting, see the {{site.data.mydoc.mydoc_urls.mydoc_scroll.link}}. This layout adds a side pane showing links to pointers in the left pane.
|
||||
If you have a long JSON message you're documenting, see the {{site.data.mydoc_urls.mydoc_scroll.link}}. This layout adds a side pane showing links to pointers in the left pane.
|
||||
|
||||
## Shuffle layout
|
||||
|
||||
If you want a dynamic card layout that allows you to filter the cards, see {{site.data.mydoc.mydoc_urls.mydoc_shuffle.link}}. This uses the Shuffle JS library.
|
||||
If you want a dynamic card layout that allows you to filter the cards, see {{site.data.mydoc_urls.mydoc_shuffle.link}}. This uses the Shuffle JS library.
|
||||
|
||||
|
||||
|
||||
@ -2,9 +2,10 @@
|
||||
title: Support
|
||||
tags: [getting_started]
|
||||
keywords: questions, troubleshooting, contact, support
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "Contact me for any support issues."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_support/
|
||||
---
|
||||
|
||||
|
||||
I'm actively developing this theme. Please let me know about any bugs or other issues that you find. Just email me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. You can also [create issues directly within the Github repository here](https://github.com/tomjohnson1492/jekyll-doc/issues).
|
||||
Let me know about any bugs or other issues that you find. Just email me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. You can also [create issues directly within the Github repository here](https://github.com/tomjohnson1492/jekyll-doc/issues).
|
||||
@ -1,36 +1,53 @@
|
||||
---
|
||||
title: Supported features
|
||||
tags:
|
||||
- "getting_started"
|
||||
- getting_started
|
||||
keywords: "features, capabilities, scalability, multichannel output, dita, hats, comparison, benefits"
|
||||
last_updated: "November 30, 2015"
|
||||
last_updated: "November 30, 2016"
|
||||
summary: "If you're not sure whether Jekyll and this theme will support your requirements, this list provides a semi-comprehensive overview of available features."
|
||||
published: true
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_supported_features/
|
||||
---
|
||||
|
||||
Before you get into exploring Jekyll as a potential platform for help content, you may be wondering if it supports some basic features. The following table shows what is supported in Jekyll and this theme.
|
||||
Before you get into exploring Jekyll as a potential platform for help content, you may be wondering if it supports some basic features needed to fulfill your tech doc requirements. The following table shows what is supported in Jekyll and this theme.
|
||||
|
||||
## Supported feautres
|
||||
|
||||
Features | Supported | Notes
|
||||
--------|-----------|-----------
|
||||
Content re-use | Yes | Supports re-use through Liquid. You can re-use variables, snippets of code, entire pages, and more. In DITA speak, this includes conref and keyref.
|
||||
Markdown | Yes | You can author content using Markdown syntax. This is a wiki-like syntax for HTML that you can probably pick up in 10 minutes. Where Markdown falls short, you can use HTML. Where HTML falls short, you use Liquid, which is a scripting that allows you to incorporate more advanced logic.
|
||||
Responsive design | Yes | Uses Bootstrap framework.
|
||||
Translation | Yes | I haven't done a translation project yet (just a pilot test). Here's the basic approach: Export the pages and send them to a translation agency. Then create a new project for that language and insert the translated pages. Everything will be translated.
|
||||
PDF | Yes | You can generate PDFs from your Jekyll site. This theme uses Prince XML (costs $495) to do the PDF conversion task. You basically set up a page that uses Liquid logic to get all the pages you want, and then you use PrinceXML (not part of Jekyll) to convert that page into a PDF.
|
||||
Responsive design | Yes | Uses Bootstrap framework for responsive design.
|
||||
Translation | Yes | I haven't done a translation project yet (just a pilot test). Here's the basic approach: Export the HTML pages and send them to a translation agency. Then create a new project for that language and insert the translated pages. Everything will be translated.
|
||||
Collaboration | Yes | You collaborate with Jekyll projects the same way that developers collaborate with software projects. (You don't need a CMS.) Because you're working with text file formats, you can use any version control software (Git, Mercurial, Perforce, Bitbucket, etc.) as a CMS for your files.
|
||||
Scalability | Yes | Your site can scale to any size. It's up to you to determine how you will design the information architecture for your thousands of pages. You can choose what you display at first, second, third, fourth, and more levels, etc. Note that when your project has thousands of pages, the build time will be longer (maybe 1 minute per thousand pages?). It really depends on how many for loops you have iterating through the pages.
|
||||
Lightweight architecture | Yes | You don't need a LAMP stack (Linux, Apache, MySQL, PHP) architecture to get your site running. All of the building is done on your own machine, and you then push the static HTML files onto a server.
|
||||
Multichannel output | Yes | This term can mean a number of things, but let's say you have 10 different sites you want to generate from the same source. Maybe you have 7 different versions of your product, and 3 different locations. You can assemble your Jekyll site with various configurations, variants, and more. Jekyll actually does all of this quite well. Just specify a different config file for each unique build.
|
||||
Skinnability | Yes | You can skin your Jekyll site to look identical to pretty much any other site online. If you have a UX team, they can really skin and design the site using all the tools familiar to the modern designer -- JavaScript, HTML5, CSS, jQuery, and more. Jekyll is built on the modern web development stack rather than the XML stack (XSLT, XPath, XQuery).
|
||||
Support | Yes | The community for your Jekyll site isn't so much other tech writers (as is the case with DITA) but rather the wider web development community. [Jekyll Talk](http://talk.jekyllrb.com) is a great resource. So is Stack Overflow.
|
||||
Blogging features | No | This theme just uses pages, not posts. I may integrate in post features in the future, but the theme really wasn't designed with posts in mind. If you want a post version of the site, you can clone my [blog theme](https://github.com/tomjohnson1492/tomjohnson1492.github.io), which is highly similar in that it's based on Bootstrap, but it uses posts to drive most of the features. I wanted to keep the project files simple.
|
||||
CMS interface | No | Unlike with WordPress, you don't log into an interface and navigate to your files. You work with text files and preview the site dynamically in your browser. Don't worry -- this is part of the simplicy that makes Jekyll awesome. I recommend using WebStorm as your text editor.
|
||||
WYSIWYG interface | No, but ... | As noted in the previous point, I use WebStorm to author content, because I like working in text file formats. But you can use any Markdown editor you want (e.g., Lightpaper for Mac, Marked) to author your content.
|
||||
Versioning | Yes, but... | Jekyll doesn't version your files. You upload your files to a version control system such as Git. Your files are versioned there.
|
||||
PC platform | Yes, but ... | Jekyll isn't officially supported on Windows, and since I'm on a Mac, I haven't tried using Jekyll on Windows. See this [page in Jekyllrb help](http://jekyllrb.com/docs/windows/) for details about installing and running Jekyll on a Windows machine. A couple of Windows users who have contacted me have been unsuccessful in installing Jekyll on Windows, so beware. In the configuration files, use `rouge` instead of `pygments` (which is Python-based) to avoid conflicts.
|
||||
Blogging features | Yes | There is a simple blogging feature. This appears as "news" and is intended to promote news that applies across products.
|
||||
Versioning | Yes | Jekyll doesn't version your files. You upload your files to a version control system such as Github. Your files are versioned there.
|
||||
PC platform | Yes | Jekyll runs on Windows. Although the experience working on the command line is better on a Mac, Windows also works, especially now that Jekyll 3.0 dropped dependencies on Python, which wasn't available by default on Windows.
|
||||
jQuery plugins | Yes | You can use any jQuery plugins you and other JavaScript, CMS, or templating tools. However, note that if you use Ruby plugins, you can't directly host the source files on Github Pages because Github Pages doesn't allow Ruby plugins. Instead, you can just push your output to any web server. If you're not planning to use Github Pages, there are no restrictions on any plugins of any sort. Jekyll makes it super easy to integrate every kind of plugin imaginable. This theme doesn't actually use any plugins, so you can publish on Github if you want.
|
||||
Bootstrap integration | Yes | This theme is built on [Bootstrap](http://getbootstrap.com/). If you don't know what Bootstrap is, basically this means there are hundreds of pre-built components, styles, and other elements that you can simply drop into your site. For example, the responsive quality of the site comes about from the Bootstrap code base.
|
||||
Fast-loading pages| Yes | This is one of the Jekyll's strengths. Because the files are static, they loading extremely fast, approximately 0.5 seconds per page. You can't beat this for performance. (A typically database-driven site like WordPress averages about 2.5 + seconds loading time per page.) Because the pages are all static, it means they are also extremely secure. You won't get hacked like you might with a WordPress site.
|
||||
Relative links | Yes | This theme is built entirely with relative links, which means you can easily move the files from one folder to the next and it will still display. You don't need to view the site on a web server either -- you can view it locally just clicking the files. This relative link structure facilitates scenarios where you need to archive versions of content or move the files from one directory (a test directory) to another (such as a production directory).
|
||||
Themes | Yes | You can have different themes for different outputs. If you know CSS, theming both the web and print outputs is pretty easy.
|
||||
Open source | Yes | This theme is entirely open source. Every piece of code is open, viewable, and editable. Note that this openness comes at a price — it's easy to make changes that break the theme or otherwise cause errors.
|
||||
|
||||
|
||||
## Features not available
|
||||
|
||||
The following features are not available.
|
||||
|
||||
Features | Supported | Notes
|
||||
--------|-----------|-----------
|
||||
CMS interface | No | Unlike with WordPress, you don't log into an interface and navigate to your files. You work with text files and preview the site dynamically in your browser. Don't worry -- this is part of the simplicy that makes Jekyll awesome. I recommend using WebStorm as your text editor.
|
||||
WYSIWYG interface | No | I use WebStorm to author content, because I like working in text file formats. But you can use any Markdown editor you want (e.g., Lightpaper for Mac, Marked) to author your content.
|
||||
Different outputs | No | This theme provides a single website output that contains documentation for multiple products. Unlike previous iterations of the theme, it's not intended to support different outputs from the same content.
|
||||
Robust search | No | The search feature is a simplistic JSON search. For more robust search, you should integrate Swiftype or Algolia. However, those services aren't currently integrated into the theme.
|
||||
Standardized templates | No | You can create pages with any structure you want. The theme does not enforce topic types such as a task or concept as the DITA specification does.
|
||||
Integration with Swagger | No | You can link to a SwaggerUI output, but there is no built-in integration of SwaggerUI into this documentation theme.
|
||||
Templates for endpoints | No | Although static site generators work well with API documentation, there aren't any built-in templates specific to endpoints in this theme. You could construct your own, though.
|
||||
eBook output | No | There isn't an eBook output for the content.
|
||||
|
||||
|
||||
|
||||
@ -2,11 +2,12 @@
|
||||
title: Syntax highlighting
|
||||
tags: [formatting]
|
||||
keywords: rouge, pygments, prettify, color coding,
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can apply syntax highlighting to your code. This theme uses pygments and applies color coding based on the lexer you specify."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_syntax_highlighting/
|
||||
---
|
||||
|
||||
{% comment %}
|
||||
## About syntax highlighting
|
||||
For syntax highlighting, use fenced code blocks optionally followed by the language syntax you want:
|
||||
|
||||
@ -56,8 +57,8 @@ highlighter: rouge
|
||||
```
|
||||
|
||||
The syntax highlighting is done via the css/syntax.css file.
|
||||
{% endcomment %}
|
||||
## Available lexers
|
||||
|
||||
## Available lexers
|
||||
|
||||
The keywords you must add to specify the highlighting (in the previous example, `ruby`) are called "lexers." You can search for "lexers." Here are some common ones I use:
|
||||
|
||||
|
||||
@ -2,12 +2,13 @@
|
||||
title: Tables
|
||||
tags: [formatting]
|
||||
keywords: datatables, tables, grids, markdown, multimarkdown, jquery plugins
|
||||
last_updated: November 30, 2015
|
||||
datatable: true
|
||||
last_updated: March 20, 2016
|
||||
datatable: active
|
||||
summary: "You can format tables using either multimarkdown syntax or HTML. You can also use jQuery datatables (a plugin) if you need more robust tables."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_tables/
|
||||
---
|
||||
|
||||
|
||||
{% unless site.output == "pdf" %}
|
||||
<script>
|
||||
$(document).ready(function(){
|
||||
@ -42,7 +43,7 @@ cell 2a | cell 2b
|
||||
|
||||
## jQuery datables
|
||||
|
||||
You also have the option of using a [jQuery datatable](https://www.datatables.net/), which gives you some more options. If you want to use a jQuery datatable, then add `datatable: true` in a page's frontmatter. This will load the right jQuery datatable scripts for the table on that page only (rather than loading the scripts on every page of the site.)
|
||||
You also have the option of using a [jQuery datatable](https://www.datatables.net/), which gives you some more options. If you want to use a jQuery datatable, then add `datatable: active` in a page's frontmatter. This will load the right jQuery datatable scripts for the table on that page only (rather than loading the scripts on every page of the site.)
|
||||
|
||||
Also, you need to add this script to trigger the jQuery table on your page:
|
||||
|
||||
|
||||
@ -1,9 +1,11 @@
|
||||
---
|
||||
title: Tag archives overview
|
||||
keywords: archives, tagging
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
tags: [navigation]
|
||||
summary: "This is an overview to the tag archives section. Really the only reason this section is listed explicitly in the TOC here is to demonstrate how to add a third-level to the navigation."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_tag_archives_overview/
|
||||
---
|
||||
|
||||
## Reasons for tags
|
||||
|
||||
@ -2,9 +2,11 @@
|
||||
title: Tags
|
||||
audience: writer, designer
|
||||
tags: [navigation]
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
keywords: tags, navigation, buttons, links, association
|
||||
summary: "Tags provide another means of navigation for your content. Unlike the table of contents, tags can show the content in a variety of arrangements and groupings. Implementing tags in this Jekyll theme is somewhat of a manual process."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_tags/
|
||||
---
|
||||
|
||||
|
||||
@ -21,13 +23,13 @@ tags: [formatting, single_sourcing]
|
||||
|
||||
## Tags overview
|
||||
|
||||
{{site.data.alerts.note}} With posts, tags have a namespace that you can access with <code>posts.tags.tagname</code>, where <code>tagname</code> is the name of the tag. You can then list all posts in that tag namespace. But pages don't off this same tag namespace, so you could actually use another key instead of <code>tags</code>. Nevertheless, I'm using the same <code>tags</code> name here.{{site.data.alerts.end}}
|
||||
{{site.data.alerts.note}} With posts, tags have a namespace that you can access with <code>posts.tags.tagname</code>, where <code>tagname</code> is the name of the tag. You can then list all posts in that tag namespace. But pages don't off this same tag namespace, so you could actually use another key instead of <code>tags</code>. Nevertheless, I'm using the same <code>tags</code> approach for posts as with pages.{{site.data.alerts.end}}
|
||||
|
||||
|
||||
To prevent tags from getting out of control and inconsistent, first make sure the tag appears in the \date/tags_doc.yml file. If it's not there, the tag you add to a page won't be read. I added this check just to make sure I'm using the same tags consistently and not adding new tags that don't have tag archive pages.
|
||||
To prevent tags from getting out of control and inconsistent, first make sure the tag appears in the \_data/tags.yml file. If it's not there, the tag you add to a page won't be read. I added this check just to make sure I'm using the same tags consistently and not adding new tags that don't have tag archive pages.
|
||||
|
||||
|
||||
{{site.data.alerts.note}} Unlike with WordPress, you have to build out the functionality for tags so that clicking a tag name shows you all pages with that tag. Tags in Jekyll are much more manual.{{site.data.alerts.end}}
|
||||
{{site.data.alerts.note}} In contrast to WordPress, with Jekyll to get tags on pages you have to build out the functionality for tags so that clicking a tag name shows you all pages with that tag. Tags in Jekyll are much more manual.{{site.data.alerts.end}}
|
||||
|
||||
|
||||
Additionally, you must create a tag archive page similar to the other pages named tag_{tagname}.html folder. This theme doesn't auto-create tag archive pages.
|
||||
@ -38,67 +40,61 @@ For simplicity, make all your tags single words (connect them with hyphens if ne
|
||||
|
||||
Tags have a few components.
|
||||
|
||||
1. First make sure you configure a few details in the conditions.html file. In particular, see this setting:
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% assign projectTags = site.data.tags_doc.allowed-tags %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The tags_doc name must correspond with how you label your tags file. Here, "doc" should be your project name.
|
||||
|
||||
2. In the \_data file, add a yml file similar to tags_doc.yml. The YML file lists the tags that are allowed:
|
||||
|
||||
```json
|
||||
allowed-tags:
|
||||
- getting_started
|
||||
- overview
|
||||
- formatting
|
||||
- publishing
|
||||
- single_sourcing
|
||||
- special_layouts
|
||||
- content types
|
||||
```
|
||||
|
||||
3. Create a tag archive file for each tag in your tags_doc.yml list. Name the file like this: tag_getting_started.html, where doc is your project name. (Again, tags with multiple words need hyphens in them.)
|
||||
|
||||
Each tag archive file needs only this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
title: "Getting Started Pages"
|
||||
tagName: getting_started
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
```
|
||||
1. In the \_data/tags.yml file, add the tag names you want to allow. For example:
|
||||
|
||||
```json
|
||||
allowed-tags:
|
||||
- getting_started
|
||||
- overview
|
||||
- formatting
|
||||
- publishing
|
||||
- single_sourcing
|
||||
- special_layouts
|
||||
- content types
|
||||
```
|
||||
|
||||
3. Create a tag archive file for each tag in your tags_doc.yml list. Name the file following the same pattern in the tags folder, like this: tag_collaboration.html.
|
||||
|
||||
Each tag archive file needs only this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
---
|
||||
title: "Collaboration pages"
|
||||
tagName: collaboration
|
||||
search: exclude
|
||||
permalink: /tag_collaboration/
|
||||
sidebar: tags_sidebar
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{{site.data.alerts.note}}In the \_includes/mydoc folder, there's a taglogic.html file. This file (included in each tag archive file) has common logic for getting the tags and listing out the pages containing the tag in a table with summaries or truncated excerpts. You don't have to do anything with the file — just leave it there because the tag archive pages reference it.{{site.data.alerts.end}}
|
||||
{{site.data.alerts.note}}In the \_includes/mydoc folder, there's a taglogic.html file. This file (included in each tag archive file) has common logic for getting the tags and listing out the pages containing the tag in a table with summaries or truncated excerpts. You don't have to do anything with the file — just leave it there because the tag archive pages reference it.{{site.data.alerts.end}}
|
||||
|
||||
4. Change the title, tagName, and permalink values to be specific to the tag name you just created.
|
||||
|
||||
By default, the \_layouts/page.html file will look for any tags on a page and insert them at the bottom of the page using this code:
|
||||
|
||||
5. Adjust button color or tag placement as desired.
|
||||
|
||||
By default, the \_layouts/page.html file will look for any tags on a page and insert them at the bottom of the page using this code:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
<div class="tags">
|
||||
{% raw %}
|
||||
```
|
||||
<div class="tags">
|
||||
{% if page.tags != null %}
|
||||
<b>Tags: </b>
|
||||
{% include custom/conditions.html %}
|
||||
{% assign projectTags = site.data.tags.allowed-tags %}
|
||||
{% for tag in page.tags %}
|
||||
{% if projectTags contains tag %}
|
||||
<a href="tag_{{tag}}.html" class="btn btn-info navbar-btn cursorNorm" role="button">{{page.tagName}}{{tag}}</a>
|
||||
<a href="{{ "/tag_" | prepend: site.baseurl | append: tag }}" class="btn btn-default navbar-btn cursorNorm" role="button">{{page.tagName}}{{tag}}</a>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</div>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Because this code appears on the \_layouts/page.html file by default, you don't need to do anything. However, if you want to alter the placement or change the button color, you can do so.
|
||||
|
||||
You can change the button color by changing the class on the button from `btn-info` to one of the other button classes bootstrap provides. See {{site.data.mydoc.mydoc_urls.mydoc_labels.link}} for more options on button class names.
|
||||
</div>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Because this code appears on the \_layouts/page.html file by default, you don't need to do anything in your page to get the tags to appear. However, if you want to alter the placement or change the button color, you can do so within the \_includes/taglogic.html file.
|
||||
|
||||
You can change the button color by changing the class on the button from `btn-info` to one of the other button classes bootstrap provides. See <a href="{{ "/mydoc_labels" | prepend: site.baseurl }}">page</a> for more options on button class names.
|
||||
|
||||
## Retrieving pages for a specific tag
|
||||
|
||||
@ -186,5 +182,5 @@ If you don't want tags to appear at all on your page, remove the tags property f
|
||||
|
||||
Since you may have many tags and find it difficult to remember what tags are allowed, I recommend creating a template that prepopulates all your frontmatter with all possible tags. Then just remove the tags that don't apply.
|
||||
|
||||
See {{site.data.mydoc.mydoc_urls.mydoc_webstorm_text_editor.link}} for tips on creating file templates in WebStorm.
|
||||
See <a href="{{ "/mydoc_webstorm_text_editor" | prepend: site.baseurl }}">WebStorm Text Editor</a> for tips on creating file templates in WebStorm.
|
||||
|
||||
|
||||
@ -2,15 +2,21 @@
|
||||
title: Themes
|
||||
tags: [publishing]
|
||||
keywords: themes, styles, colors, css
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can choose between two different themes (one green, the other blue) for your projects. The theme CSS is stored in the CSS folder and configured in the configuration file for each project."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_themes/
|
||||
---
|
||||
|
||||
|
||||
## Theme options
|
||||
You can choose a green or blue theme, or you can create your own. In the css folder, there are two theme files: theme-blue.css and theme-green.css. These files have the most common CSS elements extracted in their own CSS file. Just change the hex colors to the ones you want.
|
||||
|
||||
In the configuration file, specify the theme file you want the output to use — for example, `theme_file: theme-green.css`.
|
||||
In the \_includes/head.html file, specify the theme file you want the output to use — for example, `theme_file: theme-green.css`. See this line:
|
||||
|
||||
```html
|
||||
<link rel="stylesheet" href="{{ "/css/theme-green.css" | prepend: site.baseurl }}">
|
||||
```
|
||||
|
||||
## Theme differences
|
||||
The differences between the themes is fairly minimal. The main navigation bar, sidebar, buttons, and heading colors change color. That's about it.
|
||||
|
||||
@ -2,11 +2,19 @@
|
||||
title: Check page title consistency
|
||||
tags: [navigation]
|
||||
keywords: "validation, titles, page titles, inconsistency, errors"
|
||||
last_updated: "November 30, 2015"
|
||||
last_updated: "November 30, 2016"
|
||||
summary: "The title checker page helps ensure that the titles in your pages match the titles in your TOC."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_title_checker/
|
||||
---
|
||||
|
||||
To make sure your page titles match the sidebar titles, there's a file called "title-checker.html." After your site builds, view this file in your browser. It will tell if you any of your page titles don't match up with your sidebar titles.
|
||||
The theme has a file called title-checker.html. This file will iterate through all the pages listed in the sidebar navigation and top navigation, and compare the navigation titles against the page titles based on matching URLs. If there are inconsistencies in the titles, they get noted on the title-checker.html page.
|
||||
|
||||
This utility isn't 100% comprehensive, though. If your sidebar has a URL that doesn't match any file name in your project, it won't be able to handle that URL. Therefore, when you do validity checks for the links on your site, click through each item in the sidebar to make sure the page loads.
|
||||
To run the link checker, just build or serve your project, and go to /title-checker in your browser (such as Chrome). If there are inconsistencies, they will be noted on the page.
|
||||
|
||||
Note that in order for the title-checker file to run correctly, it has to detect a match between the URL listed in the sidebar or top navigation with the URL for the page (based on the file name). If you have the wrong URL, it won’t tell you if the page titles match. Therefore you should always click through all the topics in your navigation to make sure the URLs are accurate.
|
||||
|
||||
{{site.data.alerts.note}} If your page titles have your product name in parentheses, but your sidebar doesn't have the product name in parentheses, this title-checker tool is going to return a lot of mismatches. This is one limitation of the code right now. {{site.data.alerts.end}}
|
||||
|
||||
Note also that you must manually configure your sidebar file in the first line of the code, and then repeat the same chunk of code for each sidebar. Right now the code doesn't automatically iterate over every sidebar file. It's somewhat of a manual configuration process there.
|
||||
|
||||
|
||||
@ -1,49 +0,0 @@
|
||||
---
|
||||
title: 7. Configure the top navigation
|
||||
tags:
|
||||
- navigation
|
||||
keywords: "bootstrap, lists, drop-down, drop down navigation, top nav bar, topnav"
|
||||
last_updated: "November 30, 2015"
|
||||
summary: "The top navigation provides either single links or a drop-down menu. There are some other features, such as a feedback email, custom menu, and popout link."
|
||||
series: "Getting Started"
|
||||
weight: 7
|
||||
---
|
||||
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
|
||||
## Changing the top navigation
|
||||
|
||||
The top navigation reads from the \_data/mydoc/mydoc_topnav_doc.yml file. There are two *separate* sections in the mydoc_topnav_doc.yml file:
|
||||
|
||||
* `topnav`
|
||||
* `topnav_dropdowns`
|
||||
|
||||
Items in the `topnav` section are rendered as single links. In contrast, items in the `topnav_dropdowns` section are rendered as a drop-down menu. You can't mix up the order of single links and drop-down links. The single links appear on the left, and the drop-down menus appear on the right.
|
||||
|
||||
## The Feedback email
|
||||
|
||||
If you click the Feedback link in the default theme, you'll see that it inserts the link to the current page along with a subject header and body. The topnav.html file contains an include to feedback.html. The feedback.html file contains the JavaScript that gets the current page URL and inserts it into the message body.
|
||||
|
||||
You configure the email in the configuration file through this property: `site.feedback_email`.
|
||||
|
||||
## External links
|
||||
|
||||
If you want the URL to point to an external site, use `external_url` instead of `url` in the data file. Then just enter the full HTTP URL. When you use `external_url`, the sidebar.html will apply this logic:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
{% if item.external_url %}
|
||||
<li><a href="{{item.external_url}}" target="_blank">{{subcategory.title}}</a></li>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## No links in topnav get included in the PDF
|
||||
|
||||
The way the PDF file is currently set up, only the links in the sidebar get included in the PDF. None of the links in the top nav get included in the PDF.
|
||||
|
||||
It wouldn't be hard to iterate through the top navigation bar and included the content in the PDF as well, but I think it's a best practice to put content links in the sidebar, and to put external links/resources in the top navigation.
|
||||
|
||||
If people open the site in a small browser, the top navigation will compress to a "hamburger." There's not a ton of room for adding links in this space.
|
||||
|
||||
Also note that the drop-down menus have one level only.
|
||||
|
||||
@ -3,11 +3,13 @@ title: Top navigation
|
||||
tags:
|
||||
- navigation
|
||||
keywords: "custom menu, custom_menu, pop-out, frameescape, frame escape, top nav bar, topnav"
|
||||
last_updated: "November 30, 2015"
|
||||
last_updated: "November 30, 2016"
|
||||
summary: "The top navigation provides some additional features involving a custom menu and pop-out link that you can customize."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_top_navigation_deep_dive/
|
||||
---
|
||||
|
||||
{{site.data.alerts.note}} For basic information about configuring the top navigation, see {{site.data.mydoc.mydoc_urls.mydoc_top_navigation.link}}. This section gets into the top navigation in more depth. {{site.data.alerts.end}}
|
||||
{{site.data.alerts.note}} For basic information about configuring the top navigation, see {{site.data.mydoc_urls.mydoc_top_navigation.link}}. This section gets into the top navigation in more depth. {{site.data.alerts.end}}
|
||||
## Custom Menu
|
||||
|
||||
It's common to publish multiple sites. If you want to link the multiple together, you could simply list links to the other doc sites in a drop-down menu configured in the topnav_dropdowns section in the topnav_doc.yml file. However, suppose you want to do something more fancy.
|
||||
|
||||
@ -2,8 +2,10 @@
|
||||
title: Troubleshooting
|
||||
tags: [getting_started]
|
||||
keywords: trouble, problems, support, error messages, problems, failure, error, #fail
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "This page lists common errors and the steps needed to troubleshoot them."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_troubleshooting/
|
||||
---
|
||||
|
||||
|
||||
@ -72,7 +74,7 @@ The config file requires pygments for the highlighter. You must [download and in
|
||||
|
||||
If you build your site but the sidebar doesn't appear, check the following:
|
||||
|
||||
Look in \_includes/custom/conditions.html and make sure the conditional values there match up with the values declared in the configuration file. Specifically, you need to make sure you've declared a value for project, product, platform, and version.
|
||||
Look in \_includes/custom/sidebarconfigs.html and make sure the conditional values there match up with the values declared in the configuration file. Specifically, you need to make sure you've declared a value for project, product, platform, and version.
|
||||
|
||||
If you don't have any values for these properties, you still need to keep them in your configuration file. Just put something like `all` as the value.
|
||||
|
||||
|
||||
@ -1,36 +0,0 @@
|
||||
---
|
||||
title: 8. Customize the URL generator
|
||||
tags:
|
||||
- navigation
|
||||
keywords: "URL generator, link generator, links, hyperlinks"
|
||||
last_updated: "November 30, 2015"
|
||||
summary: "You need to customize the URL generator with your project's name. This generator helps you make quick links within your content."
|
||||
series: "Getting Started"
|
||||
weight: 8
|
||||
---
|
||||
|
||||
{% include custom/mydoc/getting_started_series.html %}
|
||||
|
||||
## About the URL generator
|
||||
|
||||
The URL generator is a special file that helps you generate the code you need for links. This generator helps you avoid broken links, and ensures more consistency.
|
||||
|
||||
To learn more about the linking strategy used with this theme, see {{site.data.mydoc.mydoc_urls.mydoc_hyperlinks.link}}. The step here simply explains how to customize the URL generator for a new project.
|
||||
|
||||
## Customize the URL generator
|
||||
|
||||
1. In the project root directory, open urls_acme.txt (a file you should have already duplicated from urls_mydoc.txt) in an earlier step.
|
||||
2. Do a find a replace for "mydoc" with "acme".
|
||||
3. Change the project conditions at the top:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% if site.project == "mydoc_writers" or site.project == "mydoc_designers" %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Add all the projects here that will use this URL generator. For example, if you have 3 different projects, list them here. Otherwise the file's contents will be replaced with the values from the latest project that you run.
|
||||
|
||||
Notice that this URL generator iterates through the sidebar file only, and it doesn't apply the attribute qualifiers as with the sidebar.html file. As such, this URL generator will work with the output from any of the project files.
|
||||
|
||||
{% include custom/mydoc/getting_started_series_next.html %}
|
||||
@ -1,46 +0,0 @@
|
||||
---
|
||||
title: Video embeds
|
||||
tags: [formatting]
|
||||
keywords: videos, youtube, vimeo, video js, video wrapper, mp4, stream
|
||||
last_updated: November 30, 2015
|
||||
summary: "You can embed files with a Video JS wrapper by adding 'video: true' in the frontmatter. Alternatively, you can just fall back on the default video wrapper in the browser."
|
||||
video: true
|
||||
---
|
||||
|
||||
|
||||
## About Video JS
|
||||
The theme has the [video.js](http://www.videojs.com/) player integrated. But the scripts only appear on a page or post if you have certain frontmatter in that page or post. If you want to embed a video in a page and use the Video JS player, add `video: true` in your frontmatter of a page or post, and then add code like this where you want the video to appear:
|
||||
|
||||
```html
|
||||
<p><video id="scenario-1" class="video-js vjs-default-skin vjs-big-play-centered" controls
|
||||
preload="auto" width="640" height="480" data-setup='{}'>
|
||||
<source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type='video/mp4'>
|
||||
</video></p>
|
||||
```
|
||||
|
||||
Here's an example:
|
||||
|
||||
<p><video id="scenario-1" class="video-js vjs-default-skin vjs-big-play-centered" controls
|
||||
preload="auto" width="640" height="480" data-setup='{}'>
|
||||
<source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type='video/mp4'>
|
||||
</video></p>
|
||||
|
||||
If you want the player button in the upper-left corner (which is the default), remove the `vjs-big-play-centered` from the video class.
|
||||
|
||||
<p><video id="scenario-1" class="video-js vjs-default-skin" controls
|
||||
preload="auto" width="640" height="480" data-setup='{}'>
|
||||
<source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type='video/mp4'>
|
||||
</video></p>
|
||||
|
||||
Here are [more details on this video player from Video JS](https://github.com/videojs/video.js/blob/stable/docs/guides/setup.md).
|
||||
|
||||
Note that if some of the js doesn't load correctly, the default fallback player is the regular HTML5 video player available via the browser. Here's an example of the built-in browser video wrapper:
|
||||
|
||||
<p><video width="640" controls>
|
||||
<source src="http://idratherbetellingstories.com/podcasts/ontariochapterpresentation/ontariochapterv4.mp4" type="video/mp4">
|
||||
Your browser does not support the video tag.
|
||||
</video></p>
|
||||
|
||||
However, I don't think the built-in browser video players work very well (you can't easily scrub around the video without seeing lots of buffering and other issues). But definitely compare the two. You may find that adding the Video JS wrapper is overkill.
|
||||
|
||||
{{site.data.alerts.warning}}Github wasn't designed to store video content. If you have an mp3 file, don't store it in your Github directory. Instead, put it on a web host using regular FTP methods, or stream the video from a video streaming service such as Youtube or Vimeo. Also, note that Github's Large File Storage (which does handle large files) isn't compatible with Github Pages.{{site.data.alerts.end}}
|
||||
@ -1,9 +1,10 @@
|
||||
---
|
||||
title: WebStorm Text Editor
|
||||
keywords: webstorm, sublime, markdown, atom, gnome, notepad ++, textpad, bbedit
|
||||
tags: [getting_started]
|
||||
last_updated: November 30, 2015
|
||||
last_updated: March 20, 2016
|
||||
summary: "You can use a variety of text editors when working with a Jekyll project. WebStorm from IntelliJ offers a lot of project-specific features, such as find and replace, that make it ideal for working with tech comm projects."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_webstorm_text_editor/
|
||||
---
|
||||
|
||||
## About text editors and WebStorm
|
||||
@ -17,14 +18,19 @@ By default, WebStorm comes packaged with a lot more functionality than you proba
|
||||
|
||||
## Add the Markdown Support plugin
|
||||
|
||||
Since you'll be writing in Markdown, having color coding and other support for Markdown is key. Install the Markdown Support plugin by going to **WebStorm > Preferences > Plugins** and clicking **Install JetBrains Plugin**. Search for **Markdown Support**.
|
||||
|
||||
Since you'll be writing in Markdown, having color coding and other support for Markdown is important. Install the Markdown Support plugin by going to **WebStorm > Preferences > Plugins** and clicking **Install JetBrains Plugin**. Search for **Markdown Support**. (I would avoid the Multimarkdown plugin — it seemed to make all my dashes in frontmatter tags extend half way across the page.)
|
||||
|
||||
## Enable Soft Wraps (word wrapping)
|
||||
|
||||
Most likely you'll want to enable soft wraps, which wraps lines rather than extending them out forever and requiring you to scroll horizontally to see the text. To enable softwrapping, go to **WebStorm > Preferences > Editor > General** and see the Soft Wraps section. Select the **Use soft wraps in editor** check box.
|
||||
|
||||
## Learn a few key commands
|
||||
## Exclude a directory
|
||||
|
||||
When you're searching for content, you don't want to edit any file that appears in the \_site directory. You can exclude a directory from Webstorm by right-clicking the directory and choosing **Mark Directory As** and then selecting **Excluded**.
|
||||
|
||||
## Shortcuts
|
||||
|
||||
It can help to learn a few key shortcuts:
|
||||
|
||||
|Command | Shortcuts |
|
||||
|-------|--------|
|
||||
@ -42,6 +48,10 @@ Most likely you'll want to enable soft wraps, which wraps lines rather than exte
|
||||
|
||||
{{site.data.alerts.tip}} If these shortcut keys aren't working for you, make sure you have the "Max OS X 10.5+" keymap selected. Go to <b>WebStorm > Preferences > Keymap</b> and select it there. {{site.data.alerts.end}}
|
||||
|
||||
## Finding files
|
||||
|
||||
When I want to find a file, I browse to the file in the preview site and copy the page name in the URL. Then in Webstorm I press **Shift** twice and paste in the file name. The search feature automatically highlights the file I want, and I press **Enter**.
|
||||
|
||||
## Identifying changed files
|
||||
|
||||
When you have the Git and Github integration, changed files appear in blue. This lets you know what needs to be committed to your repository.
|
||||
@ -52,12 +62,12 @@ Rather than insert the frontmatter by hand each time, it's much faster to simply
|
||||
|
||||
1. Right-click a file in the list of project files, and select **New > Edit File Templates**.
|
||||
|
||||
If you don't see the Edit File Templates option, you may need to create a file template first. Go to **File > Default Settings > Editor > File and Code Templates**. Create a new file template with an md extension, and then close and restart WebStorm. Then repeat this step and you will see the File Templates option appear in the right context menu.
|
||||
If you don't see the Edit File Templates option, you may need to create a file template first. Go to **File > Default Settings > Editor > File and Code Templates**. Create a new file template with an md extension, and then close and restart WebStorm. Then repeat this step and you will see the File Templates option appear in the right context menu.
|
||||
|
||||
2. In the upper-left corner of the dialog box that appears, click the **+** button to create a new template.
|
||||
3. Name it something like Jekyll page. Insert the frontmatter you want, and save it.
|
||||
|
||||
To use the Jekyll template, when you create a new file in your WebStorm project, you can select your Jekyll file template.
|
||||
To use the Jekyll template, when you create a new file in your WebStorm project, you can select your Jekyll file template.
|
||||
|
||||
## Disable pair quotes
|
||||
|
||||
|
||||
@ -3,6 +3,8 @@ title: YAML tutorial in the context of Jekyll
|
||||
tags: [formatting]
|
||||
keywords: search
|
||||
summary: "YAML is a format that relies on white spacing to separate out the various elements of content. Jekyll lets you use Liquid with YAML as a way to parse through the data. Storing items for your table of contents is one of the most common uses of YAML with Jekyll."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: /mydoc_yaml_tutorial/
|
||||
---
|
||||
## Overview
|
||||
One of the most interesting features of Jekyll is the ability to separate out data elements from formatting elements using a combination of YAML and Liquid. This setup is most common when you're trying to create a table of contents.
|
||||
@ -50,19 +52,19 @@ name:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
Husband's name: {{site.data.mydoc.samplelist.name.husband}}
|
||||
Husband's name: {{site.data.samplelist.name.husband}}
|
||||
|
||||
Wife's name: {{site.data.mydoc.samplelist.name.wife}}
|
||||
Wife's name: {{site.data.samplelist.name.wife}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Notice that in order to access the data file, you use `site.data.mydoc.samplelist`. `mydoc` is the folder, and `samplelist` is the name of the YAML file.
|
||||
Notice that in order to access the data file, you use `site.data.samplelist`. `mydoc` is the folder, and `samplelist` is the name of the YAML file.
|
||||
|
||||
**Result:**
|
||||
|
||||
Husband's name: {{site.data.mydoc.samplelist.name.husband}}
|
||||
Husband's name: {{site.data.samplelist.name.husband}}
|
||||
|
||||
Wife's name: {{site.data.mydoc.samplelist.name.wife}}
|
||||
Wife's name: {{site.data.samplelist.name.wife}}
|
||||
|
||||
## Example 2: Line breaks
|
||||
|
||||
@ -86,19 +88,19 @@ block: |
|
||||
|
||||
```liquid
|
||||
**Feedback**
|
||||
{{site.data.mydoc.samplelist.feedback}}
|
||||
{{site.data.samplelist.feedback}}
|
||||
|
||||
**Block**
|
||||
{{site.data.mydoc.samplelist.block}}
|
||||
{{site.data.samplelist.block}}
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
**Feedback**
|
||||
{{site.data.mydoc.samplelist.feedback}}
|
||||
{{site.data.samplelist.feedback}}
|
||||
|
||||
**Block**
|
||||
{{site.data.mydoc.samplelist.block}}
|
||||
{{site.data.samplelist.block}}
|
||||
|
||||
The right angle bracket `>` allows you to put the value on the next lines (which must be indented). Even if you create a line break, the output will remove all of those line breaks, creating one paragraph.
|
||||
|
||||
@ -119,7 +121,7 @@ bikes:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% for item in site.data.mydoc.samplelist.bikes %}
|
||||
{% for item in site.data.samplelist.bikes %}
|
||||
* {{item.title}}
|
||||
{% endfor %}
|
||||
```
|
||||
@ -127,7 +129,7 @@ bikes:
|
||||
|
||||
**Result:**
|
||||
|
||||
{% for item in site.data.mydoc.samplelist.bikes %}
|
||||
{% for item in site.data.samplelist.bikes %}
|
||||
* {{item.title}}
|
||||
{% endfor %}
|
||||
|
||||
@ -150,7 +152,7 @@ salesteams:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% for item in site.data.mydoc.samplelist.salesteams %}
|
||||
{% for item in site.data.samplelist.salesteams %}
|
||||
<h3>{{item.title}}</h3>
|
||||
<ul>
|
||||
{% for entry in item.subitems %}
|
||||
@ -162,7 +164,7 @@ salesteams:
|
||||
{% endraw %}
|
||||
|
||||
**Result:**
|
||||
{% for item in site.data.mydoc.samplelist.salesteams %}
|
||||
{% for item in site.data.samplelist.salesteams %}
|
||||
<h3>{{item.title}}</h3>
|
||||
<ul>
|
||||
{% for entry in item.subitems %}
|
||||
@ -202,7 +204,7 @@ toc:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% for item in site.data.mydoc.samplelist.toc %}
|
||||
{% for item in site.data.samplelist.toc %}
|
||||
<h3>{{item.title}}</h3>
|
||||
<ul>
|
||||
{% for entry in item.subitems %}
|
||||
@ -215,7 +217,7 @@ toc:
|
||||
|
||||
**Result:**
|
||||
|
||||
{% for item in site.data.mydoc.samplelist.toc %}
|
||||
{% for item in site.data.samplelist.toc %}
|
||||
<h3>{{item.title}}</h3>
|
||||
<ul>
|
||||
{% for entry in item.subitems %}
|
||||
@ -239,13 +241,13 @@ myref: *hello
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ site.data.mydoc.samplelist.myref }}
|
||||
{{ site.data.samplelist.myref }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result:**
|
||||
|
||||
{{ site.data.mydoc.samplelist.myref }}
|
||||
{{ site.data.samplelist.myref }}
|
||||
|
||||
This example is notably different. Here I'm showing how to reuse content in YAML file. If you have the same value that you want to repeat in other mappings, you can create a variable using the `&` symbol. Then when you want to refer to that variable's value, you use an asterisk `*` followed by the name of the variable.
|
||||
|
||||
@ -269,13 +271,13 @@ about:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{{ site.data.mydoc.samplelist.about[0] }}
|
||||
{{ site.data.samplelist.about[0] }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result:**
|
||||
|
||||
{{ site.data.mydoc.samplelist.about[0] }}
|
||||
{{ site.data.samplelist.about[0] }}
|
||||
|
||||
You can see that I'm accessing one of the items in the list using `[0]`. This refers to the position in the array where a list item is. Like most programming languages, you start counting at zero, not one.
|
||||
|
||||
@ -301,13 +303,13 @@ numbercolors:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{{ site.data.mydoc.samplelist.numbercolors[0].properties }}
|
||||
{{ site.data.samplelist.numbercolors[0].properties }}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
**Result:**
|
||||
|
||||
{{ site.data.mydoc.samplelist.numbercolors[0].properties }}
|
||||
{{ site.data.samplelist.numbercolors[0].properties }}
|
||||
|
||||
This example is similar as before; however, in this case were getting a specific property from the list item in the zero position.
|
||||
|
||||
@ -343,7 +345,7 @@ mypages:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% for sec in site.data.mydoc.samplelist.mypages %}
|
||||
{% for sec in site.data.samplelist.mypages %}
|
||||
{% if sec.audience == "writers" %}
|
||||
* {{sec.url}}
|
||||
{% endif %}
|
||||
@ -353,7 +355,7 @@ mypages:
|
||||
|
||||
**Result:**
|
||||
|
||||
{% for sec in site.data.mydoc.samplelist.mypages %}
|
||||
{% for sec in site.data.samplelist.mypages %}
|
||||
{% if sec.audience == "writers" %}
|
||||
* {{sec.url}}
|
||||
{% endif %}
|
||||
@ -365,7 +367,7 @@ Now let's adjust the condition just a little. Let's add a second condition so th
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% for sec in site.data.mydoc.samplelist.mypages %}
|
||||
{% for sec in site.data.samplelist.mypages %}
|
||||
{% if sec.audience == "writers" and sec.product == "gizmo" %}
|
||||
* {{sec.url}}
|
||||
{% endif %}
|
||||
@ -375,7 +377,7 @@ Now let's adjust the condition just a little. Let's add a second condition so th
|
||||
|
||||
And here is the result:
|
||||
|
||||
{% for sec in site.data.mydoc.samplelist.mypages %}
|
||||
{% for sec in site.data.samplelist.mypages %}
|
||||
{% if sec.audience == "writers" and sec.product == "gizmo" %}
|
||||
* {{sec.url}}
|
||||
{% endif %}
|
||||
|
||||
@ -1,7 +0,0 @@
|
||||
---
|
||||
title: Search
|
||||
layout: page_search
|
||||
search: exclude
|
||||
---
|
||||
|
||||
John course to third gallery of
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Collaboration pages"
|
||||
tagName: collaboration
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Content types pages"
|
||||
tagName: content-types
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Formatting pages"
|
||||
tagName: formatting
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Getting started pages"
|
||||
tagName: getting_started
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Mobile Pages"
|
||||
search: exclude
|
||||
tagName: mobile
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Navigation pages"
|
||||
tagName: navigation
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Publishing pages"
|
||||
tagName: publishing
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "single_sourcing pages"
|
||||
tagName: single_sourcing
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +0,0 @@
|
||||
---
|
||||
title: "Special layout pages"
|
||||
tagName: special_layouts
|
||||
search: exclude
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
Reference in New Issue
Block a user