version 3.0 of the theme -- complete overhaul
This commit is contained in:
Tom Johnson
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: About
|
||||
permalink: /about/
|
||||
tags: []
|
||||
keywords:
|
||||
audience: writer, designer
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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 in a pilot with some technical documentation projects. The theme is evolving, but it's stable enough for release.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Collections
|
||||
permalink: /collections/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## 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/).
|
||||
|
||||
## Create a collection
|
||||
To create a collection, add the following in your configuration file:
|
||||
|
||||
```
|
||||
collections:
|
||||
tooltips:
|
||||
output: true
|
||||
```
|
||||
|
||||
In this example, tooltips is the name of the collection.
|
||||
|
||||
## Interacting with collections
|
||||
|
||||
You can interact with collections by using the `site.<collection_namespace>` path. In this case, if I wanted to loop through all tooltips, I would use `site.tooltips` instead of `site.pages` or `site.posts`.
|
||||
|
||||
See [Collections in the Jekyll documentation](http://jekyllrb.com/docs/collections/) for more information.
|
||||
@@ -1,124 +0,0 @@
|
||||
---
|
||||
title: Pages
|
||||
permalink: /pages/
|
||||
audience: writer, designer
|
||||
tags: [getting-started, formatting]
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Where to author content
|
||||
Use a text editor such as Sublime Text, WebStorm, or Atom to create pages.
|
||||
|
||||
My preference is 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.
|
||||
|
||||
## Frontmatter
|
||||
Make sure each page has frontmatter at the top like this:
|
||||
|
||||
```
|
||||
---
|
||||
title:
|
||||
permalink: //
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
```
|
||||
Frontmatter is always formatted with three hyphens at the top and bottom. Your frontmatter must have a `title` and `permalink` value. All the other values are optional.
|
||||
|
||||
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 |
|
||||
| **permalink** | Required | The URL path 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.yml to be allowed entrance into the page. |
|
||||
| **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 is helpful for readers trying to evaluate how current and authoritative information is. |
|
||||
| **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.) |
|
||||
| **metadata** | Optional | Boolean (`true` or `false`). If you add `metadata: false` to the frontmatter, then the page metadata sidebar won't appear for the page. You might want to hide the sidebar for special pages such as glossaries, knowledge-base layouts, or more.
|
||||
| **datatable** | Optional | Boolean. If you add `true`, then scripts for the [jQuery datatables plugin](https://www.datatables.net/) appear for the page. |
|
||||
| **video** | Optional | If you add `true`, then scripts for [Video JS: The HTML5 video player](http://www.videojs.com/) appear on the page. |
|
||||
|
||||
{{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 — they degrade gracefully. {{end}}
|
||||
|
||||
Only the title and permalink are actually required. If you leave the other fields blank, the theme will not show them (for example, if you leave tags blank, the theme won't show "Tags:" with nothing after it in the page metadata. Instead, the whole line will be hidden.
|
||||
|
||||
To see how these metadata values get inserted into the theme, look at the page layout, specifically the \_includes/pagemetadata.html file.
|
||||
|
||||
## Creating a Jekyll template in WebStorm
|
||||
|
||||
Rather than insert the frontmatter by hand each time, it's much faster to simply create a Jekyll template in WebStorm (my favorite editor for Jekyll projects).
|
||||
|
||||
To create a Jekyll template:
|
||||
|
||||
1. Right-click a file in the list of project files, and select **New > Edit File Templates**.
|
||||
2. In the upper-left corner of the dialog box that appears, click the **+** button to create a new template.
|
||||
3. Name it Jekyll. 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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
## Where to save pages
|
||||
|
||||
Store all your pages inside the pages folder. The number of subfolders inside your pages directory doesn't matter. You won't have to use paths (such as ../) when linking to pages. Instead, all the pages will be pulled out to the root directory (each page rendered into its own folder), and links are established through the permalink value in the page's frontmatter.
|
||||
|
||||
If you want to use a colon in your page title, you must enclose the title's value in quotation marks.
|
||||
|
||||
## Github-flavored Markdown
|
||||
|
||||
You can use standard Multimarkdown syntax for tables. You can also use fenced code blocks. The configuration file shows the Markdown processor and extensiosn:
|
||||
|
||||
```
|
||||
markdown: redcarpet
|
||||
|
||||
redcarpet:
|
||||
extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "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 |
|
||||
| autolink | automatically create links out of URLs |
|
||||
| tables | allow table syntax |
|
||||
| with_toc_data | add ID tags to headings automatically |
|
||||
|
||||
{{note}} {% include custom/toc_id_note.html %} {{end}}
|
||||
|
||||
## Related posts
|
||||
|
||||
By default, posts contain related posts beneath them. To disable this, add `related_pages: none` or `related_posts: none` in the frontmatter of the page.
|
||||
|
||||
Pages have tags instead of related posts. (It turns out that creating "Related pages" in Jekyll is much more difficult than related posts.)
|
||||
|
||||
## 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 and layouts/posts.html files.
|
||||
|
||||
If you don't want the TOC to appear for a specific page, add `toc: false` in the frontmatter of the page.
|
||||
|
||||
This frontmatter 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 to get it to appear in the mini-TOC.
|
||||
|
||||
## Specify a particular page layout
|
||||
|
||||
The configuration file sets the default layout for pages as the page layout. You can create other layouts inside the layouts folder. You can then specify that the page use that particular layout by adding `layout: mylayout.html` in the page's frontmatter. Whatever layout you specify in the frontmatter of a page will override the layout default set in the configuration file.
|
||||
|
||||
## 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.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: Posts
|
||||
permalink: /posts/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary: "Posts are designed for blog-like entries. This theme hasn't been designed with much functionality around posts. It's assumed you're using pages for everything."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
Most of the theme is designed for using pages, but you can also use posts. Posts are intended for blog entries. They have dates in the filenames, and they sort chronologically when get the posts. Create posts inside the _posts folder.
|
||||
|
||||
The latest_posts.html file shows the latest posts. The tagindex.html file sorts posts by tags. The archive.html sorts posts by date.
|
||||
|
||||
{{note}} I haven't done much testing with posts, so you may run into some snags there. I'm planning to convert my blog (idratherbewriting.com) to Jekyll using this same theme, and when I do, I'll iron out all the issues with posts. {{end}}
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: Adding tooltips
|
||||
permalink: /adding_tooltips/
|
||||
tags: [formatting]
|
||||
keywords: popovers
|
||||
audience: writers, designers
|
||||
last_updated: May 13, 2015
|
||||
summary: "You can add tooltips to your content. These tooltips work well for glossary definitions."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
Because this theme is built on Bootstrap, you can simply use a specific attribute on an element to insert a tooltip.
|
||||
|
||||
Suppose you have a glossary.yml file inside your _data folder. You could pull in that glossary definition like this:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.</a>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
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>
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
title: Alerts
|
||||
permalink: /alerts/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
Alerts are little warnings, info, or other messages that you have called out in special formatting. In order to use these alerts or callouts, put this include at the top of your page, just below your frontmatter:
|
||||
|
||||
{%raw%}
|
||||
```liquid
|
||||
{% include linkrefs.html %}
|
||||
```
|
||||
{%endraw%}
|
||||
|
||||
Then insert any an alert or callout as described in the following sections.
|
||||
|
||||
|
||||
## Alerts
|
||||
|
||||
You can insert an alert by using any of the following code.
|
||||
|
||||
{%raw%}
|
||||
alert | code
|
||||
------|---------
|
||||
note | {{note}} your note {{end}}
|
||||
tip | {{tip}} your tip {{end}}
|
||||
warning | {{warning}} your warning {{end}}
|
||||
important | {{important}} your important info {{end}}
|
||||
{%endraw%}
|
||||
|
||||
The following demonstrate the formatting associated with each alert.
|
||||
|
||||
{{tip}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
|
||||
{{note}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
|
||||
{{important}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
|
||||
{{warning}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
|
||||
## Callouts
|
||||
|
||||
In contrast to the alerts, the callouts don't have a pre-coded bold-formatted preface such as note or tip. You just add one (if desired) in the callout text itself.
|
||||
|
||||
{%raw%}
|
||||
callout | code
|
||||
------|---------
|
||||
callout_default | {{callout_default}} your callout_default content {{end}}
|
||||
callout_primary | {{callout_primary}} your callout_primary content {{end}}
|
||||
callout_success | {{callout_success}} your callout_success content {{end}}
|
||||
callout_primary | {{callout_primary}} your callout_primary content {{end}}
|
||||
callout_warning | {{callout_warning}} your callout_warning content {{end}}
|
||||
callout_info | {{callout_info}} your callout_info content {{end}}
|
||||
|
||||
{%endraw%}
|
||||
|
||||
The following demonstrate the formatting for each callout.
|
||||
|
||||
{{callout_danger}}<b>callout_danger</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
|
||||
|
||||
{{callout_default}}
|
||||
<b>callout_default</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
|
||||
{{callout_primary}}
|
||||
<b>calloutprimary</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
|
||||
{{callout_success}}
|
||||
<b>calloutsuccess</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
|
||||
{{callout_info}}
|
||||
<b>calloutinfo</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
|
||||
{{callout_warning}}
|
||||
<b>calloutwarning</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
|
||||
|
||||
## Blast a warning to users
|
||||
|
||||
If you want to blast a warning to users on every page, add the alert or callout to the layouts/page.html page right below the frontmatter. Every page using the page layout (all, by defaut) will show this message.
|
||||
|
||||
@@ -1,182 +0,0 @@
|
||||
---
|
||||
title: Icons
|
||||
permalink: /icons/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
The theme has two font icon sets integrated: Font Awesome and Glyphicons Halflings. The latter is part of Bootstrap, while the former is independent.
|
||||
|
||||
## See Font Awesome icons available
|
||||
|
||||
Go to the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/)
|
||||
|
||||
The Font Awesome icons allow you to adjust their size by simply adding `fa-2x`, `fa-3x` and so forth as a class to the icon to adjust their size to two times or three times the original size. As vector icons, they scale crisply at any size.
|
||||
|
||||
Here's an example of how to scale up a camera icon:
|
||||
|
||||
```html
|
||||
<i class="fa fa-camera-retro"></i> normal size (1x)
|
||||
<i class="fa fa-camera-retro fa-lg"></i> fa-lg
|
||||
<i class="fa fa-camera-retro fa-2x"></i> fa-2x
|
||||
<i class="fa fa-camera-retro fa-3x"></i> fa-3x
|
||||
<i class="fa fa-camera-retro fa-4x"></i> fa-4x
|
||||
<i class="fa fa-camera-retro fa-5x"></i> fa-5x
|
||||
```
|
||||
|
||||
Here's what they render to:
|
||||
|
||||
<i class="fa fa-camera-retro"></i> 1x
|
||||
<i class="fa fa-camera-retro fa-lg"></i> fa-lg
|
||||
<i class="fa fa-camera-retro fa-2x"></i> fa-2x
|
||||
<i class="fa fa-camera-retro fa-3x"></i> fa-3x
|
||||
<i class="fa fa-camera-retro fa-4x"></i> fa-4x
|
||||
<i class="fa fa-camera-retro fa-5x"></i> fa-5x
|
||||
|
||||
With Font Awesome, you always use the `i` tag with the appropriate class. You also implement `fa` as a base class first. You can use font awesome icons inside other elements. Here I'm using a Font Awesome class inside a Bootstrap alert:
|
||||
|
||||
```html
|
||||
<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>This is a special warning message.
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle fa-lg"></i> This is a special warning message.</div>
|
||||
|
||||
Some of the Bootstrap styles are pre-coded with Font Awesome and stored in the linkrefs.html file in `capture` tags. That file includes the following:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
{% capture tip %}<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip: </b>{% endcapture %}
|
||||
{% capture note %}<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note: </b>{% endcapture %}
|
||||
{% capture important %}<div class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> <b>Important: </b>{% endcapture %}
|
||||
{% capture warning %}<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>{% endcapture %}
|
||||
{% capture end %}</div>{% endcapture %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This means you can insert a tip, note, warning, or important alert simply by using these tags:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{{note}} Add your note here. {{end}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Here's the result:
|
||||
|
||||
{{note}} Add your note here. {{end}}
|
||||
|
||||
You can innovate with your own combinations. Here's a similar approach with a check square:
|
||||
|
||||
```html
|
||||
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o fa-lg"></i> This is a special success message.</div>
|
||||
```
|
||||
|
||||
And the result:
|
||||
|
||||
<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o fa-lg"></i> This is a special success message.</div>
|
||||
|
||||
|
||||
Grab the right class name from the [Font Awesome library](http://fortawesome.github.io/Font-Awesome/icons/) and then implement it by following the pattern shown previously.
|
||||
|
||||
If you want to make your fonts even larger than the 5x style, add a custom style to your stylesheet like this:
|
||||
|
||||
```css
|
||||
.fa-10x{font-size:1700%;}
|
||||
```
|
||||
|
||||
Then any element with the attribute `fa-10x` will be enlarged 1700%.
|
||||
|
||||
## Glyphicon icons available
|
||||
|
||||
Glyphicons work similarly to Font Awesome. Go to the [Glyphicons library](http://getbootstrap.com/components/#glyphicons) to see the icons available.
|
||||
|
||||
Although the Glyphicon Halflings library doesn't provide the scalable classes like Font Awesome, there's a [StackOverflow trick](http://stackoverflow.com/questions/24960201/how-do-i-make-glyphicons-bigger-change-size) to make the icons behave in a similar way. This theme's stylesheet (customstyles.css) includes the following to the stylesheet:
|
||||
|
||||
```css
|
||||
.gi-2x{font-size: 2em;}
|
||||
.gi-3x{font-size: 3em;}
|
||||
.gi-4x{font-size: 4em;}
|
||||
.gi-5x{font-size: 5em;}
|
||||
```
|
||||
|
||||
Now you just add `gi-5x` or whatever to change the size of the font icon:
|
||||
|
||||
```html
|
||||
<span class="glyphicon glyphicon-globe gi-5x"></span>
|
||||
```
|
||||
|
||||
And here's the result:
|
||||
|
||||
<span class="glyphicon glyphicon-globe gi-5x"></span>
|
||||
|
||||
Glypicons use the `span` element instead of `i` to attach their classes.
|
||||
|
||||
Here's another example:
|
||||
|
||||
```html
|
||||
<span class="glyphicon glyphicon-download"></span>
|
||||
```
|
||||
|
||||
<span class="glyphicon glyphicon-download"></span>
|
||||
|
||||
And magnified:
|
||||
|
||||
```html
|
||||
<span class="glyphicon glyphicon-download gi-3x"></span>
|
||||
```
|
||||
|
||||
<span class="glyphicon glyphicon-download gi-3x"></span>
|
||||
|
||||
You can also put glyphicons inside other elements:
|
||||
|
||||
```html
|
||||
<div class="alert alert-danger" role="alert">
|
||||
<span class="glyphicon glyphicon-exclamation-sign" aria-hidden="true"></span>
|
||||
<b>Error:</b> Enter a valid email address
|
||||
</div>
|
||||
```
|
||||
|
||||
<div class="alert alert-danger" role="alert">
|
||||
<span class="glyphicon glyphicon-exclamation-sign" aria-hidden="true"></span>
|
||||
<b>Error:</b> Enter a valid email address
|
||||
</div>
|
||||
|
||||
## Callouts
|
||||
|
||||
The previously shown alerts might be fine for short messages, but with longer notes, the solid color takes up a bit of space. In this theme, you also have the option of using callouts, which are pretty common in Bootstrap's documentation but surprisingly not offered as an explicit element. Their styles have been copied into this theme, in a way similar to the alerts:
|
||||
|
||||
```html
|
||||
<div class="bs-callout bs-callout-info">
|
||||
This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. </div>
|
||||
```
|
||||
|
||||
<div class="alert alert-info" role="alert"><span class="glyphicon glyphicon-question-sign"></span> This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. This is a special info message. </div>
|
||||
|
||||
And here's the shortcode:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{{callout_info}}<div class="bs-callout bs-callout-info">{{end}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
You can use any of the following:
|
||||
{% raw %}
|
||||
```
|
||||
{{callout_danger}}
|
||||
{{callout_default}}
|
||||
{{callout_primary}}
|
||||
{{callout_success}}
|
||||
{{callout_info}}
|
||||
{{callout_warning}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Images
|
||||
permalink: /images/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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. The difference here is that the asset doesn't have a permalink, so here the file path actually matters.
|
||||
|
||||
## Images
|
||||
Put images inside the `images` folder in your root directory. You can create subdirectories inside this directory. Although you could use Markdown syntax for images, the HTML syntax is probably easier:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<img src="{{ "/images/jekyll.png" | prepend: site.baseurl }}">
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Here's a sample:
|
||||
|
||||
<img title="my sample image" src="{{ "/images/jekyll.png" | prepend: site.baseurl }}">
|
||||
|
||||
## SVG Images
|
||||
|
||||
You can also embed SVG graphics. Here's a sample embed:
|
||||
|
||||
```html
|
||||
<img src="{{site.baseurl}}/images/helpapi.svg" style="width: 650px;"/>
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
<img src="{{site.baseurl}}/images/helpapi.svg" style="width: 650px;"/>
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Labels
|
||||
permalink: /labels/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
These labels might come in handy for labeling things, such as POST, DELETE, UPDATE methods for endpoints. You can use any classes from Bootstrap in your content.
|
||||
|
||||
```html
|
||||
<span class="label label-default">Default</span>
|
||||
<span class="label label-primary">Primary</span>
|
||||
<span class="label label-success">Success</span>
|
||||
<span class="label label-info">Info</span>
|
||||
<span class="label label-warning">Warning</span>
|
||||
<span class="label label-danger">Danger</span>
|
||||
```
|
||||
|
||||
<span class="label label-default">Default</span>
|
||||
<span class="label label-primary">Primary</span>
|
||||
<span class="label label-success">Success</span>
|
||||
<span class="label label-info">Info</span>
|
||||
<span class="label label-warning">Warning</span>
|
||||
<span class="label label-danger">Danger</span>
|
||||
|
||||
You can have a label appear within a heading simply by including the span tag in the heading. However, you can't mix Markdown syntax with HTML, so you'd have to hard-code the heading ID for the auto-TOC to work.
|
||||
@@ -1,67 +0,0 @@
|
||||
---
|
||||
title: Links
|
||||
permalink: /links/
|
||||
audience: writer, designer
|
||||
tags: [formatting, navigation]
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Create a link
|
||||
|
||||
There are several ways to create links: Markdown, HTML, or keyref-style. I'll recommend the simplest way to create links:
|
||||
|
||||
## Markdown links
|
||||
|
||||
Markdown link pointing to an external site:
|
||||
|
||||
```
|
||||
[Google](http://google.com)
|
||||
```
|
||||
## HTML links
|
||||
|
||||
HTML link pointing to an internal site:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
<a href="{{ "/syntax_highlighting" | prepend: site.baseurl }}">Syntax Highlighting</a>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Re-using links
|
||||
|
||||
For internal links, it's a best practice to store the link in an internal file so that you can easily update all references to the link.
|
||||
|
||||
In this theme, the includes folder contains a linkrefs.html file where the capture tags are stored:
|
||||
|
||||
{%raw%}
|
||||
```html
|
||||
{% capture supported_features %}<a href="{{"/supported_features" | prepend: site.baseurl}}">Supported Features</a>{% endcapture %}
|
||||
```
|
||||
{%endraw%}
|
||||
|
||||
Anything between the capture tags is inserted when you use capture variable.
|
||||
|
||||
To insert a link to the above, you would just add this in your content. First put the linksrefs.html include below your frontmatter:
|
||||
|
||||
{%raw%}
|
||||
```html
|
||||
{% include linkrefs.html %}
|
||||
```
|
||||
{%endraw%}
|
||||
|
||||
Then insert the variable from your captured link:
|
||||
|
||||
{%raw%}
|
||||
```
|
||||
For more information, see {{supported_features}}.
|
||||
```
|
||||
{%endraw%}
|
||||
|
||||
|
||||
If you ever change the link, all references pointing to {{supported_features}} will automatically be updated. It's also easy to do a find and replace operation looking for "{{supported_features}}".
|
||||
|
||||
## Folder paths irrelevant
|
||||
|
||||
Even though you may group pages into subfolders, when you reference a page, you reference it by the permalink regardless of the subfolder it happens to be in. So even if you have formatting/syntax_highlighting, you link to it with `syntax_highlighting` instead of `formatting/syntax_highlighting` because that's the topic's permalink. Jekyll iterates through all pages in the page namespace to locate one that contains the matching permalink.
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: NavTabs Demo
|
||||
permalink: /navtabs/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary: "Navtabs provide a tabbable navagation directly in your content. Navtabs are helpful for showing code samples for different programming languages."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Common uses
|
||||
|
||||
Navtabs are particularly useful for scenarios where you want to show a variety of options, such as code samples for Java, .NET, or PHP, on the same page.
|
||||
|
||||
While you could resort to single-source publishing to provide different outputs for each unique programming language or role, you could also use navtabs to allow users to select the content you want.
|
||||
|
||||
Navtabs are better for SEO since you avoid duplicate content and drive users to the same page.
|
||||
|
||||
## Navtabs demo
|
||||
|
||||
The following is a demo of a navtab. Refresh your page to see the tab you selected remain active.
|
||||
|
||||
<ul id="profileTabs" class="nav nav-tabs">
|
||||
<li class="active"><a href="#profile" data-toggle="tab">Profile</a></li>
|
||||
<li><a href="#about" data-toggle="tab">About</a></li>
|
||||
<li><a href="#match" data-toggle="tab">Match</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div role="tabpanel" class="tab-pane active" id="profile">
|
||||
<h2>Profile</h2>
|
||||
<p>Praesent sit amet fermentum leo. Aliquam feugiat, nibh in u ltrices 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.</p>
|
||||
</div>
|
||||
|
||||
<div role="tabpanel" class="tab-pane" id="about">
|
||||
<h2>About</h2>
|
||||
<p>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 u ltrices 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.about</p></div>
|
||||
|
||||
<div role="tabpanel" class="tab-pane" id="match">
|
||||
<h2>Match</h2>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Code
|
||||
|
||||
Here's the code for the above (with the filler text abbreviated):
|
||||
|
||||
```html
|
||||
<ul id="profileTabs" class="nav nav-tabs">
|
||||
<li class="active"><a href="#profile" data-toggle="tab">Profile</a></li>
|
||||
<li><a href="#about" data-toggle="tab">About</a></li>
|
||||
<li><a href="#match" data-toggle="tab">Match</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div role="tabpanel" class="tab-pane active" id="profile">
|
||||
<h2>Profile</h2>
|
||||
<p>Praesent sit amet fermentum leo....</p>
|
||||
</div>
|
||||
|
||||
<div role="tabpanel" class="tab-pane" id="about">
|
||||
<h2>About</h2>
|
||||
<p>Lorem ipsum ...</p></div>
|
||||
|
||||
<div role="tabpanel" class="tab-pane" id="match">
|
||||
<h2>Match</h2>
|
||||
<p>Vel vehicula ....</p>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Design constraints
|
||||
|
||||
Bootstrap automatically clears any floats after the navtab. If you have a navtab that appears in the same space as pagemetadata floating column, there will be a big space after the navtab until the end of the pagemetadata element because there's a `clear: float` property applied after the nav class.
|
||||
|
||||
If you change the `clear:float` property, the first heading/text on the tab will suddenly float along side the tab, which is unfortunate.
|
||||
|
||||
## Appearance in the mini-TOC
|
||||
|
||||
If you put a heading in the navtab content, that heading will appear in the mini-TOC as long as the heading tag has an ID. If you don't want the headings for each navtab section to appear in the mini-TOC, simply omit the ID attribute from the heading tag. Without this attribute, the mini-TOC won't insert the heading title into the mini-TOC.
|
||||
|
||||
## Must use HTML
|
||||
|
||||
You must use HTML within the navtab content because each navtab section is surrounded with HTML, and you can't use Markdown inside of HTML.
|
||||
|
||||
## Match up ID tags
|
||||
|
||||
Each tab's `href` attribute must match the `id` attribute of the tab content's `div` section. So if your tab has `href="#acme"`, then you add `acme` as the ID attribute in `<div role="tabpanel" class="tab-pane" id="acme">`.
|
||||
|
||||
One of the tabs needs to be set as active, depending on what tab you want to be open by default (usually the first one).
|
||||
|
||||
```html
|
||||
<div role="tabpanel" class="tab-pane active" id="acme">
|
||||
```
|
||||
|
||||
## Sets a cookie
|
||||
|
||||
The navtabs are part of Bootstrap, but this theme sets a cookie to remember the last tab's state. The js/customscripts.js file has a long chunk of JavaScript that sets the cookie. The JavaScript comes from [this StackOverflow thread](http://stackoverflow.com/questions/10523433/how-do-i-keep-the-current-tab-active-with-twitter-bootstrap-after-a-page-reload).
|
||||
|
||||
By setting a cookie, if the user refreshes the page, the active tab is the tab the user last selected (rather than defaulting to the default active tab).
|
||||
|
||||
## Functionality to implement
|
||||
|
||||
One piece of functionality I'd like to implement is the ability to set site-wide nav tab options. For example, if the user always chooses PHP instead of Java in the code samples, it would be great to set this option site-wide by default. However, this functionality isn't yet coded.
|
||||
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: Shortcuts for Jekyll syntax
|
||||
permalink: /shortcuts_for_jekyll_syntax/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated: May 13, 2015
|
||||
summary: "You can use a typing keyword expander to make it easier to create the Jekyll syntax."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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. You get aText from the App Store on a Mac for about $5.
|
||||
|
||||
To import the shortcut keys I'm using, see the <a href="{{ "/files/shortcuts.zip" | prepend: site.baseurl }}">shortcuts.zip</a> file. After unzipping this file, you can import it into aText.
|
||||
|
||||
There are alternatives to aText, such as Typeitforme. But aText seems to work the best. Read more about it on [Lifehacker](http://lifehacker.com/5843903/the-best-text-expansion-app-for-mac).
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: Syntax highlighting
|
||||
permalink: /syntax_highlighting/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
For syntax highlighting, use fenced code blocks optionally followed by the language syntax you want:
|
||||
|
||||
```ruby
|
||||
def foo
|
||||
puts 'foo'
|
||||
end
|
||||
```
|
||||
|
||||
Fenced code blocks require a blank line before and after.
|
||||
|
||||
If you're using an HTML file, you can also use the `highlight` command with Liquid markup:
|
||||
|
||||
{% raw %}
|
||||
```ruby
|
||||
{% highlight ruby %}
|
||||
def foo
|
||||
puts 'foo'
|
||||
end
|
||||
{% endhighlight %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
The theme has syntax highlighting configured in the configuration file as follows:
|
||||
|
||||
```
|
||||
highlighter: rouge
|
||||
```
|
||||
@@ -1,123 +0,0 @@
|
||||
---
|
||||
title: Tables
|
||||
permalink: /tables/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Multimarkdown Tables
|
||||
|
||||
You can use Multimarkdown syntax for tables. The following shows a sample:
|
||||
|
||||
```
|
||||
Column 1 | Column 2
|
||||
--------|----------
|
||||
cell 1a | cell 1b
|
||||
cell 2a | cell 2b
|
||||
```
|
||||
|
||||
This renders to the following:
|
||||
|
||||
Column 1 | Column 2
|
||||
--------|----------
|
||||
cell 1a | cell 1b
|
||||
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 enable the right scripts for the table on that page only (rather than loading the scripts on every page of the site.)
|
||||
|
||||
Also, add the scripts to trigger the jQuery table on your page:
|
||||
|
||||
```js
|
||||
<script>
|
||||
$(document).ready(function(){
|
||||
|
||||
$('table.display').DataTable( {
|
||||
paging: true,
|
||||
stateSave: true,
|
||||
searching: true
|
||||
}
|
||||
);
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
The available options for the datable are described in the [datatable documentation](https://www.datatables.net/manual/options), which is excellent.
|
||||
|
||||
Additionally, you must add a class of `display` to the table. (You can change the class, but then you'll need to change the trigger above from `table.display` to whatever class you want to you. You might have different triggers with different options for different tables.)
|
||||
|
||||
Since Markdown doesn't allow you to add classes to tables, you'll need to use HTML for any datatables. Here's an example:
|
||||
|
||||
```html
|
||||
<table id="sampleTable" class="display">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
<th>Description</th>
|
||||
<th>Type</th>
|
||||
<th>Default Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Parameter 1</td>
|
||||
<td>Sample description
|
||||
</td>
|
||||
<td>Sample type</td>
|
||||
<td>Sample default value</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Parameter 2</td>
|
||||
<td>Sample description
|
||||
</td>
|
||||
<td>Sample type</td>
|
||||
<td>Sample default value</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
```
|
||||
|
||||
This renders to the following:
|
||||
|
||||
<script>
|
||||
$(document).ready(function(){
|
||||
|
||||
$('table.display').DataTable( {
|
||||
paging: false,
|
||||
stateSave: true
|
||||
}
|
||||
);
|
||||
});
|
||||
</script>
|
||||
|
||||
<table id="sampleTable" class="display">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Parameter</th>
|
||||
<th>Description</th>
|
||||
<th>Type</th>
|
||||
<th>Default Value</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Parameter 1</td>
|
||||
<td>Sample description
|
||||
</td>
|
||||
<td>Sample type</td>
|
||||
<td>Sample default value</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Parameter 2</td>
|
||||
<td>Sample description
|
||||
</td>
|
||||
<td>Sample type</td>
|
||||
<td>Sample default value</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: Videos
|
||||
permalink: /videos/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<video id="scenario-1" class="video-js vjs-default-skin" controls
|
||||
preload="auto" width="640" height="360" data-setup='{}'>
|
||||
<source src="{{site.baseurl}}/videos/scenario1.mp4" type='video/mp4'>
|
||||
</video>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You'll know it's working if the video wrapper looks like the one here: [video.js: the open source HTML5 video player](http://www.videojs.com/). The play button will be in the upper-left corner. If you want the player button in the middle, change the class to `video-js vjs-default-skin vjs-big-play-centered`.
|
||||
|
||||
Here are [more details on this video player](https://github.com/videojs/video.js/blob/stable/docs/guides/setup.md).
|
||||
|
||||
There are a number of javascript files included in inside the video-js folder inside the js folder. This allows the player to work offline.
|
||||
|
||||
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. However, I don't think the built-in video players work very well (you can't easily scrub around the video without seeing lots of buffering and other issues.)
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: Navigation
|
||||
permalink: /navigation/
|
||||
audience: writer, designer
|
||||
tags: navigation
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
The sidebar and top navigation bar read their values from yml files inside the _data folder. Follow the YML syntax shown in the file.
|
||||
|
||||
# Sidebar accordion
|
||||
The configuration file (configs/config_writer.yml) file includes a value (sidebar_accordion) that lets you choose whether to use the accordion feature in the sidebar or not. The accordion collapses other sections when a section is opened, which conserves space on the screen. Put `true` or `false` for the value.
|
||||
|
||||
You can add two levels of nesting in the sidebar nav. Follow the pattern of the existing sidebar.yml file exactly. With YML, each new level is set off with two space below it. You can't change the names of the nesting levels without also making corresponding edits to the sidebar.htm file in the _includes directory.
|
||||
|
||||
## Top nav
|
||||
|
||||
If you want the URL to point to an external site, use <code>external_url</code> instead of `url`. (The sidebar.yml file doesn't have the ability to point to external sites in the nav.)
|
||||
|
||||
The topnav folder has two link areas: a single level link and a drop-down link. (You don't make the dropdown link by adding additional levels in the single-level.)
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: Tags
|
||||
permalink: /tags/
|
||||
audience: writer, designer
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
You can add tags to pages by adding `tags` in the frontmatter, like this:
|
||||
|
||||
```
|
||||
---
|
||||
title: 2.0 Release Notes
|
||||
permalink: /release_notes_2_0/
|
||||
tags: overview, getting-started
|
||||
---
|
||||
```
|
||||
|
||||
To prevent tags from getting out of control and inconsistent, first make sure the tag appears in the tags.yml file. If it's not there, the tag you add to a page won't be read.
|
||||
|
||||
Additionally, you must create a tag archive page similar to the other pages inside the pages/tag-archive folder. This theme doesn't auto-create tag archive pages.
|
||||
|
||||
For simplicity, make all your tags single words (connect them with hyphens if necessary).
|
||||
|
||||
{% if site.audience == "designer" %}
|
||||
## Retrieving pages for a specific tag
|
||||
|
||||
If you want to retrieve pages outside of a particular tag-archive page, you could use this code:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
{% for page in site.pages limit: 5 %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "release_notes" %}
|
||||
<li><a href="{{ page.permalink | prepend: site.baseurl }}">{{page.title}}</a></li>
|
||||
<div class="summary">{{page.summary}}</div>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Tags will be sorted in alphabetical order.
|
||||
|
||||
{{warning}} Avoid using too many `for` loops. Each `for` loop you add increases the build time with Jekyll. This is why so many of the reuse components are inside data files rather than stored as includes in an HTML file.{{end}}
|
||||
|
||||
{% endif %}
|
||||
@@ -1,92 +0,0 @@
|
||||
---
|
||||
title: Setting up the configuration file
|
||||
permalink: /config_setup/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
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."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Importance of Configuration File
|
||||
|
||||
The configuration file serves important functions with single sourcing. For each site output, you create a unique configuration file for that output.
|
||||
|
||||
The configuration file contains all the settings and other details unique to that site output, such as variables, titles, output directories, build folders, and more.
|
||||
|
||||
{{warning}} This theme is coded to look for specific values set by the configuration file. If something isn't working correctly, check to make sure that you have the configuration values that are defined here properly configured.{{end}}
|
||||
|
||||
## Configuration file options
|
||||
|
||||
Some of the options you can set in the configuration file determine theme settings. For sample values, see the default configuration file.
|
||||
|
||||
Note that you can arbitrary key value pairs in the configuration file, and then you can access them through `site.yourkey`. However, the values in these tables are used to control different aspects of the theme.
|
||||
|
||||
## Cascading configuration files
|
||||
|
||||
When you build or serve Jekyll, you specify the configuration file that you want Jekyll to use. If you have multiple sites you're building, you can put all the common configuration values into a base configuration file. For the unique configuration files, you put them into another configuration file. Jekyll will read multiple configuration files.
|
||||
|
||||
The documentation on Jekyll for using multiple configuration files isn't very clear. In my experience, the build command needs to look like this:
|
||||
|
||||
```
|
||||
jekyll serve --config config_base.yml,config_designer.yml
|
||||
```
|
||||
|
||||
Later configuration files will override settings in earlier configuration files.
|
||||
|
||||
|
||||
{{warning}} You cannot use a space after the period.{{end}}
|
||||
|
||||
## Configuration settings
|
||||
|
||||
| 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. |
|
||||
| **audience** | Required | The audience for the output. Each sidebar entry in the _data/sidebar.yml files needs to have an audience attribute that matches the value here in order for the sidebar item to be included.|
|
||||
| **platform** | Required | The platform for the output. The function is the same as audience -- the sidebar file matches up with attributes defined in the configuration file to determine what sidebar items are included in the build.|
|
||||
| **product** | Required | Same function as audience, platform, and version.
|
||||
| **version** | Required | Same function as audience, platform, and product.
|
||||
| **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. It's better to specify a folder outside your project folder, by using `../`. |
|
||||
| **tagline** | Optional | Appears above the sidebar. Usually you put some tag related to the site specific build, such as the audience.|
|
||||
| **topnav_title** | Required | Appears next to the home button in the top nav bar.|
|
||||
| **topnav_version** | Optional | Appears next to the title (which is next to the home button) in the top nav bar.|
|
||||
| **homepage_title**| Required | If you're using includes to pull in the homepage content, then you set the title for your homepage via the configuration file. This is because multiple files are being displayed on the index.md page depending on the project. The page layout will use the homepage_title instead of the one on the include.|
|
||||
| **site_title**| |
|
||||
| **baseurl** | Optional | The folder where the help will appear when published. If you're publishing one version of your doc into a root directory, this isn't needed. However, most likely you will publish each output into its own folder, so add a value for the baseurl. Note that your site *must* be published in this baseurl in order to display correctly. This is because the links in the published site build are not all relative in the same way. However, you can publish the same output onto different domains (as long as you keep the same baseurl folder on those different domains).
|
||||
| **url** | Optional. | Recommended to not include this, since it allows you to easily push help from one domain to another (such as from a test environment to a production environment. As long as the baseurl's folder remains the same, the help will display well. I think the only use for the url is for the RSS feed. |
|
||||
| **baseurl** | Optional | The baseurl is everything that comes after the domain (acme.com). If you publish at acme.com/folder/version/role, then the baseurl is folder/version/role. Jekyll is hard-coded to only display properly when placed inside this baseurl folder. |
|
||||
| **port** | Required | The port used in the preview mode. This is only for the live preview and doesn't affect the published output. If you serve multiple outputs simultaneously, the port must be unique. |
|
||||
| **feedback_email** | Gets configured as the email address in the Send Feedback button in the top navigation bar.|
|
||||
| **sidebar_accordion** | Required | Boolean. Whether you want the navigation sidebar to use the accordion effect or not. The accordion effect means when you expand a section, the other sections auto-collapse. If you put false, then you can expand multiple sections at once. At the bottom of the navigation sidebar, two links will appear: Collapse All and Expand All.|
|
||||
| **floating_nav** | Optional | Boolean. Whether you want the nav bar to float or not when users scroll down. |
|
||||
| **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. |
|
||||
| **markdown** | Required | The processor to use for Markdown. This is a Jekyll-specific setting. |
|
||||
| **redcarpet** | Required | Extensions used with redcarpet. You can read more about them by searching for redcarpet extensions online. {% include custom/toc_id_note.html %} |
|
||||
| **highlighter** | Optional | The syntax highlighter used. Rouge is also an option. I think Pygments does a better job. You will need to [install Pygments](http://pygments.org/download/) on your machine or else you will see an error. |
|
||||
| **exclude** | Optional | A list of files and directories that you want excluded from the build. By default, all the content in your project is included in the output. |
|
||||
| **permalink** | Required | The structure used for the link URLs. To read more about permalinks, see [Permalinks](http://jekyllrb.com/docs/permalinks/). |
|
||||
| **defaults** | Optional | Here you can set default values for frontmatter based on the content type (page, post, or collection). |
|
||||
| **sass** | Required | The directory for sass files. This is a Jekyll-specific settings. Sass isn't customized in this theme. |
|
||||
| **collections** | Optional | Any specific collections (custom content types that extend beyond pages or posts) that you want to define. This theme defines a collection called tooltips. You access this collection by using site.tooltips instead of site.pages or site.posts. Put the tooltip content types inside a folder in your project called \_tooltips. |
|
||||
| **print** | Optional | Boolean. Whether this build is a print build or not. This setting allows you to run conditions in your content such as {% raw %} {% if site.print == true %} do this... {% endif %} {% endraw %}. |
|
||||
| **floating_nav** | Optional | Boolean. If you add `false`, then the sidebar navigation won't apply a fixed floating property. When the user scrolls. the nav bar won't stay in the same place. If you have a large nav bar, you may want to turn off the floating properties. Also, for small screens with viewports of 600px of height or smaller, the fixed nav is automatically turned off because the options tend to extend past the visible screen. Usually leave this set to `true` or omit the option altogether (the default is true).|
|
||||
| **suffix** | Optional | If you publish on Salesforce's site.com, you have to add index.html to the permalink or else the page won't render. If you add `suffix: index.html` in your config file, this file will be appended in the URLs. If you're not publishing to Salesforce, don't add this property to your configuration file.|
|
||||
|
||||
## Where to store configuration files
|
||||
|
||||
In this theme, the configuration files are listed in the root directory. There are some build scripts in the root directory that simply reference the configuration files.
|
||||
|
||||
For reasons unknown to me, Jekyll won't work if you put the configuration files into a subdirectory and are using multiple configuration files.
|
||||
|
||||
## Default config in root
|
||||
|
||||
There is also a default \_config.yml file in root that is a copy of the config_designer.yml file. This file is included so that Github Pages will build the theme.
|
||||
|
||||
It's also included because most Jekyll users are accustomed to downloading a theme, running `jekyll serve`, and expecting the site to build. The `jekyll serve` command depends on having a _config.yml file in the root.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
title: Getting started
|
||||
permalink: /getting_started/
|
||||
tags: getting-started
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Step 1: Set up the prerequisites
|
||||
|
||||
Before you start installing the theme, make sure you have all of these prerequisites in place.
|
||||
|
||||
* **Mac computer (recommended)**. If you have a PC, you need to see [Jekyll on Windows](http://jekyllrb.com/docs/windows/). Make sure you can get Jekyll working on Windows before proceeding.
|
||||
* **[Ruby](https://www.ruby-lang.org/en/)**. This should already be installed. Type `which ruby` to confirm.
|
||||
* **[Rubygems](https://rubygems.org/pages/download)**. This is a package manager for Ruby (gems). Type `which gem` to confirm.
|
||||
* **[Jekyllrb](http://jekyllrb.com/)**. To install: `gem install jekyll`. Type `which jekyll` to confirm.
|
||||
* **[Git](http://git-scm.com/download/mac)**. Type `which git` to see if you already have it installed.
|
||||
* **Text editor** (some examples: Sublime Text, Atom, WebStorm)
|
||||
* **[iTerm](http://iterm.sourceforge.net/)** - Optional but recommended instead of Terminal.
|
||||
* **[pygments](http://pygments.org/download/)** - Pygments handles syntax highlighting. In my experiments, the Pygments highlighter seemed better than the default rouge highlighter. To install Pygments, you will need Python installed. (If you don't install pygments, you'll get an error when you build the theme.) To check if Python is installed, type `which python`. To install Pygments: `gem install pygments.rb`.
|
||||
|
||||
{{warning}} These instructions are designed for users on Macs. Jekyllrb supposedly works on Windows but is not officially supported on that platform. See <a href="Jekyll on Windows">http://jekyllrb.com/docs/windows/</a> for more details. {{end}}
|
||||
|
||||
## Step 2: Build the theme
|
||||
|
||||
Before you start customizing the theme, make sure you can build the theme with the default content and settings first.
|
||||
|
||||
1. Make sure you satisfy all the prerequisites as listed in the previous section, "Prerequisites."
|
||||
2. Download the theme from the [documentation-theme-jekyll Github repository](https://github.com/tomjohnson1492/documentation-theme-jekyll) and unzip it into your ~username/projects folder.
|
||||
|
||||
You can either download the theme files directly by clicking the **Download Zip** button on the right of the repo, or use git to clone the repository to your local machine. Note, however, that you won't be using the pull command to update the theme since you'll be customizing it with your own content and won't want to overwrite those customizations, so there isn't a huge need to clone it.
|
||||
|
||||
2. After downloading the theme, note some unique aspects of the file structure:
|
||||
* In the root directory, there's a separate configuration file for each unique output you're building.
|
||||
* Each configuration file has a different preview port.
|
||||
* Each configuration file also specifies a different project (and potentially a different audience, product, platform, and version). By setting unique values for these properties in your configuration file, you determine how the sidebar and top navigation is constructed.
|
||||
|
||||
{{tip}} The main goal of this theme is to enable single sourcing. With single sourcing, you build multiple outputs from the same source, with somewhat different content in each site based on the particular product, platform, version, and audience. That's why there are separate configuration files for each output.{{end}}
|
||||
|
||||
In general, you build the sites by using build commands that specify the configuration file, like this:
|
||||
|
||||
```
|
||||
jekyll serve --config config_base.yml,config_designer.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.
|
||||
|
||||
There are two configuration files used here -- config_base.yml contains common settings used in all the configuration files. The config_designer.yml file contains unique configuration properties specific to this build.
|
||||
|
||||
{{note}} The _config.yml file in the theme's root directory is just a duplicate of the config_base.yml and config_designer.yml files combined. The _config.yml file in root allows Github Pages to build the site from the Github repo. Unless you're using Github Pages to build your sites, you don't need _config.yml in the root directory. {{end}}
|
||||
|
||||
3. In the root directory, you'll find build_writer.sh, which is a simple shell script containing this build argument. Instead of running the command above, run the following:
|
||||
|
||||
```
|
||||
. build_writer.sh
|
||||
```
|
||||
|
||||
Preview the site at the preview URL shown.
|
||||
|
||||
4. Open a new tab in iTerm and build an additional output:
|
||||
|
||||
```
|
||||
. build_designer.sh
|
||||
```
|
||||
Open a new tab in your browser and preview the site at the preview URL shown. Notice that the writer output doesn't include the Special Layouts section in the sidebar.
|
||||
|
||||
If the theme builds both outputs successfully, great. You can move on to the next section: Customizing the theme. If you run into errors building the basic theme, you must solve them before moving on. See {{troubleshooting}} for more information.
|
||||
|
||||
{{tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{iterm_profiles}} for details. {{end}}
|
||||
|
||||
## Step 3: Customize the theme
|
||||
|
||||
{{note}} Before you start customizing the theme, make sure you can build the theme by following the instructions in the previous section, "Step 2: Build the theme." {{end}}
|
||||
|
||||
The theme shows two build outputs: one for designers, and one for writers. The dual outputs is an example of the single sourcing nature of the theme. The designers output is comprehensive, whereas the writers output is a subset of the information. Follow these steps to customize the theme with your own content.
|
||||
|
||||
{{important}} In these instructions, I'll assume your project's name is "acme." I'll also assume you have two audiences you're building your acme project for: developers and marketers. {{end}}
|
||||
|
||||
1. If you haven't already downloaded the theme, see the previous section, "Step 2: Build the theme." Press Ctrl+C to stop the previews.
|
||||
2. In the theme's root directory, rename config_writer.yml to config_developer.yml and customize all the values inside that file based on the instructions {{config_setup}}. Do the same with config_designer.yml (changing it to config_marketer.yml) and continue to clone and customize the config file for other audiences you need.
|
||||
|
||||
In this theme, each output requires a separate config file. If you have 10 audiences and you want separate sites for each, then then you'll have 10 config files in this directory.
|
||||
|
||||
{{tip}} As you customize the config files, make the port values unique so that you don't run into "Address already in use" issues when you build multiple sites and want to preview them at the same time.{{end}}
|
||||
|
||||
5. In the _includes/custom directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with your developer, and `designer` with another marketer.)
|
||||
|
||||
The conditions.html file is used to apply different requirements to the sidebar and other files. The conditions.html file is included in various parts of the theme — the sidebar.html, the topnav.html, and some of the print files.
|
||||
|
||||
6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside the pages folder is fine — you won't have to worry about folder paths in links.)
|
||||
7. Inside \_data, open sidebar.yml and topnav.yml and customize the navigation.
|
||||
|
||||
{{warning}} Don't mess up the spacing or change any of the YML level names or the site or sidebar won't build. Each new YML level is indented with two spaces. {{end}}
|
||||
|
||||
8. In the root directory, rename build_writer.sh to build_developer.sh (same with build_designer.sh; change it to build_marketer.sh). In the content of each of these files, change the build parameters to point to the configuration file you want.
|
||||
9. In the root directory, customize the index.md file. This file will be the homepage for all of your projects. Use conditional tags (for example, `if site.project == "acme-writer" ...`) to change the content for different builds of your site. Store the content of the homepage in your _includes/custom folder. See {{conditional_logic}} for more information on applying conditions.
|
||||
10. For each of your pages where you want to insert a note or callout, add {%raw%}`{% include linkrefs.html %}`{%endraw%} directly below the frontmatter.
|
||||
|
||||
{{tip}} If you're using WebStorm, you can create a Jekyll template so that the frontmatter is auto-populated when you create a new Jekyll file. {{end}}
|
||||
|
||||
12. In the _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags as you did with index.md.
|
||||
11. Build your site with `. build_developer.sh` and `. build_marketer.sh` and preview it at the URLs provided.
|
||||
|
||||
{{callout_info}}<b>Publishing to web hosts:</b> If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other web host.{{end}}
|
||||
|
||||
## Questions
|
||||
|
||||
If you have questions, contact me at tomjohnson1492@gmail.com. My regular site is [http://idratherbewriting.com](idratherbewriting.com). 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.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: Support
|
||||
permalink: /support/
|
||||
audience: writer, designer
|
||||
tags: overview
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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).
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Supported features
|
||||
permalink: /supported_features/
|
||||
audience: writer, designer
|
||||
tags: [overview, getting-started]
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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.
|
||||
|
||||
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 programming language that allows you do advanced things.
|
||||
Responsive design | Yes | Uses Bootstrap framework.
|
||||
Translation | Yes | Export the pages and send them to a translation agency. Then create a new project for that language and insert the pages. Everything will be translated.
|
||||
PDF | Yes | You can generate PDFs from your Jekyll site, but this will involve a little setup. 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.
|
||||
Offline access | Yes | You can send someone a zip file of your site. You can use a tool called Sitesucker to slurp the site into an offline-viewable download.
|
||||
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.
|
||||
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.
|
||||
Blogging features | Yes | Jekyll was originally designed as a blogging engine, so it has a lot of blogging features you may be familiar with, such as tags and categories. But it also has some features similar to a CMS, such as pages, metadata, and other files.
|
||||
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.
|
||||
WYSIWYG interface | No, but ... | I use Sublime Text 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.
|
||||
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 because Github doesn't allow Ruby plugins. Instead, you can just push your output to Github. If you're not planning to use Github, there are no restrictions on any plugins of any sort. Jekyll makes it super easy to integrate every kind of plugin imaginable.
|
||||
Bootstrap integration | Yes! | This theme is built on Bootstrap. 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.)
|
||||
@@ -1,101 +0,0 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
permalink: /troubleshooting/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Issues building the site
|
||||
|
||||
### Address already in use
|
||||
|
||||
When you try to build the site, you get this error in iTerm:
|
||||
|
||||
```
|
||||
jekyll 2.5.3 | Error: Address already in use - bind(2)
|
||||
```
|
||||
This happens if a server is already in use. To fix this, edit your config file and change the port to a unique number.
|
||||
|
||||
If the previous server wasn't shut down properly, you can kill the server process using these commands:
|
||||
|
||||
`ps aux | grep jekyll`
|
||||
|
||||
Find the PID (for example, it looks like "22298").
|
||||
|
||||
Then type `kill -9 22298` where "22298" is the PID.
|
||||
|
||||
Alternatively, type the following to stop all Jekyll servers:
|
||||
|
||||
```
|
||||
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
|
||||
```
|
||||
|
||||
### Build not entirely finishing
|
||||
|
||||
If your build doesn't entirely finish on the command line, check to see if you have a space after a comma when using multiple configuration files, like this:
|
||||
|
||||
```
|
||||
jekyll serve --config config_base.yml, config_designer.yml
|
||||
```
|
||||
|
||||
Remove the space after the comma, and the build will finish executing:
|
||||
|
||||
```
|
||||
jekyll serve --config config_base.yml,config_designer.yml
|
||||
```
|
||||
|
||||
### build_writer.sh file not executable
|
||||
|
||||
If you run into permissions errors trying to run the build_writer.sh file, you may need to change the file permissions to make the sh file executable. Browse to the directory containing build_writer.sh and run the following:
|
||||
|
||||
```
|
||||
chmod +x build_writer.sh
|
||||
```
|
||||
|
||||
### Pygments not installed
|
||||
|
||||
The config file requires pygments for the highlighter. You must [download and install Pygments]([pygments](http://pygments.org/download/)), which requires Python, in order to use this syntax highlighter. If you don't want to bother with Pygments, open the configuration file and change `pygments` to `rouge`.
|
||||
|
||||
### "page 0" cross references in the PDF
|
||||
|
||||
If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build.
|
||||
|
||||
If it's not a page but rather a file, you need to add a class to the file so that your print stylesheet excludes the counter from it. Try adding `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class.
|
||||
|
||||
### The PDF is blank
|
||||
|
||||
Check the prince-file-list.txt file in the output to see if it contains links. If not, you have something wrong with the logic in the prince-file-list.txt file. Check the conditions.html file in your _includes to see if the audience specified in your configuration file aligns with the buildAudience in the conditions.html file
|
||||
|
||||
### Sidebar not appearing
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
{{note}} This theme is designed for single sourcing. If you're only building one site, you can remove these values from the _includes/sidebar.html file and _data/sidebar.yml files.{{end}}
|
||||
|
||||
Understanding how the theme works can be helpful in troubleshooting. The _includes/sidebar.html file loops through the values in the _data/sidebar.yml file. There are `if` statements that check whether the conditions are met. If the sidebar.yml item has the right product, platform, audience, and version, then it gets displayed in the sidebar. If not, it get skipped.
|
||||
|
||||
### Sidebar heading level not opening
|
||||
|
||||
In your _data/sidebar.yml file, you must also include the correct parameters (platform, product, audience version) for each heading. If an item contains something that should be displayed, the attributes for the heading should be listed.
|
||||
|
||||
Without any attributes on heading levels, you could end up with scenarios where a section is entirely designed for one output but appears in every output regardless.
|
||||
|
||||
### Page metadata is blank
|
||||
|
||||
You aren't including the right frontmatter tags and appropriate values. See {{pages}} for more details.
|
||||
|
||||
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Create PDF
|
||||
permalink: /create_pdf/
|
||||
tags: publishing
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
{% comment %}
|
||||
remaining tasks:
|
||||
|
||||
- in build script, serve jekyll, build pdf, then kill server.
|
||||
- handle tables that have 5 columns in a way that doesn't end up getting cut off
|
||||
- handle link to .zip workbook file
|
||||
- handle page 0 links -- which indicate that there is no cross reference. maybe add note in instructions.
|
||||
{% endcomment %}
|
||||
|
||||
{{warning}} The PDF creation process has some bugs and is still being worked out... {{end}}
|
||||
|
||||
This process for creating a PDF relies on Prince to transform the HTML content into PDF. Prince costs about $500 per license.
|
||||
|
||||
1. Download and install [Prince](http://www.princexml.com/).
|
||||
2. Create a new config file for each of your PDF targets. The only notable difference is the following:
|
||||
* The default page layout is page_print.
|
||||
* The baseurl and port should be different.
|
||||
* There's a `print: true` toggle in case you want to make some of your content unique to PDF output.
|
||||
|
||||
{{note}} Although you're creating a PDF, you must still build a web target before running Prince. Prince will pull from the HTML files and from the file-list for the TOC.{{end}}
|
||||
|
||||
3. In the css folder, open the print-header-writer.css and print-header-designer.css files. Change the filenames to your audiences. Customize what appears in each of the page margins.
|
||||
4. In the default_print.html file in the layout folder, customize the conditional logic to match your audience with the stylesheets you created in the previous step.
|
||||
5. In the _data folder, open sidebar.yml and add `print: true` for each page that you want to appear in the print version. (The pages in the topnav aren't pushed to PDF, so if you need some of the pages there, add them to the sidebar and add a `web: false` property to each of them (in addition to a `print: true` property).)
|
||||
{{note}} In addition to adding the right audience to the page, you must also add the audience to the section's audience attribute. This is because the theme logic first checks whether the section contains the right audience attribute, and then checks whether the items in that section have the right audience attribute.{{end}}
|
||||
6. In the project's root directory, the logic in the prince-file-list.txt will pull all files from the sidebar.yml file to be included in the PDF. You can adjust any of the logic there as needed, but you shouldn't need to do anything to the file.
|
||||
5. In the root directory, rename the build_writer_pdf.sh file and customize its contents to point to the right paths on your computer.
|
||||
5. In the root directory, rename the build_writer_prince.sh file and customize the input and output directories. The input should point to where this project builds, so the script can find the processed prince-file-list.txt file and so it knows where to build the output.
|
||||
6. In the root directory, open titlepage.html and customize the link to the logo and other details. The `site_print_title` and `site_version` variables will pull from the config_writer_pdf.yml file, so make sure there are values defined there. The titlepage.html also constructs the TOC by looping through the sidebar.yml file in the same way that the sidebar.html file loops through it. The main purpose is to replicate the hierarchy (headings and subitems).
|
||||
7. The titlepage.html file is specified in the sidebar.yml file, with a property of `web: false` so that it's not included in the online output. Very few items are specific to print only, but if you have other, add `web: false` to them to ensure they are likewise excluded from the online output.
|
||||
7. Open the _data/sidebar.yml file and add `print: true` or `print: false` depending on what files you want to include in the PDF.
|
||||
7. In iTerm, first run `. build_writer_pdf.sh` to get the pdf version of the content ready.
|
||||
8. Now run `. build_writer_prince.sh` to generate the PDF from this version.
|
||||
8. Check for links to non-existent topics in the PDF by looking for "page 0".
|
||||
9. For those broken links, conditionalize the content to whether site.print == true or not.
|
||||
10. Stop the server that has the build_writer_pdf preview.
|
||||
|
||||
{{note}} Ideally, I wanted to create a script that launched the server, then built prince, and then stopped the server, but I haven't figured that out yet. You have to detach the server, and once you detach it, the only way to kill it is by referencing a dynamically generated PID. {{end}}
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: Common Git Commands
|
||||
permalink: /git_commands/
|
||||
tags: [publishing]
|
||||
keywords: git, revision control, github, version control
|
||||
audience: writers, designers
|
||||
last_updated: May 13, 2015
|
||||
summary: "These are some sample Git commands."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
When you're interacting with Github, it's helpful to know a few basic Git commands...
|
||||
@@ -1,282 +0,0 @@
|
||||
---
|
||||
title: Create a Help API
|
||||
permalink: /help_api/
|
||||
tags: publishing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
You can create a help API that developers can use to pull in content.
|
||||
|
||||
## Full code demo
|
||||
|
||||
For the full code demo, see the notes in the <a target="_blank" title="ToolTip Demo" href="{{ "/tooltip_demo.html" | prepend: site.baseurl }}">Tooltip Demo</a>.
|
||||
|
||||
In this demo, the popovers pull in and display content from the information in an external tooltips.json file located on a different host.
|
||||
|
||||
## Diagram overview
|
||||
|
||||
Here's a diagram showing the basic idea of the help API:
|
||||
|
||||
<img src="{{site.baseurl}}/images/helpapi.svg" 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.
|
||||
|
||||
Note that in this scenario, the help is openly accessible on the web. If you have a private system, it's more complicated.
|
||||
|
||||
To deliver help this way using Jekyll, follow the steps in each of the sections below.
|
||||
|
||||
## 1. Create a "collection" for the help content (optional)
|
||||
|
||||
A collection is another content type that extends Jekyll beyond the use of pages and posts. Here I'm calling the collection "tooltips." You could also just use pages, but if you have a lot of content, it will take longer to look up information in the file because the lookup will have to scan through all your site content instead of just the tooltips.
|
||||
|
||||
Add the following information to your configuration file to declare your collection:
|
||||
|
||||
```liquid
|
||||
collections:
|
||||
tooltips:
|
||||
output: true
|
||||
```
|
||||
|
||||
In your Jekyll project, create a new folder called "_tooltips" and put every page that you want to be part of that tooltips collection inside that folder.
|
||||
|
||||
## 2. Create collection pages
|
||||
|
||||
Create pages inside your new tooltips collection. Each page needs only a unique `id` in the frontmatter. Here's an example:
|
||||
|
||||
{%raw%}
|
||||
```liquid
|
||||
---
|
||||
id: basketball
|
||||
---
|
||||
|
||||
{{site.data.definitions.basketball}}
|
||||
```
|
||||
{%endraw%}
|
||||
|
||||
You need to create a separate page for each resource you want to deliver. In this setup, the definition of basketball is stored in a data file call definitions inside the _data folder so that we can re-use it in other parts of the help as well. (This additional re-use is covered later on this page.)
|
||||
|
||||
## 3. Create a JSON file that contains the help content
|
||||
|
||||
Add the following to a file and call it tooltips.json:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
---
|
||||
layout: none
|
||||
---
|
||||
{
|
||||
"entries":
|
||||
[
|
||||
{% for page in site.tooltips %}
|
||||
{
|
||||
"id" : "{{ page.id }}",
|
||||
"body": "{{ page.content | strip_newlines | replace: '\', '\\\\' | replace: '"', '\\"' }}"
|
||||
} {% unless forloop.last %},{% endunless %}
|
||||
{% endfor %}
|
||||
]
|
||||
}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This code will loop through all pages in the tooltips collection and insert the id and body into key-value pairs for the JSON code. Here's an example of what that looks like after it's process by Jekyll in the site build: <a target="_blank" title="ToolTip Demo" href="{{ "/tooltips.json" | prepend: site.baseurl }}">Tooltips</a>.
|
||||
|
||||
{{tip}} Check out <a href="https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml">Google's style guide for JSON</a>. These best practices can help you keep your JSON file valid.{{end}}
|
||||
|
||||
Store this file in your root directory. You can add different fields depending on how you want the JSON to be structured. Here I just have to fields: `id` and `body`. And the JSON is looking just in the tooltips collection that I created.
|
||||
|
||||
When you build your site, Jekyll will iterate through every page in your _tooltips folder and put the page id and body into this format.
|
||||
|
||||
You could create different JSON files that specialize in different content. For example, suppose you have some getting started information. You could put that into a different JSON file. Using the same structure, you might add an `if` tag that checks whether the page has frontmatter that says "getting_started: true" or something. Or you could put it into a separate collection entirely (different from tooltips).
|
||||
|
||||
By chunking up your JSON files, you can provide a quicker lookup, though I'm not sure how big the JSON file can be before you experience any latency with the jQuery lookup.
|
||||
|
||||
## 4. Allow CORS access to your help
|
||||
|
||||
When people make calls to your site *from other domains*, you must allow them access to get the content. To do this, you have to enable something called CORS (cross origin resource sharing) within the server where your help resides.
|
||||
|
||||
In other words, people are going to be executing calls to reach into your site and grab your content. Just like the door on your house, you have to unlock it so people can get in. Enabling CORS is unlocking it.
|
||||
|
||||
How you enable CORS depends on the type of server.
|
||||
|
||||
If your server setup allows htaccess files to override general server permissions, then create an .htaccess file and add the following:
|
||||
|
||||
```
|
||||
Header set Access-Control-Allow-Origin "*"
|
||||
```
|
||||
|
||||
Store this in the same directory as your project. This is what I've done in a directory on my web host (bluehost.com). Inside http://idratherbewriting.com/wp-content/apidemos/, I uploaded a file called htaccess with the preceding code. After I uploaded it, I renamed it to .htaccess, right-clicked the file and set the permissions to 774.
|
||||
|
||||
To test whether your server permissions are set correctly, open a terminal and run the following curl command pointing to your tooltips.json file:
|
||||
|
||||
```
|
||||
curl -I http://idratherbewriting.com/wp-content/apidemos/tooltips.json
|
||||
```
|
||||
|
||||
If the server permissions are set correctly, you should see the following line somewhere in the response:
|
||||
|
||||
```xml
|
||||
Access-Control-Allow-Origin: *
|
||||
```
|
||||
|
||||
If you don't see this response, CORS isn't allowed for the file.
|
||||
|
||||
If you have an AWS S3 bucket, you can supposedly add a CORS configuration to the bucket permissions. Log into AWS S3 and click your bucket. On the right, in the Permissions section, click **Add CORS Configuration**. In that space, add the following policy:
|
||||
|
||||
```xml
|
||||
<CORSConfiguration>
|
||||
<CORSRule>
|
||||
<AllowedOrigin>*</AllowedOrigin>
|
||||
<AllowedMethod>GET</AllowedMethod>
|
||||
</CORSRule>
|
||||
</CORSConfiguration>
|
||||
```
|
||||
|
||||
Although this should work, in my experiment it doesn't. And I'm not sure why...
|
||||
|
||||
In other server setups, you may need to edit one of your Apache configuration files. See [Enable CORS](http://enable-cors.org/server.html) or search online for ways to allow CORS for your server.
|
||||
|
||||
If you don't have CORS enabled, users will see a CORS error/warning message in the console of the page making the request.
|
||||
|
||||
## 5. Explain how developers can access the help
|
||||
|
||||
Developers can access the help using the `.get` method from jQuery, among other methods. Here's an example of how to get a page with the ID of `basketball`:
|
||||
|
||||
{% raw %}
|
||||
```js
|
||||
<script type="text/javascript">
|
||||
$(document).ready(function(){
|
||||
|
||||
var url = "{{site.baseurl}}/tooltips.json";
|
||||
|
||||
|
||||
$.get( url, function( data ) {
|
||||
|
||||
$.each(data.entries, function(i, page) {
|
||||
if (page.id == "basketball") {
|
||||
$( "#basketball" ).attr( "data-content", page.body );
|
||||
}
|
||||
|
||||
});
|
||||
});
|
||||
|
||||
});
|
||||
</script>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
The `url` is where your tooltips.json file is. The `each` method looks through all the JSON content to find the item whose `page.id` is `basketball`. It then looks for an element on the page named `#basketball` and adds a `data-content` attribute to that element.
|
||||
|
||||
{{warning}}<b>Note:</b> Make sure your JSON file is valid. Otherwise, this method won't work. I use the <a href="https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa?hl=en">JSON Formatter extension for Chrome</a>. When I go to the tooltips.json page in my browser, the JSON content -- if valid -- is nicely formatted (and includes some color coding). If the file isn't valid, it's not formatted and there isn't any color. You can also check the JSON formatting using <a href="http://jsonformatter.curiousconcept.com/">JSON Formatter and Validator</a>. If your JSON file isn't valid, identify the problem area using the validator and troubleshoot the file causing issues. It's usually due to some code that isn't escaping correctly. {{end}}
|
||||
|
||||
Why `data-content`? Well, in this case, I'm using [Bootstrap popovers](http://getbootstrap.com/javascript/#popovers) to display the tooltip content. The `data-content` attribute is how Bootstrap injects popovers.
|
||||
|
||||
Here's the section on the page where the popover is inserted:
|
||||
|
||||
```
|
||||
<p>Basketball <span class="glyphicon glyphicon-info-sign" id="basketball" data-toggle="popover"></span></p>
|
||||
```
|
||||
|
||||
Notice that I just have `id="basketball"` added to this popover element. Developers merely need to add a unique ID to each tooltip they want to pull in the help content. Either you tell developers the unique ID they should add, or ask them what IDs they added (or just tell them to use an ID that matches the field's name).
|
||||
|
||||
In order to use jQuery and Bootstrap, you'll need to add the appropriate references in the head tags of your page:
|
||||
|
||||
```js
|
||||
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.2/css/bootstrap.min.css">
|
||||
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
|
||||
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.2/js/bootstrap.min.js"></script>
|
||||
|
||||
<script type="text/javascript">
|
||||
$(document).ready(function(){
|
||||
$('[data-toggle="popover"]').popover({
|
||||
placement : 'right',
|
||||
trigger: 'hover',
|
||||
html: true
|
||||
});
|
||||
```
|
||||
|
||||
By the way, Bootstrap's popovers require you to initialize them using the above code -- they aren't turned on by default.
|
||||
|
||||
View the source code of the <a target="_blank" title="ToolTip Demo" href="{{ "/tooltip_demo.html" | prepend: site.baseurl }}">Tooltip Demo</a> for the full comments.
|
||||
|
||||
## 6. Create easy links to embed the help in your help site
|
||||
|
||||
You might also want to insert the same content into different parts of your help site. For example, if you have tooltips providing definitions for fields, you'll probably want to create a page in your help that lists those same definitions. You could use the same method developers use to pull help content into their applications. But it will probably be easier to simply use Jekyll's tags for doing it.
|
||||
|
||||
|
||||
Here's a demo:
|
||||
|
||||
```html
|
||||
<h2>Reuse Demo</h2>
|
||||
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Sport</th>
|
||||
<th>Comments</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
|
||||
<tr>
|
||||
<td>Basketball</td>
|
||||
<td>{{site.data.definitions.basketball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Baseball</td>
|
||||
<td>{{site.data.definitions.baseball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Football</td>
|
||||
<td>{{site.data.definitions.football}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Soccer</td>
|
||||
<td>{{site.data.definitions.soccer}}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
```
|
||||
|
||||
And here's the code:
|
||||
|
||||
<h2>Reuse Demo</h2>
|
||||
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Sport</th>
|
||||
<th>Comments</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
|
||||
<tr>
|
||||
<td>Basketball</td>
|
||||
<td>{{site.data.definitions.basketball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Baseball</td>
|
||||
<td>{{site.data.definitions.baseball}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Football</td>
|
||||
<td>{{site.data.definitions.football}}</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Soccer</td>
|
||||
<td>{{site.data.definitions.soccer}}</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
title: Search configuration
|
||||
permalink: /search_configuration/
|
||||
audience: writer, designer
|
||||
tags: publishing
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
The search is configured through the search.json file in the root directory. Take a look at that code if you want to change what content is included.
|
||||
|
||||
The search is a simple search that looks at content in pages or posts. It looks at both titles and bodies. However, the search doesn't work like google -- you can't hit return and see a list of results on the search results page, with the keywords in bold. Instead, this search shows a list of page titles that contain keyword matches. It's fast, but simple.
|
||||
|
||||
|
||||
## Excluding pages form search
|
||||
|
||||
By default, every page is included in the search. The configuration file specifies this default in the frontmatter of every page:
|
||||
|
||||
```
|
||||
defaults:
|
||||
-
|
||||
scope:
|
||||
path: ""
|
||||
type: "pages"
|
||||
values:
|
||||
layout: "page"
|
||||
comments: true
|
||||
search: true
|
||||
-
|
||||
scope:
|
||||
path: ""
|
||||
type: "posts"
|
||||
values:
|
||||
layout: "post"
|
||||
comments: true
|
||||
search: true
|
||||
```
|
||||
|
||||
Some pages will break the JSON formatting. If that happens, then the search will no longer work. If you want to exclude a page from search add `search: exclude` in the frontmatter.
|
||||
|
||||
## Troubleshooting search
|
||||
|
||||
You should exclude any files from search that you don't want appearing in the search results. For example, if you have a tooltips.json file or prince-file-list.txt, don't include it, as the formatting will break the JSON format.
|
||||
|
||||
If any formatting in the search.json file is invalid (in the build), search won't work. You'll know that search isn't working if no results appear when you start typing in the search box.
|
||||
|
||||
If this happens, go directly to the search.json file in your browser, and then copy the content. Go to a [JSON validator](http://jsonlint.com/) and paste in the content. Look for the line causing trouble. Edit the file to either exclude it from search or fix the syntax so that it doesn't invalidate the JSON.
|
||||
|
||||
The search.json file already tries to strip out content that would otherwise make the JSON invalid:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```
|
||||
"body": "{{ page.content | strip_html | strip_newlines | replace: '\', '\\\\' | replace: '"', '\\"' }}",
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
However, it's possible that the formatting may not account for all the scenarios that would invalidate the JSON.
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Setting up iTerm Profiles
|
||||
permalink: /iterm_profiles/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated: May 13, 2015
|
||||
summary: "Set up profiles in iTerm to facilitate the build process. This can make it a lot easier to quickly build multiple outputs."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
When you're working with tech docs, a lot of times you're single sourcing multiple outputs. It can be a hassle to fire up each one of these outputs using the build files containing the shell scripts. Instead, it's easier to configure iTerm with profiles that initiate the scripts.
|
||||
|
||||
## Set up profiles
|
||||
|
||||
1. Open iTerm and go to **Profiles > Open Profiles.**
|
||||
2. Click **Edit Profiles**.
|
||||
3. Click the + button in the lower-left corner to create a new profile.
|
||||
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:
|
||||
|
||||
```
|
||||
. build_designer.sh
|
||||
```
|
||||
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.
|
||||
|
||||
## Launching a profile
|
||||
|
||||
1. Make sure the Toolbar is shown. Go to **View > Toggle Toolbar**.
|
||||
2. Click the **New** button and select your profile.
|
||||
|
||||
{{tip}} When you're done with the session, make sure to click **Ctrl+C**.{{end}}
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
title: Build arguments
|
||||
permalink: /build_arguments/
|
||||
tags: [single-sourcing, publishing]
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## How to build Jekyll sites
|
||||
|
||||
The normal way to build the Jekyll site is through the build command:
|
||||
|
||||
```
|
||||
jekyll build
|
||||
```
|
||||
|
||||
To build the site and view it in a live server, use the `serve` command:
|
||||
|
||||
```
|
||||
jekyll serve
|
||||
```
|
||||
|
||||
By default, the _config.yml 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.
|
||||
|
||||
```
|
||||
jekyll serve --config configs/config_writer.yml --destination /users/tjohnson/projects/documentation-theme-jekyll-builds/writer
|
||||
```
|
||||
|
||||
Here the configs/config_writer.yml file is used instead of _config.yml. The destination directory is /users/tjohnson/projects/documentation-theme-jekyll-builds/writer.
|
||||
|
||||
In order to exclude pages from being included in the build, use the `exclude` property in the configuration file:
|
||||
|
||||
```
|
||||
exclude:
|
||||
- "README.md"
|
||||
- "CHANGELOG.md"
|
||||
- "CNAME"
|
||||
- "Gemfile"
|
||||
- "Gemfile.lock"
|
||||
- content/web
|
||||
- content/acme/drafts
|
||||
```
|
||||
|
||||
These files or directories will be excluded from the build.
|
||||
|
||||
## 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 build_writer.sh file in the root directory.
|
||||
|
||||
To run the script:
|
||||
|
||||
Open Terminal and go to the directory. The first time, you may need to change the file permissions to make the sh file executable:
|
||||
|
||||
```
|
||||
chmod +x build_writer.sh
|
||||
```
|
||||
|
||||
Now to execute the build script, do this:
|
||||
|
||||
```
|
||||
. build_writer.sh
|
||||
```
|
||||
|
||||
A similar file is set up for the designer output. Note that the port listed in the configuration file for each build must be unique.
|
||||
|
||||
## Stop a server
|
||||
|
||||
When you're doing with the preview server, press `Ctrl+C` to exit out of it. If you exit Terminal without shutting down the server, the next time you build your site, you may get a server-already-in-use message.
|
||||
|
||||
You can kill the server process using these commands:
|
||||
|
||||
`ps aux | grep jekyll`
|
||||
|
||||
Find the PID (for example, it looks like "22298").
|
||||
|
||||
Then type `kill -9 22298` where "22298" is the PID.
|
||||
|
||||
|
||||
@@ -1,132 +0,0 @@
|
||||
---
|
||||
title: Conditional logic
|
||||
permalink: /conditional_logic/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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.
|
||||
|
||||
{{tip}} Definitely check out [Liquid's documentation](http://docs.shopify.com/themes/liquid-documentation/basics) for more details about how to use operators and other liquid markup. The notes here are a small, somewhat superficial sample from the site.{{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.
|
||||
|
||||
## 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:
|
||||
|
||||
```
|
||||
audience: writer
|
||||
```
|
||||
|
||||
On a page in my site (it can be HTML or markdown), I can conditionalize content using the following:
|
||||
|
||||
|
||||
{% comment %}
|
||||
{% raw %}
|
||||
```
|
||||
{% if site.audience == "writer" %}
|
||||
The writer audience should see this...
|
||||
{% elsif site.audience == "designer" %}
|
||||
The designer audience should see this ...
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
{% endcomment %}
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Here's an example of `if-else` logic inside a list:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
To bake a casserole:
|
||||
|
||||
1. Gather the ingredients.
|
||||
{% if site.audience == "writer" %}
|
||||
2. Add in a pound of meat.
|
||||
{% elsif site.audience == "designer" %}
|
||||
3. Add in an extra can of beans.
|
||||
{% endif %}
|
||||
3. Bake in oven for 45 min.
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Here's an example of using conditional logic based on a value in a data file:
|
||||
|
||||
{% comment %}
|
||||
{% raw %}
|
||||
```
|
||||
{% if site.data.options.audience == "web" %}
|
||||
show this web content...
|
||||
{% elsif site.data.options.audience == "acme" %}
|
||||
show this acme content...
|
||||
{% else %}
|
||||
this shows if neither of the above two if conditions are met.
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
{% endcomment %}
|
||||
|
||||
Here is my _data folder I have a file called options where the audience property is stored.
|
||||
|
||||
|
||||
## Or operator
|
||||
|
||||
You can use more advanced Liquid markup for conditional logic, such as an `or` command. See [Shopify's Liquid documentation](http://docs.shopify.com/themes/liquid-documentation/basics/operators) for more details.
|
||||
|
||||
For example, here's an example using `or`:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% if site.audience contains "vegan" or site.audience == "vegetarian" %}
|
||||
// run this.
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
With conditional statements, you don't need the elsif or else options.
|
||||
|
||||
## Specifying a data source
|
||||
|
||||
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.
|
||||
|
||||
For example, suppose you have 2 projects: alpha and beta. You might store all the data files for alpha inside data_alpha, and all the data files for beta inside data_beta.
|
||||
|
||||
In your configuration file, specify the data source like this:
|
||||
|
||||
```
|
||||
data_source: data_alpha
|
||||
```
|
||||
|
||||
Then create a folder called data_alpha.
|
||||
|
||||
## 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 %}
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: Content reuse
|
||||
permalink: /content_reuse/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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 folder, and then use a tag like this:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% include 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 for more information on that.
|
||||
|
||||
## Page-level variables
|
||||
|
||||
You can also create custom variables in your frontmatter like this:
|
||||
|
||||
```
|
||||
---
|
||||
title: Page-level variables
|
||||
permalink: /page_level_variables/
|
||||
thing1: Joe
|
||||
thing2: Dave
|
||||
---
|
||||
```
|
||||
|
||||
You can then access the values in those custom variables using the `page` namespace, like this:
|
||||
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
thing1: {{page.thing1}}
|
||||
thing2: {{page.thing2}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: Excluding files and folders
|
||||
permalink: /excluding_files/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
By default, all files in your project are included in your output. To exclude files, note them in the `exclude` section in the configuration file. Here's a sample:
|
||||
|
||||
```
|
||||
|
||||
exclude:
|
||||
- "Gemfile"
|
||||
- "Gemfile.lock"
|
||||
- drafts
|
||||
- _site/documentation-theme-jekyll
|
||||
- bower_components
|
||||
```
|
||||
|
||||
If you have different outputs for your site, you'll want to customize the exclude sections in your various configuration files.
|
||||
|
||||
For example, suppose you have two have two projects: alpha and beta. You would create a subfolder under pages at pages/alpha, and likewise pages/beta. In your configuration file for the alpha project, you add pages/beta to the exclude directory. In your configuration file for the beta project, you add the pages/alpha project to the exclude directory.
|
||||
|
||||
There isn't a way to automatically exclude all folders. By default, everything is included unless you explicitly list it under the exclude section.
|
||||
|
||||
## Excluding draft content
|
||||
|
||||
If you're working on a draft, put it inside the pages/drafts folder. Specify in your `exclude` section in the configuration file that this folder should be excluded. You can also create a folder called `_drafts` in the root directory. Content inside `_drafts` will automatically be excluded from builds by Jekyll.
|
||||
@@ -1,136 +0,0 @@
|
||||
---
|
||||
title: FAQ
|
||||
permalink: /faq/
|
||||
tags: special-layouts
|
||||
audience: writer, designer
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
If you want to use an FAQ format, use the syntax shown on the faq.html page.
|
||||
|
||||
<p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>
|
||||
|
||||
<div class="panel-group" id="accordion">
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseOne">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseOne" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseTwo">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseTwo" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseThree">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseThree" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseFour">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseFour" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseFive">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseFive" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseSix">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseSix" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseSeven">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseSeven" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseEight">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseEight" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseNine">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseNine" class="panel-collapse collapse">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!-- /.panel -->
|
||||
</div>
|
||||
<!-- /.panel-group -->
|
||||
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Knowledge-base homepage
|
||||
permalink: /kb_layout/
|
||||
tags: special-layouts
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
metadata: false
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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 could also add captions below each icon, and so forth. In a real implementation, you would probably make your own square graphics that included the text inside them.
|
||||
|
||||
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a href="{{ "/tag-getting-started" | prepend: site.baseurl }}"><i class="fa fa-server fa-7x border"></i></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-overview" | prepend: site.baseurl }}"><i class="fa fa-bar-chart-o fa-7x border"></i></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-single-sourcing" | prepend: site.baseurl }}"><i class="fa fa-code fa-7x border"></i></a></div>
|
||||
</div>
|
||||
<p> </p>
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a href="{{ "/tag-publishing" | prepend: site.baseurl }}"><i class="fa fa-dashboard fa-7x border"></i></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-special-layouts" | prepend: site.baseurl }}"><i class="fa fa-desktop fa-7x border"></i></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-formtting" | prepend: site.baseurl }}"><i class="fa fa-cloud fa-7x border"></i></a></div>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
## Linking to non-tag archive pages
|
||||
|
||||
If you don't want to link to a tag archive index, you could link to a page with code like this:
|
||||
{% raw %}
|
||||
```html
|
||||
Here are all pages tagged with getting_started:
|
||||
|
||||
<ul>
|
||||
{% assign counter = '0' %}
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "getting-started" and counter < '25' %}
|
||||
{% capture counter %}{{ counter | plus:'1' }}{% endcapture %}
|
||||
<li><a href="{{ page.permalink | prepend: site.baseurl }}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
```
|
||||
{% endraw %}
|
||||
@@ -1,238 +0,0 @@
|
||||
---
|
||||
title: Scroll demo
|
||||
permalink: /scroll/
|
||||
type: scroll
|
||||
audience: writer, designer
|
||||
tags: special-layouts
|
||||
last_updated:
|
||||
summary:
|
||||
metadata: false
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
<p>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.</p>
|
||||
|
||||
<script src="{{ "/js/jquery.scrollTo.min.js" | prepend:site.baseurl }}"></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" | prepend:site.baseurl }}"></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-4-->
|
||||
|
||||
<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>Fusce rhoncus elit sed quam laoreet placerat. Praesent lacinia metus quis felis mollis, ac facilisis risus consequat. Phasellus laoreet feugiat lacus. Etiam a neque est. </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-5-->
|
||||
</div> <!-- end small-box-links -->
|
||||
</div> <!-- end row -->
|
||||
</div> <!-- end container -->
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,105 +0,0 @@
|
||||
---
|
||||
title: Series pages
|
||||
permalink: /series/
|
||||
tags: []
|
||||
keywords: series
|
||||
audience: writers, designers
|
||||
last_updated: May 17, 2015
|
||||
summary: "You can automatically link together topics belonging to the same series. This helps users know the context within a particular process."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Demo
|
||||
|
||||
Here's a demo that pulls together three posts that are part of an "acme_series".
|
||||
|
||||
{% assign pages = site.pages | sort:"weight" %}
|
||||
<ol>
|
||||
{% for p in pages %}
|
||||
{% if p.series == "acme_series" %}
|
||||
<li>
|
||||
<b><a {% if p.url == page.url %}class="active"{% endif %} href="{{p.url | prepend: site.baseurl | append: site.suffix}}">{{p.title}}</a>.</b> {{p.summary}}
|
||||
</li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ol>
|
||||
|
||||
When you click on each link, you'll see a Series selector that looks like this:
|
||||
|
||||
{% include custom/acme_series.html %}
|
||||
|
||||
None of the pages in the list are highlighted because you're not on that page. If you go to a series page, the active page isn't linked, appears in bold, and has a left arrow pointing to it. This allows the user to know where he or she is within the series.
|
||||
|
||||
Why the drop-down? If you have just 2-3 pages in a series, you don't need the drop-down menu. But if you have 8+ items in the series, it gets to be lengthy. The display is one way of moving it out of the reader's way.
|
||||
|
||||
## Create a series
|
||||
|
||||
To create a series, follow the sections below.
|
||||
|
||||
### 1. Add frontmatter to your series pages
|
||||
|
||||
In the frontmatter of your series pages, add these two values:
|
||||
|
||||
```
|
||||
series: acme_deploy
|
||||
weight: 1
|
||||
```
|
||||
|
||||
Call your series whatever you want.
|
||||
|
||||
The weight represents the sorting order for the series. Use numerical values to represent the order of the series posts.
|
||||
|
||||
### 2. Create the series include
|
||||
|
||||
In _includes/custom, create a new file such as acme_series.html. In the file, create a loop that looks like this:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<div class="seriesContext">
|
||||
<div class="btn-group">
|
||||
<button type="button" data-toggle="dropdown" class="btn btn-primary dropdown-toggle">Acme Process <span class="caret"></span></button>
|
||||
<ol class="dropdown-menu">
|
||||
{% assign pages = site.pages | sort:"weight" %}
|
||||
{% for p in pages %}
|
||||
{% if p.series == "acme" %}
|
||||
{% if p.url == page.url %}
|
||||
<li class="active"> → {{p.weight}}. {{p.title}}</li>
|
||||
{% else %}
|
||||
<li>
|
||||
<a href="{{p.url | prepend: site.baseurl | append: site.suffix}}">{{p.weight}}. {{p.title}}</a>
|
||||
</li>
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ol>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Change the name of the series from `acme_series' to your own series (as you've named it in your frontmatter). Adjust any other styling for the content.
|
||||
|
||||
This code sorts pages by weight. It then uses a `for` loop to look through the pages to find all pages that have the specified series. It then arranges the pages into a list.
|
||||
|
||||
The list is packaged into a Bootstrop drop-down menu. If you don't want the drop-down menu, remove the code outside of the `ol` tags.
|
||||
|
||||
|
||||
### 3. Add the include on each of your series pages
|
||||
|
||||
For each of the pages in the series, add this near the top (below the linkrefs.html include):
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% include custom/acme_series.html %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
{{warning}} Be careful not to add too many `for` loops to your pages. Each `for` loop you add will impact the build time of your Jekyll site. This is because Liquid (where the `for` loop logic comes from, is slow.{{end}}
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: Series demo 1
|
||||
permalink: /seriesdemo1/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated: May 17, 2015
|
||||
summary: "This is the first post in the series."
|
||||
series: acme_series
|
||||
weight: 1
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
{% include custom/acme_series.html %}
|
||||
|
||||
This is the first post in the series.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,22 +0,0 @@
|
||||
---
|
||||
title: Series demo 2
|
||||
permalink: /seriesdemo2/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated: May 17, 2015
|
||||
summary: "This is the second post in the series."
|
||||
series: acme_series
|
||||
weight: 2
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
{% include custom/acme_series.html %}
|
||||
|
||||
This is the second post in the series.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
title: Series demo 3
|
||||
permalink: /seriesdemo3/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated: May 17, 2015
|
||||
summary: "This is the third post in the series."
|
||||
series: acme_series
|
||||
weight: 3
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
{% include custom/acme_series.html %}
|
||||
|
||||
This is the third post in the series.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,161 +0,0 @@
|
||||
---
|
||||
title: Shuffle
|
||||
permalink: /shuffle/
|
||||
tags: special-layouts
|
||||
type: noTags
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
metadata: false
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
<script src="{{ "/js/jquery.shuffle.min.js" | prepend:site.baseurl }}"></script>
|
||||
<script src="{{ "/js/jquery.ba-throttle-debounce.min.js" | prepend:site.baseurl }}"></script>
|
||||
|
||||
<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="single-sourcing">Single Sourcing</button>
|
||||
<button class="btn btn-primary" data-group="special-layouts">Special Layouts</button>
|
||||
<button class="btn btn-primary" data-group="news">News</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-danger">
|
||||
<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.permalink | prepend: site.baseurl }}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["news"]'>
|
||||
|
||||
<div class="panel panel-info">
|
||||
<div class="panel-heading">Latest news</div>
|
||||
<div class="panel-body">Here's the latest news about this theme. These links point to posts rather than pages.
|
||||
<ul>
|
||||
{% for post in site.posts %}
|
||||
{% for tag in post.tags %}
|
||||
{% if tag == "news" %}
|
||||
<li><a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{ post.title }}</a> ({{ post.date | date: "%b %-d, %Y" }})</li>
|
||||
<div class="summary">{{post.summary}}</div>
|
||||
{% 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-danger">
|
||||
<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>
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "formatting" %}
|
||||
<li><a href="{{ page.permalink | prepend: site.baseurl }}">{{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:
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "single-sourcing" %}
|
||||
<li><a href="{{ page.permalink | prepend: site.baseurl }}">{{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-primary">
|
||||
<div class="panel-heading">Publishing</div>
|
||||
<div class="panel-body">
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "publishing" %}
|
||||
<li><a href="{{ page.permalink | prepend: site.baseurl }}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div class="col-xs-6 col-sm-4 col-md-4" data-groups='["special-layouts"]'>
|
||||
|
||||
<div class="panel panel-warning">
|
||||
<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.permalink | prepend: site.baseurl }}">{{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 -->
|
||||
|
||||
{% include initialize_shuffle.html %}
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Special layouts
|
||||
permalink: /special_layouts/
|
||||
tags: special-layouts
|
||||
keywords:
|
||||
audience: writer, designer
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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.
|
||||
|
||||
## FAQ layout
|
||||
|
||||
See the faq.html page for an example of the FAQ format, which follows an accordion, collapse/expand format. This code is from Bootstrap.
|
||||
|
||||
## Knowledgebase layout
|
||||
|
||||
See the kb_layout.md 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 scroll.html layout. 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 shuffle.html. This uses the Shuffle JS library.
|
||||
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
title: Tag archives overview
|
||||
permalink: /tag-archives-overview/
|
||||
audience: customers, field engineers
|
||||
tags:
|
||||
keywords: tags
|
||||
last_updated: May 4, 2015
|
||||
---
|
||||
|
||||
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.
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Content Types Pages"
|
||||
permalink: /tag-content-types/
|
||||
tagName: content-types
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Formatting Pages"
|
||||
permalink: /tag-formatting/
|
||||
tagName: formatting
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Getting Started Pages"
|
||||
permalink: /tag-getting-started/
|
||||
tagName: getting-started
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Overview Pages"
|
||||
permalink: /tag-overview/
|
||||
tagName: overview
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Publishing Pages"
|
||||
permalink: /tag-publishing/
|
||||
tagName: publishing
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Single-Sourcing Pages"
|
||||
permalink: /tag-single-sourcing/
|
||||
metadata: false
|
||||
tagName: single-sourcing
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
title: "Special Layout Pages"
|
||||
permalink: /tag-special-layouts/
|
||||
metadata: false
|
||||
tagName: special-layouts
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
Reference in New Issue
Block a user