Added instructions for shortcuts, iterm profiles, collections, page frontmatter, and other documentation.
This commit is contained in:
Tom Johnson
30
pages/content_types/collections.md
Normal file
30
pages/content_types/collections.md
Normal file
@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Collections
|
||||
permalink: /collections/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## What are collections
|
||||
Collections are custom content types different from pages and posts. You might create a collection if you want to treat a specific set of articles in a unique way, such as with a custom layout or listing. For more detail on collections, see [Ben Balter's explanation of collections here](http://ben.balter.com/2015/02/20/jekyll-collections/).
|
||||
|
||||
## Create a collection
|
||||
To create a collection, add the following in your configuration file:
|
||||
|
||||
```
|
||||
collections:
|
||||
tooltips:
|
||||
output: true
|
||||
```
|
||||
|
||||
In this example, tooltips is the name of the collection.
|
||||
|
||||
## Interacting with collections
|
||||
|
||||
You can interact with collections by using the `site.<collection_namespace>` path. In this case, if I wanted to loop through all tooltips, I would use `site.tooltips` instead of `site.pages` or `site.posts`.
|
||||
|
||||
See [Collections in the Jekyll documentation](http://jekyllrb.com/docs/collections/) for more information.
|
||||
114
pages/content_types/pages.md
Normal file
114
pages/content_types/pages.md
Normal file
@ -0,0 +1,114 @@
|
||||
---
|
||||
title: Pages
|
||||
permalink: /pages/
|
||||
audience: writer, designer
|
||||
tags: [getting-started, formatting]
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Where to author content
|
||||
Use a text editor such as Sublime Text, WebStorm, or Atom to create pages.
|
||||
|
||||
My preference is WebStorm, since it will treat all files in your project as belonging to a project. This allows you to easily search for instances of keywords, do find-and-replace operations, or do other actions that apply across the whole project.
|
||||
|
||||
## Frontmatter
|
||||
Make sure each page has frontmatter at the top like this:
|
||||
|
||||
```
|
||||
---
|
||||
title:
|
||||
permalink: //
|
||||
tags: []
|
||||
keywords: audience:
|
||||
last_updated
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
```
|
||||
Frontmatter is always formatted with three hyphens at the top and bottom. Your frontmatter must have a `title` and `permalink` value. All the other values are optional.
|
||||
|
||||
The following table describes each of the frontmatter that you can use with this theme:
|
||||
|
||||
| Frontmatter | Description |
|
||||
|-------------|-------------|
|
||||
| **title** | The title for the page |
|
||||
| permalink | The URL path for the page |
|
||||
| **tags** | Tags for the page. Make all tags single words, with hyphens if needed. Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to _data/tags.yml to be allowed entrance into the page. |
|
||||
| **keywords** | Synonyms and other keywords for the page. This information gets stuffed into the page's metadata to increase SEO. The user won't see the keywords, but if you search for one of the keywords, it will be picked up by the search engine. |
|
||||
| **last_updated** | The date the page was last updated. This information is helpful for readers trying to evaluate how current and authoritative information is. |
|
||||
| **summary** | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) |
|
||||
|
||||
Only the title and permalink are actually required. If you leave the other fields blank, the theme will not show them (for example, if you leave tags blank, the theme won't show "Tags:" with nothing after it in the page metadata. Instead, the whole line will be hidden.
|
||||
|
||||
To see how these metadata values get inserted into the theme, look at the page layout, specifically the included pagemetadata.html file.
|
||||
|
||||
## Markdown or HTML format
|
||||
|
||||
Pages can be either Markdown or HTML format (specified through either an .md or .html file extension).
|
||||
|
||||
If you use Markdown, you can also include HTML formatting where needed. But not vice versa -- if you use HTML (as your file extension), you can't insert Markdown content.
|
||||
|
||||
Also, if you use HTML inside a Markdown file, you cannot use Markdown inside of HTML. But you can use HTML inside of Markdown.
|
||||
|
||||
For your Markdown files, note that a space or two indent will set text off as code or blocks, so avoid spacing indents unless intentional.
|
||||
|
||||
## Where to save pages
|
||||
|
||||
Store all your pages inside the pages folder. The number of subfolders inside your pages directory doesn't matter. You won't have to use paths (such as ../) when linking to pages. Instead, all the pages will be pulled out to the root directory (each page rendered into its own folder), and links are established through the permalink value in the page's frontmatter.
|
||||
|
||||
If you want to use a colon in your page title, you must enclose the title's value in quotation marks.
|
||||
|
||||
## 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. I'm planning to convert my blog (idratherbewriting.com) to Jekyll using this same theme, and when I do, I'll iron out all the issues with posts. {{end}}
|
||||
|
||||
## Github-flavored Markdown
|
||||
|
||||
You can use standard Multimarkdown syntax for tables. You can also use fenced code blocks. The configuration file shows the Markdown processor and extensiosn:
|
||||
|
||||
```
|
||||
markdown: redcarpet
|
||||
|
||||
redcarpet:
|
||||
extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "tables", "with_toc_data"]
|
||||
```
|
||||
These extensions mean the following:
|
||||
|
||||
| Redcarpet extension | Description |
|
||||
| --------------|---------------|
|
||||
| no_intra_emphasis | don't italicize words with underscores |
|
||||
| fenced_code_blocks | allow three backticks before and after code blocks instead of `<pre>` tags |
|
||||
| autolink | automatically create links out of URLs |
|
||||
| tables | allow table syntax |
|
||||
| with_toc_data | add ID tags to headings automatically |
|
||||
|
||||
{{note}} {% include custom/toc_id_note.html %} {{end}}
|
||||
|
||||
## Related posts
|
||||
|
||||
By default, posts contain related posts beneath them. To disable this, add `related_pages: none` or `related_posts: none` in the frontmatter of the page.
|
||||
|
||||
Pages have tags instead of related posts. (It turns out that creating "Related pages" in Jekyll is much more difficult than related posts.)
|
||||
|
||||
## Automatic mini-TOCs
|
||||
|
||||
By default, a mini-TOC appears at the top of your pages and posts. If you don't want this, you can remove the {% raw %}`{% include toc.html %}` {% endraw %} from the layouts/page.html and layouts/posts.html files.
|
||||
|
||||
If you don't want the TOC to appear for a specific page, add `toc: false` in the frontmatter of the page.
|
||||
|
||||
This frontmatter requires you to use the `##` syntax for headings. If you use `<h2>` elements, then you must add an ID attribute for the h2 element in order to get it to appear in the mini-TOC.
|
||||
|
||||
## Specify a particular page layout
|
||||
|
||||
The configuration file sets the default layout for pages as the page layout. You can create other layouts inside the layouts folder. You can then specify that the page use that particular layout by adding `layout: mylayout.html` in the page's frontmatter. Whatever layout you specify in the frontmatter of a page will override the layout default set in the configuration file.
|
||||
|
||||
## Comments
|
||||
|
||||
Disqus, a commenting system, is integrated into the theme. In the configuration file, specify the Disqus code for the universal code, and Disqus will appear. If you don't add a Disqus value, the Disqus code isn't included.
|
||||
@ -1,84 +0,0 @@
|
||||
---
|
||||
title: Pages
|
||||
permalink: /pages/
|
||||
audience: writer, designer
|
||||
tags: [getting-started, formatting]
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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.
|
||||
16
pages/formatting/shortcuts.md
Normal file
16
pages/formatting/shortcuts.md
Normal file
@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Shortcuts for Jekyll syntax
|
||||
permalink: /shortcuts_for_jekyll_syntax/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated: May 13, 2015
|
||||
summary: "You can use a typing keyword expander to make it easier to create the Jekyll syntax."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
Some of the Jekyll syntax can be slow to create. Using a utility such as [aText](https://www.trankynam.com/atext/) can make creating content a lot of faster. You get aText from the App Store on a Mac for about $5.
|
||||
|
||||
To import the shortcut keys I'm using, see the <a href="{{ "/files/shortcuts.zip" | prepend: site.baseurl }}">shortcuts.zip</a> file. After unzipping this file, you can import it into aText.
|
||||
|
||||
There are alternatives to aText, such as Typeitforme. But aText seems to work the best. Read more about it on [Lifehacker](http://lifehacker.com/5843903/the-best-text-expansion-app-for-mac).
|
||||
@ -34,7 +34,7 @@ Note that you can arbitrary key value pairs in the configuration file, and then
|
||||
| **sidebar_accordion** | Boolean. Whether you want the navigation sidebar to use the accordion effect or not. The accordion effect means when you expand a section, the other sections auto-collapse. If you put false, then you can expand multiple sections at once. At the bottom of the navigation sidebar, two links will appear: Collapse All and Expand All. |
|
||||
| **disqus_shortname** | The disqus site shortname, which is used for comments. If you don't want comment forms via disqus, leave this blank or omit altogether. |
|
||||
| **markdown** | The processer to use for Markdown. This is a Jekyll-specific setting. |
|
||||
| **redcarpet** | Extensions used with redcarpet. You can read more about them by searching for redcarpet extensions online. Make sure you leave the `with_toc_data` option included. This auto-creates an ID for each Markdown-formatted heading, which then gets injected into the mini-TOC. Without this auto-creation of IDs, the mini-TOC won't include the heading. If you ever use HTML formatting for headings, you need to manually add an ID attribute to the heading in order for the heading to appear in the mini-TOC. |
|
||||
| **redcarpet** | Extensions used with redcarpet. You can read more about them by searching for redcarpet extensions online. {% include custom/toc_id_note.html %} |
|
||||
| **highlighter** | The syntax highlighter used. Rouge is also an option. I think Pygments does a better job. You will need to [install Pygments](http://pygments.org/download/) on your machine or else you will see an error. |
|
||||
| **exclude** | A list of files and directories that you want excluded from the build. By default, all the content in your project is included in the output. |
|
||||
| **permalink** | The structure used for the link URLs. To read more about permalinks, see [Permalinks](http://jekyllrb.com/docs/permalinks/). |
|
||||
35
pages/publishing/setting_up_iterm_profiles.md
Normal file
35
pages/publishing/setting_up_iterm_profiles.md
Normal file
@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Setting up iTerm Profiles
|
||||
permalink: /iterm_profiles/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated: May 13, 2015
|
||||
summary: "Set up profiles in iTerm to facilitate the build process. This can make it a lot easier to quickly build multiple outputs."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
When you're working with tech docs, a lot of times you're single sourcing multiple outputs. It can be a hassle to fire up each one of these outputs using the build files containing the shell scripts. Instead, it's easier to configure iTerm with profiles that initiate the scripts.
|
||||
|
||||
## Set up profiles
|
||||
|
||||
1. Open iTerm and go to **Profiles > Open Profiles.**
|
||||
2. Click **Edit Profiles**.
|
||||
3. Click the + button in the lower-left corner to create a new profile.
|
||||
4. In the **Name** field, type a name describing the output, such as `Doc theme -- designers`.
|
||||
5. In the **Send text at start** field, type the command for the build script, such as this:
|
||||
|
||||
```
|
||||
. build_designer.sh
|
||||
```
|
||||
Leave the Login shell option selected.
|
||||
|
||||
6. In the Working Directory section, select **Directory** and enter the directory for your project, such as **/Users/tjohnson/projects/documentation-theme-jekyll**.
|
||||
7. Close the profiles panel.
|
||||
|
||||
## Launching a profile
|
||||
|
||||
1. Make sure the Toolbar is shown. Go to **View > Toggle Toolbar**.
|
||||
2. Click the **New** button and select your profile.
|
||||
|
||||
{{tip}} When you're done with the session, make sure to click **Ctrl+C**.{{end}}
|
||||
@ -6,6 +6,7 @@ keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
metadata: false
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
@ -6,6 +6,7 @@ audience: writer, designer
|
||||
tags: special-layouts
|
||||
last_updated:
|
||||
summary:
|
||||
metadata: false
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
@ -7,6 +7,7 @@ keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
metadata: false
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user