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

Made it so index.html in permalink is now an option in the config file. Made lots of other general improvements to the customjavascript.js file and various other parts of theme.

Browse Source
This commit is contained in:
Tom Johnson 2015-05-13 12:13:56 -07:00
parent 7f1a078520
commit ab51a49622
20 changed files with 193 additions and 237 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
_config.yml
View File

@ -88,3 +88,10 @@ collections:
# is this a print build? if so, put true. otherwise, false. # is this a print build? if so, put true. otherwise, false.
print: false print: false
floating_nav: true
# this option allows you to add a suffix to the permalinks in case you're publishing on a host such as Salesforce's site.com.
# on Salesforce's site.com, uploaded files must have index.html to display correctly. Most likely just ignore or remove this section unless
# you're publishing on Salesforce.
# suffix: index.html

5
_data/sidebar.yml
View File

@ -16,11 +16,6 @@ entries:
print: true print: true
web: false web: false
- title: Home
url: /
audience: writer, designer
print: true
- title: Getting started - title: Getting started
url: /getting_started/ url: /getting_started/
audience: writer, designer audience: writer, designer

2
_includes/custom/links.html
View File

@ -19,6 +19,7 @@
{% capture labels %}<a href="{{"/labels" | prepend: site.baseurl}}">Labels</a>{% endcapture %} {% capture labels %}<a href="{{"/labels" | prepend: site.baseurl}}">Labels</a>{% endcapture %}
{% capture icons %}<a href="{{"/icons" | prepend: site.baseurl}}">Icons</a>{% endcapture %} {% capture icons %}<a href="{{"/icons" | prepend: site.baseurl}}">Icons</a>{% endcapture %}
{% capture tables %}<a href="{{"/tables" | prepend: site.baseurl}}">Tables</a>{% endcapture %} {% capture tables %}<a href="{{"/tables" | prepend: site.baseurl}}">Tables</a>{% endcapture %}
{% capture shortcuts_for_jekyll_syntax %}<a href="{{ "/>shortcuts_for_jekyll_syntax" | prepend: site.baseurl }}">Shortcuts for Jekyll Syntax</a> {% endcapture %}
{% comment %}<!-- TAG ARCHIVES --> {% endcomment %} {% comment %}<!-- TAG ARCHIVES --> {% endcomment %}
@ -40,6 +41,7 @@
{% capture create_pdf %}<a href="{{"/create_pdf" | prepend: site.baseurl}}">Creating PDFs</a>{% endcapture %} {% capture create_pdf %}<a href="{{"/create_pdf" | prepend: site.baseurl}}">Creating PDFs</a>{% endcapture %}
{% capture help_api %}<a href="{{"/help_api" | prepend: site.baseurl}}">Creating a Help API</a>{% endcapture %} {% capture help_api %}<a href="{{"/help_api" | prepend: site.baseurl}}">Creating a Help API</a>{% endcapture %}
{% capture configuration_file %}<a href="{{"/configuration_file" | prepend: site.baseurl}}">Creating a Help API</a>{% endcapture %} {% capture configuration_file %}<a href="{{"/configuration_file" | prepend: site.baseurl}}">Creating a Help API</a>{% endcapture %}
{% capture iterm_profiles %}<a href="{{"/iterm_profiles" | prepend: site.baseurl}}">Set Up Profiles in iTerm</a>{% endcapture %}
{% comment %}<!-- NAVIGATION --> {% endcomment %} {% comment %}<!-- NAVIGATION --> {% endcomment %}

154
_includes/sidebar.html
View File

