HPCE/gitea-pages
HPCE/gitea-pages
0
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Activity

more updates to doc, some theme tweaks, finalizing the 5.0 release

Browse Source
This commit is contained in:
tomjohnson1492 2016-03-20 22:53:03 -07:00
parent 2cbb248938
commit ae69b83a96
29 changed files with 484 additions and 352 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
_data/sidebars/mydoc_sidebar.yml
View File

@ -1,9 +1,9 @@
# 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: entries:
- title: Mydoc - title: sidebar
product: Mydoc product: Jekyll Doc Theme
version: version 5.0 version: 5.0
subcategories: subcategories:
- title: - title:
@ -23,6 +23,14 @@ entries:
output: web, pdf output: web, pdf
items: items:
- title: 5.0 Release notes
url: /mydoc_release_notes_50/
output: web, pdf
- title: Get started
url: /
output: web, pdf
- title: Introduction - title: Introduction
url: /mydoc_introduction/ url: /mydoc_introduction/
output: web, pdf output: web, pdf
@ -31,10 +39,6 @@ entries:
url: /mydoc_supported_features/ url: /mydoc_supported_features/
output: web, pdf output: web, pdf
- title: Get started
url: /mydoc_getting_started/
output: web, pdf
- title: About the theme author - title: About the theme author
url: /mydoc_about/ url: /mydoc_about/
output: web, pdf output: web, pdf
@ -139,6 +143,10 @@ entries:
url: /mydoc_commenting_on_files/ url: /mydoc_commenting_on_files/
output: web, pdf output: web, pdf
# - title: Git collaboration
# url: /mydoc_git_collaboration/
# output: web, pdf
- title: Publishing - title: Publishing
output: web, pdf output: web, pdf
@ -191,6 +199,10 @@ entries:
url: /mydoc_glossary/ url: /mydoc_glossary/
output: web, pdf output: web, pdf
- title: FAQ layout
url: /mydoc_faq_layout/
output: web, pdf
- title: Troubleshooting - title: Troubleshooting
output: web, pdf output: web, pdf
@ -214,6 +226,7 @@ entries:
thirdlevel: thirdlevel:
- title: Tag archive pages - title: Tag archive pages
output: web
thirdlevelitems: thirdlevelitems:
- title: Formatting pages - title: Formatting pages
@ -238,4 +251,8 @@ entries:
- title: Collaboration pages - title: Collaboration pages
url: /tag_collaboration/ url: /tag_collaboration/
output: web
- title: Troubleshooting pages
url: /tag_troubleshooting/
output: web output: web

2
_data/sidebars/product1_sidebar.yml
View File

@ -4,7 +4,7 @@
entries: entries:
- title: Sidebar - title: Sidebar
product: Product1 product: Product1
version: version 1.0 version: 1.0
subcategories: subcategories:
- title: - title:

2
_data/sidebars/product2_sidebar.yml
View File

@ -3,7 +3,7 @@
entries: entries:
- title: Product2 - title: Product2
product: Product2 product: Product2
version: version 1.0 version: 1.0
subcategories: subcategories:
- title: - title:

20
_data/sidebars/tags_sidebar.yml
View File

@ -4,33 +4,51 @@ entries:
product: Tags product: Tags
version: all products version: all products
levels: one levels: one
output: web
subcategories: subcategories:
- title: News - title: News
output: web
items: items:
- title: News - title: News
url: /news/ url: /news/
output: web
- title: News archive - title: News archive
url: /news_archive/ url: /news_archive/
output: web
- title: Tags - title: Tags
output: web
items: items:
- title: Collaboration - title: Collaboration
url: /tag_collaboration/ url: /tag_collaboration/
output: web
- title: Content Types - title: Content Types
url: /tag_content_types/ url: /tag_content_types/
output: web
- title: Formatting - title: Formatting
url: /tag_formatting/ url: /tag_formatting/
output: web
- title: Getting started - title: Getting started
url: /tag_getting_started/ url: /tag_getting_started/
output: web
- title: Mobile - title: Mobile
url: /tag_mobile/ url: /tag_mobile/
output: web
- title: Navigation - title: Navigation
url: /tag_navigation/ url: /tag_navigation/
output: web
- title: News - title: News
url: /tag_news/ url: /tag_news/
output: web
- title: Publishing - title: Publishing
url: /tag_publishing/ url: /tag_publishing/
output: web
- title: Single sourcing - title: Single sourcing
url: /tag_single_sourcing/ url: /tag_single_sourcing/
output: web
- title: Special layouts - title: Special layouts
url: /tag_special_layouts/ url: /tag_special_layouts/
output: web
- title: Troubleshooting
url: /tag_troubleshooting/
output: web

2
_data/topnav.yml
View File

@ -24,7 +24,7 @@ topnav_dropdowns:
external_url: http://idratherbewriting.com/category-jekyll/ external_url: http://idratherbewriting.com/category-jekyll/
- title: Products - title: Products
items: items:
- title: Theme instructions - title: Jekyll Documentation Theme
url: /mydoc_introduction/ url: /mydoc_introduction/
- title: Product 1 - title: Product 1
url: /p1_landing_page/ url: /p1_landing_page/

2
_includes/head.html
View File

@ -12,7 +12,7 @@
<link rel="stylesheet" href="{{ "/css/modern-business.css" | prepend: site.baseurl }}"> <link rel="stylesheet" href="{{ "/css/modern-business.css" | prepend: site.baseurl }}">
<link rel="stylesheet" href="{{ "/css/lavish-bootstrap.css" | prepend: site.baseurl }}"> <link rel="stylesheet" href="{{ "/css/lavish-bootstrap.css" | prepend: site.baseurl }}">
<link rel="stylesheet" href="{{ "/css/customstyles.css" | prepend: site.baseurl }}"> <link rel="stylesheet" href="{{ "/css/customstyles.css" | prepend: site.baseurl }}">
<link rel="stylesheet" href="{{ "/css/theme-green.css" | prepend: site.baseurl }}"> <link rel="stylesheet" href="{{ "/css/theme-blue.css" | prepend: site.baseurl }}">
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-cookie/1.4.1/jquery.cookie.min.js"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery-cookie/1.4.1/jquery.cookie.min.js"></script>

56
_includes/sidebar.html
View File

