phoedos/pmd
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update theme from https://github.com/tomjohnson1492/documentation-theme-jekyll

Browse Source
This commit is contained in:
Andreas Dangel
2017-05-25 10:22:39 +02:00
parent b193bb28d8
commit b14da68b5a
57 changed files with 10394 additions and 9184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/pages/mydoc/mydoc_adding_tooltips.md
View File

@@ -16,7 +16,7 @@ Suppose you have a glossary.yml file inside your \_data folder. You could pull i
{% raw %}
```html
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.</a>
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.
```
{% endraw %}

5
docs/pages/mydoc/mydoc_alerts.md
View File

@@ -10,11 +10,12 @@ folder: mydoc
---
## About alerts
Alerts are little warnings, info, or other messages that you have called out in special formatting. In order to use these alerts or callouts, reference the appropriate value stored in the alerts.yml file as described in the following sections.
## Alerts
Similar to [inserting images][mydoc_images]), you insert alerts through various includes that have been developed. These includes provide templates through which you pass parameters to easily populate the right HTML code.
Similar to [inserting images][mydoc_images], you insert alerts through various includes that have been developed. These includes provide templates through which you pass parameters to easily populate the right HTML code.
```
{%raw%}{% include note.html content="This is my note. All the content I type here is treated as a single paragraph." %}{% endraw%}
@@ -118,7 +119,7 @@ Here's the result:
## Use Liquid variables inside parameters with includes
Suppose you have a product name or some other property that you're storing as a variable in your configuration file (\_congfig.yml), and you want to use this variable in the `content` parameter for your alert or callout. You will get an error if you use Liquid syntax inside a include parameter. For example, this syntax will produce an error:
Suppose you have a product name or some other property that you're storing as a variable in your configuration file (\_config.yml), and you want to use this variable in the `content` parameter for your alert or callout. You will get an error if you use Liquid syntax inside a include parameter. For example, this syntax will produce an error:
```
{%raw%}{% include note.html content="The {{site.company}} is pleased to announce an upcoming release." %}{%endraw%}

20
docs/pages/mydoc/mydoc_commenting_on_files.md
View File