@ -1,87 +1,101 @@
<!-- Content Row --> <!-- Content Row -->
<div class="row"> <div class="row">
<!-- Sidebar Column --> <!-- Sidebar Column -->
<div class="col-md-3"> <div class="col-md-3">
<script> <script>
$(document).ready(function() { $(document).ready(function() {
// Initialize navgoco with default options // Initialize navgoco with default options
$("#mysidebar").navgoco({ $("#mysidebar").navgoco({
caretHtml: '', caretHtml: '',
accordion: {{site.sidebar_accordion}}, accordion: {{site.sidebar_accordion}},
openClass: 'active', // open openClass: 'active', // open
save: false, // leave false or nav higlighting doesn't work right save: false, // leave false or nav higlighting doesn't work right
cookie: { cookie: {
name: 'navgoco', name: 'navgoco',
expires: false, expires: false,
path: '/' path: '/'
}, },
slide: { slide: {
duration: 400, duration: 400,
easing: 'swing' easing: 'swing'
} }
}); });
$("#collapseAll").click(function(e) { $("#collapseAll").click(function(e) {
e.preventDefault(); e.preventDefault();
$("#mysidebar").navgoco('toggle', false); $("#mysidebar").navgoco('toggle', false);
}); });
$("#expandAll").click(function(e) { $("#expandAll").click(function(e) {
e.preventDefault(); e.preventDefault();
$("#mysidebar").navgoco('toggle', true); $("#mysidebar").navgoco('toggle', true);
}); });
}); });
</script> </script>
{% include custom/conditions.html %} {% include custom/conditions.html %}
<ul id="mysidebar" class="nav"> <ul id="mysidebar" class="nav">
<div class="siteTagline">{{site.tagline}}</div> <div class="siteTagline">{{site.tagline}}</div>
{% for entry in sidebar %} {% for entry in sidebar %}
{% for subcategory in entry.subcategories %} {% for subcategory in entry.subcategories %}
{% if subcategory.audience contains buildAudience %} {% if subcategory.audience contains buildAudience %}
<li><a href="#">{{ subcategory.title }}</a> <li><a href="#">{{ subcategory.title }}</a>
<ul> <ul>
{% for item in subcategory.items %} {% for item in subcategory.items %}
{% if item.audience contains buildAudience and item.web != false %} {% if item.audience contains buildAudience and item.web != false %}
<li><a href="{{item.url | prepend: site.baseurl}}index.html">{{item.title}}</a> {% if item.external_url %}
{% for thirdlevel in item.thirdlevel %} <li><a href="{{item.external_url}}" target="_blank">{{subcategory.title}}</a></li>
{% if thirdlevel.audience contains buildAudience and web != false %} {% elsif page.url contains item.url %}
<li class="thirdlevel"><a href="#">{{ thirdlevel.title }}</a> <li class="active"><a href="{{item.url | prepend: site.baseurl | append: site.suffix}}">{{item.title}}</a></li>
<ul> {% else %}
{% for deeplevel in thirdlevel.thirdlevelitems%} <li><a href="{{item.url | prepend: site.baseurl | append: site.suffix}}">{{item.title}}</a></li>
{% if deeplevel.audience contains buildAudience and item.web != false %} {% endif %}
<li><a href="{{deeplevel.url | prepend: site.baseurl}}index.html">{{deeplevel.title}}</a></li>
{% endif %} {% for thirdlevel in item.thirdlevel %}
{% endfor %} {% if thirdlevel.audience contains buildAudience and web != false %}
</ul> <li class="thirdlevel"><a href="#">{{ thirdlevel.title }}</a>
</li> <ul>
{% endif %} {% for deeplevel in thirdlevel.thirdlevelitems %}
{% endfor %} {% if deeplevel.audience contains buildAudience and item.web != false %}
</li> {% if deeplevel.external_url %}
{% endif %} <li><a href="{{deeplevel.external_url}}" target="_blank">{{deeplevel.title}}</a></li>
{% endfor %} {% elsif page.url contains deeplevel.url %}
</ul> <li class="active"><a href="{{deeplevel.url | prepend: site.baseurl | append: site.suffix}}">{{deeplevel.title}}</a></li>
{% else %}
<li><a href="{{deeplevel.url | prepend: site.baseurl | append: site.suffix}}">{{deeplevel.title}}</a></li>
{% endif %}
{% endif %}
{% endfor %}
</ul>
</li>
{% endif %}
{% endfor %}
</li>
{% endif %}
{% endfor %}
</ul>
</li> </li>
{% endif %} {% endif %}
{% endfor %} {% endfor %}
{% endfor %} {% endfor %}
</ul> </ul>
{% if site.sidebar_accordion == false %} {% if site.sidebar_accordion == false %}
<p class="external"> <p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a> <a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p> </p>
{% endif %} {% endif %}
</div> </div>

2
_includes/taglogic.html
View File

@ -6,7 +6,7 @@
{% for tag in page.tags %} {% for tag in page.tags %}
{% if tag == thisTag %} {% if tag == thisTag %}
<tr><td><a href="{{ page.permalink | prepend: site.baseurl | append: "index.html" }}">{{page.title}}</a></td> <tr><td><a href="{{ page.permalink | prepend: site.baseurl | append: site.suffix" }}">{{page.title}}</a></td>
<td>{% if page.summary %} {{ page.summary | strip_html | strip_newlines | truncate: 160 }} {% else %} {{ page.content | truncatewords: 50 | strip_html }} {% endif %}</td> <td>{% if page.summary %} {{ page.summary | strip_html | strip_newlines | truncate: 160 }} {% else %} {{ page.content | truncatewords: 50 | strip_html }} {% endif %}</td>
</tr> </tr>
{% endif %} {% endif %}

12
_includes/topnav.html
View File

