major updates across the theme to make it more user-centered
This commit is contained in:
Tom Johnson
@ -1,8 +1,13 @@
|
||||
---
|
||||
title: About
|
||||
permalink: /about/
|
||||
tags: []
|
||||
keywords:
|
||||
audience: writer, designer
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
My name is Tom Johnson, and I'm a technical writer, blogger, and podcaster based in San Jose, California. My blog is here: [http://idratherbewriting.com](http://idratherbewriting.com). I write several posts there a week. See [my blog's about page](http://idratherbewriting.com/aboutme/) for more details about me.
|
||||
|
||||
|
||||
@ -1,7 +1,13 @@
|
||||
---
|
||||
title: Adding tooltips
|
||||
permalink: /adding_tooltips/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
You can add tooltips to your content. Because this theme is built on Bootstrap, you can simply use a specific attribute on an element to insert a tooltip.
|
||||
|
||||
|
||||
@ -3,8 +3,12 @@ title: Alerts
|
||||
permalink: /alerts/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
{% 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%}
|
||||
|
||||
@ -3,7 +3,12 @@ title: Icons
|
||||
permalink: /icons/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
The theme has two font icon sets integrated: Font Awesome and Glyphicons Halflings. The latter is part of Bootstrap, while the former is independent.
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Images
|
||||
permalink: /images/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
You embed an image the same way you embed other files or assets: you put the file into a folder, and then link to that file. The difference here is that the asset doesn't have a permalink, so here the file path actually matters.
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Labels
|
||||
permalink: /labels/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
These labels might come in handy for labeling things, such as POST, DELETE, UPDATE methods for endpoints. You can use any classes from Bootstrap in your content.
|
||||
|
||||
|
||||
@ -3,7 +3,10 @@ title: Links
|
||||
permalink: /links/
|
||||
audience: writer, designer
|
||||
tags: [formatting, navigation]
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Create a link
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ 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:
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Syntax highlighting
|
||||
permalink: /syntax_highlighting/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
For syntax highlighting, use fenced code blocks optionally followed by the language syntax you want:
|
||||
|
||||
|
||||
@ -1,7 +1,13 @@
|
||||
---
|
||||
title: Tables
|
||||
permalink: /tables/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Multimarkdown Tables
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Videos
|
||||
permalink: /videos/
|
||||
audience: writer, designer
|
||||
tags: formatting
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
The theme has the [video.js](http://www.videojs.com/) player integrated. But the scripts only appear on a page or post if you have certain frontmatter in that page or post. If you want to embed a video in a page and use the Video JS player, add `video: true` in your frontmatter of a page or post, and then add code like this where you want the video to appear:
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Navigation
|
||||
permalink: /navigation/
|
||||
audience: writer, designer
|
||||
tags: navigation
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
The sidebar and top navigation bar read their values from yml files inside the _data folder. Follow the YML syntax shown in the file.
|
||||
|
||||
|
||||
@ -2,7 +2,13 @@
|
||||
title: Tags
|
||||
permalink: /tags/
|
||||
audience: writer, designer
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
You can add tags to pages by adding `tags` in the frontmatter, like this:
|
||||
|
||||
|
||||
@ -3,8 +3,13 @@ title: Getting started
|
||||
permalink: /getting_started/
|
||||
tags: getting-started
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Step 1: Install all the prerequisites
|
||||
|
||||
Before you start installing the theme, make sure you have all of these prerequisites in place.
|
||||
|
||||
@ -3,7 +3,11 @@ title: Documentation theme for Jekyll
|
||||
permalink: "/"
|
||||
audience: writer, designer
|
||||
tags: getting-started
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@ -3,6 +3,10 @@ title: Support
|
||||
permalink: /support/
|
||||
audience: writer, designer
|
||||
tags: overview
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
I'm actively developing this theme. Please let me know about any bugs or other issues that you find. Just email me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. You can also [create issues directly within the Github repository here](https://github.com/tomjohnson1492/jekyll-doc/issues).
|
||||
@ -3,7 +3,11 @@ title: Supported features
|
||||
permalink: /supported_features/
|
||||
audience: writer, designer
|
||||
tags: [overview, getting-started]
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
Before you get into exploring Jekyll as a potential platform for help content, you may be wondering if it supports some basic features. The following table shows what is supported in Jekyll.
|
||||
|
||||
|
||||
@ -1,7 +1,13 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
permalink: /troubleshooting/
|
||||
tags: []
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Issues building the site
|
||||
|
||||
|
||||
@ -2,8 +2,13 @@
|
||||
title: Create PDF
|
||||
permalink: /create_pdf/
|
||||
tags: publishing
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
{% include linkrefs.html %}
|
||||
|
||||
{% comment %}
|
||||
remaining tasks:
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Create a Help API
|
||||
permalink: /help_api/
|
||||
tags: publishing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
You can create a help API that developers can use to pull in content.
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Search configuration
|
||||
permalink: /search_configuration/
|
||||
audience: writer, designer
|
||||
tags: publishing
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
The search is configured through the search.json file in the root directory. Take a look at that code if you want to change what content is included.
|
||||
|
||||
@ -23,7 +27,7 @@ defaults:
|
||||
values:
|
||||
layout: "page"
|
||||
comments: true
|
||||
search: include
|
||||
search: true
|
||||
-
|
||||
scope:
|
||||
path: ""
|
||||
@ -31,7 +35,7 @@ defaults:
|
||||
values:
|
||||
layout: "post"
|
||||
comments: true
|
||||
search: include
|
||||
search: true
|
||||
```
|
||||
|
||||
Some pages will break the JSON formatting. If that happens, then the search will no longer work. If you want to exclude a page from search add `search: exclude` in the frontmatter.
|
||||
|
||||
@ -3,7 +3,11 @@ title: Build arguments
|
||||
permalink: /build_arguments/
|
||||
tags: [single-sourcing, publishing]
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## How to build Jekyll sites
|
||||
|
||||
|
||||
@ -3,7 +3,12 @@ title: Conditional logic
|
||||
permalink: /conditional_logic/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
If you want to create different outputs for different audiences, you can do all of this using a combination of Jekyll's Liquid markup and values in your configuration file.
|
||||
|
||||
{{tip}} Definitely check out [Liquid's documentation](http://docs.shopify.com/themes/liquid-documentation/basics) for more details about how to use operators and other liquid markup. The notes here are a small, somewhat superficial sample from the site.{{end}}
|
||||
|
||||
@ -3,7 +3,11 @@ title: Content reuse
|
||||
permalink: /content_reuse/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
You can embed content from one file inside another using includes. Put the file containing content you want to reuse (e.g., mypage.html) inside the _includes folder, and then use a tag like this:
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: Excluding files and folders
|
||||
permalink: /excluding_files/
|
||||
tags: single-sourcing
|
||||
audience: writer, designer
|
||||
keywords:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
By default, all files in your project are included in your output. To exclude files, note them in the `exclude` section in the configuration file. Here's a sample:
|
||||
|
||||
|
||||
@ -3,7 +3,11 @@ title: FAQ
|
||||
permalink: /faq/
|
||||
tags: special-layouts
|
||||
audience: writer, designer
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
If you want to use an FAQ format, use the syntax shown on the faq.html page.
|
||||
|
||||
|
||||
@ -2,7 +2,12 @@
|
||||
title: Knowledge-base homepage
|
||||
permalink: /kb_layout/
|
||||
tags: special-layouts
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
This shows a sample layout for a knowledge base. Each square could link to a tag archive page.
|
||||
|
||||
|
||||
@ -4,7 +4,10 @@ permalink: /scroll/
|
||||
type: scroll
|
||||
audience: writer, designer
|
||||
tags: special-layouts
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
<p>This page demonstrates how you the integration of a script called ScrollTo, which is used here to link definitions of a JSON code sample to a list of definitions for that particular term. The scenario here is that the JSON blocks are really long, with extensive nesting and subnesting, which makes it difficult for tables below the JSON to adequately explain the term in a usable way.</p>
|
||||
|
||||
|
||||
@ -3,7 +3,12 @@ title: Shuffle
|
||||
permalink: /shuffle/
|
||||
tags: special-layouts
|
||||
type: noTags
|
||||
keywords:
|
||||
audience:
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
<script src="{{ "/js/jquery.shuffle.min.js" | prepend:site.baseurl }}"></script>
|
||||
<script src="{{ "/js/jquery.ba-throttle-debounce.min.js" | prepend:site.baseurl }}"></script>
|
||||
|
||||
@ -1,9 +1,13 @@
|
||||
---
|
||||
title: Special layouts
|
||||
permalink: /special_layouts/
|
||||
audience: writer, designer
|
||||
tags: special-layouts
|
||||
keywords:
|
||||
audience: writer, designer
|
||||
last_updated:
|
||||
summary:
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
This theme has a few special layouts. Special layouts include the JS files they need directly in the page. The JavaScript for each special layout does not load by default for every page in the site.
|
||||
|
||||
|
||||
@ -1,6 +1,10 @@
|
||||
---
|
||||
title: Tag archives overview
|
||||
permalink: /tag-archives-overview/
|
||||
audience: customers, field engineers
|
||||
tags:
|
||||
keywords: tags
|
||||
last_updated: May 4, 2015
|
||||
---
|
||||
|
||||
This is an overview to the tag archives section. Really the only reason this section is listed explicitly in the TOC here is to demonstrate how to add a third-level to the navigation.
|
||||
@ -2,6 +2,6 @@
|
||||
title: "Formatting Pages"
|
||||
permalink: /tag-formatting/
|
||||
tagName: formatting
|
||||
related_pages: false
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -2,6 +2,6 @@
|
||||
title: "Getting Started Pages"
|
||||
permalink: /tag-getting-started/
|
||||
tagName: getting-started
|
||||
related_pages: false
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -2,6 +2,6 @@
|
||||
title: "Overview Pages"
|
||||
permalink: /tag-overview/
|
||||
tagName: overview
|
||||
related_pages: false
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -2,6 +2,6 @@
|
||||
title: "Publishing Pages"
|
||||
permalink: /tag-publishing/
|
||||
tagName: publishing
|
||||
related_pages: false
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "Single-Sourcing Pages"
|
||||
permalink: /tag-single-sourcing/
|
||||
tagName: single-sourcing
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "Special Layout Pages"
|
||||
permalink: /tag-special-layouts/
|
||||
tagName: special-layouts
|
||||
metadata: false
|
||||
---
|
||||
{% include taglogic.html %}
|
||||
Reference in New Issue
Block a user