@ -0,0 +1,56 @@
{% include custom/sidebarconfigs.html %}
<div class="sidebarTitle">{{sidebar[0].product}} {{sidebar[0].version}}</div>
<ul id="mysidebar" class="nav">
{% for entry in sidebar %}
{% for subcategory in entry.subcategories %}
{% if subcategory.output contains "web" %}
<li>
<a href="#">{{ subcategory.title }}</a>
<ul>
{% for item in subcategory.items %}
{% if item.output contains "web" %}
{% if item.external_url %}
<li><a href="{{item.external_url}}" target="_blank">{{subcategory.title}}</a></li>
{% elsif page.url == item.url %}
<li class="active"><a href="{{item.url | prepend: site.baseurl}}">{{item.title}}</a></li>
{% else %}
<li><a href="{{item.url | prepend: site.baseurl}}">{{item.title}}</a></li>
{% endif %}
{% for thirdlevel in item.thirdlevel %}
{% if thirdlevel.output contains "web" %}
<li class="thirdlevel">
<a href="#">{{ thirdlevel.title }}</a>
<ul>
{% for deeplevel in thirdlevel.thirdlevelitems %}
{% if deeplevel.output contains "web" %}
{% if deeplevel.external_url %}
<li><a href="{{deeplevel.external_url}}" target="_blank">{{deeplevel.title}}</a></li>
{% elsif page.url == deeplevel.url %}
<li class="active"><a href="{{deeplevel.url | prepend: site.baseurl}}">{{deeplevel.title}}</a></li>
{% else %}
<li><a href="{{deeplevel.url | prepend: site.baseurl}}">{{deeplevel.title}}</a></li>
{% endif %}
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
{% endif %}
{% endfor %}
</ul>
{% endif %}
{% endfor %}
{% endfor %}
<!-- if you aren't using the accordion, uncomment this block:
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
-->
</li>
</ul>
</div>
<!-- this highlights the active parent class in the navgoco sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");</script>

2
_includes/toc.html
View File

@ -18,6 +18,4 @@ $('#toc').on('click', 'a', function() {
}); });
</script> </script>
{% unless page.toc == false %}
<div id="toc"></div> <div id="toc"></div>
{% endunless %}

57
_layouts/default.html
View File

@ -62,62 +62,7 @@
<!-- Sidebar Column --> <!-- Sidebar Column -->
<div class="col-md-3"> <div class="col-md-3">
{% include custom/sidebarconfigs.html %} {% include sidebar.html %}
<span class="siteTagline">{{sidebar[0].product}}</span>
<span class="versionTagline">{{sidebar[0].version}}</span>
<ul id="mysidebar" class="nav">
{% for entry in sidebar %}
{% for subcategory in entry.subcategories %}
{% if subcategory.output contains "web" %}
<li>
<a href="#">{{ subcategory.title }}</a>
<ul>
{% for item in subcategory.items %}
{% if item.output contains "web" %}
{% if item.external_url %}
<li><a href="{{item.external_url}}" target="_blank">{{subcategory.title}}</a></li>
{% elsif page.url == item.url %}
<li class="active"><a href="{{item.url | prepend: site.baseurl}}">{{item.title}}</a></li>
{% else %}
<li><a href="{{item.url | prepend: site.baseurl}}">{{item.title}}</a></li>
{% endif %}
{% for thirdlevel in item.thirdlevel %}
{% if thirdlevel.output contains "web" %}
<li class="thirdlevel">
<a href="#">{{ thirdlevel.title }}</a>
<ul>
{% for deeplevel in thirdlevel.thirdlevelitems %}
{% if deeplevel.output contains "web" %}
{% if deeplevel.external_url %}
<li><a href="{{deeplevel.external_url}}" target="_blank">{{deeplevel.title}}</a></li>
{% elsif page.url == deeplevel.url %}
<li class="active"><a href="{{deeplevel.url | prepend: site.baseurl}}">{{deeplevel.title}}</a></li>
{% else %}
<li><a href="{{deeplevel.url | prepend: site.baseurl}}">{{deeplevel.title}}</a></li>
{% endif %}
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
{% endif %}
{% endfor %}
</ul>
{% endif %}
{% endfor %}
{% endfor %}
<!-- if you aren't using the accordion, uncomment this block:
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
-->
</li>
</ul>
</div>
<!-- this highlights the active parent class in the navgoco sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");</script>
<!-- Content Column --> <!-- Content Column -->
<div class="col-md-9"> <div class="col-md-9">
{{content}} {{content}}

34
css/customstyles.css
View File