@ -37,9 +37,9 @@
{% if subcategory.external_url %} {% if subcategory.external_url %}
<li><a href="{{subcategory.external_url}}" target="_blank">{{subcategory.title}}</a></li> <li><a href="{{subcategory.external_url}}" target="_blank">{{subcategory.title}}</a></li>
{% elsif page.url contains subcategory.url %} {% elsif page.url contains subcategory.url %}
<li class="active"><a href="{{subcategory.url | prepend: site.baseurl}}index.html" class="active">{{subcategory.title}}</a></li> <li class="active"><a href="{{subcategory.url | prepend: site.baseurl | append: site.suffix}}">{{subcategory.title}}</a></li>
{% else %} {% else %}
<li><a href="{{subcategory.url | prepend: site.baseurl}}index.html">{{subcategory.title}}</a></li> <li><a href="{{subcategory.url | prepend: site.baseurl | append: site.suffix}}">{{subcategory.title}}</a></li>
{% endif %} {% endif %}
{% endif %} {% endif %}
{% endfor %} {% endfor %}
@ -62,9 +62,9 @@
{% if subitem.external_url %} {% if subitem.external_url %}
<li><a href="{{subitem.external_url}}" target="_blank">{{subitem.title}}</a></li> <li><a href="{{subitem.external_url}}" target="_blank">{{subitem.title}}</a></li>
{% elsif page.url contains subitem.url %} {% elsif page.url contains subitem.url %}
<li class="dropdownActive"><a href="{{subitem.url | prepend: site.baseurl}}index.html">{{subitem.title}}</a></li> <li class="dropdownActive"><a href="{{subitem.url | prepend: site.baseurl | append: site.suffix}}">{{subitem.title}}</a></li>
{% else %} {% else %}
<li><a href="{{subitem.url | prepend: site.baseurl}}index.html">{{subitem.title}}</a></li> <li><a href="{{subitem.url | prepend: site.baseurl | append: site.suffix}}">{{subitem.title}}</a></li>
{% endif %} {% endif %}
{% endif %} {% endif %}
{% endfor %} {% endfor %}
@ -84,8 +84,8 @@
SimpleJekyllSearch.init({ SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'), searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'), resultsContainer: document.getElementById('results-container'),
dataSource: '{{ site.baseurl }}/search.json', dataSource: '{{site.baseurl}}/search.json',
searchResultTemplate: '<li><a href="{url}index.html" title="{{page.title}}">{title}</a></li>', searchResultTemplate: '<li><a href="{url}{{site.suffix}}" title="{{page.title}}">{title}</a></li>',
noResultsText: '{{site.data.strings.search_no_results_text}}', noResultsText: '{{site.data.strings.search_no_results_text}}',
limit: 10, limit: 10,
fuzzy: true, fuzzy: true,

6
css/customstyles.css
View File

@ -83,8 +83,10 @@ body h1 {margin-top:40px;}
.post-content img { .post-content img {
margin: 12px 0px 3px 0px; margin: 12px 0px 3px 0px;
max-width: 100%; width: auto;
height: auto;
max-width: 630px;
max-height: 100%;
} }
.post-content ol li, .post-content ul li { .post-content ol li, .post-content ul li {

63
js/customscripts.js
View File

@ -1,70 +1,31 @@
$('.sub_menu').hide();
$('.clickable').toggle(function (){
$(this).next('ul').slideToggle();
$(this).css('background-position', '0px -12px');
}, function (){
$(this).next('ul').slideToggle();
$(this).css('background-position', '0px 5px');
});
$('ul.sub_menu').has('a.active').css('display', 'block');
$('#myButton').tooltip();
// this does the highlighting for the active tab of the sidebar
$(function () {
setNavigation();
});
function setNavigation() {
var path = window.location.pathname;
path = path.replace(/\/$/, "");
path = decodeURIComponent(path);
$(".nav a").each(function () {
var href = $(this).attr('href');
if (path.substring(0, href.length) === href) {
$(this).closest('li').addClass('active');
$(this).closest('li').parents().addClass('active');
}
$("ul.pagination a").each(function () {
var href = $(this).attr('href');
if (path.substring(0, href.length) === href) {
$(this).closest('li').addClass('active');
$(this).closest('li').parents().addClass('active');
}
})
}
)}
$('#mysidebar').height($(".nav").height()); $('#mysidebar').height($(".nav").height());
// only use the affix class if the viewport is greater than 500px. otherwise it gets cut off.
$( document ).ready(function() { $( document ).ready(function() {
//this script says, if the height of the viewport is greater than 600px, then insert affix class, which makes the nav bar float in a fixed
// position as your scroll. if you have a lot of nav items, this height may not work for you.
{% unless site.floating_nav == "false" %}
var h = $(window).height(); var h = $(window).height();
console.log (h); console.log (h);
if (h > 600) { if (h > 600) {
$( "#mysidebar" ).attr("class", "nav affix"); $( "#mysidebar" ).attr("class", "nav affix");
} }
}); {% endif %}
// activate tooltips. although this is a bootstrap js function, it must be activated this way in your theme.
$(document).ready(function(){
$('[data-toggle="tooltip"]').tooltip({ $('[data-toggle="tooltip"]').tooltip({
placement : 'top' placement : 'top'
}); });
// this highlights the active parent class in the navgoco sidebar. this is critical so that the parent expands when you're viewing a page.
$("li.active").parents('li').toggleClass("active");
}); });
// needed for nav tabs // needed for nav tabs on pages. See Formatting > Nav tabs for more details.
// script from http://stackoverflow.com/questions/10523433/how-do-i-keep-the-current-tab-active-with-twitter-bootstrap-after-a-page-reload // script from http://stackoverflow.com/questions/10523433/how-do-i-keep-the-current-tab-active-with-twitter-bootstrap-after-a-page-reload
$(function() { $(function() {
var json, tabsState; var json, tabsState;
@ -94,3 +55,5 @@ $(function() {
} }
}); });
}); });

36
pages/content_types/pages.md
View File

