Restructure pages: product is now "pmd", sidebar new, pages moved
Removed the samples mydoc, product1, product2
This commit is contained in:
Andreas Dangel
parent
624705bd70
commit
70ab4f2468
@ -15,7 +15,7 @@ company_name: PMD Open Source Project
|
||||
github_editme_path: pmd/pmd/blob/master/docs/
|
||||
# if you're using Github, provide the basepath to the branch you've created for reviews, following the sample here. if not, leave this value blank.
|
||||
|
||||
disqus_shortname:
|
||||
disqus_shortname:
|
||||
# if you're using disqus for comments, add the shortname here. if not, leave this value blank.
|
||||
|
||||
host: 127.0.0.1
|
||||
@ -31,7 +31,7 @@ exclude:
|
||||
|
||||
feedback_subject_line: PMD Source Code Analyzer
|
||||
|
||||
feedback_email:
|
||||
feedback_email:
|
||||
# used as a contact email for the Feedback link in the top navigation bar
|
||||
|
||||
# feedback_disable: true
|
||||
@ -68,7 +68,7 @@ defaults:
|
||||
layout: "page"
|
||||
comments: true
|
||||
search: true
|
||||
sidebar: home_sidebar
|
||||
sidebar: pmd_sidebar
|
||||
-
|
||||
scope:
|
||||
path: ""
|
||||
@ -87,19 +87,15 @@ defaults:
|
||||
layout: "post"
|
||||
comments: true
|
||||
search: true
|
||||
sidebar: home_sidebar
|
||||
sidebar: pmd_sidebar
|
||||
|
||||
# these are defaults used for the frontmatter for these file types
|
||||
|
||||
sidebars:
|
||||
- home_sidebar
|
||||
- mydoc_sidebar
|
||||
- product1_sidebar
|
||||
- product2_sidebar
|
||||
- other
|
||||
- pmd_sidebar
|
||||
|
||||
description: "Intended as a documentation theme based on Jekyll for technical writers documenting software and other technical products, this theme has all the elements you would need to handle multiple products with both multi-level sidebar navigation, tags, and other documentation features."
|
||||
# the description is used in the feed.xml file
|
||||
|
||||
# needed for sitemap.xml file only
|
||||
url: http://idratherbewriting.com
|
||||
url: http://idratherbewriting.com
|
||||
|
||||
@ -1,22 +0,0 @@
|
||||
# This is your sidebar TOC. The sidebar code loops through sections here and provides the appropriate formatting.
|
||||
|
||||
entries:
|
||||
- title: Sidebar
|
||||
levels: one
|
||||
folders:
|
||||
|
||||
- title: Products
|
||||
output: web
|
||||
folderitems:
|
||||
- title: News
|
||||
url: /news.html
|
||||
output: web
|
||||
- title: Theme instructions
|
||||
url: /mydoc_introduction.html
|
||||
output: web
|
||||
- title: Product 1
|
||||
url: /p1_landing_page.html
|
||||
output: web
|
||||
- title: Product 2
|
||||
url: /p2_landing_page.html
|
||||
output: web
|
||||
@ -1,18 +0,0 @@
|
||||
|
||||
# Follow the pattern here for the URLs -- no slash at the beginning, and include the .html. The link here is rendered exactly as is in the Markdown references.
|
||||
|
||||
entries:
|
||||
- title: other
|
||||
folders:
|
||||
|
||||
- title: Other Links
|
||||
folderitems:
|
||||
|
||||
- title: Automated links bookmark
|
||||
url: /mydoc_hyperlinks.html#automatedlinks
|
||||
|
||||
- title: Bookmark links
|
||||
url: /mydoc_hyperlinks.html#bookmarklinks
|
||||
|
||||
- title: Some link bookmark
|
||||
url: /mydoc_pages.html#someIdTag
|
||||
@ -1,4 +1,5 @@
|
||||
# This is your sidebar TOC. The sidebar code loops through sections here and provides the appropriate formatting.
|
||||
# This is your sidebar TOC. The sidebar code loops through sections here and
|
||||
# provides the appropriate formatting.
|
||||
|
||||
entries:
|
||||
- title: sidebar
|
||||
@ -26,64 +27,80 @@ entries:
|
||||
url: /index.html
|
||||
output: web, pdf
|
||||
type: homepage
|
||||
- title: How PMD Works
|
||||
url: /how_pmd_works.html
|
||||
- title: Getting Started
|
||||
url: /pmd_getting_started.html
|
||||
output: web, pdf
|
||||
- title: Supported Features
|
||||
url: /mydoc_supported_features.html
|
||||
- title: Understanding Rulesets
|
||||
url: /pmd_understanding_rulesets.html
|
||||
output: web, pdf
|
||||
- title: About the theme author
|
||||
url: /mydoc_about.html
|
||||
- title: Best Pratices
|
||||
url: /pmd_best_practices.html
|
||||
output: web, pdf
|
||||
- title: Support
|
||||
url: /mydoc_support.html
|
||||
- title: Tools / Integrations
|
||||
url: /pmd_tools.html
|
||||
output: web, pdf
|
||||
- title: Getting Help
|
||||
url: /pmd_help.html
|
||||
output: web, pdf
|
||||
- title: Rule Reference
|
||||
output: web, pdf
|
||||
folderitems:
|
||||
- title: Apex Rules
|
||||
url: /rules/apex.html
|
||||
url: /pmd_rules_apex.html
|
||||
output: web, pdf
|
||||
- title: Java Rules
|
||||
url: /rules/java.html
|
||||
url: /pmd_rules_java.html
|
||||
output: web, pdf
|
||||
- title: Developer Documentation
|
||||
output: web, pdf
|
||||
folderitems:
|
||||
- title: Code Style
|
||||
url: /pmd_devdocs_codestyle.html
|
||||
output: web, pdf
|
||||
- title: Setting up your IDE
|
||||
url: /pmd_devdocs_setting_up_ide.html
|
||||
output: web, pdf
|
||||
- title: Pull Requests
|
||||
url: /pmd_devdocs_pull_requests.html
|
||||
output: web, pdf
|
||||
- title: Building PMD from source
|
||||
url: /pmd_devdocs_building.html
|
||||
output: web, pdf
|
||||
- title: Testing / Test Framework
|
||||
url: /pmd_devdocs_testing.html
|
||||
output: web, pdf
|
||||
- title: Releasing
|
||||
url: /pmd_devdocs_releasing.html
|
||||
output: web, pdf
|
||||
- title: Architecture
|
||||
url: /pmd_devdocs_architecture.html
|
||||
output: web, pdf
|
||||
- title: Roadmap
|
||||
url: /pmd_devdocs_roadmap.html
|
||||
output: web, pdf
|
||||
- title: How PMD Works
|
||||
url: /how_pmd_works.html
|
||||
url: /pmd_devdocs_how_pmd_works.html
|
||||
output: web, pdf
|
||||
- title: Writing a Rule
|
||||
url: /writing_pmd_rules.html
|
||||
url: /pmd_devdocs_writing_pmd_rules.html
|
||||
output: web, pdf
|
||||
- title: Writing XPath Rules
|
||||
url: /writing_xpath_rules.html
|
||||
url: /pmd_devdocs_writing_xpath_rules.html
|
||||
output: web, pdf
|
||||
- title: Making Rulesets
|
||||
url: /making_rulesets.html
|
||||
url: /pmd_devdocs_making_rulesets.html
|
||||
output: web, pdf
|
||||
- title: Rule Guidelines
|
||||
url: /rule_guidelines.html
|
||||
url: /pmd_devdocs_rule_guidelines.html
|
||||
output: web, pdf
|
||||
- title: Info for Developers
|
||||
url: /info_for_developers.html
|
||||
url: /pmd_devdocs_info_for_developers.html
|
||||
output: web, pdf
|
||||
- title: Adding a New Language
|
||||
url: /adding_new_language.html
|
||||
url: /pmd_devdocs_adding_new_language.html
|
||||
output: web, pdf
|
||||
- title: Adding a New CPD Language
|
||||
url: /adding_new_cpd_language.html
|
||||
output: web, pdf
|
||||
- title: Compiling PMD
|
||||
url: /compiling_pmd.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Supported Languages
|
||||
output: web, pdf
|
||||
folderitems:
|
||||
|
||||
- title: Apex (Salesforce)
|
||||
url: /language_apex.html
|
||||
url: /pmd_devdocs_adding_new_cpd_language.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Release Notes
|
||||
@ -1,60 +0,0 @@
|
||||
# This is your sidebar TOC. The sidebar code loops through sections here and provides the appropriate formatting.
|
||||
|
||||
|
||||
entries:
|
||||
- title: Sidebar
|
||||
product: Product1
|
||||
version: 1.0
|
||||
folders:
|
||||
|
||||
- title:
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
folderitems:
|
||||
- title:
|
||||
url: /titlepage
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
- title:
|
||||
url: /tocpage
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
|
||||
- title: Getting Started
|
||||
output: web, pdf
|
||||
folderitems:
|
||||
- title: Product 1 home
|
||||
url: /p1_landing_page.html
|
||||
output: web
|
||||
|
||||
- title: Sample 1
|
||||
url: /p1_sample1.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 2
|
||||
url: /p1_sample2.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 3
|
||||
url: /p1_sample3.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Another heading
|
||||
output: web, pdf
|
||||
|
||||
folderitems:
|
||||
- title: Sample 4
|
||||
url: /p1_sample4.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 5
|
||||
url: /p1_sample5.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 6
|
||||
url: /p1_sample6.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 7
|
||||
url: /p1_sample7.html
|
||||
output: web, pdf
|
||||
@ -1,92 +0,0 @@
|
||||
# This is your sidebar TOC. The sidebar code loops through sections here and provides the appropriate formatting.
|
||||
|
||||
entries:
|
||||
- title: Product2
|
||||
product: Product2
|
||||
version: 1.0
|
||||
folders:
|
||||
|
||||
- title:
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
folderitems:
|
||||
- title:
|
||||
url: /titlepage
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
- title:
|
||||
url: /tocpage
|
||||
output: pdf
|
||||
type: frontmatter
|
||||
|
||||
- title: Introduction
|
||||
output: web, pdf
|
||||
folderitems:
|
||||
|
||||
- title: Overview
|
||||
url: /p2_landing_page.html
|
||||
output: web
|
||||
|
||||
- title: Simple Workflow
|
||||
output: web, pdf
|
||||
folderitems:
|
||||
|
||||
- title: Sample 1
|
||||
url: /p2_sample1.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 2
|
||||
url: /p2_sample2.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 3
|
||||
url: /p2_sample3.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 4
|
||||
url: /p2_sample4.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 5
|
||||
url: /p2_sample5.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Complex Workflow
|
||||
output: web, pdf
|
||||
folderitems:
|
||||
|
||||
- title: Sample 6
|
||||
url: /p2_sample6.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 7
|
||||
url: /p2_sample7.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 8
|
||||
url: /p2_sample8.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 9
|
||||
url: /p2_sample9.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 10
|
||||
url: /p2_sample10.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 11
|
||||
url: /p2_sample11.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 12
|
||||
url: /p2_sample12.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 13
|
||||
url: /p2_sample13.html
|
||||
output: web, pdf
|
||||
|
||||
- title: Sample 14
|
||||
url: /p2_sample14.html
|
||||
output: web, pdf
|
||||
@ -1,17 +1,8 @@
|
||||
{% if page.sidebar == "home_sidebar" %}
|
||||
{% assign sidebar = site.data.sidebars.home_sidebar.entries %}
|
||||
|
||||
{% elsif page.sidebar == "product1_sidebar" %}
|
||||
{% assign sidebar = site.data.sidebars.product1_sidebar.entries %}
|
||||
|
||||
{% elsif page.sidebar == "product2_sidebar" %}
|
||||
{% assign sidebar = site.data.sidebars.product2_sidebar.entries %}
|
||||
|
||||
{% elsif page.sidebar == "mydoc_sidebar" %}
|
||||
{% assign sidebar = site.data.sidebars.mydoc_sidebar.entries %}
|
||||
{% if page.sidebar == "pmd_sidebar" %}
|
||||
{% assign sidebar = site.data.sidebars.pmd_sidebar.entries %}
|
||||
|
||||
{% else %}
|
||||
{% assign sidebar = site.data.sidebars.home_sidebar.entries %}
|
||||
{% assign sidebar = site.data.sidebars.pmd_sidebar.entries %}
|
||||
{% endif %}
|
||||
|
||||
|
||||
@ -20,14 +11,6 @@
|
||||
sidebar configuration for print files
|
||||
{% endcomment %}
|
||||
|
||||
{% if site.product == "mydoc" %}
|
||||
{% assign sidebar_pdf = site.data.sidebars.mydoc_sidebar.entries %}
|
||||
{% endif %}
|
||||
|
||||
{% if site.product == "product1" %}
|
||||
{% assign sidebar_pdf = site.data.sidebars.product1_sidebar.entries %}
|
||||
{% endif %}
|
||||
|
||||
{% if site.product == "product2" %}
|
||||
{% assign sidebar_pdf = site.data.sidebars.product2_sidebar.entries %}
|
||||
{% if site.product == "pmd" %}
|
||||
{% assign sidebar_pdf = site.data.sidebars.pmd_sidebar.entries %}
|
||||
{% endif %}
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
<div class="col-lg-12 footer">
|
||||
©{{ site.time | date: "%Y" }} {{site.company_name}}. All rights reserved. <br />
|
||||
{% if page.last_updated %}<span>Page last updated:</span> {{page.last_updated}}<br/>{% endif %} Site last generated: {{ site.time | date: "%b %-d, %Y" }} <br />
|
||||
<p><img src="{{ "images/company_logo.png" }}" alt="Company logo"/></p>
|
||||
<p><img src="{{ "images/pmd-logo-small.png" }}" alt="Company logo"/></p>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
BIN
docs/images/pmd-logo-big.png
Normal file
BIN
docs/images/pmd-logo-big.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 12 KiB |
BIN
docs/images/pmd-logo-small.png
Normal file
BIN
docs/images/pmd-logo-small.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.0 KiB |
BIN
docs/images/pmd-logo.png
Normal file
BIN
docs/images/pmd-logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 4.9 KiB |
@ -2,7 +2,7 @@
|
||||
title: PMD Introduction
|
||||
keywords: java
|
||||
tags: [getting_started]
|
||||
sidebar: mydoc_sidebar
|
||||
sidebar: pmd_sidebar
|
||||
permalink: index.html
|
||||
summary: Welcome to PMD, an OpenSource project for analyzing source code.
|
||||
---
|
||||
|
||||
@ -1,22 +0,0 @@
|
||||
---
|
||||
title: About the theme author
|
||||
keywords: documentation theme, jekyll, technical writers, help authoring tools, hat replacements
|
||||
last_updated: July 3, 2016
|
||||
tags: [getting_started]
|
||||
summary: "I have used this theme for projects that I've worked on as a professional technical writer."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_about.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
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 have used this theme and variations of it for various documentation projects. This theme has undergone several major iterations, and now it's fairly stable and full of all the features that I need. You are welcome to use it for your documentation projects for free.
|
||||
|
||||
I think this theme does pretty much everything that you can do with something like OxygenXML, but without the constraints of structured authoring. Everything is completely open and changeable, so if you start tinkering around with the theme's files, you can break things. But it's completely empowering as well!
|
||||
|
||||
With a completely open architecture and code base, you can modify the code to make it do exactly what you want, without having to jump through all kinds of confusing or proprietary code.
|
||||
|
||||
If there's a feature you need but it isn't available here, let me know and I might add it. Alternatively, if you fork the theme, I would love to see your modifications and enhancements.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,254 +0,0 @@
|
||||
---
|
||||
title: About Ruby, Gems, Bundler, and other prerequisites
|
||||
tags: [getting_started, troubleshooting]
|
||||
keywords:
|
||||
summary: "Ruby is a programming language you must have on your computer in order to build Jekyll locally. Ruby has various gems (or plugins) that provide various functionality. Each Jekyll project usually requires certain gems."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_about_ruby_gems_etc.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## About Ruby
|
||||
|
||||
Jekyll runs on Ruby, a programming language. You have to have Ruby on your computer in order to run Ruby-based programs like Jekyll. Ruby is installed on the Mac by default, but you must add it to Windows.
|
||||
|
||||
## About Ruby Gems
|
||||
|
||||
Ruby has a number of plugins referred to as "gems." Just because you have Ruby doesn't mean you have all the necessary Ruby gems that your program needs to run. Gems provide additional functionality for Ruby programs. There are thousands of [Rubygems](https://rubygems.org/) available for you to use.
|
||||
|
||||
Some gems depend on other gems for functionality. For example, the Jekyll gem might depend on 20 other gems that must also be installed.
|
||||
|
||||
Each gem has a version associated with it, and not all gem versions are compatible with each other.
|
||||
|
||||
## Rubygem package managers
|
||||
|
||||
[Bundler](http://bundler.io/) is a gem package manager for Ruby, which means it goes out and gets all the gems you need for your Ruby programs. If you tell Bundler you need the [jekyll gem](https://rubygems.org/gems/jekyll), it will retrieve all the dependencies on the jekyll gem as well -- automatically.
|
||||
|
||||
Not only does Bundler retrieve the right gem dependencies, but it's smart enough to retrieve the right versions of each gem. For example, if you get the [github-pages](https://rubygems.org/gems/github-pages) gem, it will retrieve all of these other gems:
|
||||
|
||||
```
|
||||
github-pages-health-check = 1.1.0
|
||||
jekyll = 3.0.3
|
||||
jekyll-coffeescript = 1.0.1
|
||||
jekyll-feed = 0.4.0
|
||||
jekyll-gist = 1.4.0
|
||||
jekyll-github-metadata = 1.9.0
|
||||
jekyll-mentions = 1.1.2
|
||||
jekyll-paginate = 1.1.0
|
||||
jekyll-redirect-from = 0.10.0
|
||||
jekyll-sass-converter = 1.3.0
|
||||
jekyll-seo-tag = 1.3.2
|
||||
jekyll-sitemap = 0.10.0
|
||||
jekyll-textile-converter = 0.1.0
|
||||
jemoji = 0.6.2
|
||||
kramdown = 1.10.0
|
||||
liquid = 3.0.6
|
||||
mercenary ~> 0.3
|
||||
rdiscount = 2.1.8
|
||||
redcarpet = 3.3.3
|
||||
RedCloth = 4.2.9
|
||||
rouge = 1.10.1
|
||||
terminal-table ~> 1.
|
||||
```
|
||||
|
||||
See how Bundler retrieved version 3.0.3 of the jekyll gem, even though (as of this writing) the latest version of the jekyll gem is 3.1.2? That's because github-pages is only compatible up to jekyll 3.0.3. Bundler handles all of this dependency and version compatibility for you.
|
||||
|
||||
Trying to keep track of which gems and versions are appropriate for your project can be a nightmare. This is the problem Bundler solves. As explained on [Bundler.io](http://bundler.io/):
|
||||
|
||||
> Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.
|
||||
>
|
||||
> Bundler is an exit from dependency hell, and ensures that the gems you need are present in development, staging, and production. Starting work on a project is as simple as bundle install.
|
||||
|
||||
## Gemfiles
|
||||
|
||||
Bundler looks in a project's "Gemfile" (no file extension) to see which gems are required by the project. The Gemfile lists the source and then any gems, like this:
|
||||
|
||||
```
|
||||
source "https://rubygems.org"
|
||||
|
||||
gem 'github-pages'
|
||||
gem 'jekyll'
|
||||
```
|
||||
|
||||
The source indicates the site where Bundler will retrieve the gems: [https://rubygems.org](https://rubygems.org).
|
||||
|
||||
The gems it retrieves are listed separately on each line.
|
||||
|
||||
Here no versions are specified. Sometimes gemfiles will specify the versions like this:
|
||||
|
||||
```
|
||||
gem 'kramdown', '1.0'
|
||||
```
|
||||
|
||||
This means Bundler should get version 1.0 of the kramdown gem.
|
||||
|
||||
To specify a subset of versions, the Gemfile looks like this:
|
||||
|
||||
```
|
||||
gem 'jekyll', '~> 2.3'
|
||||
```
|
||||
The `~>` sign means greater than or equal to the *last digit before the last period in the number*.
|
||||
|
||||
Here it will get any gem equal to 2.3 but less than 3.0.
|
||||
|
||||
If it adds another digit, the scope is affected:
|
||||
|
||||
```
|
||||
gem `jekyll`, `~>2.3.1'
|
||||
```
|
||||
|
||||
This means to get any gem equal to 2.3.1 but less than 2.4.
|
||||
|
||||
If it looks like this:
|
||||
|
||||
```
|
||||
gem 'jekyll', '~> 3.0', '>= 3.0.3'
|
||||
```
|
||||
|
||||
This will get any Jekyll gem between versions 3.0 and up to 3.0.3.
|
||||
|
||||
See this [Stack Overflow post](http://stackoverflow.com/questions/5170547/what-does-tilde-greater-than-mean-in-ruby-gem-dependencies) for more details.
|
||||
|
||||
## Gemfile.lock
|
||||
|
||||
After Bundler retrieves and installs the gems, it makes a detailed list of all the gems and versions it has installed for your project. The snapshot of all gems + versions installed is stored in your Gemfile.lock file, which might look like this:
|
||||
|
||||
```
|
||||
GEM
|
||||
remote: https://rubygems.org/
|
||||
specs:
|
||||
RedCloth (4.2.9)
|
||||
activesupport (4.2.5.1)
|
||||
i18n (~> 0.7)
|
||||
json (~> 1.7, >= 1.7.7)
|
||||
minitest (~> 5.1)
|
||||
thread_safe (~> 0.3, >= 0.3.4)
|
||||
tzinfo (~> 1.1)
|
||||
addressable (2.3.8)
|
||||
coffee-script (2.4.1)
|
||||
coffee-script-source
|
||||
execjs
|
||||
coffee-script-source (1.10.0)
|
||||
colorator (0.1)
|
||||
ethon (0.8.1)
|
||||
ffi (>= 1.3.0)
|
||||
execjs (2.6.0)
|
||||
faraday (0.9.2)
|
||||
multipart-post (>= 1.2, < 3)
|
||||
ffi (1.9.10)
|
||||
gemoji (2.1.0)
|
||||
github-pages (52)
|
||||
RedCloth (= 4.2.9)
|
||||
github-pages-health-check (= 1.0.1)
|
||||
jekyll (= 3.0.3)
|
||||
jekyll-coffeescript (= 1.0.1)
|
||||
jekyll-feed (= 0.4.0)
|
||||
jekyll-gist (= 1.4.0)
|
||||
jekyll-mentions (= 1.0.1)
|
||||
jekyll-paginate (= 1.1.0)
|
||||
jekyll-redirect-from (= 0.9.1)
|
||||
jekyll-sass-converter (= 1.3.0)
|
||||
jekyll-seo-tag (= 1.3.1)
|
||||
jekyll-sitemap (= 0.10.0)
|
||||
jekyll-textile-converter (= 0.1.0)
|
||||
jemoji (= 0.5.1)
|
||||
kramdown (= 1.9.0)
|
||||
liquid (= 3.0.6)
|
||||
mercenary (~> 0.3)
|
||||
rdiscount (= 2.1.8)
|
||||
redcarpet (= 3.3.3)
|
||||
rouge (= 1.10.1)
|
||||
terminal-table (~> 1.4)
|
||||
github-pages-health-check (1.0.1)
|
||||
addressable (~> 2.3)
|
||||
net-dns (~> 0.8)
|
||||
octokit (~> 4.0)
|
||||
public_suffix (~> 1.4)
|
||||
typhoeus (~> 0.7)
|
||||
html-pipeline (2.3.0)
|
||||
activesupport (>= 2, < 5)
|
||||
nokogiri (>= 1.4)
|
||||
i18n (0.7.0)
|
||||
jekyll (3.0.3)
|
||||
colorator (~> 0.1)
|
||||
jekyll-sass-converter (~> 1.0)
|
||||
jekyll-watch (~> 1.1)
|
||||
kramdown (~> 1.3)
|
||||
liquid (~> 3.0)
|
||||
mercenary (~> 0.3.3)
|
||||
rouge (~> 1.7)
|
||||
safe_yaml (~> 1.0)
|
||||
jekyll-coffeescript (1.0.1)
|
||||
coffee-script (~> 2.2)
|
||||
jekyll-feed (0.4.0)
|
||||
jekyll-gist (1.4.0)
|
||||
octokit (~> 4.2)
|
||||
jekyll-mentions (1.0.1)
|
||||
html-pipeline (~> 2.3)
|
||||
jekyll (~> 3.0)
|
||||
jekyll-paginate (1.1.0)
|
||||
jekyll-redirect-from (0.9.1)
|
||||
jekyll (>= 2.0)
|
||||
jekyll-sass-converter (1.3.0)
|
||||
sass (~> 3.2)
|
||||
jekyll-seo-tag (1.3.1)
|
||||
jekyll (~> 3.0)
|
||||
jekyll-sitemap (0.10.0)
|
||||
jekyll-textile-converter (0.1.0)
|
||||
RedCloth (~> 4.0)
|
||||
jekyll-watch (1.3.1)
|
||||
listen (~> 3.0)
|
||||
jemoji (0.5.1)
|
||||
gemoji (~> 2.0)
|
||||
html-pipeline (~> 2.2)
|
||||
jekyll (>= 2.0)
|
||||
json (1.8.3)
|
||||
kramdown (1.9.0)
|
||||
liquid (3.0.6)
|
||||
listen (3.0.6)
|
||||
rb-fsevent (>= 0.9.3)
|
||||
rb-inotify (>= 0.9.7)
|
||||
mercenary (0.3.5)
|
||||
mini_portile2 (2.0.0)
|
||||
minitest (5.8.4)
|
||||
multipart-post (2.0.0)
|
||||
net-dns (0.8.0)
|
||||
nokogiri (1.6.7.2)
|
||||
mini_portile2 (~> 2.0.0.rc2)
|
||||
octokit (4.2.0)
|
||||
sawyer (~> 0.6.0, >= 0.5.3)
|
||||
public_suffix (1.5.3)
|
||||
rb-fsevent (0.9.7)
|
||||
rb-inotify (0.9.7)
|
||||
ffi (>= 0.5.0)
|
||||
rdiscount (2.1.8)
|
||||
redcarpet (3.3.3)
|
||||
rouge (1.10.1)
|
||||
safe_yaml (1.0.4)
|
||||
sass (3.4.21)
|
||||
sawyer (0.6.0)
|
||||
addressable (~> 2.3.5)
|
||||
faraday (~> 0.8, < 0.10)
|
||||
terminal-table (1.5.2)
|
||||
thread_safe (0.3.5)
|
||||
typhoeus (0.8.0)
|
||||
ethon (>= 0.8.0)
|
||||
tzinfo (1.2.2)
|
||||
thread_safe (~> 0.1)
|
||||
|
||||
PLATFORMS
|
||||
ruby
|
||||
|
||||
DEPENDENCIES
|
||||
github-pages
|
||||
jekyll
|
||||
|
||||
BUNDLED WITH
|
||||
1.11.2
|
||||
```
|
||||
|
||||
You can always delete the Gemlock file and run Bundle install again to get the latest versions. You can also run `bundle update`, which will ignore the Gemlock file to get the latest versions of each gem.
|
||||
|
||||
To learn more about Bundler, see [Bundler's Purpose and Rationale](http://bundler.io/rationale.html).
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,27 +0,0 @@
|
||||
---
|
||||
title: Tooltips
|
||||
tags: [formatting]
|
||||
keywords: popovers, tooltips, user interface text, glossaries, definitions
|
||||
last_updated: July 3, 2016
|
||||
summary: "You can add tooltips to any word, such as an acronym or specialized term. Tooltips work well for glossary definitions, because you don't have to keep repeating the definition, nor do you assume the reader already knows the word's meaning."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_adding_tooltips.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## Creating tooltips
|
||||
Because this theme is built on Bootstrap, you can simply use a specific attribute on an element to insert a tooltip.
|
||||
|
||||
Suppose you have a glossary.yml file inside your \_data folder. You could pull in that glossary definition like this:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This renders to the following:
|
||||
|
||||
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,185 +0,0 @@
|
||||
---
|
||||
title: Alerts
|
||||
tags: [formatting]
|
||||
keywords: notes, tips, cautions, warnings, admonitions
|
||||
last_updated: July 3, 2016
|
||||
summary: "You can insert notes, tips, warnings, and important alerts in your content. These notes make use of Bootstrap styling and are available through data references such as site.data.alerts.note."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_alerts.html
|
||||
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.
|
||||
|
||||
```
|
||||
{%raw%}{% include note.html content="This is my note. All the content I type here is treated as a single paragraph." %}{% endraw%}
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
{% include note.html content="This is my note. All the content I type here is treated as a single paragraph." %}
|
||||
|
||||
With alerts, there's just one include property:
|
||||
|
||||
| Property | description |
|
||||
|-------|--------|
|
||||
| content | The content for the alert. |
|
||||
|
||||
If you need multiple paragraphs, enter `<br/><br/>` tags. This is because block level tags aren't allowed here, as Kramdown is processing the content as Markdown despite the fact that the content is surrounded by HTML tags. Here's an example with a break:
|
||||
|
||||
```
|
||||
{%raw%}{% include note.html content="This is my note. All the content I type here is treated as a single paragraph. <br/><br/> Now I'm typing on a new line." %}{% endraw%}
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
{% include note.html content="This is my note. All the content I type here is treated as a single paragraph. <br/><br/> Now I'm typing on a new line." %}
|
||||
|
||||
## Types of alerts available
|
||||
|
||||
There are four types of alerts you can leverage:
|
||||
|
||||
* note.html
|
||||
* tip.html
|
||||
* warning.html
|
||||
* important.html
|
||||
|
||||
They function the same except they have a different color, icon, and alert word. You include the different types by selecting the include template you want. Here are samples of each alert:
|
||||
|
||||
{% include note.html content="This is my note." %}
|
||||
|
||||
{% include tip.html content="This is my tip." %}
|
||||
|
||||
{% include warning.html content="This is my warning." %}
|
||||
|
||||
{% include important.html content="This is my important info." %}
|
||||
|
||||
These alerts leverage includes stored in the \_include folder. The `content` option is a parameter that you pass to the include. In the include, the parameter is passed like this:
|
||||
|
||||
```
|
||||
{% raw %}<div markdown="span" class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> {{include.content}}{% endraw %}</div>
|
||||
```
|
||||
|
||||
The content in `content="This is my note."` gets inserted into the `{% raw %}{{include.content}}}{% endraw %}` part of the template. You can follow this same pattern to build additional includes. See this [Jekyll screencast on includes](http://jekyll.tips/jekyll-casts/includes/) or [this screencast](https://www.youtube.com/watch?v=TJcn_PJ2100) for more information.
|
||||
|
||||
## Callouts
|
||||
|
||||
There's another type of callout available called callouts. This format is typically used for longer callout that spans more than one or two paragraphs, but really it's just a stylistic preference whether to use an alert or callout.
|
||||
|
||||
Here's the syntax for a callout:
|
||||
|
||||
```
|
||||
{% raw %}{% include callout.html content="This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs. " type="primary" %} {% endraw %}
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
{% include callout.html content="This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs." type="primary" %}
|
||||
|
||||
The available properties for callouts are as follows:
|
||||
|
||||
| Property | description |
|
||||
|-------|--------|
|
||||
| content | The content for the callout. |
|
||||
| type | The style for the callout. Options are `danger`, `default`, `primary`, `success`, `info`, and `warning`.|
|
||||
|
||||
The types just define the color of the left border. Each of these callout types get inserted as a class name in the callout template. These class names correspond with styles in Bootstrap. These classes are common Bootstrap class names whose style attributes differ depending on your Bootstrap theme and style definitions.
|
||||
|
||||
Here's an example of each different type of callout:
|
||||
|
||||
{% include callout.html content="This is my **danger** type callout. It has a border on the left whose color you define by passing a type parameter." type="danger" %}
|
||||
|
||||
{% include callout.html content="This is my **default** type callout. It has a border on the left whose color you define by passing a type parameter." type="default" %}
|
||||
|
||||
{% include callout.html content="This is my **primary** type callout. It has a border on the left whose color you define by passing a type parameter." type="primary" %}
|
||||
|
||||
{% include callout.html content="This is my **success** type callout. It has a border on the left whose color you define by passing a type parameter." type="success" %}
|
||||
|
||||
{% include callout.html content="This is my **info** type callout. It has a border on the left whose color you define by passing a type parameter." type="info" %}
|
||||
|
||||
{% include callout.html content="This is my **warning** type callout. It has a border on the left whose color you define by passing a type parameter." type="warning" %}
|
||||
|
||||
Now that in contrast to alerts, callouts don't include the alert word (note, tip, warning, or important). You have to manually include it inside `content` if you want it.
|
||||
|
||||
To include paragraph breaks, use `<br/><br/>` inside the callout:
|
||||
|
||||
```
|
||||
{% raw %}{% include callout.html content="**Important information**: This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs. <br/><br/>Here I am starting a new paragraph, because I have lots of information to share. You may wonder why I'm using line breaks instead of paragraph tags. This is because Kramdown processes the Markdown here as a span rather than a div (for whatever reason). Be grateful that you can be using Markdown at all inside of HTML. That's usually not allowed in Markdown syntax, but it's allowed here." type="primary" %} {% endraw %}
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
{% include callout.html content="**Important information**: This is my callout. It has a border on the left whose color you define by passing a type parameter. I typically use this style of callout when I have more information that I want to share, often spanning multiple paragraphs. <br/><br/>Here I am starting a new paragraph, because I have lots of information to share. You may wonder why I'm using line breaks instead of paragraph tags. This is because Kramdown processes the Markdown here as a span rather than a div (for whatever reason). Be grateful that you can be using Markdown at all inside of HTML. That's usually not allowed in Markdown syntax, but it's allowed here." type="primary" %}
|
||||
|
||||
## 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 (\_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%}
|
||||
```
|
||||
|
||||
The error will say something like this:
|
||||
|
||||
```
|
||||
Liquid Exception: Invalid syntax for include tag. File contains invalid characters or sequences: ... Valid syntax: {%raw%}{% include file.ext param='value' param2='value' %}{%endraw%}
|
||||
```
|
||||
|
||||
To use variables in your include parameters, you must use the "variable parameter" approach. First you use a `capture` tag to capture some content. Then you reference this captured tag in your include. Here's an example.
|
||||
|
||||
In my site configuration file (\_congfig.yml), I have a property called `company_name`.
|
||||
|
||||
```yaml
|
||||
company_name: Your company
|
||||
```
|
||||
|
||||
I want to use this variable in my note include.
|
||||
|
||||
First, before the note I capture the content for my note's include like this:
|
||||
|
||||
```liquid
|
||||
{%raw%}{% capture company_note %}The {{site.company_name}} company is pleased to announce an upcoming release.{% endcapture %}{%endraw%}
|
||||
```
|
||||
|
||||
Now reference the `company_note` in your `include` parameter like this:
|
||||
|
||||
```
|
||||
{%raw%}{% include note.html content=company_note}{%endraw%}
|
||||
```
|
||||
|
||||
Here's the result:
|
||||
|
||||
{% capture company_note %}The {{site.company_name}} is pleased to announce an upcoming release.{% endcapture %}
|
||||
{% include note.html content=company_note %}
|
||||
|
||||
Note the omission of quotation marks with variable parameters.
|
||||
|
||||
Also note that instead of storing the variable in your site's configuration file, you could also put the variable in your page's frontmatter. Then instead of using `{%raw%}{{site.company_name}}{%endraw%}` you would use `{%raw%}{{page.company_name}}{%endraw%}`.
|
||||
|
||||
## Markdown inside of callouts and alerts
|
||||
|
||||
You can use Markdown inside of callouts and alerts, even though this content actually gets inserted inside of HTML in the include. This is one of the advantages of kramdown Markdown. The include template has an attribute of `markdown="span"` that allows for the processor to parse Markdown inside of HTML.
|
||||
|
||||
## Validity checking
|
||||
|
||||
If you have some of the syntax wrong with an alert or callout, you'll see an error when Jekyll tries to build your site. The error may look like this:
|
||||
|
||||
```
|
||||
{% raw %}Liquid Exception: Invalid syntax for include tag: content="This is my **info** type callout. It has a border on the left whose color you define by passing a type parameter. type="info" Valid syntax: {% include file.ext param='value' param2='value' %} in mydoc/mydoc_alerts.md {% endraw %}
|
||||
```
|
||||
|
||||
These errors are a good thing, because it lets you know there's an error in your syntax. Without the errors, you may not realize that you coded something incorrectly until you see the lack of alert or callout styling in your output.
|
||||
|
||||
In this case, the quotation marks aren't set correctly. I forgot the closing quotation mark for the content parameter include.
|
||||
|
||||
## Blast a warning to users on every page
|
||||
|
||||
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.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Atom Text Editor
|
||||
keywords: atom, text editor,
|
||||
last_updated: March 20, 2016
|
||||
summary: "Atom is a free text editor that is a favorite tool of many writers because it is free. This page provides some tips for using Atom."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_atom_text_editor.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
If you haven't downloaded [Atom](https://atom.io/), download and install it. Use this as your editor when working with Jekyll. The syntax highlighting is probably the best among the available editors, as it was designed with Jekyll-authoring in mind. However, if you prefer Sublime Text, WebStorm, or some other editor, you can also use that.
|
||||
|
||||
Customize the invisibles and tab spacing in Atom:
|
||||
|
||||
1. Go to **Atom > Preferences**.
|
||||
2. On the **Settings** tab, keep the default options but also select the following:
|
||||
* **Show Invisibles**
|
||||
* **Soft Wrap**
|
||||
* For the **Tab Length**, type **4**.
|
||||
* For the **Tab Type**, select **soft**.
|
||||
|
||||
Turn off auto-complete:
|
||||
|
||||
1. Go to **Atom > Preferences**.
|
||||
2. Click the **Packages** tab.
|
||||
3. Search for **autocomplete-plus**.
|
||||
4. Disable the autocomplete package.
|
||||
|
||||
### Atom Shortcuts
|
||||
|
||||
* **Cmd + T**: Find file
|
||||
* **Cmd + Shift + F**: Find across project
|
||||
* **Cmd + Alt + S**: Save all
|
||||
|
||||
(For Windows, replace "Cmd" with "Ctrl".)
|
||||
@ -1,68 +0,0 @@
|
||||
---
|
||||
title: Build arguments
|
||||
tags: [publishing]
|
||||
keywords: building, serving, serve, build
|
||||
last_updated: July 3, 2016
|
||||
summary: "You use various build arguments with your Jekyll project. You can also create shell scripts to act as shortcuts for long build commands. You can store the commands in iTerm as profiles as well."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_build_arguments.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## 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 so that Jekyll rebuilds that site each time you make a change, use the `serve` command:
|
||||
|
||||
```
|
||||
jekyll serve
|
||||
```
|
||||
|
||||
By default, the \_config.yml in the root directory 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 like this:
|
||||
|
||||
```
|
||||
jekyll serve --config configs/myspecialconfig.yml --destination ../doc_outputs
|
||||
```
|
||||
|
||||
Here the `configs/myspecialconfig.yml` file is used instead of `_config.yml`. The destination directory is `../doc_outputs`, which would be one level up from your current directory.
|
||||
|
||||
## Shortcuts for the build arguments
|
||||
|
||||
If you have a long build argument and don't want to enter it every time in Jekyll, noting all your configuration details, you can create a shell script and then just run the script. Simply put the build argument into a text file and save it with the .sh extension (for Mac) or .bat extension (for Windows). Then run it like this:
|
||||
|
||||
```
|
||||
. myscript.sh
|
||||
```
|
||||
|
||||
My preference is to add the scripts to profiles in iTerm. See [iTerm Profiles][mydoc_iterm_profiles] for more details.
|
||||
|
||||
## Stop a server
|
||||
|
||||
When you're done with the preview server, press **Ctrl+C** to exit out of it. If you exit iTerm or Terminal without shutting down the server, the next time you build your site, or if you build multiple sites with the same port, 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.
|
||||
|
||||
To kill all Jekyll instances, use this:
|
||||
|
||||
```
|
||||
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
|
||||
```
|
||||
|
||||
I recommend creating a profile in iTerm that stores this command. Here's what the iTerm settings look like:
|
||||
|
||||
{% include image.html file="killalljekyll.png" caption="iTerm profile settings to kill all Jekyll" %}
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,197 +0,0 @@
|
||||
---
|
||||
title: 10. Configure the build scripts
|
||||
tags:
|
||||
- publishing
|
||||
keywords: "build scripts, generating outputs, building, publishing"
|
||||
last_updated: "November 30, 2016"
|
||||
summary: "You need to customize the build scripts. These script automate the publishing of your PDFs and web outputs through shell scripts on the command line."
|
||||
series: "Getting Started"
|
||||
weight: 10
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_build_scripts.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
{% include custom/getting_started_series.html %}
|
||||
|
||||
## About the build scripts
|
||||
|
||||
The mydoc project has 5 build scripts and a script that runs them all. These scripts will require a bit of detail to configure. Every team member who is publishing on the project should set up their folder structure in the way described here.
|
||||
|
||||
## Get Set Up
|
||||
|
||||
Your command-line terminal opens up to your user name (for example, `Users/tjohnson`). I like to put all of my projects from repositories into a subfolder under my username called "projects." This makes it easy to get to the projects from the command line. You can vary from the project organization I describe here, but following the pattern I outline will make configuration easier.
|
||||
|
||||
To set up your projects:
|
||||
|
||||
1. Set up your Jekyll theme in a folder called "docs." All of the source files for every project the team is working on should live in this directory. Most likely you already either downloaded or cloned the jekyll-documentation-theme. Just rename the folder to "docs" and move it into the projects folder as shown here.
|
||||
2. In the same root directory where the docs folder is, create another directory parallel to docs called doc_outputs.
|
||||
|
||||
Thus, your folder structure should be something like this:
|
||||
|
||||
```
|
||||
projects
|
||||
- docs
|
||||
- doc_outputs
|
||||
```
|
||||
|
||||
The docs folder contains the source of all your files, while the doc_outputs contains the site outputs.
|
||||
|
||||
## Configure the Build Scripts
|
||||
|
||||
For the mydocs project, you'll see a series of build scripts for each project. There are 5 build scripts, described in the following sections. Note that you really only need to run the last one, e.g., mydoc_all.sh, because it runs all of the build scripts. But you have to make sure each script is correctly configured so that they all build successfully.
|
||||
|
||||
{% include tip.html content="In the descriptions of the build scripts, \"mydoc\" is used as the sample project. Substitute in whatever your real project name is." %}
|
||||
|
||||
### mydoc_1_multiserve_pdf.sh
|
||||
|
||||
Here's what this script looks like:
|
||||
|
||||
```
|
||||
echo 'Killing all Jekyll instances'
|
||||
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
|
||||
clear
|
||||
|
||||
|
||||
echo "Building PDF-friendly HTML site for Mydoc Writers ..."
|
||||
jekyll serve --detach --config configs/mydoc/config_writers.yml,configs/mydoc/config_writers_pdf.yml
|
||||
echo "done"
|
||||
|
||||
echo "Building PDF-friendly HTML site for Mydoc Designers ..."
|
||||
jekyll serve --detach --config configs/mydoc/config_designers.yml,configs/mydoc/config_designers_pdf.yml
|
||||
echo "done"
|
||||
|
||||
echo "All done serving up the PDF-friendly sites. Now let's generate the PDF files from these sites."
|
||||
echo "Now run . mydoc_2_multibuild_pdf.sh"
|
||||
```
|
||||
|
||||
After killing all existing Jekyll instances that may be running, this script serves up a PDF friendly version of the docs (in HTML format) at the destination specified in the configuration file.
|
||||
|
||||
Each of your configuration files needs to have a destination like this: `../doc_outputs/mydoc/adtruth-java`. That is, the project should build in the doc_outputs folder, in a subfolder that matches the project name.
|
||||
|
||||
The purpose of this script is to make a version of the HTML output that is friendly to the Prince XML PDF generator. This version of the output strips out the sidebar, topnav, and other components to just render a bare-bones HTML representation of the content.
|
||||
|
||||
Customize the script with your own PDF configuration file names.
|
||||
|
||||
### mydoc_2_multibuild_pdf.sh
|
||||
|
||||
Here's what this script looks like:
|
||||
|
||||
```
|
||||
# Doc Writers
|
||||
echo "Building the Mydoc Writers PDF ..."
|
||||
prince --javascript --input-list=../doc_outputs/mydoc/writers-pdf/prince-file-list.txt -o mydoc/files/mydoc_writers_pdf.pdf;
|
||||
echo "done"
|
||||
|
||||
# Doc Designers
|
||||
echo "Building Mydoc Designers PDF ..."
|
||||
prince --javascript --input-list=../doc_outputs/mydoc/designers-pdf/prince-file-list.txt -o mydoc/files/mydoc_designers_pdf.pdf;
|
||||
echo "done"
|
||||
|
||||
echo "All done building the PDFs!"
|
||||
echo "Now build the web outputs: . mydoc_3_multibuild_web.sh"
|
||||
```
|
||||
|
||||
This script builds the PDF output using the Prince command. The script reads the location of the prince-file-list.txt file in the PDF friendly output folder (as defined in the previous script) and builds a PDF.
|
||||
|
||||
The Prince build command takes an input parameter (`--input-list=`) that lists where all the pages are (prince-file-list.txt), and then combines all the pages into a PDF, including cross-references and other details. The Prince build command also specifies the output folder (`-o`).
|
||||
|
||||
The prince-file-list.txt file (which simply contains a list of URLs to HTML pages) is generated by iterating through the table of contents (mydoc_sidebar.yml) and creating a list of URLs. You can open up prince-file-list.txt in the doc output to ensure that it has a list of absolute URLs (not relative) in order for Prince to build the PDF.
|
||||
|
||||
This is one way the configuration file for the PDF-friendly output differs from the HTML output. (If the PDF isn't building, it's because the prince-file-list.txt in the output is empty or it contains relative URLs.)
|
||||
|
||||
The Prince build script puts the output PDF into the mydoc/mydoc/files directory. Now you can reference the PDF file in your HTML site. For example, on the homepage you can allow people to download a PDF of the content at files/adtruth_dotnet_pdf.pdf.
|
||||
|
||||
### mydoc_3_multibuild_web.sh
|
||||
|
||||
Here's what this script looks like:
|
||||
|
||||
```
|
||||
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
|
||||
clear
|
||||
|
||||
echo "Building Mydoc Writers website..."
|
||||
jekyll build --config configs/doc/config_writers.yml
|
||||
# jekyll serve --config configs/doc/config_writers.yml
|
||||
echo "done"
|
||||
|
||||
echo "Building Mydoc Designers website..."
|
||||
jekyll build --config configs/doc/config_designers.yml
|
||||
# jekyll serve --config configs/doc/config_designers.yml
|
||||
echo "done"
|
||||
|
||||
echo "All finished building all the web outputs!!!"
|
||||
echo "Now push the builds to the server with . mydoc_4_publish.sh"
|
||||
```
|
||||
|
||||
After killing all Jekyll instances, this script builds an HTML version of the projects and puts the output into the doc_outputs folder. This is the version of the content that users will mainly navigate. Since the sites are built with relative links, you can browse to the folder on your local machine, double-click the index.html file, and see the site.
|
||||
|
||||
The `#` part below the `jekyll build` commands contains a serve command that is there for mere convenience in case you want to serve up just one site among many that you're building. For example, if you don't want to build everything — just one site — you might just use the serve command instead. (Anything after # in a YAML file comments out the content.)
|
||||
|
||||
### mydoc_4_publish.sh
|
||||
|
||||
Here's what this script looks like:
|
||||
|
||||
```
|
||||
echo "remove previous directory and any subdirectories without a warning prompt"
|
||||
ssh yourusername@yourdomain.com 'rm -rf /var/www/html/yourpublishingdirectory'
|
||||
|
||||
echo "push new content into the remote directory"
|
||||
scp -r -vrC ../mydoc_outputs/doc-writers yourusername@yourdomain:/var/www/html/yourpublishingdirectory
|
||||
|
||||
echo "All done pushing doc outputs to the server"
|
||||
|
||||
```
|
||||
|
||||
This script assumes you're publishing content onto a Linux server.
|
||||
|
||||
Change `yourusername` to your own user name.
|
||||
|
||||
This script first removes the project folder on /var/www/html/yourpublishingdirectory site and then transfers the content from doc_outputs over to the appropriate folder in /var/www/html/yourpublishingdirectory.
|
||||
|
||||
Note that the delete part of the script (`rm -rf`) works really well. It annihilates a folder in a heartbeat and doesn't give you any warning prompts, so make sure you have it set up correctly.
|
||||
|
||||
Also, in case you haven't set up the SSH publishing without a password, see [Getting around the password prompts in SCP][mydoc_no_password_prompts_scp]. Otherwise the script will stop and ping you to enter your password for each directory it transfers.
|
||||
|
||||
### (Optional) Push to repositories
|
||||
|
||||
This script isn't included in the theme, but you might optionally decide to push the built sites into another github repository. For example, if you're using Cloud Cannon to deploy your sites, you can have Cloud Cannon read files from a specific Github repository.
|
||||
|
||||
Here's what this script looks like:
|
||||
|
||||
```
|
||||
cd doc_outputs/mydoc/designers
|
||||
git add --all
|
||||
git commit -m "publishing latest version of docs"
|
||||
git push
|
||||
echo "All done pushing to Github"
|
||||
echo "Here's the link to download the guides..."
|
||||
cd ../../docs
|
||||
```
|
||||
|
||||
This final script simply makes a commit into a Github repo for one of your outputs.
|
||||
|
||||
The doc_outputs/mydoc/designers contains the site output from mydoc, so when you push content from this folder into Github, you're actually pushing the HTML site output into Github, not the mydoc source files.
|
||||
|
||||
Your delivery team can also grab the site output from these repos. After downloading it, the person unzips the folder and sees the website folders inside.
|
||||
|
||||
### mydoc_all.sh
|
||||
|
||||
Here's what this script looks like:
|
||||
|
||||
```
|
||||
. deviceinsight_1_multiserve_pdf.sh; . deviceinsight_2_multibuild_pdf.sh; . deviceinsight_3_multibuild_web.sh; . deviceinsight_4_publish.sh;
|
||||
```
|
||||
|
||||
This script simply runs the other scripts. To sequence the commands, you just separate them with semicolons. (If you added the optional script, be sure to include it here.)
|
||||
|
||||
After you've configured all the scripts, you can run them all by running `. mydoc_all.sh`. You might want to run this script at lunchtime, since it may take about 10 to 20 minutes to completely build the scripts. But note that since everything is now automated, you don't have to do anything at all after executing the script. After the script finishes, everything is published and in the right location.
|
||||
|
||||
|
||||
## Test out the scripts
|
||||
|
||||
After setting up and customizing the build scripts, run a few tests to make sure everything is generating correctly. Getting this part right is somewhat difficult and may likely require you to tinker around with the scripts a while before it works flawlessly.
|
||||
|
||||
{% include custom/getting_started_series_next.html %}
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,27 +0,0 @@
|
||||
---
|
||||
title: Code samples
|
||||
tags: [formatting]
|
||||
keywords: dcode samples syntax highlighting
|
||||
last_updated: July 3, 2016
|
||||
datatable: true
|
||||
summary: "You can use fenced code blocks with the language specified after the first set of backtick fences."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_code_samples.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## Code Samples
|
||||
|
||||
Use fenced code blocks with the language specified, like this:
|
||||
|
||||
```js
|
||||
console.log('hello');
|
||||
````
|
||||
|
||||
**Result:**
|
||||
|
||||
```js
|
||||
console.log('hello');
|
||||
```
|
||||
|
||||
For the list of supported languages you can use (similar to `js` for JavaScript), see [Supported languages](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers).
|
||||
@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Collections
|
||||
tags: [content_types]
|
||||
keywords: groups, api, structure
|
||||
last_updated: July 3, 2016
|
||||
summary: "Collections are useful if you want to loop through a special folder of pages that you make available in a content API. You could also use collections if you have a set of articles that you want to treat differently from the other content, with a different layout or format."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_collections.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## 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/2016/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.collectionname` namespace, where `collectionname` is what you've configured. 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.
|
||||
|
||||
## How to use collections
|
||||
|
||||
I haven't found a huge use for collections in normal documentation. However, I did find a use for collections in generating a tooltip file that would be used for delivering tooltips to a user interface from text files in the documentation. See [Help APIs and UI tooltips][mydoc_help_api] for details.
|
||||
|
||||
## Video tutorial on collections
|
||||
|
||||
See this [video tutorial on Jekyll.tips](http://jekyll.tips/jekyll-casts/introduction-to-collections/) for more details on collections.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,57 +0,0 @@
|
||||
---
|
||||
title: Commenting on files
|
||||
tags:
|
||||
- navigation
|
||||
keywords: "annotations, comments, feedback"
|
||||
last_updated: "November 30, 2016"
|
||||
summary: "You can add a button to your pages that allows people to add comments."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_commenting_on_files.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## About the review process
|
||||
|
||||
If you're using the doc as code approach, you might also consider using the same techniques for reviewing the doc as people use in reviewing code. This approach will involve using Github to edit the files.
|
||||
|
||||
There's an Edit me button on each page on this theme. This button allows collaborators to edit the content on Github.
|
||||
|
||||
Here's the code for that button on the page.html layout:
|
||||
|
||||
|
||||
```
|
||||
{% raw %}{% 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>
|
||||
|
||||
{% endif %}{% 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
|
||||
|
||||
If you want people to collaborate on your project so that their edits get committed to a branch on your project, you need to add them as collaborators. For your Github repo, click **Settings** and add the collaborators on the Collaborators tab using their Github usernames.
|
||||
|
||||
If you don't want to allow anyone to commit to your Github branch, don't add the reviewers as collaborators. When someone makes an edit, Github will fork the theme. The person's edit then will appear as a pull request to your repo. You can then choose to merge the change indicated in the pull or not.
|
||||
|
||||
{% include note.html content="When you process pull requests, you have to accept everything or nothing. You can't pick and choose which changes you'll merge. Therefore you'll probably want to edit the branch you're planning to merge or ask the contributor to make some changes to the fork before processing the pull request." %}
|
||||
|
||||
|
||||
## Workflow
|
||||
|
||||
Users will make edits in your "reviews" branch (or whatever you want to call it). You can then commit those edits as you make updates.
|
||||
|
||||
When you're finished making all updates in the branch, you can merge the branch into the master.
|
||||
|
||||
Note that if you're making updates online, those updates will be out of sync with any local edits.
|
||||
|
||||
{% include warning.html content="Don't make edits both online using Github's browser-based interface AND offline on your local machine using your local tools. When you try to push from your local, you'll likely get a merge conflict error. Instead, make sure you do a pull and update on your local after making any edits online." %}
|
||||
|
||||
## Prose.io
|
||||
|
||||
Prose.io is an overlay on Github that would allow people to make comments in an easier interface. If you simply go to [prose.io](http://prose.io), it asks to authorize your Github account, and so it will read files directly from Github but in the Prose.io interface.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,156 +0,0 @@
|
||||
---
|
||||
title: Conditional logic
|
||||
tags: [single_sourcing]
|
||||
keywords: if else logic, conditions, conditional attributes, conditional filtering
|
||||
last_updated: July 3, 2016
|
||||
summary: "You can implement advanced conditional logic that includes if statements, or statements, unless, and more. This conditional logic facilitates single sourcing scenarios in which you're outputting the same content for different audiences."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_conditional_logic.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## About Liquid and conditional statements
|
||||
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. This is how I previously configured the theme. I had different configuration files for each output. Each configuration file specified different values for product, audience, version, and so on. Then I had different build processes that would leverage the different configuration files. It seemed like a perfect implementation of DITA-like techniques with Jekyll.
|
||||
|
||||
But I soon found that having lots of separate outputs for a project was undesirable. If you have 10 different outputs that have different nuances for different audiences, it's hard to manage and maintain. In this latest version of the theme, I consolidated all information into the same output to explicitly do away with the multi-output approach.
|
||||
|
||||
As such, the conditional logic won't have as much play as it previously did. Instead of conditions, you'll probably want to incorporate [navtabs](mydoc_navtabs) to split up the information.
|
||||
|
||||
However, you can still of course use conditional logic as needed.
|
||||
|
||||
{% include tip.html content="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." %}
|
||||
|
||||
## Where to store filtering values
|
||||
|
||||
You can filter content based on values that you have set either in your page's frontmatter, a 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 or page frontmatter, 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 page's frontmatter. Suppose you have the following in your frontmatter:
|
||||
|
||||
```
|
||||
platform: mac
|
||||
```
|
||||
|
||||
On a page in my site (it can be HTML or markdown), you can conditionalize content using the following:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if page.platform == "mac" %}
|
||||
Here's some info about the Mac.
|
||||
{% elsif page.platform == "windows" %}
|
||||
Here's some info about Windows ...
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
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 page.audience == "writer" %}
|
||||
2. Add in a pound of meat.
|
||||
{% elsif page.audience == "designer" %}
|
||||
3. Add in an extra can of beans.
|
||||
{% endif %}
|
||||
3. Bake in oven for 45 min.
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You don't need the `elsif` or `else`. You could just use an `if` (but be sure to close it with `endif`).
|
||||
|
||||
## 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 %}
|
||||
```liquid
|
||||
{% if page.audience contains "vegan" or page.audience == "vegetarian" %}
|
||||
Then run this...
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Note that you have to specify the full condition each time. You can't shorten the above logic to the following:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if page.audience contains "vegan" or "vegetarian" %}
|
||||
// run this.
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This won't work.
|
||||
|
||||
## Unless operator
|
||||
|
||||
You can also use `unless` in your logic, like this:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% unless site.output == "pdf" %}
|
||||
...do this
|
||||
{% endunless %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
When figuring out this logic, read it like this: "Run the code here *unless* this condition is satisfied."."
|
||||
|
||||
Don't read it the other way around or you'll get confused. (It's *not* executing the code only if the condition is satisfied.)
|
||||
|
||||
## Storing conditions in the \_data folder
|
||||
|
||||
Here's an example of using conditional logic based on a value in a data file:
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% if site.data.options.output == "alpha" %}
|
||||
show this content...
|
||||
{% elsif site.data.options.output == "beta" %}
|
||||
show this content...
|
||||
{% else %}
|
||||
this shows if neither of the above two if conditions are met.
|
||||
{% endif %}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
To use this, I would need to have a \_data folder called options where the `output` property is stored.
|
||||
|
||||
## Specifying the location for \_data
|
||||
|
||||
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 files.
|
||||
|
||||
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 alpha configuration file, specify the data source like this:
|
||||
|
||||
```
|
||||
data_source: data_alpha
|
||||
```
|
||||
|
||||
Then create a folder called \_data_alpha.
|
||||
|
||||
For your beta configuration file, specify the data source like this:
|
||||
|
||||
```
|
||||
data_source: data_beta
|
||||
```
|
||||
|
||||
Then create a folder called \_data_beta.
|
||||
|
||||
|
||||
## Conditions versus includes
|
||||
|
||||
If you have a lot of conditions in your text, it can get confusing. As a best practice, whenever you insert an `if` condition, add the `endif` at the same time. This will reduce the chances of forgetting to close the if statement. Jekyll won't build if there are problems with the liquid logic.
|
||||
|
||||
If your text is getting busy with a lot of conditional statements, consider putting a lot of content into includes so that you can more easily see where the conditions begin and end.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,54 +0,0 @@
|
||||
---
|
||||
title: Content reuse
|
||||
tags: [single_sourcing]
|
||||
keywords: includes, conref, dita, transclusion, transclude, inclusion, reference
|
||||
last_updated: July 3, 2016
|
||||
summary: "You can reuse chunks of content by storing these files in the includes folder. You then choose to include the file where you need it. This works similar to conref in DITA, except that you can include the file in any content type."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_content_reuse.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
## About content reuse
|
||||
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/custom folder and then use a tag like this:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{% include custom/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 the following Jekyll cast for more info about using parameters with includes:
|
||||
|
||||
<iframe width="640" height="480" src="https://www.youtube.com/embed/kzpGqdEMbIs" frameborder="0" allowfullscreen></iframe>
|
||||
|
||||
## Page-level variables
|
||||
|
||||
You can also create custom variables in your frontmatter like this:
|
||||
|
||||
{% raw %}
|
||||
```yaml
|
||||
---
|
||||
title: Page-level variables
|
||||
permalink: page_level_variables/
|
||||
thing1: Joe
|
||||
thing2: Dave
|
||||
---
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
You can then access the values in those custom variables using the `page` namespace, like this:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
thing1: {{page.thing1}}
|
||||
thing2: {{page.thing2}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
|
||||
I use includes all the time. Most of the includes in the \_includes directory are pulled into the theme layouts. For those includes that change, I put them inside custom and then inside a specific project folder.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,86 +0,0 @@
|
||||
---
|
||||
title: Excluding files
|
||||
tags: [single_sourcing]
|
||||
last_updated: July 3, 2016
|
||||
keywords: exclusion, separating outputs, removing files from outputs
|
||||
summary: "By default, all the files in your Jekyll project are included in the output (this differs from DITA projects, which don't include files unless noted on the map). If you're single sourcing, you'll need to exclude the files that shouldn't be included in the output. The sidebar doesn't control inclusion or exclusion."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_exluding_files.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
|
||||
## About exclusion
|
||||
By default, all files in your project are included in your output (regardless of whether they're listed in the sidebar_doc.yml file or not). To exclude files, note them in the `exclude` section in the configuration file. Here's a sample:
|
||||
|
||||
```
|
||||
|
||||
exclude:
|
||||
- mydoc_writers_*
|
||||
- bower_components
|
||||
- Gemfile
|
||||
```
|
||||
|
||||
If you have different outputs for your site, you'll want to customize the exclude sections in your various configuration files.
|
||||
|
||||
## Exclude strategies
|
||||
Here's the process I recommend. Put all files in the root directory of your project. Suppose one project's name is alpha and the other is beta. Then name each file as follows:
|
||||
|
||||
* alpha_sample.html
|
||||
* beta_sample.html
|
||||
|
||||
In your exclude list for your beta project, specify it as follows:
|
||||
|
||||
```
|
||||
exclude:
|
||||
- alpha_*
|
||||
```
|
||||
|
||||
In your exclude list for your alpha project, specify it as follows:
|
||||
|
||||
```
|
||||
exclude:
|
||||
- beta_*
|
||||
```
|
||||
|
||||
If you have more sophisticated exclusion, add another level to your file names. For example, if you have different programming languages you want to filter by, add this:
|
||||
|
||||
* alpha_java_sample.html
|
||||
* alpha_cpp_sample.html
|
||||
|
||||
Then you exclude files for your Alpha C++ project as follows:
|
||||
|
||||
```
|
||||
exclude:
|
||||
|
||||
- alpha_java_*
|
||||
- beta_*
|
||||
```
|
||||
|
||||
And you exclude files for your Alpha Java project as follows:
|
||||
|
||||
```
|
||||
exclude:
|
||||
|
||||
- alpha_cpp_*
|
||||
- alpha_beta_*
|
||||
```
|
||||
|
||||
When you exclude folders, include the trailing slash at the end of the folder name:
|
||||
|
||||
```
|
||||
exclude:
|
||||
- images/alpha/
|
||||
```
|
||||
|
||||
There isn't a way to automatically exclude anything. 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 \_drafts folder or add `published: false` in the frontmatter. The \_drafts folder is excluded by default, so you don't have to specify it in your exclude list.
|
||||
|
||||
## Limitations
|
||||
|
||||
What if a file should appear in two projects but not the third? This can get tricky. For some files, rather than using a wildcard, you may need to manually specify the entire filename that you're excluding instead of excluding it by way of a wildcard pattern.
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,136 +0,0 @@
|
||||
---
|
||||
title: FAQ layout
|
||||
permalink: mydoc_faq_layout.html
|
||||
sidebar: mydoc_sidebar
|
||||
tags: [special_layouts]
|
||||
keywords: frequently asked questions, FAQ, question and answer, collapsible sections, expand, collapse
|
||||
last_updated: November 30, 2015
|
||||
summary: "You can use an accordion-layout that takes advantage of Bootstrap styling. This is useful for an FAQ page."
|
||||
toc: false
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
<p>If you want to use an FAQ format, use the syntax shown on the faq.html page. Rather than including code samples here (which are bulky with a lot of nested <code>div</code> tags), just look at the source in the mydoc_faq.html theme file.</p>
|
||||
|
||||
<div class="panel-group" id="accordion">
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="noCrossRef 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 noCrossRef">
|
||||
<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="noCrossRef 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 noCrossRef">
|
||||
<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="noCrossRef 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 noCrossRef">
|
||||
<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="noCrossRef 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="noCrossRef 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="noCrossRef 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="noCrossRef 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="noCrossRef 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="noCrossRef 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 -->
|
||||
|
||||
{% include links.html %}
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,185 +0,0 @@
|
||||
---
|
||||
title: Git notes and tips
|
||||
summary: "If you're interacting with your team using Git, the notes and tips will help you collaborate efficiently."
|
||||
tags: collaboration
|
||||
keywords: git, github, collaboration, interaction, file sharing, push
|
||||
published: false
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_git_collaboration.html
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
|
||||
hg fetch does a pull and update at the same time
|
||||
you're prompted about any conflicts
|
||||
you fix them. then you do this:
|
||||
|
||||
|
||||
hg pull -u (i think this is pull and then update)
|
||||
|
||||
$ hg [COMMAND] [ARGUMENTS]
|
||||
|
||||
hg init
|
||||
hg add
|
||||
hg log
|
||||
hg diff
|
||||
hg revert
|
||||
hg remove
|
||||
hg update
|
||||
You have seen that it is possible to switch revision using hg update.
|
||||
clone
|
||||
|
||||
commit
|
||||
|
||||
The first feature of the diff command is to show the differences between the last revision of a file (the state at the last commit command) and the current version. It can also show the differences between any two specified revisions. For example, on apache2.conf, the diff command can be used as follows:
|
||||
$ hg diff -r 1 -r 2 apache2.conf
|
||||
|
||||
To print each line of a file with the revision at which the line was created (and with the --user option, we come to know who committed this revision), type:
|
||||
$ hg annotate [FILE] or $ hg blame [FILE]
|
||||
|
||||
To search for a pattern in version controlled files, use hg grep; it will search this pattern in every version of the file and it will print the first one in which it appears, such as hg annotate. For example:
|
||||
$ hg grep new apache2.conf
|
||||
|
||||
You can also print the content of a file at a given revision even without changing the current working directory using hg cat -r REVISION.
|
||||
|
||||
Whenever changes have been committed but not yet pushed, the outgoing command lists all the changesets that are present in the current repository but not yet found in the destination (the ones that are candidates to be pushed), whereas the incoming command shows you the changesets that are found in the source repository but have not been pulled yet. So here, if you use the outgoing command, you will see
|
||||
|
||||
push
|
||||
pull
|
||||
fetch
|
||||
merge
|
||||
resolve --mark
|
||||
|
||||
As you can see, you have added John's change to your repository because hg log is listing it. But it is not yet present in your working copy; you need to update the working directory to the tip revision, which is the default of the update command, when no revision is passed as argument:
|
||||
|
||||
You can now see John's change in the working directory. If some files had been modified, either committed or not, the modifications would have been seamlessly merged with that of John's. If there was a conflict, Mercurial would have told us.
|
||||
|
||||
hg pull --update or -u: This option combines both the pull and the update commands, not only pulling new changesets into the local repository, but also updating the working directory to the head of these new changes.
|
||||
|
||||
| annotate, blame | show changeset information by line for each file |
|
||||
| diff | diff repository (or selected files) |
|
||||
| forget {filename} | forget the specified files on the next commit |
|
||||
|
||||
|
||||
hg fetch. This extension acts as a combination of hg pull -u, hg merge and hg commit. It begins by pulling changes from another repository into the current repository. If it finds that the changes added a new head to the repository, it updates to the new head, begins a merge, then (if the merge succeeded) commits the result of the merge with an automatically-generated commit message. If no new heads were added, it updates the working directory to the new tip changeset.
|
||||
|
||||
|
||||
|
||||
i like
|
||||
|
||||
hg fetch does a pull and update at the same time
|
||||
you're prompted about any conflicts
|
||||
you fix them. then you do this: hg resolve --mark
|
||||
|
||||
|
||||
hg pull -u (i think this is pull and then update)
|
||||
|
||||
$ hg [COMMAND] [ARGUMENTS]
|
||||
|
||||
hg init
|
||||
hg add
|
||||
hg log
|
||||
hg diff
|
||||
hg revert
|
||||
hg remove
|
||||
hg update
|
||||
You have seen that it is possible to switch revision using hg update.
|
||||
clone
|
||||
addremove, which allows you to automatically add all new files and remove (from version control) files that have been deleted.
|
||||
log
|
||||
commit
|
||||
|
||||
The first feature of the diff command is to show the differences between the last revision of a file (the state at the last commit command) and the current version. It can also show the differences between any two specified revisions. For example, on apache2.conf, the diff command can be used as follows:
|
||||
$ hg diff -r 1 -r 2 apache2.conf
|
||||
|
||||
To print each line of a file with the revision at which the line was created (and with the --user option, we come to know who committed this revision), type:
|
||||
$ hg annotate [FILE] or $ hg blame [FILE]
|
||||
|
||||
To search for a pattern in version controlled files, use hg grep; it will search this pattern in every version of the file and it will print the first one in which it appears, such as hg annotate. For example:
|
||||
$ hg grep new apache2.conf
|
||||
|
||||
You can also print the content of a file at a given revision even without changing the current working directory using hg cat -r REVISION.
|
||||
|
||||
Whenever changes have been committed but not yet pushed, the outgoing command lists all the changesets that are present in the current repository but not yet found in the destination (the ones that are candidates to be pushed), whereas the incoming command shows you the changesets that are found in the source repository but have not been pulled yet. So here, if you use the outgoing command, you will see
|
||||
|
||||
push
|
||||
pull
|
||||
fetch
|
||||
merge
|
||||
resolve --mark
|
||||
|
||||
As you can see, you have added John's change to your repository because hg log is listing it. But it is not yet present in your working copy; you need to update the working directory to the tip revision, which is the default of the update command, when no revision is passed as argument:
|
||||
|
||||
You can now see John's change in the working directory. If some files had been modified, either committed or not, the modifications would have been seamlessly merged with that of John's. If there was a conflict, Mercurial would have told us.
|
||||
|
||||
hg pull --update or -u: This option combines both the pull and the update commands, not only pulling new changesets into the local repository, but also updating the working directory to the head of these new changes.
|
||||
|
||||
Bookmarks are tags that move forward automatically to subsequent changes, leaving no mark on the changesets that previously had that bookmark pointing toward them. Named branches, on the other hand, are indelible marks that are part of a changeset. Multiple heads can be on the same branch, but only one head at a time can be pointed to by the same bookmark. Named branches are pushed/pulled from repo to repo, and bookmarks don't travel.
|
||||
|
||||
The default branch name in Mercurial is “default”.
|
||||
|
||||
The slowest, safest way to create a branch with Mercurial is to make a new clone of the repository. this is really fascinating -- a clone is merely a branch.
|
||||
|
||||
Discarding a branch you don’t want any more is very easy with cloned branches. It’s as simple as rm -rf test-project-feature-branch. There’s no need to mess around with editing repository history, you just delete the damn thing.
|
||||
|
||||
The next way to branch is to use a bookmark. For example:
|
||||
|
||||
$ cd ~/src/test-project
|
||||
$ hg bookmark main
|
||||
$ hg bookmark feature
|
||||
Now you’ve got two bookmarks (essentially a tag) for your two branches at the current changeset.
|
||||
|
||||
To switch to one of these branches you can use hg update feature to update to the tip changeset of that branch and mark yourself as working on that branch. When you commit, it will move the bookmark to the newly created changeset.
|
||||
|
||||
|
||||
## Git
|
||||
HEAD is a reference to the last commit in the current checked out branch.
|
||||
|
||||
This is a good tutorial: https://www.digitalocean.com/community/tutorials/how-to-use-git-branches.
|
||||
|
||||
|
||||
## Branching
|
||||
|
||||
| Commands | Description |
|
||||
|------|-------|
|
||||
| List all branches | `git branch a` (the * indicates the branch you're on) |
|
||||
| Create new branch | `git -b branchname` or `git branch branchname` |
|
||||
| Checkout a branch | `git checkout branchname` |
|
||||
| Create new branch and checkout at the same time| `git checkout -b branchname` |
|
||||
| Merge into current branch | First go into the branch you want to merge changes into. Then do `git merge branchname`. For example, to merge branch b into branch master, first checkout branch master: `git checkout a`. Now merge b into master: `git merge b`.|
|
||||
|
||||
git lg
|
||||
|
||||
git checkout master
|
||||
git merge search | git merge --no-ff search
|
||||
|
||||
the latter (--no-ff) keeps the additional information that these commits were made on a branch.
|
||||
then type a commit message (:wq)
|
||||
git branch -d search
|
||||
|
||||
git add . (works same as add --all)
|
||||
git commit am "my commit message" (this performs both adding and commit message at same time)
|
||||
|
||||
with merge conflicts:
|
||||
|
||||
git status (shows you all the files that can't be added due to merge conflicts)
|
||||
fix the conflicts
|
||||
then git add . (tells git you fixed the conflicts)
|
||||
then git status
|
||||
git commit
|
||||
|
||||
From the interface, you can also create a pull request to merge all of the changes from a specific branch into another branch.
|
||||
|
||||
|
||||
|
||||
## General commands
|
||||
|
||||
| Commands | Description |
|
||||
|------|-------|
|
||||
| start tracking files | `git add` |
|
||||
| see what has changed since last commit | `git diff` |
|
||||
| commit changes | `git commit` |
|
||||
| | |
|
||||
|
||||
|
||||
{% include links.html %}
|
||||
@ -1,111 +0,0 @@
|
||||
---
|
||||
title: Glossary layout
|
||||
tags: [formatting, special_layouts]
|
||||
keywords: definitions, glossaries, terms, style guide
|
||||
last_updated: July 3, 2016
|
||||
summary: "Your glossary page can take advantage of definitions stored in a data file. This gives you the ability to reuse the same definition in multiple places. Additionally, you can use Bootstrap classes to arrange your definition list horizontally."
|
||||
sidebar: mydoc_sidebar
|
||||
permalink: mydoc_glossary.html
|
||||
toc: false
|
||||
folder: mydoc
|
||||
---
|
||||
|
||||
|
||||
You can create a glossary for your content. First create your glossary items in a data file such as glossary.yml.
|
||||
|
||||
Then create a page and use definition list formatting, like this:
|
||||
|
||||
fractious
|
||||
: {{site.data.glossary.fractious}}
|
||||
|
||||
gratuitous
|
||||
: {{site.data.glossary.gratuitous}}
|
||||
|
||||
haughty
|
||||
: {{site.data.glossary.haughty}}
|
||||
|
||||
gratuitous
|
||||
: {{site.data.glossary.gratuitous}}
|
||||
|
||||
impertinent
|
||||
: {{site.data.glossary.intrepid}}
|
||||
|
||||
Here's the code:
|
||||
|
||||
```
|
||||
{% raw %}fractious
|
||||
: {{site.data.glossary.fractious}}
|
||||
|
||||
gratuitous
|
||||
: {{site.data.glossary.gratuitous}}
|
||||
|
||||
haughty
|
||||
: {{site.data.glossary.haughty}}
|
||||
|
||||
gratuitous
|
||||
: {{site.data.glossary.gratuitous}}
|
||||
|
||||
impertinent
|
||||
: {{site.data.glossary.intrepid}}{% endraw %}
|
||||
```
|
||||
|
||||
The glossary works well as a link in the top navigation bar.
|
||||
|
||||
## Horizontally styled definiton lists
|
||||
|
||||
You can also change the definition list (`dl`) class to `dl-horizontal`. This is a Bootstrap specific class. If you do, the styling looks like this:
|
||||
|
||||
<dl class="dl-horizontal">
|
||||
|
||||
<dt id="fractious">fractious</dt>
|
||||
<dd>{{site.data.glossary.fractious}}</dd>
|
||||
|
||||
<dt id="gratuitous">gratuitous</dt>
|
||||
<dd>{{site.data.glossary.gratuitous}}</dd>
|
||||
|
||||
<dt id="haughty">haughty</dt>
|
||||
<dd>{{site.data.glossary.haughty}}</dd>
|
||||
|
||||
<dt id="benchmark_id">gratuitous</dt>
|
||||
<dd>{{site.data.glossary.gratuitous}}</dd>
|
||||
|
||||
<dt id="impertinent">impertinent</dt>
|
||||
<dd>{{site.data.glossary.impertinent}}</dd>
|
||||
|
||||
<dt id="intrepid">intrepid</dt>
|
||||
<dd>{{site.data.glossary.intrepid}}</dd>
|
||||
|
||||
</dl>
|
||||
|
||||
For this type of list, you must use HTML. The list would then look like this:
|
||||
|
||||
```html
|
||||
{% raw %}<dl class="dl-horizontal">
|
||||
|
||||
<dt id="fractious">fractious</dt>
|
||||
<dd>{{site.data.glossary.fractious}}</dd>
|
||||
|
||||
<dt id="gratuitous">gratuitous</dt>
|
||||
<dd>{{site.data.glossary.gratuitous}}</dd>
|
||||
|
||||
<dt id="haughty">haughty</dt>
|
||||
<dd>{{site.data.glossary.haughty}}</dd>
|
||||
|
||||
<dt id="benchmark_id">gratuitous</dt>
|
||||
<dd>{{site.data.glossary.gratuitous}}</dd>
|
||||
|
||||
<dt id="impertinent">impertinent</dt>
|
||||
<dd>{{site.data.glossary.impertinent}}</dd>
|
||||
|
||||
<dt id="intrepid">intrepid</dt>
|
||||
<dd>{{site.data.glossary.intrepid}}</dd>
|
||||
|
||||
</dl>{% endraw %}
|
||||
```
|
||||
|
||||
If you squish your screen small enough, at a certain breakpoint this style reverts to the regular `dl` class.
|
||||
|
||||
Although I like the side-by-side view for shorter definitions, I found it problematic with longer definitions.
|
||||
|
||||
|
||||
{% include links.html %}
|
||||
File diff suppressed because it is too large
Load Diff
Some files were not shown because too many files have changed in this diff Show More
Loading…
x
Reference in New Issue
Block a user