@ -72,16 +72,16 @@ body {
.breadcrumb > .active {color: #777 !important;} .breadcrumb > .active {color: #777 !important;}
/* make room for the nav bar */ /* make room for the nav bar */
h1[id], /*h1[id],*/
h2[id], /*h2[id],*/
h3[id], /*h3[id],*/
h4[id], /*h4[id],*/
h5[id], /*h5[id],*/
h6[id], /*h6[id],*/
dt[id]{ /*dt[id]{*/
padding-top: 60px; /*padding-top: 60px; */
margin-top: -40px /*margin-top: -40px*/
} /*}*/
body h1 {margin-top:40px;} body h1 {margin-top:40px;}
@ -395,8 +395,6 @@ text-decoration: none;
} }
ul#mysidebar { ul#mysidebar {
margin-top:40px;
border-radius:0px; border-radius:0px;
} }
@ -1000,4 +998,14 @@ span.label.label-default {
span.label.label-primary { span.label.label-primary {
background-color: #f0ad4e; background-color: #f0ad4e;
} }
.col-lg-12 .nav li a {background-color: white} .col-lg-12 .nav li a {background-color: white}
div.sidebarTitle {
margin-top:40px;
font-weight:normal;
font-size:130%;
color: #ED1951;
margin-bottom:10px;
margin-left: 5px;
}

4
css/theme-blue.css
View File

@ -86,4 +86,8 @@ body.print h4 {color: #679DCE !important; font-size:14px; font-style: italic !im
.anchorjs-link:hover { .anchorjs-link:hover {
color: #216f9b; color: #216f9b;
}
div.sidebarTitle {
color: #015CAE;
} }

4
css/theme-green.css
View File

@ -82,4 +82,8 @@ body.print h4 {color: #679DCE !important; font-size:14px; font-style: italic;}
.anchorjs-link:hover { .anchorjs-link:hover {
color: #4f7233; color: #4f7233;
}
div.sidebarTitle {
color: #E50E51;
} }

8
index.html
View File

@ -1,8 +0,0 @@
---
title: Introduction
tags: [getting_started]
sidebar: home_sidebar
toc: none
---

51
mydoc/mydoc_getting_started.md → index.md
View File

@ -1,18 +1,13 @@
--- ---
title: Getting started title: Getting started
tags: [getting_started] tags: [getting_started]
keywords: start, introduction, begin, install, build, hello world,
last_updated: March 20, 2016
summary: "To get started with this theme, first make sure you have all the prerequisites in place; then build the theme following the sample build commands."
series: "Getting Started"
sidebar: mydoc_sidebar sidebar: mydoc_sidebar
permalink: /mydoc_getting_started/
--- ---
## Getting up and running ## Getting up and running
To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/). To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/).
If you're in Windows, you might want to [install Jekyll using Chocolately](https://www.google.com/search?q=install+jekyll+using+chocolately). If you're in Windows, you might want to [install Jekyll using Chocolately](https://www.google.com/search?q=install+jekyll+using+chocolately).
@ -80,12 +75,12 @@ Note that your sidebar can only have 2 levels. Given that each product has its o
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown: The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown:
```yaml ```yaml
- title: Overview - title: Overview
output: web, pdf output: web, pdf
items: items:
- title: Mydoc home - title: Mydoc home
url: /mydoc_landing_page/ url: /mydoc_landing_page/
output: web output: web
``` ```
Each heading must contain a title and output property. Each item must contain a title, url, and output property. Each heading must contain a title and output property. Each item must contain a title, url, and output property.
@ -97,18 +92,18 @@ The YAML syntax depends on exact spacing, so make sure you follow the pattern sh
To accommodate the title page and table of contents in PDF outputs, each product sidebar must list these pages before any other: To accommodate the title page and table of contents in PDF outputs, each product sidebar must list these pages before any other:
```yaml ```yaml
- title: - title:
output: pdf output: pdf
type: frontmatter type: frontmatter
items: items:
- title: - title:
url: /titlepage/ url: /titlepage/
output: pdf output: pdf
type: frontmatter type: frontmatter
- title: - title:
url: /tocpage/ url: /tocpage/
output: pdf output: pdf
type: frontmatter type: frontmatter
``` ```
Leave the output as `output: pdf` so that they don't appear in the web output. Leave the output as `output: pdf` so that they don't appear in the web output.
@ -135,7 +130,7 @@ For titles, surrounding the title in quotes is optional, but if you have a colon
Keywords get populated into the metadata of the page for SEO. Keywords get populated into the metadata of the page for SEO.
Tags must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.) Tags must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.)
``` ```
If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: none` in the frontmatter. If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: none` in the frontmatter.
@ -148,7 +143,7 @@ For external URLs, use `external_url` in the item property, as shown in the exam
Note that the topnav has two sections: topnav and topnav_dropdowns. The topnav section contains single links, while the topnav_dropdowns section contains dropdown menus. The two sections are independent of each other. Note that the topnav has two sections: topnav and topnav_dropdowns. The topnav section contains single links, while the topnav_dropdowns section contains dropdown menus. The two sections are independent of each other.
## Generating PDF ## Generating PDF
If you want to generate PDF, you'll need a license for [Prince XML](http://www.princexml.com/). You will also need to [install Prince](http://www.princexml.com/doc/installing/). You can generate PDFs by product (but not for every product on the site combined together into one massive PDF). Prince will work even without a license, but it will imprint a small Prince image on the first page. If you want to generate PDF, you'll need a license for [Prince XML](http://www.princexml.com/). You will also need to [install Prince](http://www.princexml.com/doc/installing/). You can generate PDFs by product (but not for every product on the site combined together into one massive PDF). Prince will work even without a license, but it will imprint a small Prince image on the first page.
@ -158,7 +153,7 @@ See the section on [generating PDFs](mydoc_generating_pdfs) for more details abo
## Blogs / News ## Blogs / News
For blog posts, create your markdown files in the \_posts folder following the sample formats. Post file names always begin with the date (YYYY-MM-DD-title). For blog posts, create your markdown files in the \_posts folder following the sample formats. Post file names always begin with the date (YYYY-MM-DD-title).
The news/news.html file displays the posts, and the news_archive.html file shows a yearly history of posts. In documentation, you might use the news to highlight product features outside of your documentation, or to provide release notes and other updates. The news/news.html file displays the posts, and the news_archive.html file shows a yearly history of posts. In documentation, you might use the news to highlight product features outside of your documentation, or to provide release notes and other updates.
@ -173,5 +168,3 @@ For other details in working with the theme, see the various sections in the sid

16
mydoc/mydoc_faq.html
View File

@ -1,17 +1,17 @@
--- ---
title: FAQ layout title: FAQ layout
permalink: /mydoc_faq_layout/
sidebar: mydoc_sidebar
tags: [special_layouts] tags: [special_layouts]
keywords: frequently asked questions, FAQ, question and answer, collapsible sections, expand, collapse keywords: frequently asked questions, FAQ, question and answer, collapsible sections, expand, collapse
last_updated: March 20, 2016 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." summary: "You can use an accordion-layout that takes advantage of Bootstrap styling. This is useful for an FAQ page."
sidebar: mydoc_sidebar toc: none
permalink: /mydoc_faq/
--- ---
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>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-group" id="accordion">
<div class="panel panel-default"> <div class="panel panel-default">
<div class="panel-heading"> <div class="panel-heading">
<h4 class="panel-title"> <h4 class="panel-title">
@ -129,6 +129,6 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
</div> </div>
</div> </div>
<!-- /.panel --> <!-- /.panel -->
</div> </div>
<!-- /.panel-group --> <!-- /.panel-group -->

7
mydoc/mydoc_install_dependencies.md
View File

@ -1,17 +1,14 @@
--- ---
title: Adding all project dependencies title: Adding all project dependencies
tags: [getting-started] tags: [getting-started, troubleshooting]
keywords: keywords:
summary: "" summary: "You want to be sure that you have all the required gems and other utilities on your computer to make the project run. Jekyll runs on Ruby, and there are various plugins for Ruby that enable different functionality. These Ruby plugins are referred to as gems, and you install the gems you need for your projects."
sidebar: mydoc_sidebar sidebar: mydoc_sidebar
permalink: /mydoc_install_dependencies/ permalink: /mydoc_install_dependencies/
--- ---
You want to be sure that you have all the required gems and other utilities on your computer to make the project run. Jekyll runs on Ruby, and there are various plugins for Ruby that enable different functionality. These Ruby plugins are referred to as gems, and you install the gems you need for your projects.
To manage the various gems and their versions needed for your project, you can use a package manager called Bundler. Many projects will have a gemfile in their project that lists the gems required for the project. You then run Bundler in order to automatically install the required gems and any dependencies for those gems on your machine. To manage the various gems and their versions needed for your project, you can use a package manager called Bundler. Many projects will have a gemfile in their project that lists the gems required for the project. You then run Bundler in order to automatically install the required gems and any dependencies for those gems on your machine.
## RubyGems ## RubyGems
Make sure you have RubyGems. This should be installed by default on Mac. Make sure you have RubyGems. This should be installed by default on Mac.

9
mydoc/mydoc_iterm_profiles.md
View File

@ -3,15 +3,14 @@ title: iTerm profiles
tags: [publishing] tags: [publishing]
keywords: iterm, terminal, build shortcuts, mac keywords: iterm, terminal, build shortcuts, mac
last_updated: March 20, 2016 last_updated: March 20, 2016
summary: "Set up profiles in iTerm to facilitate the build process with just a few clicks. This can make it a lot easier to quickly build multiple outputs." summary: "You can set up profiles in iTerm to facilitate the build process with just a few clicks. This can make it a lot easier to quickly build multiple outputs."
sidebar: mydoc_sidebar sidebar: mydoc_sidebar
permalink: /mydoc_iterm_profiles/ permalink: /mydoc_iterm_profiles/
--- ---
## About iTerm profiles ## About iTerm profiles
When you're working with tech docs, a lot of times you're single sourcing multiple outputs. It can be a hassle to fire up each one of these outputs using the build files containing the shell scripts. Instead, it's easier to configure iTerm with profiles that initiate the scripts. When you're working with tech docs, a lot of times you have builds that push files onto different servers, or that build the content for different environments. It can be a hassle to type out these commands each time. Instead, it's easier to configure iTerm with profiles that initiate the scripts.
## Set up profiles ## Set up profiles
@ -22,7 +21,7 @@ When you're working with tech docs, a lot of times you're single sourcing multip
5. In the **Send text at start** field, type the command for the build script, such as this: 5. In the **Send text at start** field, type the command for the build script, such as this:
``` ```
jekyll serve --config configs/config_designers.yml JEKYLL_ENV=production jekyll serve
``` ```
Leave the Login shell option selected. Leave the Login shell option selected.
@ -38,4 +37,4 @@ Here's an example:
1. In iTerm, make sure the Toolbar is shown. Go to **View > Toggle Toolbar**. 1. In iTerm, make sure the Toolbar is shown. Go to **View > Toggle Toolbar**.
2. Click the **New** button and select your profile. 2. Click the **New** button and select your profile.
{{site.data.alerts.tip}} When you're done with the session, make sure to click **Ctrl+C**.{{site.data.alerts.end}} {{site.data.alerts.tip}} When you're done with the session, make sure to click <b>Ctrl+C</b>.{{site.data.alerts.end}}

88
mydoc/mydoc_kb_layout.md
View File

@ -8,38 +8,92 @@ sidebar: mydoc_sidebar
permalink: /mydoc_kb_layout/ permalink: /mydoc_kb_layout/
--- ---
<div class="row"> <div class="row">
<div class="col-md-4"><a class="noCrossRef" href="tag_getting_started.html"><i class="fa fa-file-image-o fa-5x border"></i><div class="kbCaption">Getting Started</div></a></div> <div class="col-lg-12">
<div class="col-md-4"><a class="noCrossRef" href="tag_navigation.html"><i class="fa fa-bar-chart-o fa-5x border"></i><div class="kbCaption">Navigation</a></div></div> <h2 class="page-header">Knowledge Base Categories</h2>
<div class="col-md-4"><a class="noCrossRef" href="tag_single_sourcing.html"><i class="fa fa-code fa-5x border"></i><div class="kbCaption">single_sourcing</div></a></div> </div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-tree fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Getting started</h4>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
<a href="{{ '/tag_getting_started' | prepend: site.baseurl }}" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-car fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Navigation</h4>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
<a href="{{ '/tag_navigation' | prepend: site.baseurl }}" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-support fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Single sourcing</h4>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
<a href="{{ '/tag_single_sourcing' | prepend: site.baseurl }}" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-database fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Formatting</h4>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</p>
<a href="{{ '/tag_formatting' | prepend: site.baseurl }}" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
</div> </div>
<p>&nbsp;</p>
<div class="row">
<div class="col-md-4"><a class="noCrossRef" href="tag_publishing.html"><i class="fa fa-dashboard fa-5x border"></i><div class="kbCaption">Publishing</div></a></div>
<div class="col-md-4"><a class="noCrossRef" href="tag_special_layouts.html"><i class="fa fa-desktop fa-5x border"></i><div class="kbCaption">Special layouts</div></a></div>
<div class="col-md-4"><a class="noCrossRef" href="tag_formatting.html"><i class="fa fa-cloud fa-5x border"></i><div class="kbCaption">Formatting</div></a></div>
</div>
## Generating a list of all pages with a certain tag ## Generating a list of all pages with a certain tag
If you don't want to link to a tag archive index, but instead want to list all pages that have a certain tag, you could use this code: If you don't want to link to a tag archive index, but instead want to list all pages that have a certain tag, you could use this code:
{% raw %}
```html ```html
Getting started pages: {% raw %}Getting started pages:
<ul> <ul>
{% assign sorted_pages = (site.pages | sort: 'title') %} {% assign sorted_pages = (site.pages | sort: 'title') %}
{% for page in sorted_pages %} {% for page in sorted_pages %}
{% for tag in page.tags %} {% for tag in page.tags %}
{% if tag == "getting_started" %} {% if tag == "getting_started" %}
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li> <li><a href="{{ page.url | prepend: site.baseurl}}">{{page.title}}</a></li>
{% endif %} {% endif %}
{% endfor %} {% endfor %}
{% endfor %} {% endfor %}
</ul> </ul>{% endraw %}
``` ```
{% endraw %}
Here's the result:
Getting started pages: Getting started pages:
@ -48,7 +102,7 @@ Getting started pages:
{% for page in sorted_pages %} {% for page in sorted_pages %}
{% for tag in page.tags %} {% for tag in page.tags %}
{% if tag == "getting_started" %} {% if tag == "getting_started" %}
<li><a href="{{page.url | prepend: '..'}}">{{page.title}}</a></li> <li><a href="{{page.url | prepend: site.baseurl }}">{{page.title}}</a></li>
{% endif %} {% endif %}
{% endfor %} {% endfor %}
{% endfor %} {% endfor %}

229
mydoc/mydoc_no_password_prompts_scp.md
View File

@ -1,126 +1,129 @@
--- ---
title: Getting around the password prompts in SCP title: Getting around the password prompts in SCP
sidebar: mydoc_sidebar sidebar: mydoc_sidebar
tags: [publishing, troubleshooting]
permalink: /mydoc_no_password_prompts_scp/ permalink: /mydoc_no_password_prompts_scp/
summary: "You can publish your docs via SSH through a Terminal window or more likely, via a shell script that you simply execute as part of the publishing process. However, you will be prompted for your password with each file transfer unless you configure passwordless SSH. The basic process for setting up password less SSH is to create a key on your own machine that you also transfer to the remote machine. When you use the SCP command, the remote machine checks that you have the authorized key and allows access without a password prompt."
--- ---
You can publish your docs via SSH through a Terminal window or more likely, via a shell script that you simply execute as part of the publishing process. However, you will be prompted for your password with each file transfer unless you configure passwordless SSH. ## Get rid of password prompts
The basic process for setting up password less SSH is to create a key on your own machine that you also transfer to the remote machine. When you use the SCP command, the remote machine checks that you have the authorized key and allows access without a password prompt.
To remove the password prompts when connecting to servers via SSH: To remove the password prompts when connecting to servers via SSH:
1. On your local machine, go to your .ssh directory: 1. On your local machine, go to your .ssh directory:
``` ```
cd ~/.ssh cd ~/.ssh
``` ```
Note that any directory that starts with a dot, like .ssh, is hidden. You can view hidden folders by enabling them on your Mac. See [this help topic](http://ianlunn.co.uk/articles/quickly-showhide-hidden-files-mac-os-x-mavericks/). Additionally, when you look at the files in a directory, use ls -a instead of just ls to view the hidden files.
If you don't have an .ssh directory, create one with `mkdir .ssh`.
2. Create a new key inside your .ssh directory:
```
ssh-keygen -t rsa
```
3. Press **Enter**. When prompted about "Enter file in which to save the key ...", press ```Enter``` again.
This will create a file called id_rsa.pub (the key) and id_rsa (your identification) in this .ssh folder.
Note that any directory that starts with a dot, like .ssh, is hidden. You can view hidden folders by enabling them on your Mac. See [this help topic](http://ianlunn.co.uk/articles/quickly-showhide-hidden-files-mac-os-x-mavericks/). Additionally, when you look at the files in a directory, use ls -a instead of just ls to view the hidden files. When prompted for a passphrase for the key, just leave it empty and press **Enter** twice. You should see something like this:
```
tjohnson-mbpr13:.ssh tjohnson$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/tjohnson/.ssh/id_rsa.
Your public key has been saved in /Users/tjohnson/.ssh/id_rsa.pub.
The key fingerprint is:
9a:8f:b5:495:39:78:t5:dc:19:d6:29:66:02:e8:02:a0 tjohnson@tjohnson-mbpr13.local
```
The key's randomart image is:
```
+--[ RSA 2048]----+
|. |
|+ |
|E |
|o. . |
|.. = o S |
|.&^ + 7i = o |
| = B . |
| o O + |
| *.o |
+-----------------+
```
As you can see, RSA draws a picture for you. Take a screenshot of the picture, print it out, and put it up on your fridge.
4. Open up another terminal window (in iTerm, open another tab), and SSH in to your remote server:
```
ssh <your_username>@remoteserver.com
```
5. Change `<your_username>` to your actual username, such as tjohnson.
When you connect, you'll be prompted for your password.
When you connect, by default you are routed to the personal folder on the directory. For example, `/home/remoteserver/<your_username>`. To see this directory, type `pwd` (or `dir` on Windows).
6. Create a new directory called .ssh on remoteserver.com server inside the `/home/remoteserver/<your_username>` directory.
```
mkdir -p .ssh
```
You can ensure that it's there with this command:
```
ls -a
```
Without the -a, the hidden directory won't be shown.
7. Open another Terminal window and browse to /Users/<your_username>/.ssh on your local machine.
```
cd ~/.ssh
```
8. Copy the id_rsa.pub from the /.ssh directory on your local machine to the /home/remoteserver/<your_username>/.ssh directory on the remoteserver server:
```
scp id_rsa.pub <your-username>@yourserver.com:/home/remoteserver/<your-username>/.ssh
```
9. Switch back into your terminal window that is connected to remoteserver.com, change directory to the .ssh directory, and rename the file from id_rsa.pub to `authorized_keys` (without any file extension):
```
mv id_rsa.pub authorized_keys
```
10. Change the file permissions to 700:
```
chmod 700 authorized_keys
```
Now you should be able to SSH onto remoteserver without any password prompts.
If you don't have an .ssh directory, create one with `mkdir .ssh`. 11. Open another terminal (which is not already SSH'd into remoteserver.com) and try the following:
Create a new key inside your .ssh directory: ```
ssh <your_username>@remoteserver.com
``` ```
ssh-keygen -t rsa
``` If successful, you shouldn't be prompted for a password.
Press Enter. When prompted about "Enter file in which to save the key ...", press Enter again. Now that you can connect without password prompts, you can use the scp scripts to transfer files to the server without password prompts. For example:
This will create a file called id_rsa.pub (the key) and id_rsa (your identification) in this .ssh folder. ```
scp -r ../doc_outputs/mydoc/writers <your-username>@remoteserver:/var/www/html/
When prompted for a passphrase for the key, just leave it empty and press Enter twice. You should see something like this: ```
tjohnson-mbpr13:.ssh tjohnson$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/tjohnson/.ssh/id_rsa.
Your public key has been saved in /Users/tjohnson/.ssh/id_rsa.pub.
The key fingerprint is:
9a:8f:b5:495:39:78:t5:dc:19:d6:29:66:02:e8:02:a0 tjohnson@tjohnson-mbpr13.local
The key's randomart image is:
```
+--[ RSA 2048]----+
|. |
|+ |
|E |
|o. . |
|.. = o S |
|.&^ + 7i = o |
| = B . |
| o O + |
| *.o |
+-----------------+
```
Icon
As you can see, RSA draws a picture for you. Take a screenshot of the picture, print it out, and put it up on your fridge.
Open up another terminal window (in iTerm, open another tab), and SSH in to your remote server:
```
ssh <your_username>@remoteserver.com
```
Change `<your_username>` to your actual username, such as tjohnson.
When you connect, you'll be prompted for your password.
When you connect, by default you are routed to the personal folder on the directory. For example, `/home/remoteserver/<your_username>`. To see this directory, type `pwd`.
Create a new directory called .ssh on remoteserver.com server inside the `/home/remoteserver/<your_username>` directory.
```
mkdir -p .ssh
```
You can ensure that it's there with this command:
```
ls -a
```
Without the -a, the hidden directory won't be shown.
Open another Terminal window and browse to /Users/<your_username>/.ssh on your local machine.
```
cd ~/.ssh
```
Copy the id_rsa.pub from the /.ssh directory on your local machine to the /home/remoteserver/<your_username>/.ssh directory on the remoteserver server:
```
scp id_rsa.pub <your-username>@yourserver.com:/home/remoteserver/<your-username>/.ssh
```
Switch back into your terminal window that is connected to remoteserver.com, change directory to the .ssh directory, and rename the file from id_rsa.pub to `authorized_keys` (without any file extension):
```
mv id_rsa.pub authorized_keys
```
Change the file permissions to 700:
```
chmod 700 authorized_keys
```
Now you should be able to SSH onto remoteserver without any password prompts.
Open another terminal (which is not already SSH'd into remoteserver.com) and try the following:
```
ssh <your_username>@remoteserver.com
```
If successful, you shouldn't be prompted for a password.
Now that you can connect without password prompts, you can use the scp scripts to transfer files to the server without password prompts. For example:
```
scp -r ../doc_outputs/mydoc/writers <your-username>@remoteserver:/var/www/html/
```

8
mydoc/mydoc_push_build_to_server.md
View File

@ -14,19 +14,19 @@ permalink: /mydoc_push_build_to_server/
If you have the AWS Command Line Interface installed and are pushing your builds to AWS, the following commands show how you can build and push to an AWS location from the command line: If you have the AWS Command Line Interface installed and are pushing your builds to AWS, the following commands show how you can build and push to an AWS location from the command line:
``` ```
#aws s3 cp ~/users/tjohnson/projects/documentation-theme-jekyll-builds/mydoc_writers s3://[aws path]documentation-theme-jekyll/mydoc_writers --recursive aws s3 cp ~/users/tjohnson/projects/mydocproject/ s3://[aws path]docpath/mydocproject --recursive
#aws s3 cp ~/users/tjohnson/projects/documentation-theme-jekyll-builds/mydoc_designers s3://[aws path]/documentation-theme-jekyll/mydoc_designers --recursive aws s3 cp ~/users/tjohnson/projects/anotherdocproject2/ s3://[aws path]docpath/anotherdocproject --recursive
``` ```
The first path is the local location; the second path is the destination. The first path in the argument is the local location; the second path is the destination.
## Pushing to a regular server ## Pushing to a regular server
If you're pushing to a regular server that you can ssh into, you can use `scp` commands to push your build. Here's an example: If you're pushing to a regular server that you can ssh into, you can use `scp` commands to push your build. Here's an example:
``` ```
scp -r /users/tjohnson/projects/documentation-theme-jekyll-builds/mydoc_writers name@domain:/var/www/html/documentation-theme-jekyll/mydoc_writers scp -r /users/tjohnson/projects/mydocproject/ name@domain:/var/www/html/mydocproject
``` ```
Similar to the above, the first path is the local location; the second path is the destination. Similar to the above, the first path is the local location; the second path is the destination.

27
mydoc/mydoc_release_notes_50.md Normal file
View File

@ -0,0 +1,27 @@
---
title: Release notes 5.0
tags: [getting_started]
keywords: release notes, announcements, what's new, new features
last_updated: March 20, 2016
summary: "Version 5.0 of the Documentation theme for Jekyll changes some fundamental ways the theme works to provide product-specific sidebars, intended to accommodate a site where multiple products are grouped together on the same site rather than generated out as separate outputs."
sidebar: mydoc_sidebar
permalink: /mydoc_release_notes_50/
---
## Unique sidebars for each product
In previous versions of the theme, I architected the theme to generate different outputs for different scenarios based on various filtering attributes including product, version, platform, and audience.
However, this model results in siloed outputs and lots of different file directories to manage. Instead of having 10 separate sites for your content, in this version of the theme I move towards a strategy of having one site with multiple products.
For each product, you can associate a unique sidebar with each of the product's pages. This allows you to easily browse products and have a unique sidebar appear for each product.
You can still output to both web and PDF.
## Permalinks
Since you'll be publishing to one site, I've implement permalinks instead of using relative links. Using permalinks means the way you store pages is much more flexible. You can use folders and subfolders etc. to any degree. But if you want to view the content offline or on a separate site other than the one specified in the configuration file, you won't be able to do that.
## Updated documentation
I updated the documentation for using the theme. The switch from the multi-site outputs to the single-site with multiple sidebars required updating a lot of different parts of the documentation and code.

107
mydoc/mydoc_search_configuration.md
View File

@ -8,11 +8,8 @@ sidebar: mydoc_sidebar
permalink: /mydoc_search_configuration/ permalink: /mydoc_search_configuration/
--- ---
## About search ## About search
The search is configured through the search.json file in the root directory. Take a look at that code if you want to change what fields are included. The search is configured through the search.json file in the root directory. The search is a simple search that looks at content in pages. It looks at titles, summaries, keywords, and tags.
The search is a simple search that looks at content in pages. It looks at titles, summaries, keywords, and tags.
However, the search doesn't work like google &mdash; you can't hit return and see a list of results on the search results page, with the keywords in bold. Instead, this search shows a list of page titles that contain keyword matches. It's fast, but simple. However, the search doesn't work like google &mdash; you can't hit return and see a list of results on the search results page, with the keywords in bold. Instead, this search shows a list of page titles that contain keyword matches. It's fast, but simple.
@ -20,17 +17,20 @@ However, the search doesn't work like google &mdash; you can't hit return and se
By default, every page is included in the search. Depending on the type of content you're including, you may find that some pages will break the JSON formatting. If that happens, then the search will no longer work. By default, every page is included in the search. Depending on the type of content you're including, you may find that some pages will break the JSON formatting. If that happens, then the search will no longer work.
If you want to exclude a page from search add `search: exclude` in the frontmatter. If you want to exclude a page from search add `search: exclude` in the page's frontmatter.
## Troubleshooting search ## Troubleshooting search
You should exclude any files from search that you don't want appearing in the search results. For example, if you have a tooltips.json file or prince-file-list.txt, don't include it, as the formatting will break the JSON format. You should exclude any files from search that you don't want appearing in the search results. For example, if you have a tooltips.json file or prince-list.txt, don't include it, as the formatting will break the JSON format.
If any formatting in the search.json file is invalid (in the build), search won't work. You'll know that search isn't working if no results appear when you start typing in the search box. If any formatting in the search.json file is invalid (in the build), search won't work. You'll know that search isn't working if no results appear when you start typing in the search box.
If this happens, go directly to the search.json file in your browser, and then copy the content. Go to a [JSON validator](http://jsonlint.com/) and paste in the content. Look for the line causing trouble. Edit the file to either exclude it from search or fix the syntax so that it doesn't invalidate the JSON. If this happens, go directly to the search.json file in your browser, and then copy the content. Go to a [JSON validator](http://jsonlint.com/) and paste in the content. Look for the line causing trouble. Edit the file to either exclude the page from search or fix the syntax so that it doesn't invalidate the JSON. (Note that tabs in the body will invalidate JSON.)
The search.json file already tries to strip out content that would otherwise make the JSON invalid: The search.json file already tries to strip out content that would otherwise make the JSON invalid.
## Including the body field in search
I've found that include the `body` field in the search creates too many problems, and so I've removed `body` from the search. You can see the results of including the `body` by adding this along with the other fields in search.json:
{% raw %} {% raw %}
```json ```json
@ -38,55 +38,78 @@ The search.json file already tries to strip out content that would otherwise mak
``` ```
{% endraw %} {% endraw %}
Note that the last replace, `| replace: '^t', ' ' `, looks for any tab character and replaces it with four spaces. Yes, an innocent little tab character invalidates JSON. Geez. If you run into other problematic formatting, you can use regex expressions to find and replace the content. See [Regular Expressions](http://www.ultraedit.com/support/tutorials_power_tips/ultraedit/regular_expressions.html) for details on finding and replacing code. Note that the last replace, `| replace: '^t', ' ' `, looks for any tab character and replaces it with four spaces. (Tab characters invalidate JSON.) If you run into other problematic formatting, you can use regex expressions to find and replace the content. See [Regular Expressions](http://www.ultraedit.com/support/tutorials_power_tips/ultraedit/regular_expressions.html) for details on finding and replacing code.
It's possible that the formatting may not account for all the scenarios that would invalidate the JSON. (Sometimes it's an extra comma after the last item that makes it invalid.) It's possible that the formatting may not account for all the scenarios that would invalidate the JSON. (Sometimes it's an extra comma after the last item that makes it invalid.)
{% if site.audience == "designers" %} Note that including the body in the search creates other problems as well. The search results show the most immediate matches in the JSON file. If several topics have matches for the keyword in the body, these matches might appear before other files that have matches in the title, summary, or keywords. This is because this simple search does not provide any weighting mechanisms for the content.
## Customizing search results ## Customizing search results
At some point, you may want to customize the search results more. Here's a little more detail that will be helpful. The search.json file retrieves various page values: At some point, you may want to customize the search results more. Here's a little more detail that will be helpful. The search.json file retrieves various page values:
```json ```json
{% raw %} {% raw %}---
{% if page.search == true %} title: search
{ layout: none
"title": "{{ page.title | escape }}", search: exclude
"tags": "{{ page.tags }}", ---
"keywords": "{{page.keywords}}",
"url": "{{ page.url | replace: "/", "" }}", [
"last_updated": "{{ page.last_updated }}", {% for page in site.pages %}
"summary": "{{page.summary}}", {% unless page.search == "exclude" %}
"body": "{{ page.content | strip_html | strip_newlines | replace: '\', '\\\\' | replace: '"', '\\"' }}" {
} "title": "{{ page.title | escape }}",
{% endraw %} "tags": "{{ page.tags }}",
"keywords": "{{page.keywords}}",
"url": "{{ page.url | prepend: site.baseurl }}",
"summary": "{{page.summary | strip }}"
},
{% endunless %}
{% endfor %}
{% for post in site.posts %}
{
"title": "{{ post.title | escape }}",
"tags": "{{ post.tags }}",
"keywords": "{{post.keywords}}",
"url": "{{ post.url | prepend: site.baseurl }}",
"summary": "{{post.summary | strip }}"
}
{% unless forloop.last %},{% endunless %}
{% endfor %}
]{% endraw %}
``` ```
The \_includes/topnav.html file then makes use of these values: The \_includes/topnav.html file then makes use of these values:
```html ```html
<!-- start search --> <li>
<div id="search-demo-container"> <!--start search-->
<input type="text" id="search-input" placeholder="{{site.data.strings.search_placeholder_text}}"> <div id="search-demo-container">
<ul id="results-container"></ul> <input type="text" id="search-input" placeholder="{{site.data.strings.search_placeholder_text}}">
</div> <ul id="results-container"></ul>
<script src="js/jekyll-search.js" type="text/javascript"></script> </div>
<script type="text/javascript"> <script src="{{ "/js/jekyll-search.js" | prepend: site.baseurl }}" type="text/javascript"></script>
SimpleJekyllSearch.init({ <script type="text/javascript">
searchInput: document.getElementById('search-input'), SimpleJekyllSearch.init({
resultsContainer: document.getElementById('results-container'), searchInput: document.getElementById('search-input'),
dataSource: 'search.json', resultsContainer: document.getElementById('results-container'),
searchResultTemplate: '<li><a href="{url}" title="{{page.title | replace: "'", "\"}}">{title}</a></li>', dataSource: '{{ "/search.json" | prepend: site.baseurl }}',
noResultsText: '{{site.data.strings.search_no_results_text}}', searchResultTemplate: '<li><a href="{url}" title="{{page.title | replace: "'", "\"}}">{title}</a></li>',
limit: 10, noResultsText: '{{site.data.strings.search_no_results_text}}',
fuzzy: true, limit: 10,
}) fuzzy: true,
</script> })
<!-- end search --> </script>
<!--end search-->
</li> </li>
``` ```
Where you see `{url}` and `{title}`, the search is retrieving the values for these as specified in the search.json file. Where you see `{url}` and `{title}`, the search is retrieving the values for these as specified in the search.json file.
At some point, you may want to add in the `{summary}` as well. You could create a dedicated search page that could include the summary as an instant result as you type. ## More robust search
{% endif %}
For more robust search, consider integrating either [Algolia](http://algolia.com) or [Swifttype](http://swiftype.com).

2
mydoc/mydoc_support.md
View File

@ -1,6 +1,6 @@
--- ---
title: Support title: Support
tags: [getting_started] tags: [getting_started, troubleshooting]
keywords: questions, troubleshooting, contact, support keywords: questions, troubleshooting, contact, support
last_updated: March 20, 2016 last_updated: March 20, 2016
summary: "Contact me for any support issues." summary: "Contact me for any support issues."

45
mydoc/mydoc_troubleshooting.md
View File

@ -1,6 +1,6 @@
--- ---
title: Troubleshooting title: Troubleshooting
tags: [getting_started] tags: [troubleshooting]
keywords: trouble, problems, support, error messages, problems, failure, error, #fail keywords: trouble, problems, support, error messages, problems, failure, error, #fail
last_updated: March 20, 2016 last_updated: March 20, 2016
summary: "This page lists common errors and the steps needed to troubleshoot them." summary: "This page lists common errors and the steps needed to troubleshoot them."
@ -8,7 +8,6 @@ sidebar: mydoc_sidebar
permalink: /mydoc_troubleshooting/ permalink: /mydoc_troubleshooting/
--- ---
## Issues building the site ## Issues building the site
### Address already in use ### Address already in use
@ -34,20 +33,6 @@ Alternatively, type the following to stop all Jekyll servers:
kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}') kill -9 $(ps aux | grep '[j]ekyll' | awk '{print $2}')
``` ```
### Build not entirely finishing
If your build doesn't entirely finish on the command line, check to see if you have a space after a comma when using multiple configuration files, like this:
```
jekyll serve --config config_base.yml, config_designer.yml
```
Remove the space after the comma, and the build will finish executing:
```
jekyll serve --config config_base.yml,config_designer.yml
```
### shell file not executable ### shell file not executable
If you run into permissions errors trying to run a shell script file (such as mydoc_multibuild_web.sh), you may need to change the file permissions to make the sh file executable. Browse to the directory containing the shell script and run the following: If you run into permissions errors trying to run a shell script file (such as mydoc_multibuild_web.sh), you may need to change the file permissions to make the sh file executable. Browse to the directory containing the shell script and run the following:
@ -56,37 +41,29 @@ If you run into permissions errors trying to run a shell script file (such as my
chmod +x build_writer.sh chmod +x build_writer.sh
``` ```
### Pygments not installed ## shell file not runnable
The config file requires pygments for the highlighter. You must [download and install Pygments](http://pygments.org/download/), which requires Python, in order to use this syntax highlighter. If you don't want to bother with Pygments, open the configuration file and change `pygments` to `rouge`. If you're using a PC, rename your shell files with a .bat extension.
### "page 0" cross references in the PDF ### "page 0" cross references in the PDF
If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build. If you see "page 0" cross-references in the PDF, the URL doesn't exist. Check to make sure you actually included this page in the build.
If it's not a page but rather a file, you need to add a `noCrossRef` class to the file so that your print stylesheet excludes the counter from it. Add `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class. If it's not a page but rather a file, you need to add a `noCrossRef` class to the file so that your print stylesheet excludes the counter from it. Add `class="noCrossRef"` as an attribute to the link. In the css/printstyles.css file, there is a style that should remove the counter from anchor elements with this class.
### The PDF is blank ### The PDF is blank
Check the prince-file-list.txt file in the output to see if it contains links. If not, you have something wrong with the logic in the prince-file-list.txt file. Check the conditions.html file in your \_includes to see if the audience specified in your configuration file aligns with the buildAudience in the conditions.html file Check the prince-list.txt file in the output to see if it contains links. If not, you have something wrong with the logic in the prince-list.txt file. Check the conditions.html file in your \_includes to see if the audience specified in your configuration file aligns with the buildAudience in the conditions.html file
### Sidebar not appearing ### Sidebar not appearing
If you build your site but the sidebar doesn't appear, check the following: If you build your site but the sidebar doesn't appear, check the following:
Look in \_includes/custom/sidebarconfigs.html and make sure the conditional values there match up with the values declared in the configuration file. Specifically, you need to make sure you've declared a value for project, product, platform, and version. Look in \_includes/custom/sidebarconfigs.html and make sure the conditional values there match up with values you're using in each page's frontmatter.
If you don't have any values for these properties, you still need to keep them in your configuration file. Just put something like `all` as the value. Make sure each TOC item has an output property that specifies web or pdf.
{{site.data.alerts.note}} This theme is designed for single sourcing. If you're only building one site, you can remove these values from the \_includes/sidebar.html file and \_data/sidebar.yml files.{{site.data.alerts.end}} Understanding how the theme works can be helpful in troubleshooting. The \_includes/sidebar.html file loops through the values in the \_data/sidebar.yml file. There are `if` statements that check whether the conditions (as specified in the conditions.html file) are met. If the sidebar.yml item doesn't have the right output, then it won't get displayed in the sidebar. It would instead get skipped.
Understanding how the theme works can be helpful in troubleshooting. The \_includes/sidebar.html file loops through the values in the \_data/sidebar.yml file. There are `if` statements that check whether the conditions (as specified in the conditions.html file) are met. If the sidebar.yml item has the right product, platform, audience, and version, then it gets displayed in the sidebar. If not, it get skipped.
### Sidebar heading level not opening
In your \_data/sidebar.yml file, you must also include the correct parameters (platform, product, audience version) for each heading. If an item contains something that should be displayed, the attributes for the heading should be listed.
Without any attributes on heading levels, you could end up with scenarios where a section is entirely designed for one output but appears in every output regardless.
### Sidebar isn't collapsed ### Sidebar isn't collapsed

8
mydoc/mydoc_webstorm_text_editor.md
View File

@ -28,6 +28,14 @@ Most likely you'll want to enable soft wraps, which wraps lines rather than exte
When you're searching for content, you don't want to edit any file that appears in the \_site directory. You can exclude a directory from Webstorm by right-clicking the directory and choosing **Mark Directory As** and then selecting **Excluded**. When you're searching for content, you don't want to edit any file that appears in the \_site directory. You can exclude a directory from Webstorm by right-clicking the directory and choosing **Mark Directory As** and then selecting **Excluded**.
## Set tabs to 3 spaces
You can set the default number of spaces a tab sets, including whether Webstorm uses a tab character or spaces. You want spaces, and you want to set this to default number of spaces to ```3``` spaces instead of 4. Note that this is due to the way Kramdown handles the continuation of lists.
When you intercept a list with a paragraph or code sample, the indentation of the intercepting paragraph or list must align with the beginning of the first character after the space in the list item numbering. This is typically 3 spaces, not 4. Note that this style differs from the Github-flavored Markdown style. (Welcome to the world of subtle and infuriating discrepancies between Markdown flavors.)
To set the indentation, see the "Tabs and Indents" topic in this [Code Style. Javascript](https://www.jetbrains.com/help/webstorm/2016.1/code-style-javascript.html?origin=old_help#d658997e132) topic in Webstorm's help.
## Shortcuts ## Shortcuts
It can help to learn a few key shortcuts: It can help to learn a few key shortcuts:

4
search.json
View File

@ -12,7 +12,7 @@ search: exclude
"tags": "{{ page.tags }}", "tags": "{{ page.tags }}",
"keywords": "{{page.keywords}}", "keywords": "{{page.keywords}}",
"url": "{{ page.url | prepend: site.baseurl }}", "url": "{{ page.url | prepend: site.baseurl }}",
"summary": "{{page.summary}}" "summary": "{{page.summary | strip }}"
}, },
{% endunless %} {% endunless %}
{% endfor %} {% endfor %}
@ -24,7 +24,7 @@ search: exclude
"tags": "{{ post.tags }}", "tags": "{{ post.tags }}",
"keywords": "{{post.keywords}}", "keywords": "{{post.keywords}}",
"url": "{{ post.url | prepend: site.baseurl }}", "url": "{{ post.url | prepend: site.baseurl }}",
"summary": "{{post.summary}}" "summary": "{{post.summary | strip }}"
} }
{% unless forloop.last %},{% endunless %} {% unless forloop.last %},{% endunless %}
{% endfor %} {% endfor %}

2
tags/tag_single_sourcing.html
View File

@ -1,5 +1,5 @@
--- ---
title: "single_sourcing pages" title: "Single sourcing pages"
tagName: single_sourcing tagName: single_sourcing
search: exclude search: exclude
permalink: /tag_single_sourcing/ permalink: /tag_single_sourcing/

8
tags/tag_troubleshooting.html Normal file
View File

@ -0,0 +1,8 @@
---
title: "Troubleshooting pages"
tagName: troubleshooting
search: exclude
permalink: /tag_troubleshooting/
sidebar: tags_sidebar
---
{% include taglogic.html %}

1
tooltips.html
View File

@ -1,5 +1,6 @@
--- ---
layout: none layout: none
search: exclude
--- ---
<html> <html>