@ -32,18 +32,36 @@ Frontmatter is always formatted with three hyphens at the top and bottom. Your f
The following table describes each of the frontmatter that you can use with this theme: The following table describes each of the frontmatter that you can use with this theme:
| Frontmatter | Description | | Frontmatter | Required? | Description |
|-------------|-------------| |-------------|-------------|-------------|
| **title** | The title for the page | | **title** | Required | The title for the page |
| permalink | The URL path for the page | | **permalink** | Required | The URL path for the page |
| **tags** | Tags for the page. Make all tags single words, with hyphens if needed. Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to _data/tags.yml to be allowed entrance into the page. | | **tags** | Optional | Tags for the page. Make all tags single words, with hyphens if needed. Separate them with commas. Enclose the whole list within brackets. Also, note that tags must be added to \_data/tags.yml to be allowed entrance into the page. |
| **keywords** | Synonyms and other keywords for the page. This information gets stuffed into the page's metadata to increase SEO. The user won't see the keywords, but if you search for one of the keywords, it will be picked up by the search engine. | | **keywords** | Optional | Synonyms and other keywords for the page. This information gets stuffed into the page's metadata to increase SEO. The user won't see the keywords, but if you search for one of the keywords, it will be picked up by the search engine. |
| **last_updated** | The date the page was last updated. This information is helpful for readers trying to evaluate how current and authoritative information is. | | **last_updated** | Optional | The date the page was last updated. This information is helpful for readers trying to evaluate how current and authoritative information is. |
| **summary** | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) | | **summary** | Optional | A 1-2 word sentence summarizing the content on the page. This gets formatted into the summary section in the page layout. Adding summaries is a key way to make your content more scannable by users (check out [Jakob Nielsen's site](http://www.nngroup.com/articles/corporate-blogs-front-page-structure/) for a great example of page summaries.) |
| **metadata** | Optional | Boolean (`true` or `false`). If you add `metadata: false` to the frontmatter, then the page metadata sidebar won't appear for the page. You might want to hide the sidebar for special pages such as glossaries, knowledge-base layouts, or more.
| **datatable** | Optional | Boolean. If you add `true`, then scripts for the [jQuery datatables plugin](https://www.datatables.net/) appear for the page. |
| **video** | Optional | If you add `true`, then scripts for [Video JS: The HTML5 video player](http://www.videojs.com/) appear on the page. |
{{tip}} You can see the scripts that conditionally appear by looking in the \_layouts/default.html page. Note that these scripts are served via a CDN, so the user must be online for the scripts to work. However, if the user isn't online, the tables and video still appear &mdash; they degrade gracefully. {{end}}
Only the title and permalink are actually required. If you leave the other fields blank, the theme will not show them (for example, if you leave tags blank, the theme won't show "Tags:" with nothing after it in the page metadata. Instead, the whole line will be hidden. Only the title and permalink are actually required. If you leave the other fields blank, the theme will not show them (for example, if you leave tags blank, the theme won't show "Tags:" with nothing after it in the page metadata. Instead, the whole line will be hidden.
To see how these metadata values get inserted into the theme, look at the page layout, specifically the included pagemetadata.html file. To see how these metadata values get inserted into the theme, look at the page layout, specifically the \_includes/pagemetadata.html file.
## Creating a Jekyll template in WebStorm
Rather than insert the frontmatter by hand each time, it's much faster to simply create a Jekyll template in WebStorm (my favorite editor for Jekyll projects).
To create a Jekyll template:
1. Right-click a file in the list of project files, and select **New > Edit File Templates**.
2. In the upper-left corner of the dialog box that appears, click the **+** button to create a new template.
3. Name it Jekyll. Insert the frontmatter you want, and save it.
To use the Jekyll template, when you create a new file in your WebStorm project, you can select your Jekyll file template.
## Markdown or HTML format ## Markdown or HTML format

18
pages/formatting/adding_tooltips.md
View File

@ -1,28 +1,24 @@
---
title: Adding tooltips title: Adding tooltips
permalink: /adding_tooltips/ permalink: /adding_tooltips/
tags: [formatting] tags: [formatting]
keywords: popovers keywords: popovers
audience: writers, designers audience: writers, designers
last_updated: May 8, 2015 last_updated: May 13, 2015
summary: "You can add tooltips to your content. These tooltips work well for glossary definitions." summary: "You can add tooltips to your content. These tooltips work well for glossary definitions."
--- ---
{% include linkrefs.html %} {% include linkrefs.html %}
=======
## permalink: /adding_tooltips/
Because this theme is built on Bootstrap, you can simply use a specific attribute on an element to insert a tooltip. 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: Suppose you have a glossary.yml file inside your _data folder. You could pull in that glossary definition like this:
<!--|%%|%7B%25%20raw%20%25%7D|%%|--> {% raw %}
```html
<a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.</a>
``` ```
<a href="#" data-toggle="tooltip" data-original-title="<!--|%%|%7B%7Bsite.data.glossary.jekyll_platform%7D%7D|%%|-->">Jekyll</a> is my favorite tool for building websites.</a> {% endraw %}
```
<!--|%%|%7B%25%20endraw%20%25%7D|%%|-->
This renders to the following: This renders to the following:
<a data-toggle="tooltip" data-original-title="<!--|%%|%7B%7Bsite.data.glossary.jekyll_platform%7D%7D|%%|-->" href="#">Jekyll</a> is my favorite tool for building websites. <a href="#" data-toggle="tooltip" data-original-title="{{site.data.glossary.jekyll_platform}}">Jekyll</a> is my favorite tool for building websites.</a>

2
pages/navigation/navigation.md
View File

@ -11,7 +11,7 @@ summary:
The sidebar and top navigation bar read their values from yml files inside the _data folder. Follow the YML syntax shown in the file. The sidebar and top navigation bar read their values from yml files inside the _data folder. Follow the YML syntax shown in the file.
# Sidebar nav # Sidebar accordion
The configuration file (configs/config_writer.yml) file includes a value (sidebar_accordion) that lets you choose whether to use the accordion feature in the sidebar or not. The accordion collapses other sections when a section is opened, which conserves space on the screen. Put `true` or `false` for the value. The configuration file (configs/config_writer.yml) file includes a value (sidebar_accordion) that lets you choose whether to use the accordion feature in the sidebar or not. The accordion collapses other sections when a section is opened, which conserves space on the screen. Put `true` or `false` for the value.
You can add two levels of nesting in the sidebar nav. Follow the pattern of the existing sidebar.yml file exactly. With YML, each new level is set off with two space below it. You can't change the names of the nesting levels without also making corresponding edits to the sidebar.htm file in the _includes directory. You can add two levels of nesting in the sidebar nav. Follow the pattern of the existing sidebar.yml file exactly. With YML, each new level is set off with two space below it. You can't change the names of the nesting levels without also making corresponding edits to the sidebar.htm file in the _includes directory.

3
pages/overview/config_setup.md
View File

@ -42,7 +42,8 @@ Note that you can arbitrary key value pairs in the configuration file, and then
| **sass** | The directory for sass files. This is a Jekyll-specific settings. Sass isn't customized in this theme. | | **sass** | The directory for sass files. This is a Jekyll-specific settings. Sass isn't customized in this theme. |
| **collections** | Any specific collections (custom content types that extend beyond pages or posts) that you want to define. This theme defines a collection called tooltips. You access this collection by using site.tooltips instead of site.pages or site.posts. Put the tooltip content types inside a folder in your project called \_tooltips. | **collections** | Any specific collections (custom content types that extend beyond pages or posts) that you want to define. This theme defines a collection called tooltips. You access this collection by using site.tooltips instead of site.pages or site.posts. Put the tooltip content types inside a folder in your project called \_tooltips.
| **print** | Boolean. Whether this build is a print build or not. This setting allows you to run conditions in your content such as {% raw %} {% if site.print == true %} do this... {% endif %} {% endraw %}. | | **print** | Boolean. Whether this build is a print build or not. This setting allows you to run conditions in your content such as {% raw %} {% if site.print == true %} do this... {% endif %} {% endraw %}. |
| **floating_nav** | Boolean. If you add `false`, then the sidebar navigation won't apply a fixed floating property. When the user scrolls. the nav bar won't stay in the same place. If you have a large nav bar, you may want to turn off the floating properties. Also, for small screens with viewports of 600px of height or smaller, the fixed nav is automatically turned off because the options tend to extend past the visible screen. Usually leave this set to `true` or omit the option altogether (the default is true).
| **suffix** | If you publish on Salesforce's site.com, you have to add index.html to the permalink or else the page won't render. I'm not sure why. If you add `suffix: index.html` in your config file, this file will be appended in the URLs. If you're not publishing to Salesforce, don't add this property to your configuration file.
## Where to store configuration files ## Where to store configuration files

45
pages/overview/getting_started.md
View File

@ -10,37 +10,38 @@ summary:
{% include linkrefs.html %} {% include linkrefs.html %}
## Step 1: Install all the prerequisites ## Step 1: Set up the prerequisites
Before you start installing the theme, make sure you have all of these prerequisites in place. Before you start installing the theme, make sure you have all of these prerequisites in place.
* Mac computer (recommended). If you have a PC, you need to see [Jekyll on Windows](http://jekyllrb.com/docs/windows/). Make sure you can get Jekyll working on Windows before proceeding. * **Mac computer (recommended)**. If you have a PC, you need to see [Jekyll on Windows](http://jekyllrb.com/docs/windows/). Make sure you can get Jekyll working on Windows before proceeding.
* [Ruby](https://www.ruby-lang.org/en/). This should already be installed. Type `which ruby` to confirm. * **[Ruby](https://www.ruby-lang.org/en/)**. This should already be installed. Type `which ruby` to confirm.
* [Rubygems](https://rubygems.org/pages/download). This is a package manager for Ruby (gems). Type `which gem` to confirm. * **[Rubygems](https://rubygems.org/pages/download)**. This is a package manager for Ruby (gems). Type `which gem` to confirm.
* [Jekyllrb](http://jekyllrb.com/). To install: `gem install jekyll`. Type `which jekyll` to confirm. * **[Jekyllrb](http://jekyllrb.com/)**. To install: `gem install jekyll`. Type `which jekyll` to confirm.
* [Git](http://git-scm.com/download/mac). Type `which git` to see if you already have it installed. * **[Git](http://git-scm.com/download/mac)**. Type `which git` to see if you already have it installed.
* Text editor (some examples: Sublime Text, Atom, WebStorm) * **Text editor** (some examples: Sublime Text, Atom, WebStorm)
* [iTerm](http://iterm.sourceforge.net/) - Optional but recommended instead of Terminal. * **[iTerm](http://iterm.sourceforge.net/)** - Optional but recommended instead of Terminal.
* [pygments](http://pygments.org/download/) - Pygments handles syntax highlighting. In my experiments, the Pygments highlighter seemed better than the default rouge highlighter. To install Pygments, you will need Python installed. (If you don't install pygments, you'll get an error when you build the theme.) To check if Python is installed, type `which python`. To install Pygments: `gem install pygments.rb`. * **[pygments](http://pygments.org/download/)** - Pygments handles syntax highlighting. In my experiments, the Pygments highlighter seemed better than the default rouge highlighter. To install Pygments, you will need Python installed. (If you don't install pygments, you'll get an error when you build the theme.) To check if Python is installed, type `which python`. To install Pygments: `gem install pygments.rb`.
{{warning}} These instructions are designed for users on Macs. Jekyllrb supposedly works on Windows but is not officially supported on that platform. See <a href="Jekyll on Windows">http://jekyllrb.com/docs/windows/</a> for more details. {{end}} {{warning}} These instructions are designed for users on Macs. Jekyllrb supposedly works on Windows but is not officially supported on that platform. See <a href="Jekyll on Windows">http://jekyllrb.com/docs/windows/</a> for more details. {{end}}
## Step 2: Build the theme ## Step 2: Build the theme
{{important}} Because this theme is intended to build multiple outputs from the same project, it doesn't use the default _config.yml file like other Jekyll themes. Instead, each different output has its own config file in the configs directory. As a result, you can't type `jekyll serve` to build the theme, since this command looks for the _config.yml file in your project directory, and there isn't one there.{{end}}
1. Make sure you satisfy all the prerequisites as listed in the previous section, "Prerequisites." 1. Make sure you satisfy all the prerequisites as listed in the previous section, "Prerequisites."
1. Download the theme from the [documentation-theme-jekyll Github repository](https://github.com/tomjohnson1492/documentation-theme-jekyll) and unzip it into your ~username/projects folder. 1. Download the theme from the [documentation-theme-jekyll Github repository](https://github.com/tomjohnson1492/documentation-theme-jekyll) and unzip it into your ~username/projects folder.
You can either download the theme files directly by clicking the **Download Zip** button on the right of the repo, or use git to clone the repository to your local machine. Note, however, that you won't be using the pull command to update the theme since you'll be customizing it with your own content and won't want to overwrite those customizations, so there isn't a huge need to clone or fork it. You can either download the theme files directly by clicking the **Download Zip** button on the right of the repo, or use git to clone the repository to your local machine. Note, however, that you won't be using the pull command to update the theme since you'll be customizing it with your own content and won't want to overwrite those customizations, so there isn't a huge need to clone it.
2. After downloading the theme, note some unique aspects of the file structure: *Inside the configs folder, there's a separate config file for each unique output you're building.* Each config file has a different preview port and build destination. Each config file also specifies a different audience. The whole point of this theme is to enable single sourcing, which allows you to build multiple outputs from the same source. That's why there are separate config files for each output. 2. After downloading the theme, note some unique aspects of the file structure:
* Inside the configs folder, there's a separate config file for each unique output you're building.
* Each config file has a different preview port and build destination. Each config file also specifies a different audience. The whole point of this theme is to enable single sourcing, which allows you to build multiple outputs from the same source. That's why there are separate config files for each output.
In general, you build the sites by using build commands that specify the config file and destination , like this: In general, you build the sites by using build commands that specify the config file and destination, like this:
``` ```
jekyll serve --config configs/config_writer.yml --destination ../documentation-theme-jekyll-builds/writer jekyll serve --config configs/config_writer.yml --destination ../documentation-theme-jekyll-builds/writer
``` ```
The `--config` parameter specifies the location of the configuration file to be used in the build, and the `--destination` parameter specifies where you want the site to be built. The `--config` parameter specifies the location of the configuration file to be used in the build, and the `--destination` parameter specifies where you want the site to be built.
Because these commands are long and bulky, it's easier to store them in a small shell script and then run the script. Because these commands are long and bulky, it's easier to store them in a small shell script and then run the script.
{{tip}} The _config.yml file in the theme's root directory is just a duplicate of the config_designer.yml file inside the configs directory. The _config.yml file in root allows Github Pages to build the site from the Github repo. Unless you're using Github Pages to build your sites, you don't need _config.yml in the root directory. {{end}}
3. In the root directory, you'll find build_writer.sh, which is a simple shell script containing this build argument. Instead of running the command above, run the following: 3. In the root directory, you'll find build_writer.sh, which is a simple shell script containing this build argument. Instead of running the command above, run the following:
``` ```
@ -58,6 +59,8 @@ jekyll serve --config configs/config_writer.yml --destination ../documentation-t
If the theme builds both outputs successfully, great. You can move on to the next section: Customizing the theme. If you run into errors building the basic theme, you must solve them before moving on. See {{troubleshooting}} for more information. If the theme builds both outputs successfully, great. You can move on to the next section: Customizing the theme. If you run into errors building the basic theme, you must solve them before moving on. See {{troubleshooting}} for more information.
{{tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{iterm_profiles}} for details. {{end}}
## Step 3: Customize the theme ## Step 3: Customize the theme
{{note}} Before you start customizing the theme, make sure you can build the theme by following the instructions in the previous section, "Step 2: Build the theme." {{end}} {{note}} Before you start customizing the theme, make sure you can build the theme by following the instructions in the previous section, "Step 2: Build the theme." {{end}}
@ -75,25 +78,25 @@ The theme shows two build outputs: one for designers, and one for writers. The d
5. In the _includes directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with your developer, and `designer` with another marketer.) 5. In the _includes directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with your developer, and `designer` with another marketer.)
The conditions.html file is used to apply different audience requirements to the sidebar and other files. The conditions.html file is included in various parts of the theme -- the sidebar.html, the topnav.html, and some of the print files. The conditions.html file is used to apply different audience requirements to the sidebar and other files. The conditions.html file is included in various parts of the theme &mdash; the sidebar.html, the topnav.html, and some of the print files.
6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside the pages folder is fine -- you won't have to worry about folder paths in links.) 6. Remove the content inside the pages folder, and then add your own pages in this pages folder. (Using subfolders and sub-subfolders inside the pages folder is fine &mdash; you won't have to worry about folder paths in links.)
7. Inside _data, open sidebar.yml and topnav.yml and customize the navigation. 7. Inside \_data, open sidebar.yml and topnav.yml and customize the navigation.
{{warning}} Don't mess up the spacing or change any of the YML level names or the site or sidebar won't build.) {{end}} {{warning}} Don't mess up the spacing or change any of the YML level names or the site or sidebar won't build. Each new YML level is indented with two spaces. {{end}}
8. In the root directory, rename build_writer.sh to build_developer.sh (same with build_designer.sh; change it to build_marketer.sh). In the content of each of these files, change the build parameters to point to the configuration file and output directory that you want. 8. In the root directory, rename build_writer.sh to build_developer.sh (same with build_designer.sh; change it to build_marketer.sh). In the content of each of these files, change the build parameters to point to the configuration file and output directory that you want.
{{note}} When you're just starting out, don't worry about setting up the PDF builds. This workflow for PDFs is more complicated and somewhat touchy. See {{create_pdf}} for more details. You will need to set up Prince in order for the PDF build to work. {{end}} {{note}} When you're just starting out, don't worry about setting up the PDF builds. This workflow for PDFs is more complicated and somewhat touchy. See {{create_pdf}} for more details. You will need to set up Prince in order for the PDF build to work. {{end}}
9. In the root directory, customize the index.md file. This file will be the homepage for all of your projects. Use conditional tags (for example, `if site.audience == "developer" ...`) to change the content for different builds of your site. See {{conditional_logic}} for more information. 9. In the root directory, customize the index.md file. This file will be the homepage for all of your projects. Use conditional tags (for example, `if site.audience == "developer" ...`) to change the content for different builds of your site. See {{conditional_logic}} for more information.
10. In the _includes folder, open linkrefs.html and add capture tags for all the pages in your site following the sample format shown. This will make it easy to link to each of the topics. (Don't remove the capture tags for the alerts and callouts.) 10. Optional. In the _includes/custom folder, open links.html and add capture tags for all the pages in your site following the sample format shown. This will make it easy to link to each of the topics.
{{note}} You don't need to use capture tags for links, but it does provide one way to try to manage all your links in one place. However, I'm still on the fence about the best way to manage links in a Jekyll theme. If you make your link text blend in with your sentence (which actually may be a better way of doing linking), this method wouldn't really work.{{end}}
11. For each of your pages where you want to insert a link, note, or callout, add {%raw%}`{% include linkrefs.html %}`{%endraw%} directly below the frontmatter. 11. For each of your pages where you want to insert a link, note, or callout, add {%raw%}`{% include linkrefs.html %}`{%endraw%} directly below the frontmatter.
{{tip}} If you're using WebStorm, you can create a Jekyll template so that the frontmatter is auto-populated when you create a new Jekyll file. {{end}}
12. In the _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags as you did with index.md. 12. In the _includes folder, open footer.html and customize the content. If you have different footers for different outputs, use conditional tags as you did with index.md.
12. In the layouts folder, open page.html and customize the values in the `site.show_audience_label` section. These are labels that appear on the page based on the audience attributes in the frontmatter for that page. If you want audiencd tags shown, make sure you have `true` set for the `site.show_audience_label` property in your config file. Each of your pages will need an audience property in the frontmatter.
11. Build your site with `. build_developer.sh` and `. build_marketer.sh` and preview it at the URLs provided. 11. Build your site with `. build_developer.sh` and `. build_marketer.sh` and preview it at the URLs provided.
{{callout_info}}<b>Publishing to web hosts:</b> If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other web host.{{end}} {{callout_info}}<b>Publishing to web hosts:</b> If you have multiple outputs, you probably don't want to use Github Pages to publish your site, since Github Pages looks for a _config.yml file in the root directory and uses that to build a site in the gh-pages branch of your repository. You can't instruct Github pages to look in another directory for the right configuration file. Instead, you'll probably have a better experience publishing to a Amazon Web Services S3 bucket or some other web host.{{end}}
## Questions ## Questions

2
pages/special-layouts/kb_layout.md
View File

@ -10,7 +10,7 @@ metadata: false
--- ---
{% include linkrefs.html %} {% include linkrefs.html %}
This shows a sample layout for a knowledge base. Each square could link to a tag archive page. This shows a sample layout for a knowledge base. Each square could link to a tag archive page. In this example, font icons from Font Awesome are enlarged to a large size. You could also add captions below each icon, and so forth. In a real implementation, you would probably make your own square graphics that included the text inside them.
<div class="row"> <div class="row">

6
pages/special-layouts/scroll.html
View File

@ -144,7 +144,7 @@ $('#small-box-links').localScroll({
<a href="#paranoia">"paranoia"</a>: "the constant feeling that others are out to get you, conspiring against your success", <a href="#paranoia">"paranoia"</a>: "the constant feeling that others are out to get you, conspiring against your success",
<a href="#qui">"qui"</a>: "a life force that runs through your body", <a href="#qui">"qui"</a>: "a life force that runs through your body",
<a href="#radical">"radical"</a>: "someone who opposes the status quo in major ways", <a href="#radical">"radical"</a>: "someone who opposes the status quo in major ways",
<a href="#silly">"silly": "how I feel writing this dummy copy", <a href="#silly">"silly"</a>: "how I feel writing this dummy copy",
<a href="#taffy">"taffy"</a>: "the sweets children like the most and dentists hate the worst", <a href="#taffy">"taffy"</a>: "the sweets children like the most and dentists hate the worst",
<a href="#umbrella">"umbrella"</a>: "an invention that has not had any advancements in 200 years", <a href="#umbrella">"umbrella"</a>: "an invention that has not had any advancements in 200 years",
<a href="#vampire">"vampire"</a>: "a paranormal figure that is surprisingly in vogue despite its basic nature", <a href="#vampire">"vampire"</a>: "a paranormal figure that is surprisingly in vogue despite its basic nature",
@ -194,7 +194,7 @@ $('#small-box-links').localScroll({
<div id="manifold"><h5>manifold</h5> Donec finibus massa vel nisi ullamcorper, vitae ornare enim euismod. Aliquam auctor quam erat. Duis interdum rutrum orci, ac interdum urna pharetra eget.</div> <div id="manifold"><h5>manifold</h5> Donec finibus massa vel nisi ullamcorper, vitae ornare enim euismod. Aliquam auctor quam erat. Duis interdum rutrum orci, ac interdum urna pharetra eget.</div>
<div id="octopus"><h5><octopus/h5>Nulla id egestas enim. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse potenti. Curabitur eu lobortis ligula.</div> <div id="octopus"><h5><octopus</h5>Nulla id egestas enim. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse potenti. Curabitur eu lobortis ligula.</div>
<div id="paranoia"><h5>paranoia</h5>Aenean hendrerit mauris ipsum, non laoreet ipsum luctus vel. Curabitur tristique auctor elit ut pulvinar. Quisque arcu arcu, condimentum aliquam sodales nec, dignissim nec justo. Nunc tristique sem felis, pharetra euismod lorem volutpat sed. Ut porttitor metus sit amet elit rhoncus semper.</div> <div id="paranoia"><h5>paranoia</h5>Aenean hendrerit mauris ipsum, non laoreet ipsum luctus vel. Curabitur tristique auctor elit ut pulvinar. Quisque arcu arcu, condimentum aliquam sodales nec, dignissim nec justo. Nunc tristique sem felis, pharetra euismod lorem volutpat sed. Ut porttitor metus sit amet elit rhoncus semper.</div>
@ -202,7 +202,7 @@ $('#small-box-links').localScroll({
<div id="radical"><h5>radical</h5>Etiam hendrerit interdum tellus, at aliquet sapien egestas in. Aenean eu urna nisl. Cras vitae risus pharetra, elementum mauris nec, auctor lectus. Fusce pellentesque venenatis dictum. Proin at augue at mauris finibus semper ultricies sed eros.</div> <div id="radical"><h5>radical</h5>Etiam hendrerit interdum tellus, at aliquet sapien egestas in. Aenean eu urna nisl. Cras vitae risus pharetra, elementum mauris nec, auctor lectus. Fusce pellentesque venenatis dictum. Proin at augue at mauris finibus semper ultricies sed eros.</div>
<div id="silly"><h5><silly/h5>Praesent pulvinar consequat posuere. Morbi egestas rhoncus felis, id fermentum metus lobortis in. Vestibulum nibh orci, euismod eget vestibulum nec, vehicula vitae tortor. Aenean ullamcorper enim nunc, eu auctor ligula auctor eget.</div> <div id="silly"><h5>silly</h5>Praesent pulvinar consequat posuere. Morbi egestas rhoncus felis, id fermentum metus lobortis in. Vestibulum nibh orci, euismod eget vestibulum nec, vehicula vitae tortor. Aenean ullamcorper enim nunc, eu auctor ligula auctor eget.</div>
<div id="taffy"><h5>taffy</h5>Etiam et arcu vel lacus aliquet lobortis in in massa. Nunc non mollis elit. Aenean accumsan orci quis risus aliquam, non gravida nulla molestie. Mauris pharetra libero et magna aliquam aliquam. Integer quis luctus dolor. </div> <div id="taffy"><h5>taffy</h5>Etiam et arcu vel lacus aliquet lobortis in in massa. Nunc non mollis elit. Aenean accumsan orci quis risus aliquam, non gravida nulla molestie. Mauris pharetra libero et magna aliquam aliquam. Integer quis luctus dolor. </div>

1
pages/tag-archives/tag-single-sourcing.html
View File

@ -2,5 +2,6 @@
title: "Single-Sourcing Pages" title: "Single-Sourcing Pages"
permalink: /tag-single-sourcing/ permalink: /tag-single-sourcing/
metadata: false metadata: false
tagName: single-sourcing
--- ---
{% include taglogic.html %} {% include taglogic.html %}

1
pages/tag-archives/tag-special-layouts.html
View File

@ -2,5 +2,6 @@
title: "Special Layout Pages" title: "Special Layout Pages"
permalink: /tag-special-layouts/ permalink: /tag-special-layouts/
metadata: false metadata: false
tagName: special-layouts
--- ---
{% include taglogic.html %} {% include taglogic.html %}

4
prince-file-list.txt
View File

@ -9,12 +9,12 @@ search: false
{% if subcategory.audience contains buildAudience %} {% if subcategory.audience contains buildAudience %}
{% for item in subcategory.items %} {% for item in subcategory.items %}
{% if item.audience contains buildAudience and item.print == true %} {% if item.audience contains buildAudience and item.print == true %}
{{site.url}}{{item.url | prepend: site.baseurl}}index.html {{site.url}}{{item.url | prepend: site.baseurl}}{{site.suffix}}
{% for thirdlevel in item.thirdlevel %} {% for thirdlevel in item.thirdlevel %}
{% if thirdlevel.audience contains buildAudience %} {% if thirdlevel.audience contains buildAudience %}
{% for deeplevel in thirdlevel.thirdlevelitems %} {% for deeplevel in thirdlevel.thirdlevelitems %}
{% if deeplevel.audience contains buildAudience and deeplevel.print == true %} {% if deeplevel.audience contains buildAudience and deeplevel.print == true %}
{{site.url}}{{item.url | prepend: site.baseurl}}index.html {{site.url}}{{item.url | prepend: site.baseurl}}{{site.suffix}}
{% endif %} {% endif %}
{% endfor %} {% endfor %}
{% endif %} {% endif %}

47
search.html
View File

@ -1,47 +0,0 @@
---
title: Search
permalink: /search/
search: exclude
related_pages: none
---
<style type="text/css">
#search-demo-container {
max-width: 40em;
padding: 1em;
margin: 1em auto;
border: 1px solid lightgrey;
}
#search-input {
display: inline-block;
padding: .5em;
width: 100%;
font-size: 0.8em;
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
}
</style>
<div id="search-demo-container">
<input type="text" id="search-input" placeholder="search...">
<ul id="results-container"></ul>
</div>
<script src="{{ site.baseurl }}/js/jekyll-search.js" type="text/javascript"></script>
<script type="text/javascript">
SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
dataSource: 'http://127.0.0.1:4000/jekyll-doc/search.json',
searchResultTemplate: '<li><a href="{url}" title="{desc}">{title}</a></li>',
noResultsText: 'No results found',
limit: 10,
fuzzy: false,
})
</script>