@@ -18,28 +18,18 @@ There's an Edit me button on each page on this theme. This button allows collabo
Here's the code for that button on the page.html layout:
{% raw %}
```
{% unless jekyll.environment == "production" %}
{% raw %}{% if site.github_editme_path %}
{% if site.github_editme_path %}
<a target="_blank" href="https://github.com/{{site.github_editme_path}}/{{page.folder}}{{page.url | append: ".md"}}{% endif %}" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>
<a target="_blank" href="https://github.com/{{site.github_editme_path}}/{{page.folder}}{{page.url | append: ".md"}}{% endif %}" class="btn btn-default githubEditButton" role="button"><i class="fa fa-github fa-lg"></i> Edit me</a>
{% endif %}{% endraw %}
```
{% endraw %}
This code is only active if you're publishing in a development environment, which is the default.
To activate the production environment, add the [production environment flag](http://jekyllrb.com/docs/configuration/) in your build command:
{% raw %}
```
JEKYLL_ENV=production jekyll serve
```
{% endraw %}
In your configuration file, edit the value for `github_editme_path`. For example, you might create a branch called "reviews" on your Github repo. Then you would add something like this in your configuration file for the 'github_editme_path': tomjohnson1492/documentation-theme-jekyll/edit/reviews. Here "tomjohnson1492" is my github account name. The repo name is "documentation-theme-jekyll". The "reviews" name is the branch.
To suppress this button, comment out the `github_editme_path` in the \_config.yml file.
## Add reviewers as collaborators

86
docs/pages/mydoc/mydoc_help_api.md
View File

@@ -39,7 +39,7 @@ A collection is another content type that extends Jekyll beyond the use of pages
Add the following information to your configuration file to declare your collection:
```liquid
```
collections:
tooltips:
output: false
@@ -65,19 +65,19 @@ Create pages inside your new tooltips collection (that is, inside the \_tooltips
Here's an example:
{% highlight yaml %}
{% raw %}```liquid
```yaml
{% raw %}
---
id: basketball
doc_id: basketball
product: mydoc
---
{{site.data.definitions.basketball}}{% endraw %}
```
{% endhighlight %}
(Note: Avoid using `id`, as it seems to generate out as `/tooltips/basketball` instead of just `basketball.)
You need to create a separate page for each tooltip you want to deliver.
You need to create a separate file for each tooltip you want to deliver.
The product attribute is required in the frontmatter to distinguish the tooltips produced here from the tooltips for other products in the same \_tooltips folder. When creating the JSON file, Jekyll will iterate through all the pages inside \_tooltips, regardless of any subfolders included here.
@@ -90,46 +90,44 @@ Inside your project's pages directory (e.g., mydoc), add a file called "tooltips
{% raw %}
```liquid
---
layout: none
layout: null
search: exclude
---
{
"entries":
[
{% for page in site.tooltips %}
{% if page.product == "mydoc" %}
{
"id" : "{{ page.id }}",
"doc_id": "{{ page.doc_id }}",
"body": "{{ page.content | strip_newlines | replace: '\', '\\\\' | replace: '"', '\\"' }}"
} {% unless forloop.last %},{% endunless %}
{% endif %}
{% endfor %}
]
}
```
{% endraw %}
Change "mydoc" to the product name you used in each of the tooltip files. The template here will only include content in the JSON file if it meets the `product` attribute requirements. We need this `if` statement to prevent tooltips from other products from being included in the JSON file.
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 processed by Jekyll in the site build:
```
```json
{
"entries": [
{
"id": "baseball",
"doc_id": "baseball",
"body": "{{site.data.definitions.baseball}}"
},
{
"id": "basketball",
"doc_id": "basketball",
"body": "{{site.data.definitions.basketball}}"
},
{
"id": "football",
"doc_id": "football",
"body": "{{site.data.definitions.football}}"
},
{
"id": "soccer",
"doc_id": "soccer",
"body": "{{site.data.definitions.soccer}}"
}
]
@@ -138,7 +136,7 @@ This code will loop through all pages in the tooltips collection and insert the
You can also view the same JSON file here: <a target="_blank" href="tooltips.json">tooltips.json</a>.
You can add different fields depending on how you want the JSON to be structured. Here we just have to fields: `id` and `body`. And the JSON is looking just in the tooltips collection that we created.
You can add different fields depending on how you want the JSON to be structured. Here we just have to fields: `doc_id` and `body`. And the JSON is looking just in the tooltips collection that we created.
{% include tip.html content="Check out [Google's style guide](https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml) for JSON. These best practices can help you keep your JSON file valid." %}
@@ -148,7 +146,7 @@ By chunking up your JSON files, you can provide a quicker lookup. (I'm not sure
## 5. Build your site and look for the JSON file
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. In the output, look for the JSON file in the tooltips.json file. You'll see that Jekyll has populated it with content. This is because of the triple hyphen lines in the JSON file &mdash; this instructs Jekyll to process the file.
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. In the output, look for the JSON file in the tooltips.json file. You'll see that Jekyll has populated it with content. This is because of the triple hyphen lines in the JSON file &mdash; this instructs Jekyll to process the file.
## 6. Allow CORS access to your help if stored on a remote server
@@ -207,30 +205,38 @@ If you don't have CORS enabled, users will see a CORS error/warning message in t
## 7. 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`:
Developers can access the help using the `.get` method from jQuery, among other methods. Here's an example of how to get tooltips for basketball, baseball, football, and soccer:
```js
{% raw %}<script type="text/javascript">
$(document).ready(function(){
var url = "mydoc_tooltips_source.json";
$.get( url, function( data ) {
$.each(data.entries, function(i, page) {
if (page.id == "basketball") {
$( "#basketball" ).attr( "data-content", page.body );
}
});
});
});
</script>{% endraw %}
{% raw %}var url = "tooltips.json";
$.get( url, function( data ) {
/* Bootstrap popover text is defined inside a data-content attribute inside an element. That's
why I'm using attr here. If you just want to insert content on the page, use append and remove the data-content argument from the parentheses.*/
$.each(data.entries, function(i, page) {
if (page.doc_id == "basketball") {
$( "#basketball" ).attr( "data-content", page.body );
}
if (page.doc_id == "baseball") {
$( "#baseball" ).attr( "data-content", page.body );
}
if (page.doc_id == "football") {
$( "#football" ).attr( "data-content", page.body );
}
if (page.doc_id == "soccer") {
$( "#soccer" ).attr( "data-content", page.body );
}
});
});{% endraw %}
```
View the <a target="_blank" href="tooltips.html" class="noCrossRef">tooltip demo</a> for a demonstration.
View the <a target="_blank" href="tooltips.html" class="noCrossRef">tooltip demo</a> for a demonstration. See the source code for full code details.
The `url` in the demo is relative, but you could equally point it to an absolute path on a remote host assuming CORS is enabled on the host.
@@ -264,7 +270,7 @@ $(document).ready(function(){
});
```
Again, see the <a class="noCrossRef" href="/tooltips">Tooltip Demo</a> for a demo of the full code.
Again, see the <a class="noCrossRef" href="tooltips.html">Tooltip Demo</a> for a demo of the full code.
Note that even though you reference a Bootstrap JS script, Bootstrap's popovers require you to initialize them using the above code as well &mdash; they aren't turned on by default.

4
docs/pages/mydoc/mydoc_icons.md
View File

@@ -199,13 +199,13 @@ And here's the shortcode:
{% raw %}
```
{{site.data.alerts.callout_info}This is a special callout information message.
{{site.data.alerts.callout_info}This is a special callout information message.{{site.data.alerts.end}}
{% endraw %}
```
Here's the result:
{{site.data.alerts.callout_info}}This is a special callout information message.
{{site.data.alerts.callout_info}}This is a special callout information message.{{site.data.alerts.end}}
You can use any of the following:
{% raw %}

2
docs/pages/mydoc/mydoc_images.md
View File

@@ -11,7 +11,7 @@ folder: mydoc
## Image Include Template
Instead of using Markdown or HMTL syntax directly in your page for images, the syntax for images has been extracted out into an image include that allows you to pass the parameters you need. Include the image.html like this:
Instead of using Markdown or HTML syntax directly in your page for images, the syntax for images has been extracted out into an image include that allows you to pass the parameters you need. Include the image.html like this:
```liquid
{% raw %}

43
docs/pages/mydoc/mydoc_install_jekyll_on_mac.md
View File

@@ -111,4 +111,47 @@ The vanilla Jekyll site you create through `jekyll new my-awesome-site` doesn't
2. Type `jekyll serve`
3. Go to the preview address in the browser. (Make sure you include the `/` at the end.)
## Resolve "No Github API authentication" errors {#githuberror}
After making an edit, Jekyll auto-rebuilds the site. If you have the Gemfile in the theme with the github-pages gem, you may see the following error:
```
GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
```
If you see this error, you will need to take some additional steps to resolve it. (Note that this error only appears if you have the github-pages gem in your gemfile.) The resolution involves adding a Github token and a cert file.
{% include note.html content="These instructions apply to Mac OS X, but they're highly similar to Windows. These instructions are adapted from a post on [Knight Codes](http://knightcodes.com/miscellaneous/2016/09/13/fix-github-metadata-error.html). If you're on Windows, see the Knight Codes post for details instead of following along below." %}
To resolve the "No Github API authentication" error:
1. Follow Github's instructions to [create a personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/).
2. Open the **.bash_profile** file in your user directory:
```
open ~/.bash_profile
```
The file will open in your default terminal editor. If you don't have a .bash_profile file, you can just create a file with this name. Note that files that begin with `.` are hidden, so if you're looking in your user directory for the file, use `ls -a` to see hidden files.
3. In your **.bash_profile** file, reference your token as a system variable like this:
```
export JEKYLL_GITHUB_TOKEN=abc123abc123abc123abc123abc123abc123abc123abc123
```
Replace `abc123...` with your own token that you generated in step 1.
4. Go to **[https://curl.haxx.se/ca/cacert.pem][https://curl.haxx.se/ca/cacert.pem]. Right-click the page, select **Save as**, and save the file on your computer (save it somewhere safe, where you won't delete it). Name the file **cacert**.
5. Open your **.bash_profile** file again and add this line, replacing `Users/johndoe/projects/` with the path to your cacert.pem file:
```
export SSL_CERT_FILE=/Users/johndoe/projects/cacert.pem
```
6. Close and restart your terminal.
Browse to your jekyll project and run `bundle exec jekyll serve`. Make an edit to a file and observe that no Github API errors appear when Jekyll rebuilds the project.
{% include links.html %}

12
docs/pages/mydoc/mydoc_install_jekyll_on_windows.md
View File

@@ -92,4 +92,16 @@ Although you can use the default command prompt with Windows, it's recommended t
Unfortunately, the Command Prompt doesn't allow you to easily copy and paste the URL, so you'll have to type it manually.
## Resolving Github Metadata errors {#githuberror}
After making an edit, Jekyll auto-rebuilds the site. If you have the Gemfile in the theme with the github-pages gem, you may see the following error:
```
GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
```
If so, you will need to take some additional steps to resolve it. (Note that this error only appears if you have the github-pages gem in your gemfile.) The resolution involves adding a Github token and a cert file.
See this post on [Knight Codes](http://knightcodes.com/miscellaneous/2016/09/13/fix-github-metadata-error.html) for instructions on how to fix the error. You basically generate a personal token on Github and set it as a system variable. You also download a certification file and set it as a system variable. This resolves the issue.
{% include links.html %}

5
docs/pages/mydoc/mydoc_introduction.md
View File

@@ -3,13 +3,8 @@ title: Introduction
sidebar: mydoc_sidebar
permalink: mydoc_introduction.html
folder: mydoc
published: true
---
## Hey There
Some new text
## Overview
This site provides documentation, training, and other notes for the Jekyll Documentation theme. There's a lot of information about how to do a variety of things here, and it's not all unique to this theme. But by and large, understanding how to do things in Jekyll depends on how your theme is coded. As a result, these additional details are provided.

2
docs/pages/mydoc/mydoc_posts.md
View File

@@ -9,6 +9,8 @@ permalink: mydoc_posts.html
folder: mydoc
---
hello there.
## About posts
Posts are typically used for blogs or other news information because they contain a date and are sorted in reverse chronological order.

48
docs/pages/mydoc/mydoc_release_notes_50.md Normal file
View File

@@ -0,0 +1,48 @@
---
title: Release notes 5.0
tags: [getting_started]
keywords: release notes, announcements, what's new, new features
last_updated: July 3, 2016
summary: "Version 5.0 of the Documentation theme for Jekyll changes some fundamental ways the theme works to provide product-specific sidebars, intended to accommodate a site where multiple products are grouped together on the same site rather than generated out as separate outputs."
sidebar: mydoc_sidebar
permalink: mydoc_release_notes_50.html
folder: mydoc
---
## Unique sidebars for each product
In previous versions of the theme, I built the theme to generate different outputs for different scenarios based on various filtering attributes that might include product, version, platform, and audience variants.
However, this model results in siloed outputs and lots of separate file directories to manage. Instead of having 30 separate sites for your content (or however many variants you might have been producing), in this version of the theme I've moved towards a strategy of having one site with multiple products.
For each product, you can associate a unique sidebar with each of the product's pages. This allows you to have all your documentation on one site, but with separate navigation that is tailored to a view of that product.
You can still output to both web and PDF. And if you really need multiple site outputs, you can still do so by using multiple configuration files that trigger different builds. But my conclusion after using the multiple site output model for some years is that it's a bad practice for tech comm.
## Permalinks
With this theme, since you'll be publishing to one site, I've implement permalinks instead of relative links. Using permalinks means the way you store pages is much more flexible. You can store topics in folders and subfolders, etc., to any degree. But note that with permalinks you can't view the content offline (outside of Jekyll's preview server) nor on a separate site other than the one specified in the configuration file. Permalinks are how Jekyll was designed to work, and the sites just work better that way.
## Kramdown and Rouge
I also switched from redcarpet and Pygments to Kramdown and Rouge to align with the current direction of Jekyll 3.0. Kramdown is a Markdown filter (it's slightly different from Github-flavored Markdown). Rouge is a syntax highlighter. Pygments had some dependencies on Python, which made it more cumbersome for Windows users.
## Blog feature
I included a blog feature with this version of the theme. You can write posts and view them through the News link. There's also an archive for blog posts that sorts posts by year.
Additionally, the tagging system works across both the blog and pages, so your tags allow users to move laterally across the site based on topics they're interested in. When you view a tag archive, the sidebar shows a list of tags.
## Updated documentation
I updated the documentation for the theme. The switch from the multi-site outputs to the single-site with multiple sidebars required updating a lot of different parts of the documentation and code.
## Fixed errors
Previously I had some errors with the HTML that showed up in w3c HTML validator analyses. This caused some small problems in certain browsers or systems less tolerant of the errors. I fixed all of the errors.
## Accessing the old theme
If you want to access the old theme, you can still find it [here](https://github.com/tomjohnson1492/jekylldoctheme-separate-outputs).
{% include links.html %}

40
docs/pages/mydoc/mydoc_release_notes_60.md Normal file
View File

@@ -0,0 +1,40 @@
---
title: Release notes 6.0
tags: [getting_started]
keywords: release notes, announcements, what's new, new features
last_updated: July 16, 2016
summary: "Version 6.0 of the Documentation theme for Jekyll, released July 4, 2016, implements relative links so you can view the files offline or on any server without configuring urls and baseurls. Additionally, you can store pages in subdirectories. Templates for alerts and images are available."
sidebar: mydoc_sidebar
permalink: mydoc_release_notes_60.html
folder: mydoc
---
## Relative links
You can now view the site offline rather than solely through the Jekyll preview server or deployed on a web server. The linking approach in both the sidebar and with inline links uses relative linking throughout.
## Subfolders for pages
You can creates folders and subfolders for your pages, similar to how you can store posts in folders and subfolders. When Jekyll builds the site, all pages get pushed into the root directory as single html files (rather than being pushed inside folders, or remaining in subfolders). See [Pages][mydoc_pages] for more details.
## Alerts templates
You can use include templates for notes, tips, and warnings. These include templates make it easier to insert notes. If you make an error, you're immediately made aware since the site won't build. See [Alerts][mydoc_alerts] for more details.
## Image templates
Similar to alerts, images also have include templates. You can insert both regular images and inline images, such as images that are a button or icon. See [Images][mydoc_images] for more details.
## Automated links using Markdown formatting
Instead of using YAML references to handle links, I've switched to a Markdown reference style approach. A links.html file iterates through the sidebar files and formats the content in the Markdown reference. You then just use Markdown syntax for the links. See [Links][mydoc_hyperlinks] for more details.
## Workflow maps
If you want to display a workflow map for a process, you can do so by adding some properties in your frontmatter. The workflow map helps guide users through a process. Both simple and complex workflow maps are available. For more details, see [Workflow maps][mydoc_workflow_maps].
## Upgrading
If you want to upgrade from an earlier version of the theme, I recommend that you download the new theme and copy of your Markdown files into the new theme. You'll then need to make adjustments to your page frontmatter, to the sidebar table of contents, links, image references, and alert references. In short, there's no easy upgrade path. But all of this won't take too long if you don't have mountains of content.
{% include links.html %}

2
docs/pages/mydoc/mydoc_search_configuration.md
View File

@@ -35,7 +35,7 @@ I've found that include the `body` field in the search creates too many problems
{% raw %}
```json
"body": "{{ page.content | strip_html | strip_newlines | replace: '\', '\\\\' | replace: '"', '\\"' | replace: '^t', ' ' }}",
"body": "{{ page.content | strip_html | strip_newlines | replace: '\', '\\\\' | replace: '"', '\\"' | replace: ' ', ' ' }}",
```
{% endraw %}

2
docs/pages/mydoc/mydoc_series.md
View File

@@ -11,7 +11,7 @@ folder: mydoc
## Using series for pages
You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a [demo][mydoc_seriesdemo1]</a>.
You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a <a href="mydoc_seriesdemo1.html">demo</a>.
## 1. Create the series button

4
docs/pages/mydoc/mydoc_seriesdemo1.md
View File

@@ -9,7 +9,7 @@ permalink: mydoc_seriesdemo1.html
folder: mydoc
---
{% include custom/series_acme.html %}
{% include custom/series_acme_next.html %}
This is the first post in the series.
@@ -17,6 +17,6 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo. Aliquam feugiat, nibh in ultrices mattis, felis ipsum venenatis metus, vel vehicula libero mauris a enim. Sed placerat est ac lectus vestibulum tempor. Quisque ut condimentum massa. Proin venenatis leo id urna cursus blandit. Vivamus sit amet hendrerit metus.
{% include custom/series_acme_next.html %}
{% include links.html %}

3
docs/pages/mydoc/mydoc_seriesdemo2.md
View File

@@ -10,7 +10,7 @@ folder: mydoc
---
{% include custom/series_acme.html %}
{% include custom/series_acme_next.html %}
This is the second post in the series.
@@ -20,6 +20,5 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo.
{% include custom/series_acme_next.html %}
{% include links.html %}

3
docs/pages/mydoc/mydoc_seriesdemo3.md
View File

@@ -10,7 +10,7 @@ permalink: mydoc_seriesdemo3.html
folder: mydoc
---
{% include custom/series_acme.html %}
{% include custom/series_acme_next.html %}
This is the third post in the series.
@@ -20,6 +20,5 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudi
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius. Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fermentum leo. Aliquam feugiat, nibh in ultrices mattis, felis ipsum venenatis metus, vel vehicula libero mauris a enim. Sed placerat est ac lectus vestibulum tempor. Quisque ut condimentum massa. Proin venenatis leo id urna cursus blandit. Vivamus sit amet hendrerit metus.
{% include custom/series_acme_next.html %}
{% include links.html %}

5
docs/pages/mydoc/mydoc_seriesdemo4.md
View File

@@ -10,7 +10,7 @@ folder: mydoc
---
{% include custom/series_acme.html %}
{% include custom/series_acme_next.html %}
This is the fourth post in the series.
@@ -23,7 +23,4 @@ Mauris consequat accumsan ex, a iaculis metus fermentum a. Praesent sit amet fer
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aliquam vel sollicitudin felis. Sed eu arcu sed ipsum semper luctus eu a tortor. Suspendisse id leo eu metus laoreet varius.
{% include custom/series_acme_next.html %}
{% include links.html %}

2
docs/pages/mydoc/mydoc_supported_features.md
View File

@@ -13,7 +13,7 @@ folder: mydoc
Before you get into exploring Jekyll as a potential platform for help content, you may be wondering if it supports some basic features needed to fulfill your tech doc requirements. The following table shows what is supported in Jekyll and this theme.
## Supported feautres
## Supported features
Features | Supported | Notes
--------|-----------|-----------

83
docs/pages/mydoc/mydoc_syntax_highlighting.md
View File

@@ -13,43 +13,76 @@ folder: mydoc
For syntax highlighting, use fenced code blocks optionally followed by the language syntax you want:
<pre>
```ruby
def foo
puts 'foo'
end
```java
import java.util.Scanner;
public class ScannerAndKeyboard
{
public static void main(String[] args)
{ Scanner s = new Scanner(System.in);
System.out.print( "Enter your name: " );
String name = s.nextLine();
System.out.println( "Hello " + name + "!" );
}
}
```
</pre>
This looks as follows:
```ruby
def foo
puts 'foo'
end
```java
import java.util.Scanner;
public class ScannerAndKeyboard
{
public static void main(String[] args)
{ Scanner s = new Scanner(System.in);
System.out.print( "Enter your name: " );
String name = s.nextLine();
System.out.println( "Hello " + name + "!" );
}
}
```
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:
If you're using an HTML file, you can also use the `highlight` command with Liquid markup.
{% raw %}
<pre>
{% highlight ruby %}
def foo
puts 'foo'
end
{% raw %}{% highlight java %}
import java.util.Scanner;
public class ScannerAndKeyboard
{
public static void main(String[] args)
{ Scanner s = new Scanner(System.in);
System.out.print( "Enter your name: " );
String name = s.nextLine();
System.out.println( "Hello " + name + "!" );
}
}
{% endhighlight %}{% endraw %}
</pre>
Result:
{% highlight java %}
import java.util.Scanner;
public class ScannerAndKeyboard
{
public static void main(String[] args)
{ Scanner s = new Scanner(System.in);
System.out.print( "Enter your name: " );
String name = s.nextLine();
System.out.println( "Hello " + name + "!" );
}
}
{% endhighlight %}
</pre>
{% endraw %}
It renders the same:
{% highlight ruby %}
def foo
puts 'foo'
end
{% endhighlight %}
The theme has syntax highlighting specified in the configuration file as follows:

182
docs/pages/mydoc/mydoc_tables.md
View File

@@ -10,20 +10,6 @@ permalink: mydoc_tables.html
folder: mydoc
---
{% unless site.output == "pdf" %}
<script>
$(document).ready(function(){
$('table.display').DataTable( {
paging: true,
stateSave: true,
searching: true
}
);
});
</script>
{% endunless %}
## Multimarkdown Tables
You can use Multimarkdown syntax for tables. The following shows a sample:
@@ -48,7 +34,7 @@ You can use Multimarkdown syntax for tables. The following shows a sample:
## HTML Tables {#htmltables}
If you need a more sophisticated table syntax, use HTML syntax for the table. Although you're using HTML, you can use Markdown inside the table cells by adding `markdown="1"` as an attribute for the `td` tag, as shown in the following table. You can also control the column widths.
If you need a more sophisticated table syntax, use HTML syntax for the table. Although you're using HTML, you can use Markdown inside the table cells by adding `markdown="span"` as an attribute for the `td` tag, as shown in the following table. You can also control the column widths.
```html
<table>
@@ -58,27 +44,24 @@ If you need a more sophisticated table syntax, use HTML syntax for the table. Al
</colgroup>
<thead>
<tr class="header">
<th align="left">Field</th>
<th align="left">Description</th>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" markdown="1">First column **fields**</td>
<td align="left" markdown="1">Some descriptive text. This is a markdown link to [Google](http://google.com). Or see [some link][mydoc_tags].</td>
<td markdown="span">First column **fields**</td>
<td markdown="span">Some descriptive text. This is a markdown link to [Google](http://google.com). Or see [some link][mydoc_tags].</td>
</tr>
<tr>
<td align="left" markdown="1">Second column **fields**</td>
<td align="left" markdown="1">Some more descriptive text. Here we have a Markdown-formatted list:
* first item
* second item
* third item
<td markdown="span">Second column **fields**</td>
<td markdown="span">Some more descriptive text.
</td>
</tr>
</tbody>
</table>
```
**Result:**
<table>
<colgroup>
@@ -87,138 +70,63 @@ If you need a more sophisticated table syntax, use HTML syntax for the table. Al
</colgroup>
<thead>
<tr class="header">
<th align="left">Field</th>
<th align="left">Description</th>
<th>Field</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" markdown="1">First column **fields**</td>
<td align="left" markdown="1">Some descriptive text. This is a markdown link to [Google](http://google.com). Or see [some link][mydoc_tags].</td>
<td markdown="span">First column **fields**</td>
<td markdown="span">Some descriptive text. This is a markdown link to [Google](http://google.com). Or see [some link][mydoc_tags].</td>
</tr>
<tr>
<td align="left" markdown="1">Second column **fields**</td>
<td align="left" markdown="1">Some more descriptive text. Here we have a Markdown-formatted list:
* first item
* second item
* third item
<td markdown="span">Second column **fields**</td>
<td markdown="span">Some more descriptive text.
</td>
</tr>
</tbody>
</table>
## jQuery datables
## jQuery DataTables
You also have the option of using a [jQuery datatable](https://www.datatables.net/), which gives you some more options. If you want to use a jQuery datatable, then add `datatable: true` in a page's frontmatter. This will load the right jQuery datatable scripts for the table on that page only (rather than loading the scripts on every page of the site.)
You also have the option of using a [jQuery DataTable](https://www.datatables.net/), which gives you some additional capabilities. To use a jQuery DataTable in a page, include `datatable: true` in a page's frontmatter. This tells the default layout to load the necessary CSS and javascript bits and to include a `$(document).ready()` function that initializes the DataTables library.
Also, you need to add this script to trigger the jQuery table on your page:
You can change the options used to initialize the DataTables library by editing the call to `$('table.display').DataTable()` in the default layout. The available options for Datatables are described in the [DataTable documentation](https://www.datatables.net/manual/options), which is excellent.
```js
<script>
$(document).ready(function(){
You also must add a class of `display` to your tables. You can change the class, but then you'll need to change the trigger defined in the `$(document).ready()` function in the default layout from `table.display` to the class you prefer.
$('table.display').DataTable( {
paging: true,
stateSave: true,
searching: true
}
);
});
</script>
You can also add page-specific triggers (by copying the `<script></script>` block from the default layout into the page) and classes, which lets you use different options on different tables.
If you use an HTML table, adding `class="display"` to the `<table>` tag is sufficient.
Markdown, however, doesn't allow you to add classes to tables, so you'll need to use a trick: add `<div class="datatable-begin"></div>` before the table and `<div class="datatable-end"></div>` after the table. The default layout includes a jQuery snippet that automagically adds the `display` class to any table it finds between those two markers. So you can start with this (we've trimmed the descriptions for display):
```markdown
<div class="datatable-begin"></div>
Food | Description | Category | Sample type
------- | ------------------------------------- | -------- | -----------
Apples | A small, somewhat round ... | Fruit | Fuji
Bananas | A long and curved, often-yellow ... | Fruit | Snow
Kiwis | A small, hairy-skinned sweet ... | Fruit | Golden
Oranges | A spherical, orange-colored sweet ... | Fruit | Navel
<div class="datatable-end"></div>
```
The available options for the datable are described in the [datatable documentation](https://www.datatables.net/manual/options), which is excellent.
and get this:
Additionally, you must add a class of `display` to your tables. (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.)
<div class="datatable-begin"></div>
Since Markdown doesn't allow you to add classes to tables, you'll need to use HTML for any datatables. Here's an example:
Food | Description | Category | Sample type
------- | ------------------------------------------------------------------------------------------------- | -------- | -----------
Apples | A small, somewhat round and often red-colored, crispy fruit grown on trees. | Fruit | Fuji
Bananas | A long and curved, often-yellow, sweet and soft fruit that grows in bunches in tropical climates. | Fruit | Snow
Kiwis | A small, hairy-skinned sweet fruit with green-colored insides and seeds. | Fruit | Golden
Oranges | A spherical, orange-colored sweet fruit commonly grown in Florida and California. | Fruit | Navel
```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>
<tr>
<td>Parameter 3</td>
<td>Sample description
</td>
<td>Sample type</td>
<td>Sample default value</td>
</tr>
<tr>
<td>Parameter 4</td>
<td>Sample description
</td>
<td>Sample type</td>
<td>Sample default value</td>
</tr>
</tbody>
</table>
```
<div class="datatable-end"></div>
This renders to the following:
<table id="sampleTable" class="display">
<thead>
<tr>
<th>Food</th>
<th>Description</th>
<th>Category</th>
<th>Sample type</th>
</tr>
</thead>
<tbody>
<tr>
<td>Apples</td>
<td>A small, somewhat round and often red-colored, crispy fruit grown on trees.
</td>
<td>Fruit</td>
<td>Fuji</td>
</tr>
<tr>
<td>Bananas</td>
<td>A long and curved, often-yellow, sweet and soft fruit that grows in bunches in tropical climates.
</td>
<td>Fruit</td>
<td>Snow</td>
</tr>
<tr>
<td>Kiwis</td>
<td>A small, hairy-skinned sweet fruit with green-colored insides and seeds.
</td>
<td>Fruit</td>
<td>Golden</td>
</tr>
<tr>
<td>Oranges</td>
<td>A spherical, orange-colored sweet fruit commonly grown in Florida and California.
</td>
<td>Fruit</td>
<td>Navel</td>
</tr>
</tbody>
</table>
Notice a few features:
@@ -226,7 +134,7 @@ Notice a few features:
* You can sort the column order.
* You can page the results so that you show only a certain number of values on the first page and then require users to click next to see more entries.
Read more of the [datatable documentation](https://www.datatables.net/manual/options) to get a sense of the options you can configure. You should probably only use datatables when you have long, massive tables full of information.
Read more of the [DataTable documentation](https://www.datatables.net/manual/options) to get a sense of the options you can configure. You should probably only use DataTables when you have long, massive tables full of information.
{% include note.html content=" Try to keep the columns to 3 or 4 columns only. If you add 5+ columns, your table may create horizontal scrolling with the theme. Additionally, keep the column heading titles short." %}

3
docs/pages/mydoc/mydoc_tags.md
View File

@@ -49,8 +49,7 @@ Tags have a few components.
- publishing
- single_sourcing
- special_layouts
- content type
- release_notes
- content types
```
3. Create a tag archive file for each tag in your tags_doc.yml list. Name the file following the same pattern in the tags folder, like this: tag_collaboration.html.

2
docs/pages/mydoc/mydoc_themes.md
View File

@@ -9,6 +9,8 @@ permalink: mydoc_themes.html
folder: mydoc
---
{% include note.html content="The [gem-based theme](https://jekyllrb.com/docs/themes/) approach is not yet integrated into this theme." %}
## Theme options
You can choose a green or blue theme, or you can create your own. In the css folder, there are two theme files: theme-blue.css and theme-green.css. These files have the most common CSS elements extracted in their own CSS file. Just change the hex colors to the ones you want.

13
docs/pages/mydoc/mydoc_webstorm_text_editor.md
View File

@@ -21,13 +21,13 @@ By default, WebStorm comes packaged with a lot more functionality than you proba
You can set the way the tab works, and whether it uses spaces or a tab character. For details, see [Code Style. JavaScript](https://www.jetbrains.com/help/webstorm/2016.1/code-style-javascript.html?origin=old_help#d658997e132) in WebStorm's help.
On a Mac, go to **WebStorm | Preferences | Editor | Code Style | Other File Types**. Don't select the "Use tab character" check box. Set **3** for the **Tab size** and **Indent** check boxes.
On a Mac, go to **WebStorm > Preferences > Editor > Code Style > Other File Types**. Don't select the "Use tab character" check box. Set **4** for the **Tab size** and **Indent** check boxes.
On Windows, go to **File | Settings | Editor | Code Style | Other File Types** to access the same menu.
On Windows, go to **File > Settings > Editor > Code Style > Other File Types** to access the same menu.
## Add the Markdown Support plugin
Since you'll be writing in Markdown, having color coding and other support for Markdown is important. Install the Markdown Support plugin by going to **WebStorm > Preferences > Plugins** and clicking **Install JetBrains Plugin**. Search for **Markdown Support**. (I would avoid the Multimarkdown plugin &mdash; it seemed to make all my dashes in frontmatter tags extend half way across the page.)
Since you'll be writing in Markdown, having color coding and other support for Markdown is important. Install the Markdown Support plugin by going to **WebStorm > Preferences > Plugins** and clicking **Install JetBrains Plugin**. Search for **Markdown Support**. You can also implement the Markdown Navigator plugin.
## Enable Soft Wraps (word wrapping)
@@ -37,11 +37,10 @@ Most likely you'll want to enable soft wraps, which wraps lines rather than exte
When you're searching for content, you don't want to edit any file that appears in the \_site directory. You can exclude a directory from Webstorm by right-clicking the directory and choosing **Mark Directory As** and then selecting **Excluded**.
## Set tabs to 3 spaces
## Set tabs to 4 spaces
You can set the default number of spaces a tab sets, including whether Webstorm uses a tab character or spaces. You want spaces, and you want to set this to default number of spaces to ```3``` spaces instead of 4. Note that this is due to the way Kramdown handles the continuation of lists.
When you intercept a list with a paragraph or code sample, the indentation of the intercepting paragraph or list must align with the beginning of the first character after the space in the list item numbering. This is typically 3 spaces, not 4. Note that this style differs from the Github-flavored Markdown style. (Welcome to the world of subtle and infuriating discrepancies between Markdown flavors.)
You can set the default number of spaces a tab sets, including whether Webstorm uses a tab character or spaces. You want spaces, and you want to set this to default number of spaces to ```4```. Note that this is due to the way Kramdown handles the continuation
of lists.
To set the indentation, see the "Tabs and Indents" topic in this [Code Style. Javascript](https://www.jetbrains.com/help/webstorm/2016.1/code-style-javascript.html?origin=old_help#d658997e132) topic in Webstorm's help.

107
docs/pages/mydoc/mydoc_yaml_tutorial.md
View File

@@ -7,6 +7,17 @@ sidebar: mydoc_sidebar
permalink: mydoc_yaml_tutorial.html
folder: mydoc
---
<style>
.result {
background-color: #f0f0f0;
border: 1px solid #dedede;
padding: 10px;
margin-top: 10px;
margin-bottom: 10px;
}
</style>
## Overview
One of the most interesting features of Jekyll is the ability to separate out data elements from formatting elements using a combination of YAML and Liquid. This setup is most common when you're trying to create a table of contents.
@@ -51,21 +62,19 @@ name:
**Markdown + Liquid:**
{% raw %}
```liquid
Husband's name: {{site.data.samplelist.name.husband}}
Wife's name: {{site.data.samplelist.name.wife}}
{% raw %}<p>Husband's name: {{site.data.samplelist.name.husband}}</p>
<p>Wife's name: {{site.data.samplelist.name.wife}}</p>{% endraw %}
```
{% endraw %}
Notice that in order to access the data file, you use `site.data.samplelist`. `mydoc` is the folder, and `samplelist` is the name of the YAML file.
**Result:**
Husband's name: {{site.data.samplelist.name.husband}}
Wife's name: {{site.data.samplelist.name.wife}}
<div class="result">
<p>Husband's name: {{site.data.samplelist.name.husband}}</p>
<p>Wife's name: {{site.data.samplelist.name.wife}}</p>
</div>
## Example 2: Line breaks
@@ -88,20 +97,22 @@ block: |
**Markdown:**
```liquid
**Feedback**
{{site.data.samplelist.feedback}}
{% raw %}<p><b>Feedback</b></p>
<p>{{site.data.samplelist.feedback}}</p>
**Block**
{{site.data.samplelist.block}}
<p><b>Block</b></p>
<p>{{site.data.samplelist.block}}</p>{% endraw %}
```
**Result:**
**Feedback**
{{site.data.samplelist.feedback}}
<div class="result">
<p><b>Feedback</b></p>
<p>{{site.data.samplelist.feedback}}</p>
**Block**
{{site.data.samplelist.block}}
<p><b>Block</b></p>
<p>{{site.data.samplelist.block}}</p>
</div>
The right angle bracket `>` allows you to put the value on the next lines (which must be indented). Even if you create a line break, the output will remove all of those line breaks, creating one paragraph.
@@ -120,19 +131,24 @@ bikes:
**Markdown + Liquid:**
{% raw %}
```liquid
{% raw %}<ul>
{% for item in site.data.samplelist.bikes %}
* {{item.title}}
<li>{{item.title}}</li>
{% endfor %}
</ul>{% endraw %}
```
{% endraw %}
**Result:**
<div class="result">
<ul>
{% for item in site.data.samplelist.bikes %}
* {{item.title}}
<li>{{item.title}}</li>
{% endfor %}
</ul>
</div>
Here we use a "for" loop to get each item in the bikes list. By using `.title` we only get the `title` property from each list item.
@@ -165,14 +181,17 @@ salesteams:
{% endraw %}
**Result:**
<div class="result">
{% for item in site.data.samplelist.salesteams %}
<h3>{{item.title}}</h3>
<ul>
{% for entry in item.subitems %}
{% for entry in item.subfolderitems %}
<li>{{entry.location}}</li>
{% endfor %}
</ul>
{% endfor %}
</div>
Hopefully you can start to see how to wrap more complex formatting around the YAML content. When you use a "for" loop, you choose the variable of what to call the list items. The variable you choose to use becomes how you access the properties of each list item. In this case, I decided to use the variable `item`. In order to get each property of the list item, I used `item.subitems`.
@@ -218,6 +237,7 @@ toc:
**Result:**
<div class="result">
{% for item in site.data.samplelist.toc %}
<h3>{{item.title}}</h3>
<ul>
@@ -226,6 +246,7 @@ toc:
{% endfor %}
</ul>
{% endfor %}
</div>
This example is similar to the previous one, but it's more developed as a real table of contents.
@@ -248,7 +269,9 @@ myref: *hello
**Result:**
<div class="result">
{{ site.data.samplelist.myref }}
</div>
This example is notably different. Here I'm showing how to reuse content in YAML file. If you have the same value that you want to repeat in other mappings, you can create a variable using the `&` symbol. Then when you want to refer to that variable's value, you use an asterisk `*` followed by the name of the variable.
@@ -270,15 +293,14 @@ about:
**Markdown:**
{% raw %}
```
{{ site.data.samplelist.about[0] }}
{% raw %}{{ site.data.samplelist.about[0] }}{% endraw %}
```
{% endraw %}
**Result:**
<div class="result">
{{ site.data.samplelist.about[0] }}
</div>
You can see that I'm accessing one of the items in the list using `[0]`. This refers to the position in the array where a list item is. Like most programming languages, you start counting at zero, not one.
@@ -309,8 +331,9 @@ numbercolors:
{% endraw %}
**Result:**
<div class="result">
{{ site.data.samplelist.numbercolors[0].properties }}
</div>
This example is similar as before; however, in this case were getting a specific property from the list item in the zero position.
@@ -344,48 +367,60 @@ mypages:
**Markdown + Liquid:**
{% raw %}
```liquid
{% raw %}<ul>
{% for sec in site.data.samplelist.mypages %}
{% if sec.audience == "writers" %}
* {{sec.url}}
<li>{{sec.url}}</li>
{% endif %}
{% endfor %}
```
</ul>
{% endraw %}
```
**Result:**
<div class="result">
<ul>
{% for sec in site.data.samplelist.mypages %}
{% if sec.audience == "writers" %}
* {{sec.url}}
<li>{{sec.url}}</li>
{% endif %}
{% endfor %}
</ul>
</div>
This example shows how you can use conditions in order to selectively get the YAML content. In your table of contents, you might have a lot of different pages. However, you might only want to get the pages for a particular audience. Conditions lets you get only the items that meet those audience attributes.
Now let's adjust the condition just a little. Let's add a second condition so that the `audience` property has to be `writers` and the `product` property has to be gizmo. This is how you would write it:
{% raw %}
```liquid
{% raw %}<ul>
{% for sec in site.data.samplelist.mypages %}
{% if sec.audience == "writers" and sec.product == "gizmo" %}
* {{sec.url}}
<li>{{sec.url}}</li>
{% endif %}
{% endfor %}
</ul>{% endraw %}
```
{% endraw %}
And here is the result:
<div class="result">
<ul>
{% for sec in site.data.samplelist.mypages %}
{% if sec.audience == "writers" and sec.product == "gizmo" %}
* {{sec.url}}
<li>{{sec.url}}</li>
{% endif %}
{% endfor %}
</ul>
</div>
## More resources
For more examples and explanations, see this helpful post on tournemille.com: [How to create data-driven navigation in Jekyll](http://www.tournemille.com/blog/How-to-create-data-driven-navigation-in-Jekyll/).
For more examples and explanations, see this helpful post on tournemille.com: [How to create data-driven navigation in Jekyll](http://www.tournemille.com/blog/How-to-create-data-driven-navigation-in-Jekyll).
{% include links.html %}

6
docs/pages/news/news.html
View File

@@ -16,17 +16,17 @@ folder: news
<span class="post-meta">{{ post.date | date: "%b %-d, %Y" }} /
{% for tag in post.tags %}
<a href="{{ "tag_" | append: tag | append: ".html"}}">{{tag}}{{tag}}</a>{% unless forloop.last %}, {% endunless%}
<a href="{{ "tag_" | append: tag | append: ".html"}}">{{tag}}</a>{% unless forloop.last %}, {% endunless%}
{% endfor %}</span>
<p>{% if page.summary %} {{ page.summary | strip_html | strip_newlines | truncate: 160 }} {% else %} {{ post.content | truncatewords: 50 | strip_html }} {% endif %}</p>
{% endfor %}
<p><a href="feed.xml"" class="btn btn-primary navbar-btn cursorNorm" role="button">RSS Subscribe{{tag}}</a></p>
<p><a href="feed.xml" class="btn btn-primary navbar-btn cursorNorm" role="button">RSS Subscribe{{tag}}</a></p>
<hr />
<p>See more posts from the <a href="news_archive.html">News Archive</a>. </p>
</div>
</div>

8
docs/pages/news/news_archive.html
View File

@@ -30,12 +30,6 @@ folder: news
{% endfor %}
</ul>
</section>
<hr/>
</div>
</div>