removing gh-pages branch and putting everything in master
This commit is contained in:
Tom Johnson
9
pages/about.md
Normal file
9
pages/about.md
Normal file
@ -0,0 +1,9 @@
|
||||
---
|
||||
title: About
|
||||
permalink: /about/
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
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.
|
||||
88
pages/formatting/alerts.md
Normal file
88
pages/formatting/alerts.md
Normal file
@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Alerts
|
||||
permalink: /alerts/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
---
|
||||
{% 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.
|
||||
|
||||
170
pages/formatting/icons.md
Normal file
170
pages/formatting/icons.md
Normal file
@ -0,0 +1,170 @@
|
||||
---
|
||||
title: Icons
|
||||
permalink: /icons/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## 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 %}
|
||||
|
||||
|
||||
36
pages/formatting/images.md
Normal file
36
pages/formatting/images.md
Normal file
@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Images
|
||||
permalink: /images/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
26
pages/formatting/labels.md
Normal file
26
pages/formatting/labels.md
Normal file
@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Labels
|
||||
permalink: /labels/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
---
|
||||
|
||||
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.
|
||||
64
pages/formatting/links.md
Normal file
64
pages/formatting/links.md
Normal file
@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Links
|
||||
permalink: /links/
|
||||
audience: writer, designer
|
||||
tags: [formatting, navigation]
|
||||
---
|
||||
|
||||
## 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.
|
||||
80
pages/formatting/pages.md
Normal file
80
pages/formatting/pages.md
Normal file
@ -0,0 +1,80 @@
|
||||
---
|
||||
title: Pages
|
||||
permalink: /pages/
|
||||
audience: writer, designer
|
||||
tags: [getting-started, formatting]
|
||||
---
|
||||
|
||||
Use a text editor such as Sublime Text, WebStorm, or Emacs to create pages. Make sure each page has frontmatter at the top like this:
|
||||
|
||||
```
|
||||
---
|
||||
title: Getting started
|
||||
permalink: /getting_started/
|
||||
tags: newbies
|
||||
---
|
||||
```
|
||||
|
||||
Frontmatter is always formatted with three hyphens at the top and bottom. Your frontmatter must have a `title` and `permalink` value. The `tags` property is optional but potentially useful for knowledge-base articles. Make all tags single words, with hyphens if needed. Separate them with commas.
|
||||
|
||||
Pages can be either Markdown or HTML format. 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, 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.
|
||||
|
||||
## Pages versus posts
|
||||
|
||||
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. {{end}}
|
||||
|
||||
## 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:
|
||||
|
||||
- don't italicize words with underscores
|
||||
- allow three backticks before and after code blocks instead of `<pre>` tags
|
||||
- automatically create links out of URLs
|
||||
- allow table syntax
|
||||
- add ID tags to headings automatically
|
||||
|
||||
|
||||
## 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.
|
||||
35
pages/formatting/syntax_highlighting.md
Normal file
35
pages/formatting/syntax_highlighting.md
Normal file
@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Syntax highlighting
|
||||
permalink: /syntax_highlighting/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
---
|
||||
|
||||
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
|
||||
```
|
||||
117
pages/formatting/tables.md
Normal file
117
pages/formatting/tables.md
Normal file
@ -0,0 +1,117 @@
|
||||
---
|
||||
title: Tables
|
||||
permalink: /tables/
|
||||
---
|
||||
|
||||
## 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>
|
||||
25
pages/formatting/videos.md
Normal file
25
pages/formatting/videos.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Videos
|
||||
permalink: /videos/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
---
|
||||
|
||||
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.)
|
||||
65
pages/getting_started.md
Normal file
65
pages/getting_started.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Getting started
|
||||
permalink: /getting_started/
|
||||
tags: getting-started
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
* 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. This should already be installed. Type `which ruby` to confirm.
|
||||
* [Rubygems](https://rubygems.org/pages/download). This is a package manager for Ruby (gems).
|
||||
* Jekyllrb. To install: `gem install jekyll`
|
||||
* * [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, Emacs)
|
||||
* [iTerm](http://iterm.sourceforge.net/) - optional but recommended instead of Terminal.
|
||||
|
||||
{{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}}
|
||||
|
||||
## Build the theme
|
||||
|
||||
Because this theme is intended to build multiple outputs from the same project, it doesn't use the default _config.yml file like other Jekyll themes. Instead, each different output has its own config file in the configs directory.
|
||||
|
||||
Each config file has a different preview port and build destination. It also specifies a different audience.
|
||||
|
||||
You build the sites by using more specific build commands, like this:
|
||||
|
||||
```
|
||||
jekyll serve --config configs/config_writer.yml --destination /users/tjohnson/projects/documentation-theme-jekyll-builds/writer
|
||||
```
|
||||
Because these commands are long and bulky, it's easier to store them in a small shell script and then run the script. In the root directory, you'll find build_writer.sh, which simply contains this build argument. Instead of running the command above, run the following:
|
||||
|
||||
```
|
||||
. build_writer.sh
|
||||
```
|
||||
|
||||
If you run into permissions errors trying to run the .sh file, you may need to change the file permissions to make the sh file executable. To do that, browse to the directory containing build_writer.sh and run the following:
|
||||
|
||||
```
|
||||
chmod +x build_writer.sh
|
||||
```
|
||||
|
||||
## Customizing the theme
|
||||
|
||||
The theme shows two build outputs: one for designers, and one for writers. Here's how you would customize the theme. In these instructions, I'll assume your project's name is "acme."
|
||||
|
||||
1. Using iTerm, go to the directory where you want to install the project. I like using ~[username]/projects, because ~[username] is the default directory that appears when you open iTerm on a Mac.
|
||||
2. git clone `https://github.com/tomjohnson1492/documentation-theme-jekyll.git .`
|
||||
3. Rename the documentation-theme-jekyll folder to acme.
|
||||
4. In the theme's configs directory, rename config_writer.yml to config_acme.yml and customize all the values based on the instructions in that file. Do the same with config_designer.yml if you have additional outputs.
|
||||
5. In the _includes directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace writer with your audience, and designer with another audience.)
|
||||
5. Add your pages inside the pages folder. (Using subfolders and sub-subfolders inside pages is all right -- you don't have to worry about folder paths in links.)
|
||||
5. Inside _data, open sidebar.yml and topnav.yml and customize the navigation. (Don't mess up the spacing or change any of the level names or the site won't build.)
|
||||
6. In the root directory, rename build_writer.sh to build_acme.sh (same with build_designer.sh for additional outputs). In the file's contents, change the build parameters to point to the configuration file and destination/output directory that you want.
|
||||
6. Build your site with `. build_writer.sh` and preview it at the URL provided.
|
||||
|
||||
If you have 10 different outputs, you'll have 10 separate configuration files in your configs directory, and probably 10 different shell scripts containing build arguments for each configuration.
|
||||
|
||||
{{callout_info}}If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other host.{{end}}
|
||||
|
||||
## Questions
|
||||
|
||||
If you have questions, contact me at tomjohnson1492@gmail.com. My regular site is [http://idratherbewriting.com](idratherbewriting.com).
|
||||
|
||||
|
||||
20
pages/navigation/navigation.md
Normal file
20
pages/navigation/navigation.md
Normal file
@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Navigation
|
||||
permalink: /navigation/
|
||||
audience: writer, designer
|
||||
tags: navigation
|
||||
---
|
||||
|
||||
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 nav
|
||||
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.)
|
||||
|
||||
45
pages/navigation/tags copy.md
Normal file
45
pages/navigation/tags copy.md
Normal file
@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Tags
|
||||
permalink: /tags/
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
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 %}
|
||||
45
pages/navigation/tags.md
Normal file
45
pages/navigation/tags.md
Normal file
@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Tags
|
||||
permalink: /tags/
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
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 %}
|
||||
64
pages/overview/homepage.md
Normal file
64
pages/overview/homepage.md
Normal file
@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Documentation theme for Jekyll
|
||||
permalink: "/"
|
||||
audience: writer, designer
|
||||
tags: getting-started
|
||||
---
|
||||
|
||||
This is a Jekyll theme intended for documentation projects. What makes this theme unique is the approach in using Jekyll for single sourcing, that is, producing multiple outputs from the same theme. For example, you might have 3 different help systems that you're generating from the same Jekyll project files. More than anything, this Jekyll theme shows you how to use Jekyll for documentation projects from the perspective of a technical writer.
|
||||
|
||||
## Intended audience
|
||||
|
||||
Although this theme could be used for any website, I'm assuming that my main audience involves technical writers. Very few technical writers are even aware of Jekyll as a platform, let alone how to use it for tech comm scenarios. The instructions for this theme, therefore, are a little more extensive because they discuss a lot of Jekyll basics as well.
|
||||
|
||||
## Supported tech comm features with Jekyll
|
||||
|
||||
As far as I can tell, Jekyll supports most of the features a technical writer needs to author and publish content. See {{supported_features}} for an extensive list. Most importantly, using Jekyll allows you to take full advantage of a modern web development platform.
|
||||
|
||||
## Theme features
|
||||
|
||||
This theme specifically provides the following:
|
||||
|
||||
* Bootstrap framework
|
||||
* Font Awesome
|
||||
* Integrated search
|
||||
* Navigation sidebar with three navigation levels
|
||||
* Top navigation with single list links and drop-down links
|
||||
* PDF integration with Prince (no Prince license included)
|
||||
|
||||
## Getting started
|
||||
|
||||
To get started, see {{getting_started}}. It explains how to create a new project.
|
||||
|
||||
## Questions
|
||||
|
||||
|
||||
Feel free to ask me a question if there's something I haven't addressed here.
|
||||
|
||||
Tom Johnson <br /><a href="mailto:">tomjohnson1492@gmail.com</a><br />[idratherbewriting.com](http://idratherbewriting.com)
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
8
pages/overview/support.md
Normal file
8
pages/overview/support.md
Normal file
@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Support
|
||||
permalink: /support/
|
||||
audience: writer, designer
|
||||
tags: overview
|
||||
---
|
||||
|
||||
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).
|
||||
31
pages/overview/supported_features.md
Normal file
31
pages/overview/supported_features.md
Normal file
@ -0,0 +1,31 @@
|
||||
---
|
||||
title: Supported features
|
||||
permalink: /supported_features/
|
||||
audience: writer, designer
|
||||
tags: [overview, getting-started]
|
||||
---
|
||||
|
||||
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.)
|
||||
34
pages/publishing/create_pdf.md
Normal file
34
pages/publishing/create_pdf.md
Normal file
@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Create PDF
|
||||
permalink: /create_pdf/
|
||||
tags: publishing
|
||||
---
|
||||
|
||||
{% 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 %}
|
||||
|
||||
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-fe.css file. Change the filename to your audience. 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).)
|
||||
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 pdf_fe.sh file and customize its contents to point to the right folders on your computer (the configuration file and the output destination).
|
||||
6. In the root directory, open the pdf_writer.sh file and customize the directory paths. They should point to where this project builds, so the script can find the processed prince-file-list file and so it knows where to build the output. This .sh file allows you to run the PDF build.
|
||||
7. Browse to the directory containing pdf_writer.sh file and type `. pdf_writer.sh`.
|
||||
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.
|
||||
278
pages/publishing/help_api.md
Normal file
278
pages/publishing/help_api.md
Normal file
@ -0,0 +1,278 @@
|
||||
---
|
||||
title: Create a Help API
|
||||
permalink: /help_api/
|
||||
tags: publishing
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
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>
|
||||
55
pages/publishing/search_configuration.md
Normal file
55
pages/publishing/search_configuration.md
Normal file
@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Search configuration
|
||||
permalink: /search_configuration/
|
||||
audience: writer, designer
|
||||
tags: publishing
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
If you want to exclude a page from search add `search: exclude` in the frontmatter. By default, every page is included. The configuration file specifies this default in the frontmatter of every page:
|
||||
|
||||
```
|
||||
defaults:
|
||||
-
|
||||
scope:
|
||||
path: ""
|
||||
type: "pages"
|
||||
values:
|
||||
layout: "page"
|
||||
comments: true
|
||||
search: include
|
||||
-
|
||||
scope:
|
||||
path: ""
|
||||
type: "posts"
|
||||
values:
|
||||
layout: "post"
|
||||
comments: true
|
||||
search: include
|
||||
```
|
||||
This is why you need to add `search: exclude` if you want do not want a page to appear in search.
|
||||
|
||||
## 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, don't include it, as the formatting will be invalid in the search.
|
||||
|
||||
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 strips 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.
|
||||
77
pages/single-sourcing/build_arguments.md
Normal file
77
pages/single-sourcing/build_arguments.md
Normal file
@ -0,0 +1,77 @@
|
||||
---
|
||||
title: Build arguments
|
||||
permalink: /build_arguments/
|
||||
tags: [single-sourcing, publishing]
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
127
pages/single-sourcing/conditional_logic.md
Normal file
127
pages/single-sourcing/conditional_logic.md
Normal file
@ -0,0 +1,127 @@
|
||||
---
|
||||
title: Conditional logic
|
||||
permalink: /conditional_logic/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
---
|
||||
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 %}
|
||||
43
pages/single-sourcing/content_reuse.md
Normal file
43
pages/single-sourcing/content_reuse.md
Normal file
@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Content reuse
|
||||
permalink: /content_reuse/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
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 %}
|
||||
|
||||
|
||||
28
pages/single-sourcing/excluding_files.md
Normal file
28
pages/single-sourcing/excluding_files.md
Normal file
@ -0,0 +1,28 @@
|
||||
---
|
||||
title: Excluding files and folders
|
||||
permalink: /excluding_files/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
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.
|
||||
132
pages/special-layouts/faq.html
Normal file
132
pages/special-layouts/faq.html
Normal file
@ -0,0 +1,132 @@
|
||||
---
|
||||
title: FAQ
|
||||
permalink: /faq/
|
||||
tags: special-layouts
|
||||
audience: writer, designer
|
||||
---
|
||||
|
||||
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 -->
|
||||
|
||||
41
pages/special-layouts/kb_layout.md
Normal file
41
pages/special-layouts/kb_layout.md
Normal file
@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Knowledge-base homepage
|
||||
permalink: /kb_layout/
|
||||
tags: special-layouts
|
||||
---
|
||||
|
||||
This shows a sample layout for a knowledge base. Each square could link to a tag archive page.
|
||||
|
||||
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a href="{{ "/tag-getting-started" | prepend: site.baseurl }}"><img src="//placehold.it/300x300" class="img-responsive"></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-overview" | prepend: site.baseurl }}"><img src="//placehold.it/300x300" class="img-responsive"></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-single-sourcing" | prepend: site.baseurl }}"><img src="//placehold.it/300x300" class="img-responsive"></a></div>
|
||||
</div>
|
||||
<p> </p>
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a href="{{ "/tag-publishing" | prepend: site.baseurl }}"><img src="//placehold.it/300x300" class="img-responsive"></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-special-layouts" | prepend: site.baseurl }}"><img src="//placehold.it/300x300" class="img-responsive"></a></div>
|
||||
<div class="col-md-4"><a href="{{ "/tag-formtting" | prepend: site.baseurl }}"><img src="//placehold.it/300x300" class="img-responsive"></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 %}
|
||||
234
pages/special-layouts/scroll.html
Normal file
234
pages/special-layouts/scroll.html
Normal file
@ -0,0 +1,234 @@
|
||||
---
|
||||
title: Scroll demo
|
||||
permalink: /scroll/
|
||||
type: scroll
|
||||
audience: writer, designer
|
||||
tags: special-layouts
|
||||
---
|
||||
|
||||
<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": "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 -->
|
||||
|
||||
|
||||
|
||||
|
||||
155
pages/special-layouts/shuffle.html
Normal file
155
pages/special-layouts/shuffle.html
Normal file
@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Shuffle
|
||||
permalink: /shuffle/
|
||||
tags: special-layouts
|
||||
type: noTags
|
||||
---
|
||||
|
||||
<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>
|
||||
|
||||
|
||||
|
||||
26
pages/special-layouts/special_layouts.md
Normal file
26
pages/special-layouts/special_layouts.md
Normal file
@ -0,0 +1,26 @@
|
||||
---
|
||||
title: Special layouts
|
||||
permalink: /special_layouts/
|
||||
audience: writer, designer
|
||||
tags: special-layouts
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
|
||||
6
pages/tag-archives/tag-archives-overview.md
Normal file
6
pages/tag-archives/tag-archives-overview.md
Normal file
@ -0,0 +1,6 @@
|
||||
---
|
||||
title: Tag archives overview
|
||||
permalink: /tag-archives-overview/
|
||||
---
|
||||
|
||||
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.
|
||||
7
pages/tag-archives/tag-formatting.html
Normal file
7
pages/tag-archives/tag-formatting.html
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: "Formatting Pages"
|
||||
permalink: /tag-formatting/
|
||||
tagName: formatting
|
||||
related_pages: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
7
pages/tag-archives/tag-getting_started.html
Normal file
7
pages/tag-archives/tag-getting_started.html
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: "Getting Started Pages"
|
||||
permalink: /tag-getting-started/
|
||||
tagName: getting-started
|
||||
related_pages: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
7
pages/tag-archives/tag-overview.html
Normal file
7
pages/tag-archives/tag-overview.html
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: "Overview Pages"
|
||||
permalink: /tag-overview/
|
||||
tagName: overview
|
||||
related_pages: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
7
pages/tag-archives/tag-publishing.html
Normal file
7
pages/tag-archives/tag-publishing.html
Normal file
@ -0,0 +1,7 @@
|
||||
---
|
||||
title: "Publishing Pages"
|
||||
permalink: /tag-publishing/
|
||||
tagName: publishing
|
||||
related_pages: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
6
pages/tag-archives/tag-single-sourcing.html
Normal file
6
pages/tag-archives/tag-single-sourcing.html
Normal file
@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "Single-Sourcing Pages"
|
||||
permalink: /tag-single-sourcing/
|
||||
tagName: single-sourcing
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
6
pages/tag-archives/tag-special-layouts.html
Normal file
6
pages/tag-archives/tag-special-layouts.html
Normal file
@ -0,0 +1,6 @@
|
||||
---
|
||||
title: "Special Layout Pages"
|
||||
permalink: /tag-special-layouts/
|
||||
tagName: special-layouts
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
Reference in New Issue
Block a user