I changed the way I create links to use references to a data YML file instead of relying on the capture tag and including reference to the file with the captions. Using the capture tag was highly susceptible to broken links and way too manual. See the Links topic for more detail about the new method.
This commit is contained in:
Tom Johnson
parent
a24859dc66
commit
445b1d1f44
15
_data/alerts.yml
Normal file
15
_data/alerts.yml
Normal file
@ -0,0 +1,15 @@
|
||||
tip: '<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip: </b>'
|
||||
note: '<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note: </b>'
|
||||
important: '<div class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> <b>Important: </b>'
|
||||
warning: '<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>'
|
||||
end: '</div>'
|
||||
|
||||
callout_danger: '<div class="bs-callout bs-callout-danger">'
|
||||
callout_default: '<div class="bs-callout bs-callout-default">'
|
||||
callout_primary: '<div class="bs-callout bs-callout-primary">'
|
||||
callout_success: '<div class="bs-callout bs-callout-success">'
|
||||
callout_info: '<div class="bs-callout bs-callout-info">'
|
||||
callout_warning: '<div class="bs-callout bs-callout-warning">'
|
||||
|
||||
hr_faded: '<hr class="faded"/>'
|
||||
hr_shaded: '<hr class="shaded"/>'
|
||||
@ -35,6 +35,7 @@ entries:
|
||||
print: true
|
||||
|
||||
items:
|
||||
|
||||
- title: Introduction
|
||||
url: /index.html
|
||||
audience: writers, designers
|
||||
@ -70,7 +71,6 @@ entries:
|
||||
product: all
|
||||
version: all
|
||||
|
||||
|
||||
- title: Authoring
|
||||
audience: writers, designers
|
||||
platform: all
|
||||
|
||||
308
_data/urls.yml
Normal file
308
_data/urls.yml
Normal file
@ -0,0 +1,308 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
titlepage:
|
||||
title: "Title Page"
|
||||
url: "titlepage.html"
|
||||
link: "<a href='titlepage.html'>Title Page</a>"
|
||||
|
||||
|
||||
tocpage:
|
||||
title: "Table of Contents"
|
||||
url: "tocpage.html"
|
||||
link: "<a href='tocpage.html'>Table of Contents</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
index:
|
||||
title: "Introduction"
|
||||
url: "index.html"
|
||||
link: "<a href='index.html'>Introduction</a>"
|
||||
|
||||
|
||||
doc_getting_started:
|
||||
title: "Getting started with this theme"
|
||||
url: "doc_getting_started.html"
|
||||
link: "<a href='doc_getting_started.html'>Getting started with this theme</a>"
|
||||
|
||||
|
||||
doc_configuration_settings:
|
||||
title: "Setting configuration options"
|
||||
url: "doc_configuration_settings.html"
|
||||
link: "<a href='doc_configuration_settings.html'>Setting configuration options</a>"
|
||||
|
||||
|
||||
doc_customizing_the_theme:
|
||||
title: "Customizing the theme"
|
||||
url: "doc_customizing_the_theme.html"
|
||||
link: "<a href='doc_customizing_the_theme.html'>Customizing the theme</a>"
|
||||
|
||||
|
||||
doc_supported_features:
|
||||
title: "Supported features"
|
||||
url: "doc_supported_features.html"
|
||||
link: "<a href='doc_supported_features.html'>Supported features</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
doc_pages:
|
||||
title: "Pages"
|
||||
url: "doc_pages.html"
|
||||
link: "<a href='doc_pages.html'>Pages</a>"
|
||||
|
||||
|
||||
doc_webstorm_text_editor:
|
||||
title: "WebStorm Text Editor"
|
||||
url: "doc_webstorm_text_editor.html"
|
||||
link: "<a href='doc_webstorm_text_editor.html'>WebStorm Text Editor</a>"
|
||||
|
||||
|
||||
doc_series:
|
||||
title: "Series"
|
||||
url: "doc_series.html"
|
||||
link: "<a href='doc_series.html'>Series</a>"
|
||||
|
||||
|
||||
doc_collections:
|
||||
title: "Collections"
|
||||
url: "doc_collections.html"
|
||||
link: "<a href='doc_collections.html'>Collections</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
doc_sidebar_navigation:
|
||||
title: "Sidebar navigation"
|
||||
url: "doc_sidebar_navigation.html"
|
||||
link: "<a href='doc_sidebar_navigation.html'>Sidebar navigation</a>"
|
||||
|
||||
|
||||
doc_top_navigation:
|
||||
title: "Top navigation"
|
||||
url: "doc_top_navigation.html"
|
||||
link: "<a href='doc_top_navigation.html'>Top navigation</a>"
|
||||
|
||||
|
||||
doc_tags:
|
||||
title: "Tags"
|
||||
url: "doc_tags.html"
|
||||
link: "<a href='doc_tags.html'>Tags</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
doc_adding_tooltips:
|
||||
title: "Tooltips"
|
||||
url: "doc_adding_tooltips.html"
|
||||
link: "<a href='doc_adding_tooltips.html'>Tooltips</a>"
|
||||
|
||||
|
||||
doc_alerts:
|
||||
title: "Alerts"
|
||||
url: "doc_alerts.html"
|
||||
link: "<a href='doc_alerts.html'>Alerts</a>"
|
||||
|
||||
|
||||
doc_icons:
|
||||
title: "Icons"
|
||||
url: "doc_icons.html"
|
||||
link: "<a href='doc_icons.html'>Icons</a>"
|
||||
|
||||
|
||||
doc_images:
|
||||
title: "Images"
|
||||
url: "doc_images.html"
|
||||
link: "<a href='doc_images.html'>Images</a>"
|
||||
|
||||
|
||||
doc_labels:
|
||||
title: "Labels"
|
||||
url: "doc_labels.html"
|
||||
link: "<a href='doc_labels.html'>Labels</a>"
|
||||
|
||||
|
||||
doc_hyperlinks:
|
||||
title: "Links"
|
||||
url: "doc_hyperlinks.html"
|
||||
link: "<a href='doc_hyperlinks.html'>Links</a>"
|
||||
|
||||
|
||||
doc_navtabs:
|
||||
title: "Navtabs"
|
||||
url: "doc_navtabs.html"
|
||||
link: "<a href='doc_navtabs.html'>Navtabs</a>"
|
||||
|
||||
|
||||
doc_video_embeds:
|
||||
title: "Video embeds"
|
||||
url: "doc_video_embeds.html"
|
||||
link: "<a href='doc_video_embeds.html'>Video embeds</a>"
|
||||
|
||||
|
||||
doc_tables:
|
||||
title: "Tables"
|
||||
url: "doc_tables.html"
|
||||
link: "<a href='doc_tables.html'>Tables</a>"
|
||||
|
||||
|
||||
doc_syntax_highlighting:
|
||||
title: "Syntax highlighting"
|
||||
url: "doc_syntax_highlighting.html"
|
||||
link: "<a href='doc_syntax_highlighting.html'>Syntax highlighting</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
doc_conditional_logic:
|
||||
title: "Conditional logic"
|
||||
url: "doc_conditional_logic.html"
|
||||
link: "<a href='doc_conditional_logic.html'>Conditional logic</a>"
|
||||
|
||||
|
||||
doc_content_reuse:
|
||||
title: "Content reuse"
|
||||
url: "doc_content_reuse.html"
|
||||
link: "<a href='doc_content_reuse.html'>Content reuse</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
doc_build_arguments:
|
||||
title: "Build arguments"
|
||||
url: "doc_build_arguments.html"
|
||||
link: "<a href='doc_build_arguments.html'>Build arguments</a>"
|
||||
|
||||
|
||||
doc_themes:
|
||||
title: "Themes"
|
||||
url: "doc_themes.html"
|
||||
link: "<a href='doc_themes.html'>Themes</a>"
|
||||
|
||||
|
||||
doc_generating_pdfs:
|
||||
title: "Generating PDFs"
|
||||
url: "doc_generating_pdfs.html"
|
||||
link: "<a href='doc_generating_pdfs.html'>Generating PDFs</a>"
|
||||
|
||||
|
||||
doc_excluding_files:
|
||||
title: "Exclude files"
|
||||
url: "doc_excluding_files.html"
|
||||
link: "<a href='doc_excluding_files.html'>Exclude files</a>"
|
||||
|
||||
|
||||
doc_help_api:
|
||||
title: "Help API and UI tooltips"
|
||||
url: "doc_help_api.html"
|
||||
link: "<a href='doc_help_api.html'>Help API and UI tooltips</a>"
|
||||
|
||||
|
||||
doc_search_configuration:
|
||||
title: "Search configuration"
|
||||
url: "doc_search_configuration.html"
|
||||
link: "<a href='doc_search_configuration.html'>Search configuration</a>"
|
||||
|
||||
|
||||
doc_iterm_profiles:
|
||||
title: "iTerm profiles"
|
||||
url: "doc_iterm_profiles.html"
|
||||
link: "<a href='doc_iterm_profiles.html'>iTerm profiles</a>"
|
||||
|
||||
|
||||
doc_push_build_to_server:
|
||||
title: "Pushing builds to server"
|
||||
url: "doc_push_build_to_server.html"
|
||||
link: "<a href='doc_push_build_to_server.html'>Pushing builds to server</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
doc_kb_layout:
|
||||
title: "Knowledge-base layout"
|
||||
url: "doc_kb_layout.html"
|
||||
link: "<a href='doc_kb_layout.html'>Knowledge-base layout</a>"
|
||||
|
||||
|
||||
doc_scroll:
|
||||
title: "Scroll layout"
|
||||
url: "doc_scroll.html"
|
||||
link: "<a href='doc_scroll.html'>Scroll layout</a>"
|
||||
|
||||
|
||||
doc_shuffle:
|
||||
title: "Shuffle layout"
|
||||
url: "doc_shuffle.html"
|
||||
link: "<a href='doc_shuffle.html'>Shuffle layout</a>"
|
||||
|
||||
|
||||
doc_faq:
|
||||
title: "FAQ layout"
|
||||
url: "doc_faq.html"
|
||||
link: "<a href='doc_faq.html'>FAQ layout</a>"
|
||||
|
||||
|
||||
doc_glossary:
|
||||
title: "Glossary layout"
|
||||
url: "doc_glossary.html"
|
||||
link: "<a href='doc_glossary.html'>Glossary layout</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
doc_tag_archives_overview:
|
||||
title: "Tag archives overview"
|
||||
url: "doc_tag_archives_overview.html"
|
||||
link: "<a href='doc_tag_archives_overview.html'>Tag archives overview</a>"
|
||||
|
||||
|
||||
doc_tag-getting-started:
|
||||
title: "Getting started pages"
|
||||
url: "doc_tag-getting-started.html"
|
||||
link: "<a href='doc_tag-getting-started.html'>Getting started pages</a>"
|
||||
|
||||
doc_tag-formatting:
|
||||
title: "Formatting pages"
|
||||
url: "doc_tag-formatting.html"
|
||||
link: "<a href='doc_tag-formatting.html'>Formatting pages</a>"
|
||||
|
||||
doc_tag-navigation:
|
||||
title: "Navigation pages"
|
||||
url: "doc_tag-navigation.html"
|
||||
link: "<a href='doc_tag-navigation.html'>Navigation pages</a>"
|
||||
|
||||
doc_tag-content-types:
|
||||
title: "Content types pages"
|
||||
url: "doc_tag-content-types.html"
|
||||
link: "<a href='doc_tag-content-types.html'>Content types pages</a>"
|
||||
|
||||
doc_tag-publishing:
|
||||
title: "Publishing pages"
|
||||
url: "doc_tag-publishing.html"
|
||||
link: "<a href='doc_tag-publishing.html'>Publishing pages</a>"
|
||||
|
||||
doc_tag-special-layouts:
|
||||
title: "Special layout pages"
|
||||
url: "doc_tag-special-layouts.html"
|
||||
link: "<a href='doc_tag-special-layouts.html'>Special layout pages</a>"
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -6,6 +6,5 @@ audience: writers, designers
|
||||
last_updated: May 13, 2015
|
||||
summary: "These are some sample Git commands."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
When you're interacting with Github, it's helpful to know a few basic Git commands...
|
||||
@ -1,5 +0,0 @@
|
||||
{% capture tip %}<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip: </b>{% endcapture %}
|
||||
{% capture note %}<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note: </b>{% endcapture %}
|
||||
{% capture important %}<div class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> <b>Important: </b>{% endcapture %}
|
||||
{% capture warning %}<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>{% endcapture %}
|
||||
{% capture end %}</div>{% endcapture %}
|
||||
@ -1,9 +0,0 @@
|
||||
{% capture callout_danger %}<div class="bs-callout bs-callout-danger">{% endcapture %}
|
||||
{% capture callout_default %}<div class="bs-callout bs-callout-default">{% endcapture %}
|
||||
{% capture callout_primary %}<div class="bs-callout bs-callout-primary">{% endcapture %}
|
||||
{% capture callout_success %}<div class="bs-callout bs-callout-success">{% endcapture %}
|
||||
{% capture callout_info %}<div class="bs-callout bs-callout-info">{% endcapture %}
|
||||
{% capture callout_warning %}<div class="bs-callout bs-callout-warning">{% endcapture %}
|
||||
|
||||
{% capture hr_faded %}<hr class="faded"/> {%endcapture %}
|
||||
{% capture hr_shaded %}<hr class="shaded"/> {%endcapture %}
|
||||
@ -1,38 +0,0 @@
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Overview
|
||||
|
||||
This site provides documentation, training, and other notes for the Jekyll Documentation theme. There's a lot of information about how to do a variety of things here, and it's not all unique to this theme. But by and large, understanding how to do things in Jekyll depends on how your theme is coded.
|
||||
|
||||
## Survey of features
|
||||
|
||||
Some of the more prominent features of this theme include the following:
|
||||
|
||||
* Bootstrap framework
|
||||
* Sidebar with page hierarchy and advanced toc
|
||||
* PDF generation (with Prince XML utility)
|
||||
* Notes, tips, and warning information notes
|
||||
* Tags
|
||||
* Single sourced outputs
|
||||
* Emphasis on pages, not posts
|
||||
* Relative (rather than absolute) link structure
|
||||
|
||||
I'm using this theme for my documentation projects, building about 15 different outputs for various products, versions, languages, and audiences from the same set of files. This single sourcing requirement has influenced how I constructed this theme.
|
||||
|
||||
For more discussion about the available features, see {{doc_supported_features}}.
|
||||
|
||||
## Getting started
|
||||
|
||||
To get started, see these three topics:
|
||||
|
||||
1. {{doc_getting_started}}
|
||||
2. {{doc_configuration_settings}}
|
||||
3. {{doc_customizing_the_theme}}
|
||||
|
||||
## PDF Download
|
||||
|
||||
If you would like to download this help file as a PDF, you can do so here. The PDF most of the same content as the online help, except that some elements (such as video or special layouts) don't translate the the print medium, so they're excluded.
|
||||
|
||||
<a target="_blank" class="noCrossRef" href="doc_{{site.audience}}_pdf.pdf"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
|
||||
The PDF contains a timestamp in the header indicating when it was last generated. If you download a PDF, keep in mind that it may go out of date quickly. Always compare your PDF timestamp against the online help timestamp (which you can find in the footer).
|
||||
@ -1,129 +0,0 @@
|
||||
{% comment %} leave this end_i capture here, since all links with _i rely on it. {% endcomment %}
|
||||
{% capture end_i %}</a>{% endcapture %}
|
||||
|
||||
{% capture doc_about %}<a href="about.html">About this theme</a>{% endcapture %}
|
||||
{% capture doc_about_i %}<a href="about.html">{% endcapture %}
|
||||
|
||||
{% capture doc_adding_tooltips %}<a href="doc_adding_tooltips.html">Tooltips</a>{% endcapture %}
|
||||
{% capture doc_adding_tooltips_i %}<a href="doc_adding_tooltips.html">{% endcapture %}
|
||||
|
||||
{% capture doc_alerts %}<a href="doc_alerts.html">Alerts</a>{% endcapture %}
|
||||
{% capture doc_alerts_i %}<a href="doc_alerts.html">{% endcapture %}
|
||||
|
||||
{% capture doc_build_arguments %}<a href="doc_build_arguments.html">Build arguments</a>{% endcapture %}
|
||||
{% capture doc_build_arguments_i %}<a href="doc_build_arguments.html">{% endcapture %}
|
||||
|
||||
{% capture doc_collections %}<a href="doc_collections.html">Collections</a>{% endcapture %}
|
||||
{% capture doc_collections_i %}<a href="doc_collections.html">{% endcapture %}
|
||||
|
||||
{% capture doc_conditional_logic %}<a href="doc_conditional_logic.html">Conditional logic</a>{% endcapture %}
|
||||
{% capture doc_conditional_logic_i %}<a href="doc_conditional_logic.html">{% endcapture %}
|
||||
|
||||
{% capture doc_configuration_settings %}<a href="doc_configuration_settings.html">Setting configuration options</a>{% endcapture %}
|
||||
{% capture doc_configuration_settings_i %}<a href="doc_configuration_settings.html">{% endcapture %}
|
||||
|
||||
{% capture doc_content_reuse %}<a href="doc_content_reuse.html">Content reuse</a>{% endcapture %}
|
||||
{% capture doc_content_reuse_i %}<a href="doc_content_reuse.html">{% endcapture %}
|
||||
|
||||
|
||||
{% capture doc_customizing_the_theme %}<a href="doc_customizing_the_theme.html">Customizing the theme</a>{% endcapture %}
|
||||
{% capture doc_customizing_the_theme_i %}<a href="doc_customizing_the_theme.html">{% endcapture %}
|
||||
|
||||
{% capture doc_excluding_files %}<a href="doc_excluding_files.html">Excluding files</a>{% endcapture %}
|
||||
{% capture doc_excluding_files_i %}<a href="doc_excluding_files.html">{% endcapture %}
|
||||
|
||||
{% capture doc_faq %}<a href="doc_faq.html">FAQ layout</a>{% endcapture %}
|
||||
{% capture doc_faq_i %}<a href="doc_faq.html">{% endcapture %}
|
||||
|
||||
{% capture doc_generating_pdfs %}<a href="doc_generating_pdfs.html">Generating PDFs</a>{% endcapture %}
|
||||
{% capture doc_generating_pdfs_i %}<a href="doc_generating_pdfs.html">{% endcapture %}
|
||||
|
||||
{% capture doc_getting_started %}<a href="doc_getting_started.html">Getting started with this theme</a>{% endcapture %}
|
||||
{% capture doc_getting_started_i %}<a href="doc_getting_started.html">{% endcapture %}
|
||||
|
||||
{% capture doc_glossary %}<a href="doc_glossary.html">Glossary layout</a>{% endcapture %}
|
||||
{% capture doc_glossary_i %}<a href="doc_glossary.html">{% endcapture %}
|
||||
|
||||
{% capture doc_help_api %}<a href="doc_help_api.html">Help API and UI tooltips</a>{% endcapture %}
|
||||
{% capture doc_help_api_i %}<a href="doc_help_api.html">{% endcapture %}
|
||||
|
||||
{% capture doc_icons %}<a href="doc_icons.html">Icons</a>{% endcapture %}
|
||||
{% capture doc_icons_i %}<a href="doc_icons.html">{% endcapture %}
|
||||
|
||||
|
||||
{% capture doc_images %}<a href="doc_images.html">Images</a>{% endcapture %}
|
||||
{% capture doc_images_i %}<a href="doc_images.html">{% endcapture %}
|
||||
|
||||
{% capture doc_kb_layout %}<a href="doc_kb_layout.html">Knowledge-base layout</a>{% endcapture %}
|
||||
{% capture doc_kb_layout_i %}<a href="doc_kb_layout.html">{% endcapture %}
|
||||
|
||||
{% capture doc_labels %}<a href="doc_labels.html">Labels</a>{% endcapture %}
|
||||
{% capture doc_labels_i %}<a href="doc_labels.html">{% endcapture %}
|
||||
|
||||
{% capture doc_hyperlinks %}<a href="doc_hyperlinks.html">Links</a>{% endcapture %}
|
||||
{% capture doc_hyperlinks_i %}<a href="doc_hyperlinks.html">{% endcapture %}
|
||||
|
||||
|
||||
{% capture doc_navtabs %}<a href="doc_navtabs.html">Navtabs</a>{% endcapture %}
|
||||
{% capture doc_navtabs_i %}<a href="doc_navtabs.html">{% endcapture %}
|
||||
|
||||
{% capture doc_pages %}<a href="doc_pages.html">Pages</a>{% endcapture %}
|
||||
{% capture doc_pages_i %}<a href="doc_pages.html">{% endcapture %}
|
||||
|
||||
{% capture doc_push_build_to_server %}<a href="doc_push_build_to_server.html">Pushing builds to the server</a>{% endcapture %}
|
||||
{% capture doc_push_build_to_server_i %}<a href="doc_push_build_to_server.html">{% endcapture %}
|
||||
|
||||
{% capture doc_search_configuration %}<a href="doc_search_configuration.html">Search configuration</a>{% endcapture %}
|
||||
{% capture doc_search_configuration_i %}<a href="doc_search_configuration.html">{% endcapture %}
|
||||
|
||||
|
||||
{% capture doc_series %}<a href="doc_series.html">Series pages</a>{% endcapture %}
|
||||
{% capture doc_series_i %}<a href="doc_series.html">{% endcapture %}
|
||||
|
||||
{% capture doc_shuffle %}<a href="doc_shuffle.html">Shuffle layout</a>{% endcapture %}
|
||||
{% capture doc_shuffle_i %}<a href="doc_shuffle.html">{% endcapture %}
|
||||
|
||||
{% capture doc_sidebar_navigation %}<a href="doc_sidebar_navigation.html">Sidebar navigation</a>{% endcapture %}
|
||||
{% capture doc_sidebar_navigation_i %}<a href="doc_sidebar_navigation.html">{% endcapture %}
|
||||
|
||||
{% capture doc_special_layouts %}<a href="doc_special_layouts.html">Special layouts</a>{% endcapture %}
|
||||
{% capture doc_special_layouts_i %}<a href="doc_special_layouts.html">{% endcapture %}
|
||||
|
||||
|
||||
{% capture doc_support %}<a href="doc_support.html">Support</a>{% endcapture %}
|
||||
{% capture doc_support_i %}<a href="doc_support.html">{% endcapture %}
|
||||
|
||||
{% capture doc_supported_features %}<a href="doc_supported_features.html">Supported features</a>{% endcapture %}
|
||||
{% capture doc_supported_features_i %}<a href="doc_supported_features.html">{% endcapture %}
|
||||
|
||||
{% capture doc_syntax_highlighting %}<a href="doc_syntax_highlighting.html">Syntax highlighting</a>{% endcapture %}
|
||||
{% capture doc_syntax_highlighting_i %}<a href="doc_syntax_highlighting.html">{% endcapture %}
|
||||
|
||||
{% capture doc_tables %}<a href="doc_tables.html">Tables</a>{% endcapture %}
|
||||
{% capture doc_tables_i %}<a href="doc_tables.html">{% endcapture %}
|
||||
|
||||
|
||||
{% capture doc_tags %}<a href="doc_tags.html">Tags</a>{% endcapture %}
|
||||
{% capture doc_tags_i %}<a href="doc_tags.html">{% endcapture %}
|
||||
|
||||
{% capture doc_themes %}<a href="doc_themes.html">Themes</a>{% endcapture %}
|
||||
{% capture doc_themes_i %}<a href="doc_themes.html">{% endcapture %}
|
||||
|
||||
{% capture doc_top_navigation %}<a href="doc_top_navigation.html">Top navigation</a>{% endcapture %}
|
||||
{% capture doc_top_navigation_i %}<a href="doc_top_navigation.html">{% endcapture %}
|
||||
|
||||
{% capture doc_troubleshooting %}<a href="doc_troubleshooting.html">Troubleshooting</a>{% endcapture %}
|
||||
{% capture doc_troubleshooting_i %}<a href="doc_troubleshooting.html">{% endcapture %}
|
||||
|
||||
{% capture doc_video_embeds %}<a href="doc_video_embeds.html">Video embeds</a>{% endcapture %}
|
||||
{% capture doc_video_embeds_i %}<a href="doc_video_embeds.html">{% endcapture %}
|
||||
|
||||
{% capture doc_iterm_profiles %}<a href="doc_iterm_profiles.html">iTerm profiles</a>{% endcapture %}
|
||||
{% capture doc_iterm_profiles_i %}<a href="doc_iterm_profiles.html">{% endcapture %}
|
||||
|
||||
{% capture doc_webstorm_text_editor %}<a href="doc_webstorm_text_editor.html">WebStorm Text Editor</a>{% endcapture %}
|
||||
{% capture doc_webstorm_text_editor_i %}<a href="doc_webstorm_text_editor.html">{% endcapture %}
|
||||
|
||||
{% capture doc_seriesdemo1_1 %}<a href="doc_seriesdemo1_1.html">Series demo</a>{% endcapture %}
|
||||
{% capture doc_seriesdemo1_1_i %}<a href="doc_seriesdemo1_1.html">{% endcapture %}
|
||||
|
||||
@ -9,11 +9,8 @@
|
||||
<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">
|
||||
<link rel="stylesheet" type="text/css" href="css/modern-business.css">
|
||||
<link rel="stylesheet" type="text/css" href="css/lavish-bootstrap.css">
|
||||
<link rel="canonical" href="{{ page.url | replace:'index.html',''}}">
|
||||
<link rel="stylesheet" type="text/css" href="css/customstyles.css">
|
||||
<link rel="stylesheet" type="text/css" href="css/{{site.theme_file}}">
|
||||
<link rel="canonical" href="{{ page.url | replace:'index.html','' }}">
|
||||
<link rel="alternate" type="application/rss+xml" title="{{ site.title }}" href="feed.xml" />
|
||||
<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="js/jquery.navgoco.min.js"></script>
|
||||
|
||||
@ -1,4 +0,0 @@
|
||||
{% include custom/conditions.html %}
|
||||
{% include {{link}} %}
|
||||
{% include alerts.html %}
|
||||
{% include callouts.html %}
|
||||
@ -14,7 +14,7 @@ layout: default
|
||||
{% include toc.html %}
|
||||
|
||||
{{content}}
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
<div class="tags">
|
||||
{% if page.tags != null %}
|
||||
|
||||
@ -5,7 +5,7 @@ last_updated: August 12, 2015
|
||||
tags: [getting-started]
|
||||
summary: "I use this theme for sophisticated single-sourcing projects that I work on as a professional technical writer."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
My name is Tom Johnson, and I'm a technical writer, blogger, and podcaster based in San Jose, California. My blog is here: [http://idratherbewriting.com](http://idratherbewriting.com). I write several posts there a week. See [my blog's about page](http://idratherbewriting.com/aboutme/) for more details about me.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: popovers, tooltips, user interface text, glossaries, definitions
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can add tooltips to any word, such as an acronym or specialized term. Tooltips work well for glossary definitions, because you don't have to keep repeating the definition, nor do you assume the reader already knows the word's meaning."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Creating tooltips
|
||||
Because this theme is built on Bootstrap, you can simply use a specific attribute on an element to insert a tooltip.
|
||||
|
||||
@ -5,18 +5,9 @@ keywords: notes, tips, cautions, warnings, admonitions
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can insert notes, tips, warnings, and important alerts in your content. These notes are stored as shortcodes made available through the linksrefs.hmtl include."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## About alerts
|
||||
Alerts are little warnings, info, or other messages that you have called out in special formatting. In order to use these alerts or callouts, put this include at the top of your page, just below your frontmatter:
|
||||
|
||||
{%raw%}
|
||||
```liquid
|
||||
{% include linkrefs.html %}
|
||||
```
|
||||
{%endraw%}
|
||||
|
||||
Then insert any an alert or callout as described in the following sections.
|
||||
Alerts are little warnings, info, or other messages that you have called out in special formatting. In order to use these alerts or callouts, just reference the appropriate value stored in the alerts.yml file as described in the following sections.
|
||||
|
||||
## Alerts
|
||||
|
||||
@ -25,21 +16,21 @@ You can insert an alert by using any of the following code.
|
||||
{%raw%}
|
||||
alert | code
|
||||
------|---------
|
||||
note | {{note}} your note {{end}}
|
||||
tip | {{tip}} your tip {{end}}
|
||||
warning | {{warning}} your warning {{end}}
|
||||
important | {{important}} your important info {{end}}
|
||||
note | {{site.data.alerts.note}} your note {{site.data.alerts.end}}
|
||||
tip | {{site.data.alerts.tip}} your tip {{site.data.alerts.end}}
|
||||
warning | {{site.data.alerts.warning}} your warning {{site.data.alerts.end}}
|
||||
important | {{site.data.alerts.important}} your important info {{site.data.alerts.end}}
|
||||
{%endraw%}
|
||||
|
||||
The following demonstrate the formatting associated with each alert.
|
||||
|
||||
{{tip}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
{{site.data.alerts.tip}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
|
||||
|
||||
{{note}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
{{site.data.alerts.note}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
|
||||
|
||||
{{important}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
{{site.data.alerts.important}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
|
||||
|
||||
{{warning}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{end}}
|
||||
{{site.data.alerts.warning}} Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. {{site.data.alerts.end}}
|
||||
|
||||
## Callouts
|
||||
|
||||
@ -48,40 +39,38 @@ In contrast to the alerts, the callouts don't have a pre-coded bold-formatted pr
|
||||
{%raw%}
|
||||
callout | code
|
||||
------|---------
|
||||
callout_default | {{callout_default}} your callout_default content {{end}}
|
||||
callout_primary | {{callout_primary}} your callout_primary content {{end}}
|
||||
callout_success | {{callout_success}} your callout_success content {{end}}
|
||||
callout_primary | {{callout_primary}} your callout_primary content {{end}}
|
||||
callout_warning | {{callout_warning}} your callout_warning content {{end}}
|
||||
callout_info | {{callout_info}} your callout_info content {{end}}
|
||||
|
||||
callout_default | {{site.data.alerts.callout_default}} your callout_default content {{site.data.alerts.end}}
|
||||
callout_primary | {{site.data.alerts.callout_primary}} your callout_primary content {{site.data.alerts.end}}
|
||||
callout_success | {{site.data.alerts.callout_success}} your callout_success content {{site.data.alerts.end}}
|
||||
callout_warning | {{site.data.alerts.callout_warning}} your callout_warning content {{site.data.alerts.end}}
|
||||
callout_info | {{site.data.alerts.callout_info}} your callout_info content {{site.data.alerts.end}}
|
||||
{%endraw%}
|
||||
|
||||
The following demonstrate the formatting for each callout.
|
||||
|
||||
{{callout_danger}}<b>callout_danger</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
{{site.data.alerts.callout_danger}}<b>callout_danger</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{site.data.alerts.end}}
|
||||
|
||||
|
||||
{{callout_default}}
|
||||
{{site.data.alerts.callout_default}}
|
||||
<b>callout_default</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
{{site.data.alerts.end}}
|
||||
|
||||
{{callout_primary}}
|
||||
{{site.data.alerts.callout_primary}}
|
||||
<b>calloutprimary</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
{{site.data.alerts.end}}
|
||||
|
||||
{{callout_success}}
|
||||
{{site.data.alerts.callout_success}}
|
||||
<b>calloutsuccess</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
{{site.data.alerts.end}}
|
||||
|
||||
{{callout_info}}
|
||||
{{site.data.alerts.callout_info}}
|
||||
<b>calloutinfo</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
{{site.data.alerts.end}}
|
||||
|
||||
{{callout_warning}}
|
||||
{{site.data.alerts.callout_warning}}
|
||||
<b>calloutwarning</b>: Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.
|
||||
{{end}}
|
||||
{{site.data.alerts.end}}
|
||||
|
||||
|
||||
## Blast a warning to users
|
||||
@ -90,5 +79,5 @@ If you want to blast a warning to users on every page, add the alert or callout
|
||||
|
||||
## Using Markdown inside of notes
|
||||
|
||||
You can't use Markdown formatting inside notes.
|
||||
You can't use Markdown formatting inside alerts. This is because the alerts leverage HTML, and you can't use Markdown inside of HTML tags.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: building, serving, serve, build
|
||||
last_updated: August 12, 2015
|
||||
summary: "When you have a single sourcing project, you use more advanced arguments when you're building or serving your Jekyll sites. These arguments specify a particular configuration file and may build on other configuration files."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## How to build Jekyll sites
|
||||
|
||||
@ -33,7 +33,7 @@ Here the `configs/config_writers.yml` file is used instead of `_config.yml`. The
|
||||
|
||||
If you don't want to enter the long Jekyll argument every time, with all your configuration details, you can create a shell script and then just run the script. This theme shows an example with the doc_multibuild_web.sh file in the root directory.
|
||||
|
||||
My preference is to add the scripts to profiles in iTerm. See {{doc_iterm_profiles}} for more details.
|
||||
My preference is to add the scripts to profiles in iTerm. See {{site.data.urls.doc_iterm_profiles}} for more details.
|
||||
|
||||
## Stop a server
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: groups, api, structure
|
||||
last_updated: August 12, 2015
|
||||
summary: "Collections are useful if you want to loop through a special folder of pages that you make available in a content API. You could also use collections if you have a set of articles that you want to treat differently from the other content, with a different layout or format."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## What are collections
|
||||
Collections are custom content types different from pages and posts. You might create a collection if you want to treat a specific set of articles in a unique way, such as with a custom layout or listing. For more detail on collections, see [Ben Balter's explanation of collections here](http://ben.balter.com/2015/02/20/jekyll-collections/).
|
||||
@ -29,4 +29,4 @@ See [Collections in the Jekyll documentation](http://jekyllrb.com/docs/collectio
|
||||
|
||||
## How to use collections
|
||||
|
||||
I haven't found a huge use for collections in normal documentation. However, I did find a use for collections in generating a tooltip file that would be used for delivering tooltips to a user interface from text files in the documentation. See {{doc_help_api}} for details.
|
||||
I haven't found a huge use for collections in normal documentation. However, I did find a use for collections in generating a tooltip file that would be used for delivering tooltips to a user interface from text files in the documentation. See {{site.data.urls.doc_help_api}} for details.
|
||||
@ -5,14 +5,14 @@ keywords: if else logic, conditions, conditional attributes, conditional filteri
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can implement advanced conditional logic that includes if statements, or statements, unless, and more. This conditional logic facilitates single sourcing scenarios in which you're outputting the same content for different audiences."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About Liquid and conditional statements
|
||||
If you want to create different outputs for different audiences, you can do all of this using a combination of Jekyll's Liquid markup and values in your configuration file.
|
||||
|
||||
You can then incorporate conditional statements that check the values in the configuration files.
|
||||
|
||||
{{tip}} Definitely check out <a href="http://docs.shopify.com/themes/liquid-documentation/basics">Liquid's documentation</a> for more details about how to use operators and other liquid markup. The notes here are a small, somewhat superficial sample from the site.{{end}}
|
||||
{{site.data.alerts.tip}} Definitely check out <a href="http://docs.shopify.com/themes/liquid-documentation/basics">Liquid's documentation</a> for more details about how to use operators and other liquid markup. The notes here are a small, somewhat superficial sample from the site.{{site.data.alerts.end}}
|
||||
|
||||
## Where to store filtering values
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: configuration, config, publishing options, outputs, projects
|
||||
last_updated: August 12, 2015
|
||||
summary: "The configuration file contains important settings for your project. Some of the values you set here affect — especially the product, platform, audience, and version — the display and functionality of the theme."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Importance of Configuration File
|
||||
|
||||
@ -13,7 +13,7 @@ The configuration file serves important functions with single sourcing. For each
|
||||
|
||||
The configuration file contains all the settings and other details unique to that site output, such as variables, titles, output directories, build folders, and more.
|
||||
|
||||
{{warning}} This theme is coded to look for specific values set by the configuration file. If something isn't working correctly, check to make sure that you have the configuration values that are defined here.{{end}}
|
||||
{{site.data.alerts.warning}} This theme is coded to look for specific values set by the configuration file. If something isn't working correctly, check to make sure that you have the configuration values that are defined here.{{site.data.alerts.end}}
|
||||
|
||||
## Configuration file options
|
||||
|
||||
@ -101,7 +101,7 @@ jekyll serve --detach --config configs/config_writers.yml,configs/config_writers
|
||||
|
||||
First Jekyll will read the config_writers.yml file, and then Jekyll will read the config_writers_pdf.yml file.
|
||||
|
||||
More detail about generating PDFs is provided in {{doc_generating_pdfs}}, but the configuration settings used for the PDFs are described here.
|
||||
More detail about generating PDFs is provided in {{site.data.urls.doc_generating_pdfs.link}}, but the configuration settings used for the PDFs are described here.
|
||||
|
||||
The process for creating PDFs relies on two steps:
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: includes, conref, dita, transclusion, transclude, inclusion, reference
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can reuse chunks of content by storing these files in the includes folder. You then choose to include the file where you need it. This works similar to conref in DITA, except that you can include the file in any content type."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About content reuse
|
||||
You can embed content from one file inside another using includes. Put the file containing content you want to reuse (e.g., mypage.html) inside the \_includes folder, and then use a tag like this:
|
||||
@ -18,7 +18,7 @@ You can embed content from one file inside another using includes. Put the file
|
||||
|
||||
With content in your \_includes folder, you don't add any frontmatter to these pages because they will be included on other pages already containing frontmatter.
|
||||
|
||||
Also, when you include a file, all of the file's contents get included. You can't specify that you only want a specific part of the file included. However, you can use parameters with includes. See []Jekyll's documentation](http://stackoverflow.com/questions/21976330/passing-parameters-to-inclusion-in-liquid-templates) for more information on that.
|
||||
Also, when you include a file, all of the file's contents get included. You can't specify that you only want a specific part of the file included. However, you can use parameters with includes. See [Jekyll's documentation](http://stackoverflow.com/questions/21976330/passing-parameters-to-inclusion-in-liquid-templates) for more information on that.
|
||||
|
||||
## Page-level variables
|
||||
|
||||
|
||||
@ -5,23 +5,23 @@ last_updated: August 12, 2015
|
||||
keywords: getting started, customization, beginning steps, modifying the theme, modification
|
||||
summary: "You start customizing the theme by gutting the existing content in this theme and replacing it with your own content. Start with the configuration files, then customize the data files, and add your own markdown pages in the root directory."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About customizing the theme
|
||||
|
||||
The theme shows two build outputs: one for designers, and one for writers. The dual outputs is an example of the single sourcing nature of the theme. The designers output is comprehensive, whereas the writers output is a subset of the information. Follow these steps to customize the theme with your own content.
|
||||
|
||||
{{important}} In these instructions, I'll assume your project's name is "acme." I'll also assume you have two audiences you're building your acme project for: marketers and developers. {{end}}
|
||||
{{site.data.alerts.important}} In these instructions, I'll assume your project's name is "acme." I'll also assume you have two audiences you're building your acme project for: marketers and developers. {{site.data.alerts.end}}
|
||||
|
||||
To customize the theme:
|
||||
|
||||
1. In the theme's root directory, rename config_writer.yml to config_marketer.yml and customize all the values inside that file based on the instructions in {{doc_configuration_settings}}. Do the same with config_designer.yml (changing it to config_developer.yml) and continue to clone and customize the config file for other audiences you need.
|
||||
1. In the theme's root directory, rename config_writer.yml to config_marketer.yml and customize all the values inside that file based on the instructions in {{site.data.urls.doc_configuration_settings.link}}. Do the same with config_designer.yml (changing it to config_developer.yml) and continue to clone and customize the config file for other audiences you need.
|
||||
|
||||
In this theme, each output requires a separate config file. If you have 10 audiences and you want separate sites for each, then then you'll have 10 config files in this directory.
|
||||
|
||||
2. Make similar customizations to the PDF configuration files. You will later use these files when you create PDFs.
|
||||
|
||||
{{tip}} As you customize the config files, make the port values unique so that you don't run into "Address already in use" issues when you build multiple sites and want to preview them at the same time.{{end}}
|
||||
{{site.data.alerts.tip}} As you customize the config files, make the port values unique so that you don't run into "Address already in use" issues when you build multiple sites and want to preview them at the same time.{{site.data.alerts.end}}
|
||||
|
||||
5. In the \_includes/custom directory, open conditions.html and customize the values there specific to your outputs. (Basically, replace `writer` with `developer`, and `designer` with `marketer`.)
|
||||
|
||||
@ -35,17 +35,13 @@ To customize the theme:
|
||||
|
||||
7. Inside \_data, open sidebar_doc.yml and topnav_doc.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 appear. Each new YML level is indented with two spaces. Sometimes getting this spacing right is tricky. I recommend you save the sample template here that shows the various levels, and then just copy and paste the levels where you need them. YML is very picky and it can be frustrating sorting out spacing and level issues. {{end}}
|
||||
{{site.data.alerts.warning}} Don't mess up the spacing or change any of the YML level names or the site or sidebar won't appear. Each new YML level is indented with two spaces. Sometimes getting this spacing right is tricky. I recommend you save the sample template here that shows the various levels, and then just copy and paste the levels where you need them. YML is very picky and it can be frustrating sorting out spacing and level issues. {{site.data.alerts.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, `{% raw %}{% if site.project == "writers" %} ... {% endif %}{% endraw %}`) to change the content for different builds of your site. Store the content of the homepage in your \_includes/custom/{project_name} folder. See {{conditional_logic}} for more information on applying conditions.
|
||||
|
||||
10. For each of your pages where you want to insert a 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. Ctrl + click the file area and choose <b>New > Edit File Templates</b>. {{end}}
|
||||
|
||||
|
||||
Use conditional tags (for example, `{% raw %}{% if site.project == "writers" %} ... {% endif %}{% endraw %}`) to change the content for different builds of your site. Store the content of the homepage in your \_includes/custom/{project_name} folder. See {{site.data.urls.conditional_logic.link}} for more information on applying conditions.
|
||||
|
||||
12. In the \_includes folder, open footer.html and customize the content (namely the footer image). If you have different footers for different outputs, use conditional tags as you did with index.md.
|
||||
11. Build your site with a command such as `jekyll serve --config configs/config_writers.yml` etc., 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. See {{doc_push_build_to_server}} for more information.{{end}}
|
||||
{{site.data.alerts.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. See {{site.data.urls.doc_push_build_to_server.link}} for more information.{{site.data.alerts.end}}
|
||||
14058
doc_designers_pdf.pdf
14058
doc_designers_pdf.pdf
File diff suppressed because it is too large
Load Diff
@ -5,7 +5,7 @@ last_updated: August 12, 2015
|
||||
keywords: exclusion, separating outputs, removing files from outputs
|
||||
summary: "By default, all the files in your Jekyll project are included in the output (this differs from DITA projects, which don't include files unless noted on the map). If you're single sourcing, you'll need to exclude the files that shouldn't be included in the output. The sidebar doesn't control inclusion or exclusion."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About exclusion
|
||||
By default, all files in your project are included in your output (regardless of whether they're listed in the sidebar_doc.yml file or not). To exclude files, note them in the `exclude` section in the configuration file. Here's a sample:
|
||||
|
||||
25
doc_faq.html
25
doc_faq.html
@ -5,7 +5,6 @@ keywords: frequently asked questions, FAQ, question and answer, collapsible sect
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can use an accordion-layout that takes advantage of Bootstrap styling. This is useful for an FAQ page."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
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 doc_faq.html theme file.
|
||||
|
||||
@ -14,10 +13,10 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseOne">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseOne">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseOne" class="panel-collapse collapse">
|
||||
<div id="collapseOne" class="panel-collapse collapse noCrossRef">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
@ -27,10 +26,10 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseTwo">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseTwo">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseTwo" class="panel-collapse collapse">
|
||||
<div id="collapseTwo" class="panel-collapse collapse noCrossRef">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
@ -40,10 +39,10 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseThree">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseThree">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseThree" class="panel-collapse collapse">
|
||||
<div id="collapseThree" class="panel-collapse collapse noCrossRef">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
@ -53,7 +52,7 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseFour">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseFour">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseFour" class="panel-collapse collapse">
|
||||
@ -66,7 +65,7 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseFive">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseFive">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseFive" class="panel-collapse collapse">
|
||||
@ -79,7 +78,7 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseSix">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseSix">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseSix" class="panel-collapse collapse">
|
||||
@ -92,7 +91,7 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseSeven">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseSeven">Lorem ipsum dolor sit amet, consectetur adipiscing elit?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseSeven" class="panel-collapse collapse">
|
||||
@ -105,7 +104,7 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseEight">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseEight">Curabitur eget leo at velit imperdiet varius. In eu ipsum vitae velit congue iaculis vitae at risus?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseEight" class="panel-collapse collapse">
|
||||
@ -118,7 +117,7 @@ If you want to use an FAQ format, use the syntax shown on the faq.html page. Rat
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading">
|
||||
<h4 class="panel-title">
|
||||
<a class="accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseNine">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
<a class="noCrossRef accordion-toggle" data-toggle="collapse" data-parent="#accordion" href="#collapseNine">Aenean consequat lorem ut felis ullamcorper?</a>
|
||||
</h4>
|
||||
</div>
|
||||
<div id="collapseNine" class="panel-collapse collapse">
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: PDF, prince, prince XML, ant, xsl fo
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can generate a PDF from your Jekyll project. You do this by creating a web version of your project that is printer friendly. You then use utility called Prince to iterate through the pages and create a PDF from them. It works quite well and gives you complete control to customize the PDF output through CSS, including page directives and dynamic tags from Prince."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## PDF overview
|
||||
This process for creating a PDF relies on Prince XML to transform the HTML content into PDF. Prince costs about $500 per license. That might seem like a lot, but if you're creating a PDF, you're probably working for a company that sells a product, so you likely have access to some resources.
|
||||
@ -57,7 +57,7 @@ defaults:
|
||||
search: true
|
||||
```
|
||||
|
||||
{{note}} Although you're creating a PDF, you must still build a web target before running Prince. Prince will pull from the HTML files and from the file-list for the TOC. Prince won't be able to find files if they simply have relative paths, such as /sample.html. The must have full URLs it can access — hence the <code>url</code> and <code>baseurl</code>. {{end}}
|
||||
{{site.data.alerts.note}} Although you're creating a PDF, you must still build a web target before running Prince. Prince will pull from the HTML files and from the file-list for the TOC. Prince won't be able to find files if they simply have relative paths, such as /sample.html. The must have full URLs it can access — hence the <code>url</code> and <code>baseurl</code>. {{site.data.alerts.end}}
|
||||
|
||||
Unlike the other configuration files, the PDF configuration files require a `url` and `baseurl`. This is because the Prince utility needs to access the pages in a specific place. While you could probably set up locations via absolute paths to file folders, it's easier just to provide the locations here as `url` and `baseurl`.
|
||||
|
||||
@ -110,7 +110,7 @@ The code in the tocpage.html is nearly identical to that of the sidebar.html pag
|
||||
|
||||
There's another file (in the root directory of the theme) that is critical to the PDF generation process: prince-file-list.txt. This file simply iterates through the items in your sidebar and creates a list of links. Prince will consume the list of links from prince-file-list.txt and create a running PDF that contains all of the pages listed, with appropriate cross references and styling for them all.
|
||||
|
||||
{{note}} If you have any files that you do not want to appear in the PDF, add <code>print: false</code> in the list of attributes in your sidebar. The prince-file-list.txt file that loops through the sidebar_doc.yml file to grab the URLs of each page that should appear in the PDF will skip over any items that have <code>print: false</code> in the item attributes. For example, you might not want your tag archives to appear in the PDF, but you probably will want to list them in the online help navigation. {{end}}
|
||||
{{site.data.alerts.note}} If you have any files that you do not want to appear in the PDF, add <code>print: false</code> in the list of attributes in your sidebar. The prince-file-list.txt file that loops through the sidebar_doc.yml file to grab the URLs of each page that should appear in the PDF will skip over any items that have <code>print: false</code> in the item attributes. For example, you might not want your tag archives to appear in the PDF, but you probably will want to list them in the online help navigation. {{site.data.alerts.end}}
|
||||
|
||||
## 4. Customize your headers and footers
|
||||
|
||||
@ -135,7 +135,7 @@ a[href*="mailto"]::after, a[data-toggle="tooltip"]::after, a[href].noCrossRef::a
|
||||
}
|
||||
```
|
||||
|
||||
If you have a link to a file download, for example, add `noCrossRef` as a class to avoid having it say "page 0" in the cross reference.
|
||||
{{site.data.alerts.tip}} If you have a link to a file download, or some other link that shouldn't have a cross reference (such as link used in JavaScript for navtabs or collapsible sections, for example, add `noCrossRef` as a class to the link to avoid having it say "page 0" in the cross reference.{{site.data.alerts.end}}
|
||||
|
||||
This style specifies that after links to web resources, the URL should be inserted instead of the page number:
|
||||
|
||||
@ -367,7 +367,7 @@ To generate the PDF, you just run several scripts that have the commands package
|
||||
2. Then run doc_multibuild_pdf.sh to build the PDF files.
|
||||
3. Now run doc_multibuild_web.sh to build the web version that includes the generated PDF files.
|
||||
|
||||
{{note}} If you don't like the style of the PDFs, just adjust the styles in the printstyles.css file.{{end}}
|
||||
{{site.data.alerts.note}} If you don't like the style of the PDFs, just adjust the styles in the printstyles.css file.{{site.data.alerts.end}}
|
||||
|
||||
## JavaScript conflicts
|
||||
|
||||
@ -391,4 +391,4 @@ javascript content here ...
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
For more detail about using `unless` in conditional logic, see {{doc_conditional_logic}}. What this code means is basically the opposite of `{% raw %}if site.print == true {% endraw %}`.
|
||||
For more detail about using `unless` in conditional logic, see {{site.data.urls.doc_conditional_logic.link}}. What this code means is basically the opposite of `{% raw %}if site.print == true {% endraw %}`.
|
||||
|
||||
@ -5,8 +5,6 @@ keywords: start, introduction, begin, install, build, hello world,
|
||||
last_updated: August 12, 2015
|
||||
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. Because this theme is set up for single sourcing projects, it doesn't follow the same pattern as most Jekyll projects (which have just a _config.yml file in the root directory)."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Step 1: Set up the prerequisites
|
||||
|
||||
@ -34,7 +32,7 @@ Before you start customizing the theme, make sure you can build the theme with t
|
||||
* Each configuration file specifies a different project and potentially a different audience, product, platform, and version. By setting unique values for these properties in the includes/custom/conditions.html file, you determine how the sidebar and top navigation get constructed.
|
||||
* You can build all the outputs in your configs directory by running the doc_multibuild_web.sh file in the root directory.
|
||||
|
||||
{{tip}} The main goal of this theme is to enable single sourcing. With single sourcing, you build multiple outputs from the same source, with somewhat different content in each site based on the particular product, platform, version, and audience. You don't have to use this theme for single sourcing, but most tech writing projects involve this requirement.{{end}}
|
||||
{{site.data.alerts.tip}} The main goal of this theme is to enable single sourcing. With single sourcing, you build multiple outputs from the same source, with somewhat different content in each site based on the particular product, platform, version, and audience. You don't have to use this theme for single sourcing, but most tech writing projects involve this requirement.{{site.data.alerts.end}}
|
||||
|
||||
There are four configuration files in this project: config_writer.yml and config_designer.yml as well as their PDF equivalents. The idea is that there's an output specific to writers, and an output specific to designers.
|
||||
|
||||
@ -70,15 +68,15 @@ Before you start customizing the theme, make sure you can build the theme with t
|
||||
|
||||
Open the writers and designers folders and click the index.html file. The themes should launch and appear similar to their appearance in the preview folder. This is because the themes are build using a relative link structure, so you can move the theme to any folder you want without breaking the links.
|
||||
|
||||
If the theme builds both outputs successfully, great. You can move on to the other sections. If you run into errors building the themes, try to solve them before moving on. See {{doc_troubleshooting}} for more information.
|
||||
If the theme builds both outputs successfully, great. You can move on to the other sections. If you run into errors building the themes, try to solve them before moving on. See {{site.data.urls.doc_troubleshooting.link}} for more information.
|
||||
|
||||
{{tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{doc_iterm_profiles}} for details. {{end}}
|
||||
|
||||
More information about building the PDF versions is provided in {{doc_generating_pdfs}}.
|
||||
{{site.data.alerts.tip}} You can set up profiles in iTerm to initiate all your builds with one selection. See {{site.data.urls.doc_iterm_profiles.link}} for details. {{site.data.alerts.end}}
|
||||
|
||||
More information about building the PDF versions is provided in {{site.data.urls.doc_generating_pdfs.link}}.
|
||||
|
||||
## Questions
|
||||
|
||||
If you have questions, contact me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. My regular site is [http://idratherbewriting.com](idratherbewriting.com). I'm eager to make these installation instructions as clear as possible, so please let me know if there are areas of confusion that need clarifying.
|
||||
If you have questions, contact me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. My regular site is [idratherbewriting.com](http://idratherbewriting.com). I'm eager to make these installation instructions as clear as possible, so please let me know if there are areas of confusion that need clarifying.
|
||||
|
||||
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: definitions, glossaries, terms, style guide
|
||||
last_updated: August 12, 2015
|
||||
summary: "Your glossary page can take advantage of definitions stored in a data file. This gives you the ability to reuse the same definition in multiple places. Additionally, you can use Bootstrap classes to arrange your definition list horizontally."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
You can create a glossary for your content. First create your glossary items in a data file such as glossary.yml.
|
||||
|
||||
|
||||
@ -5,13 +5,13 @@ last_updated: August 12, 2015
|
||||
keywords: API, content API, UI text, inline help, context-sensitive help, popovers, tooltips
|
||||
summary: "You can loop through files and generate a JSON file that developers can consume like a help API. Developers can pull in values from the JSON into interface elements, styling them as popovers for user interface text, for example. The beauty of this method is that the UI text remains in the help system and isn't hard-coded into the UI."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Full code demo of content API
|
||||
|
||||
You can create a help API that developers can use to pull in content.
|
||||
|
||||
For the full code demo, see the notes in the <a target="_blank" title="ToolTip Demo" href="{{ "tooltip_demo.html" | prepend: site.baseurl }}">Tooltip Demo</a>.
|
||||
For the full code demo, see the notes in the <a href="tooltip_demo.html" class="noCrossRef">tooltip demo</a>.
|
||||
|
||||
In this demo, the popovers pull in and display content from the information in an external tooltips.json file located on a different host.
|
||||
|
||||
@ -80,9 +80,9 @@ layout: none
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
This code will loop through all pages in the tooltips collection and insert the id and body into key-value pairs for the JSON code. Here's an example of what that looks like after it's processed by Jekyll in the site build: <a target="_blank" title="ToolTip Demo" href="{{ "/tooltips.json" | prepend: site.baseurl }}">Tooltips</a>.
|
||||
This code will loop through all pages in the tooltips collection and insert the id and body into key-value pairs for the JSON code. Here's an example of what that looks like after it's processed by Jekyll in the site build: <a class="noCrossRef" href="tooltips.json">tooltips.json</a>.
|
||||
|
||||
{{tip}} Check out <a href="https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml">Google's style guide for JSON</a>. These best practices can help you keep your JSON file valid.{{end}}
|
||||
{{site.data.alerts.tip}} Check out <a href="https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml">Google's style guide for JSON</a>. These best practices can help you keep your JSON file valid.{{site.data.alerts.end}}
|
||||
|
||||
Store this tooltips.json file in your root directory. You can add different fields depending on how you want the JSON to be structured. Here I just have to fields: `id` and `body`. And the JSON is looking just in the tooltips collection that I created.
|
||||
|
||||
@ -141,7 +141,7 @@ In other server setups, you may need to edit one of your Apache configuration fi
|
||||
|
||||
If you don't have CORS enabled, users will see a CORS error/warning message in the console of the page making the request.
|
||||
|
||||
{{tip}} If enabling CORS is problematic, you could always just send developers the tooltips.json file and ask them to place it on their own server. {{end}}
|
||||
{{site.data.alerts.tip}} If enabling CORS is problematic, you could always just send developers the tooltips.json file and ask them to place it on their own server. {{site.data.alerts.end}}
|
||||
|
||||
## 5. Explain how developers can access the help
|
||||
|
||||
@ -172,7 +172,7 @@ $.get( url, function( data ) {
|
||||
|
||||
The `{url}` is where your tooltips.json file is. The `each` method looks through all the JSON content to find the item whose `page.id` is equal to `basketball`. It then looks for an element on the page named `#basketball` and adds a `data-content` attribute to that element.
|
||||
|
||||
{{warning}}<b>Note:</b> Make sure your JSON file is valid. Otherwise, this method won't work. I use the <a href="https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa?hl=en">JSON Formatter extension for Chrome</a>. When I go to the tooltips.json page in my browser, the JSON content — if valid — is nicely formatted (and includes some color coding). If the file isn't valid, it's not formatted and there isn't any color. You can also check the JSON formatting using <a href="http://jsonformatter.curiousconcept.com/">JSON Formatter and Validator</a>. If your JSON file isn't valid, identify the problem area using the validator and troubleshoot the file causing issues. It's usually due to some code that isn't escaping correctly. {{end}}
|
||||
{{site.data.alerts.warning}}<b>Note:</b> Make sure your JSON file is valid. Otherwise, this method won't work. I use the <a href="https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa?hl=en">JSON Formatter extension for Chrome</a>. When I go to the tooltips.json page in my browser, the JSON content — if valid — is nicely formatted (and includes some color coding). If the file isn't valid, it's not formatted and there isn't any color. You can also check the JSON formatting using <a href="http://jsonformatter.curiousconcept.com/">JSON Formatter and Validator</a>. If your JSON file isn't valid, identify the problem area using the validator and troubleshoot the file causing issues. It's usually due to some code that isn't escaping correctly. {{site.data.alerts.end}}
|
||||
|
||||
Why `data-content`? Well, in this case, I'm using [Bootstrap popovers](http://getbootstrap.com/javascript/#popovers) to display the tooltip content. The `data-content` attribute is how Bootstrap injects popovers.
|
||||
|
||||
@ -202,7 +202,7 @@ $(document).ready(function(){
|
||||
|
||||
Note that even though you reference a Bootstrap js script, Bootstrap's popovers require you to initialize them using the above code as well — they aren't turned on by default.
|
||||
|
||||
View the source code of the <a target="_blank" title="ToolTip Demo" href="{{ "/tooltip_demo.html" | prepend: site.baseurl }}">Tooltip Demo</a> for the full comments.
|
||||
View the source code of the <a class="noCrossRef" href="tooltip_demo.html">Tooltip Demo</a> for the full comments.
|
||||
|
||||
## 6. Create easy links to embed the help in your help site
|
||||
|
||||
|
||||
@ -3,14 +3,16 @@ title: Links
|
||||
audience: writer, designer
|
||||
tags: [formatting, navigation]
|
||||
keywords: links, hyperlinks, cross references, related links, relationship tables
|
||||
summary: "When creating links, although you can use standard HTML or Markdown, a better way to handle links is to store them as captured variables in an include file, and then reference the capture keywords for the links. This way you can update titles in one place, more easily identify broken links, and better manage your links. This approach is simliar to the keyref-style links in DITA."
|
||||
summary: "When creating links, although you can use standard HTML or Markdown, this approach is usually susceptible to a lot of errors and broken links. A better approach to handling links is to use references to a YML file."
|
||||
last_updated: August 12, 2015
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Link strategies
|
||||
|
||||
One of the more difficult parts of a documentation site is keeping all the internal links accurate and valid. Although there are many ways to create links, I'll just describe what I've found to work well.
|
||||
One of the more difficult parts of a documentation site is keeping all the internal links accurate and valid. When you're single sourcing, you usually have multiple documentation outputs that include certain pages for certain audiences. Orphan links are a common problem to avoid.
|
||||
|
||||
Although there are many ways to create links, I'll just describe what I've found to work well.
|
||||
|
||||
## Create an external link
|
||||
|
||||
@ -46,54 +48,89 @@ In my experience, coding links like this results in a lot of broken links.
|
||||
|
||||
## Managed links
|
||||
|
||||
For internal links, I've found that it's a best practice to store the link in an internal file so that I can easily update all references to the link.
|
||||
For internal links, I've found that it's a best practice to store the link in a YAML file that is derived from the table of contents.
|
||||
|
||||
In this theme, the \_includes folder contains a links_doc.html file where the capture tags are stored. For each link, I create the follow pair of capture tags:
|
||||
The theme has a file called urls.txt. This file contains the same code as the table of contents (but without the conditional qualifiers). It iterates through every page listed in the table of contents sidebar (as well as the top navigation menus) and creates an output that looks like this for each link:
|
||||
|
||||
```yaml
|
||||
{% raw %}
|
||||
doc_getting_started:
|
||||
title: "Getting started with this theme"
|
||||
url: "doc_getting_started.html"
|
||||
link: "<a href='doc_getting_started.html'>Getting started with this theme</a>"
|
||||
{% raw %}
|
||||
```
|
||||
|
||||
From the site output folder, open urls.txt and observe that it is properly populated (blank spaces between entries doesn't matter). Then manually copy the contents from the urls.txt and insert it into the urls.yml in your project folder.
|
||||
|
||||
Because the urls.txt is produced from the table of contents, you ensure that the same titles and URLs used in your table of contents and top navigation will also be used in your inline links.
|
||||
|
||||
To create a link in a topic, just reference the appropriate value in the urls.yml file, like this:
|
||||
|
||||
```html
|
||||
{%raw%}
|
||||
{% capture sample %}<a href="sample.html">Sample</a>{% endcapture %}
|
||||
{% capture sample_i %}<a href="sample.html">{% endcapture %}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
The linksref.html file includes the links_doc.html, so when you add `{% raw %}{% include linkrefs.html %}{% endraw %}` at the top of a page, it includes all of the link variables captured here.
|
||||
|
||||
To insert a link to sample, do this:
|
||||
|
||||
```liquid
|
||||
{% raw %}
|
||||
{{sample}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
If you want to insert the link with custom anchor text, use this:
|
||||
|
||||
```liquid
|
||||
{{site.data.urls.doc_getting_started.link}}
|
||||
{% raw %}
|
||||
See the {{sample_i}}sample page here{{end_i}}.
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
Make sure that the links_doc.html file also includes this capture at least once:
|
||||
This will insert the following into your topic:
|
||||
|
||||
```
|
||||
```html
|
||||
{% raw %}
|
||||
{% capture end_i %}</a>{% endcapture %}
|
||||
<a href='doc_getting_started.html'>Getting started with this theme</a>
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
Otherwise, your link won't close.
|
||||
You don't need to worry whether you can use Markdown syntax when inserting a link this way, because the insertion is HTML.
|
||||
|
||||
To insert a link in the context of a phrase, you can use this syntax:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
After downloading the theme, you can [get started in building the theme]({{site.data.urls.doc_getting_started.url}}).
|
||||
```
|
||||
|
||||
This leverages Markdown syntax. If you're in an HTML file or section, use this:
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
<p>After downloading the theme, you can <a href="{{site.data.urls.doc_getting_started.url}}">get started in building the theme</a>.</p>
|
||||
```
|
||||
|
||||
Note that the `url` value accesses the URL for the page only, whereas `link` gets the title and url in a link format.
|
||||
|
||||
You shouldn't have to copy the contents from the urls.txt file into your YAML data source too often — only when you're creating new pages.
|
||||
|
||||
By using this approach, you're less likely to end up with broken links.
|
||||
|
||||
## Always make sure your TOC page is accurate
|
||||
|
||||
You should treat your sidebar_doc.yml file with a lot of care. Every time you add a page to your site, make sure it's listed in your sidebar_doc.yml file (or in your top navigation). If you don't have pages listed in your sidebar_doc.yml file, they won't be included in the urls.txt file, and as your site grows, it will be harder to recognize pages that are absent from the TOC.
|
||||
|
||||
Because all the pages are stored in the root directory, the list of files can grow really long. I typically find pages by navigating to the page in the preview server, copying the page name (e.g., doc_hyperlinks), and then pressing **Shift + Shift** in WebStorm to locate the page. This is the only sane way to locate your pages when you have hundreds of pages in your root directory. If the page isn't listed in your TOC, it will be difficult to navigate to it and find it.
|
||||
|
||||
## Checking for broken links
|
||||
|
||||
Another way to ensure you don't have any broken links in your output is to [generate a PDF]({{site.data.urls.doc_generating_pdfs.url}}). When you generate a PDF, look for the following two problems in the output:
|
||||
|
||||
* page 0
|
||||
* see .
|
||||
|
||||
Both instances indicate a broken link. The "page 0" indicates that Prince XML couldn't find the page that the link points to, and so it can't create a cross reference. This may be because the page doesn't exist, or because the anchor is pointing to a missing location.
|
||||
|
||||
If you see "see ." it means that the reference (for example, `{% raw %}{{mylink...}}{% endraw %}` doesn't actually refer to anything. As a result, it's simply blank in the output.
|
||||
|
||||
{{site.data.alerts.note}} To keep Prince XML from trying to insert a cross reference into a link, add <code>class="noCrossRef"</code> to the link. {{site.data.alerts.end}}
|
||||
|
||||
## Relative link paths
|
||||
|
||||
The site is coded with relative links. There aren't any permalinks, urls, or baseurls. The folder structure you see in the project directory is the same folder directory that gets built in the site output.
|
||||
|
||||
Author all pages in your root directory. This greatly simplifies linking. However, when you're linking to images, files, or other content, you can put them in subfolders.
|
||||
Author all pages in your root directory. This greatly simplifies linking. However, when you're linking to images, files, or other content, you can put these assets into subfolders.
|
||||
|
||||
For example, to link to a file stored in files/doc/myguide.pdf, you would use "files/doc/myguide.pdf" as the link.
|
||||
For example, to link to a file stored in files/doc/whitepaper.pdf, you would use "files/doc/whitepaper.pdf" as the link.
|
||||
|
||||
Why not put pages into subfolders? If you put a page into a subfolder, then links to the stylesheets, JavaScript, and other sources will fail. On those sub-folder pages, you'd need to use `../` to move up a level in the directory. But if you have some pages in some folders, others in sub-sub-folders, and others in the root, trying to guess which files should contain `../` or `../../` or nothing at all and which shouldn't will be a nightmare.
|
||||
Why not put pages too into subfolders? If you put a page into a subfolder, then links to the stylesheets, JavaScript, and other sources will fail. On those sub-folder pages, you'd need to use `../` to move up a level in the directory to access the stylesheets, JavaScript, etc. But if you have some pages in folders on one level, others in sub-sub-folders, and others in the root, trying to guess which files should contain `../` or `../../` or nothing at all and which shouldn't will be a nightmare.
|
||||
|
||||
Jekyll gets around some of this link path variation by using `baseurl` and including code that prepends the `baseurl` before a link. This converts the links into absolute rather than relative links.
|
||||
|
||||
@ -101,9 +138,4 @@ With absolute links, the site only displays at the `baseurl` you configured. Thi
|
||||
|
||||
## Limitations with links
|
||||
|
||||
One of the shortcomings in this theme is that your links_doc.html file and your sidebar.yml file aren't generated from the same source. If you change a link title, you have to change it in both of these locations.
|
||||
|
||||
Another limitation is that a link to the page never gets the title of the page automatically.
|
||||
|
||||
If you have solutions for either of these issues, please let me know.
|
||||
|
||||
One of the shortcomings in this theme is that the link titles in the sidebar and inline links don't necessarily have to match the titles specified on each page. You have to manually keep the page titles in sync with the titles listed in the sidebar and top navigation. Although I could potentially get rid of the titles key in the article topic, it would make it more difficult to know what page you're editing.
|
||||
|
||||
51
doc_icons.md
51
doc_icons.md
@ -5,7 +5,6 @@ keywords: font icons, buttons, images, vectors, font awesome, glyphicons
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can integrate font icons through the Font Awesome and Glyphical Halflings libraries. These libraries allow you to embed icons through their libraries delivered as a link reference. You don't need any image libraries downloaded in your project."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
## Font icon options
|
||||
The theme has two font icon sets integrated: Font Awesome and Glyphicons Halflings. The latter is part of Bootstrap, while the former is independent. Font icons allow you to insert icons drawn as vectors from a CDN (so you don't have any local images on your own site).
|
||||
@ -46,35 +45,45 @@ Here's the result:
|
||||
|
||||
<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle fa-lg"></i> This is a special warning message.</div>
|
||||
|
||||
The notes, tips, warnings, etc., are pre-coded with Font Awesome and stored in the linkrefs.html file in `capture` tags. That file includes the following:
|
||||
The notes, tips, warnings, etc., are pre-coded with Font Awesome and stored in the alerts.yml file. That file includes the following:
|
||||
|
||||
{% raw %}
|
||||
```html
|
||||
{% capture tip %}<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip: </b>{% endcapture %}
|
||||
{% capture note %}<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note: </b>{% endcapture %}
|
||||
{% capture important %}<div class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> <b>Important: </b>{% endcapture %}
|
||||
{% capture warning %}<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>{% endcapture %}
|
||||
{% capture end %}</div>{% endcapture %}
|
||||
```yaml
|
||||
tip: '<div class="alert alert-success" role="alert"><i class="fa fa-check-square-o"></i> <b>Tip: </b>'
|
||||
note: '<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note: </b>'
|
||||
important: '<div class="alert alert-warning" role="alert"><i class="fa fa-warning"></i> <b>Important: </b>'
|
||||
warning: '<div class="alert alert-danger" role="alert"><i class="fa fa-exclamation-circle"></i> <b>Warning: </b>'
|
||||
end: '</div>'
|
||||
|
||||
callout_danger: '<div class="bs-callout bs-callout-danger">'
|
||||
callout_default: '<div class="bs-callout bs-callout-default">'
|
||||
callout_primary: '<div class="bs-callout bs-callout-primary">'
|
||||
callout_success: '<div class="bs-callout bs-callout-success">'
|
||||
callout_info: '<div class="bs-callout bs-callout-info">'
|
||||
callout_warning: '<div class="bs-callout bs-callout-warning">'
|
||||
|
||||
hr_faded: '<hr class="faded"/>'
|
||||
hr_shaded: '<hr class="shaded"/>'
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
This means you can insert a tip, note, warning, or important alert simply by using these tags:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{{note}} Add your note here. {{end}}
|
||||
```liquid
|
||||
{{site.data.alerts.note}} Add your note here. {{site.data.alerts.end}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Here's the result:
|
||||
|
||||
{{note}} Add your note here. {{end}}
|
||||
{{site.data.alerts.note}} Add your note here. {{site.data.alerts.end}}
|
||||
|
||||
{{tip}} Here's my tip. {{end}}
|
||||
{{site.data.alerts.tip}} Here's my tip. {{site.data.alerts.end}}
|
||||
|
||||
{{important}} This information is very important.{{end}}
|
||||
{{site.data.alerts.important}} This information is very important.{{site.data.alerts.end}}
|
||||
|
||||
{{warning}} If you overlook this, you may die. {{end}}
|
||||
{{site.data.alerts.warning}} If you overlook this, you may die. {{site.data.alerts.end}}
|
||||
|
||||
The color scheme is the default colors from Bootstrap. You can modify the icons or colors as needed.
|
||||
|
||||
@ -171,7 +180,7 @@ And here's the shortcode:
|
||||
|
||||
{% raw %}
|
||||
```
|
||||
{{callout_info}}<div class="bs-callout bs-callout-info">{{end}}
|
||||
{{site.data.alerts.callout_info}}<div class="bs-callout bs-callout-info">{{site.data.alerts.end}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
@ -179,13 +188,13 @@ You can use any of the following:
|
||||
{% raw %}
|
||||
```
|
||||
{{callout_danger}}
|
||||
{{callout_default}}
|
||||
{{callout_primary}}
|
||||
{{callout_success}}
|
||||
{{callout_info}}
|
||||
{{callout_warning}}
|
||||
{{site.data.alerts.callout_default}}
|
||||
{{site.data.alerts.callout_primary}}
|
||||
{{site.data.alerts.callout_success}}
|
||||
{{site.data.alerts.callout_info}}
|
||||
{{site.data.alerts.callout_warning}}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
Callouts are explained in a bit more detail here: {{doc_alerts}}.
|
||||
Callouts are explained in a bit more detail here: {{site.data.urls.doc_alerts.link}}.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: images, screenshots, vectors, svg, markdown syntax
|
||||
last_updated: August 12, 2015
|
||||
summary: "You embed images using traditional HTML or Markdown syntax for images. Unlike pages, you can store images in subfolders (in this theme). This is because when pages reference the images, the references are always as subpaths, never requiring the reference to move up directories."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
You embed an image the same way you embed other files or assets: you put the file into a folder, and then link to that file.
|
||||
|
||||
@ -50,7 +50,7 @@ Also, if you're working with SVG graphics, note that Firefox does not support SV
|
||||
|
||||
Also, remove the check box for "Use textpath element for text on a path". And select "Embed" rather than "Link." The following screenshot shows the settings I use. Your graphics will look great in Firefox.
|
||||
|
||||
<img src="{{ "images/illustratoroptions.png" | prepend: site.baseurl }}" alt="Essential options for SVG with Illustrator" />
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: iterm, terminal, build shortcuts, mac
|
||||
last_updated: August 12, 2015
|
||||
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."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About iTerm profiles
|
||||
|
||||
@ -36,4 +36,4 @@ Here's an example:
|
||||
1. In iTerm, make sure the Toolbar is shown. Go to **View > Toggle Toolbar**.
|
||||
2. Click the **New** button and select your profile.
|
||||
|
||||
{{tip}} When you're done with the session, make sure to click **Ctrl+C**.{{end}}
|
||||
{{site.data.alerts.tip}} When you're done with the session, make sure to click **Ctrl+C**.{{site.data.alerts.end}}
|
||||
@ -5,18 +5,18 @@ keywords: knowledge base, support portal, grid, doc portal
|
||||
last_updated: August 12, 2015
|
||||
summary: "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 can also add captions below each icon."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a href="doc_tag-getting-started.html"><i class="fa fa-file-image-o fa-6x border"></i><div class="kbCaption">Getting Started</div></a></div>
|
||||
<div class="col-md-4"><a href="doc_tag-navigation.html"><i class="fa fa-bar-chart-o fa-6x border"></i><div class="kbCaption">Navigation</a></div></div>
|
||||
<div class="col-md-4"><a href="doc_tag-single-sourcing.html"><i class="fa fa-code fa-6x border"></i><div class="kbCaption">Single-sourcing</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="doc_tag-getting-started.html"><i class="fa fa-file-image-o fa-6x border"></i><div class="kbCaption">Getting Started</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="doc_tag-navigation.html"><i class="fa fa-bar-chart-o fa-6x border"></i><div class="kbCaption">Navigation</a></div></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="doc_tag-single-sourcing.html"><i class="fa fa-code fa-6x border"></i><div class="kbCaption">Single-sourcing</div></a></div>
|
||||
</div>
|
||||
<p> </p>
|
||||
<div class="row">
|
||||
<div class="col-md-4"><a href="doc_tag-publishing.html"><i class="fa fa-dashboard fa-6x border"></i><div class="kbCaption">Publishing</div></a></div>
|
||||
<div class="col-md-4"><a href="doc_tag-special-layouts.html"><i class="fa fa-desktop fa-6x border"></i><div class="kbCaption">Special layouts</div></a></div>
|
||||
<div class="col-md-4"><a href="doc_tag-formatting.html"><i class="fa fa-cloud fa-6x border"></i><div class="kbCaption">Formatting</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="doc_tag-publishing.html"><i class="fa fa-dashboard fa-6x border"></i><div class="kbCaption">Publishing</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="doc_tag-special-layouts.html"><i class="fa fa-desktop fa-6x border"></i><div class="kbCaption">Special layouts</div></a></div>
|
||||
<div class="col-md-4"><a class="noCrossRef" href="doc_tag-formatting.html"><i class="fa fa-cloud fa-6x border"></i><div class="kbCaption">Formatting</div></a></div>
|
||||
</div>
|
||||
|
||||
## Generating a list of all pages with a certain tag
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: labels, buttons, bootstrap, api methods
|
||||
last_updated: August 12, 2015
|
||||
summary: "Labels are just a simple Bootstrap component that you can include in your pages as needed. They represent one of many Bootstrap options you can include in your theme."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About labels
|
||||
Labels might come in handy for adding button-like tags next to elements, such as POST, DELETE, UPDATE methods for endpoints. You can use any classes from Bootstrap in your content.
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: navigation tabs, hide sections, tabbers, interface tabs
|
||||
last_updated: August 12, 2015
|
||||
summary: "Navtabs provide a tab-based navagation directly in your content, allowing users to click from tab to tab to see different panels of content. Navtabs are especially helpful for showing code samples for different programming languages. The only downside to using navtabs is that you must use HTML instead of Markdown."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Common uses
|
||||
|
||||
@ -20,9 +20,9 @@ Navtabs are better for SEO since you avoid duplicate content and drive users to
|
||||
The following is a demo of a navtab. Refresh your page to see the tab you selected remain active.
|
||||
|
||||
<ul id="profileTabs" class="nav nav-tabs">
|
||||
<li class="active"><a href="#profile" data-toggle="tab">Profile</a></li>
|
||||
<li><a href="#about" data-toggle="tab">About</a></li>
|
||||
<li><a href="#match" data-toggle="tab">Match</a></li>
|
||||
<li class="active"><a class="noCrossRef" href="#profile" data-toggle="tab">Profile</a></li>
|
||||
<li><a class="noCrossRef" href="#about" data-toggle="tab">About</a></li>
|
||||
<li><a class="noCrossRef" href="#match" data-toggle="tab">Match</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div role="tabpanel" class="tab-pane active" id="profile">
|
||||
|
||||
10
doc_pages.md
10
doc_pages.md
@ -5,7 +5,7 @@ keywords: pages, authoring, exclusion, frontmatter
|
||||
last_updated: August 12, 2015
|
||||
summary: "This theme uses pages only, not posts. You need to make sure your pages have the appropriate frontmatter. One frontmatter tag your users might find helpful is the summary tag. This functions similar in purpose to the shortdesc element in DITA."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Where to author content
|
||||
Use a text editor such as Sublime Text, WebStorm, IntelliJ, or Atom to create pages.
|
||||
@ -40,7 +40,7 @@ last_updated: August 12, 2015
|
||||
summary: "Deploying DeviceInsight requires the following steps."
|
||||
{% endraw %}
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
```
|
||||
Frontmatter is always formatted with three hyphens at the top and bottom. Your frontmatter must have a `title` value. All the other values are optional.
|
||||
|
||||
@ -56,7 +56,7 @@ The following table describes each of the frontmatter that you can use with this
|
||||
| **datatable** | Optional | Boolean. If you add `true`, then scripts for the [jQuery datatables plugin](https://www.datatables.net/) get included on the page. |
|
||||
| **video** | Optional | If you add `true`, then scripts for [Video JS: The HTML5 video player](http://www.videojs.com/) get included 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. In other words, they degrade gracefully. {{end}}
|
||||
{{site.data.alerts.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. In other words, they degrade gracefully. {{site.data.alerts.end}}
|
||||
|
||||
## What about permalinks?
|
||||
What about permalinks? This theme isn't build using permalinks because it makes linking and directory structures problematic. Permalinks generate an index file inside a folder for each file in the output. This makes it so links (to other pages as well as to resources such as styles and scripts) need to include `../` depending upon where the other assets are located. But for any pages outside folders, such as the index.html page, you wouldn't use the `../` structure.
|
||||
@ -71,7 +71,7 @@ If you want to use a colon in your page title, you must enclose the title's valu
|
||||
|
||||
If you add `published: false` in the frontmatter, your page won't be published. You can also move draft pages into the _drafts folder to exclude them from the build.
|
||||
|
||||
{{tip}} You can create file templates in WebStorm that have all your common frontmatter, such as all possible tags, prepopulated. See {{doc_webstorm_text_editor}} for details. {{end}}
|
||||
{{site.data.alerts.tip}} You can create file templates in WebStorm that have all your common frontmatter, such as all possible tags, prepopulated. See {{site.data.urls.doc_webstorm_text_editor.link}} for details. {{site.data.alerts.end}}
|
||||
|
||||
## Markdown or HTML format
|
||||
|
||||
@ -110,7 +110,7 @@ These extensions mean the following:
|
||||
|
||||
You can also add "autolink" as an option if you want links such as http://google.com to automatically be converted into links.
|
||||
|
||||
{{note}} Make sure you leave the <code>with_toc_data</code> option included. This auto-creates an ID for each Markdown-formatted heading, which then gets injected into the mini-TOC. Without this auto-creation of IDs, the mini-TOC won't include the heading. If you ever use HTML formatting for headings, you need to manually add an ID attribute to the heading in order for the heading to appear in the mini-TOC. {{end}}
|
||||
{{site.data.alerts.note}} Make sure you leave the <code>with_toc_data</code> option included. This auto-creates an ID for each Markdown-formatted heading, which then gets injected into the mini-TOC. Without this auto-creation of IDs, the mini-TOC won't include the heading. If you ever use HTML formatting for headings, you need to manually add an ID attribute to the heading in order for the heading to appear in the mini-TOC. {{site.data.alerts.end}}
|
||||
|
||||
## Automatic mini-TOCs
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: AWS, Amazon, command line, pushing build
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can push your build to AWS using commands from the command line. By including your copy commands in commands, you can package all of the build and deploy process into executable scripts."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Pushing to AWS S3
|
||||
|
||||
|
||||
@ -6,10 +6,10 @@ tags: special-layouts
|
||||
last_updated: August 12, 2015
|
||||
summary: "This page demonstrates how you the integration of a script called ScrollTo, which is used here to link definitions of a JSON code sample to a list of definitions for that particular term. The scenario here is that the JSON blocks are really long, with extensive nesting and subnesting, which makes it difficult for tables below the JSON to adequately explain the term in a usable way."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
{% if site.print == true %}
|
||||
{{note}} The content on this page doesn't display well on PDF, but I included it anyway so you could see the problems this layout poses if you're including it in PDF. {{end}}
|
||||
{{site.data.alerts.note}} The content on this page doesn't display well on PDF, but I included it anyway so you could see the problems this layout poses if you're including it in PDF. {{site.data.alerts.end}}
|
||||
{% endif %}
|
||||
|
||||
{% if site.print == false %}
|
||||
@ -234,5 +234,5 @@ $('#small-box-links').localScroll({
|
||||
</div> <!-- end row -->
|
||||
</div> <!-- end container -->
|
||||
|
||||
{{note}} This was mostly an experiment to see if there was a better way to document a long JSON code example. I haven't actually used this approach in my own documentation.{{end}}
|
||||
{{site.data.alerts.note}} This was mostly an experiment to see if there was a better way to document a long JSON code example. I haven't actually used this approach in my own documentation.{{site.data.alerts.end}}
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: search, json, configuration, findability
|
||||
last_updated: August 12, 2015
|
||||
summary: "The search feature uses JavaScript to look for keyword matches in a JSON file. The results show instant matches, but it doesn't provide a search results page like Google. Also, sometimes invalid formatting can break the JSON file."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
@ -5,10 +5,10 @@ keywords: series, connected articles, tutorials, hello world
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can automatically link together topics belonging to the same series. This helps users know the context within a particular process."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Using series for pages
|
||||
You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a demo: {{doc_seriesdemo1_1}}.
|
||||
You create a series by looking for all pages within a tag namespace that contain certain frontmatter. Here's a <a href="doc_seriesdemo1_0.html" class="noCrossRef">demo</a>.
|
||||
|
||||
## 1. Create the series button
|
||||
|
||||
@ -98,4 +98,4 @@ On each series page, add a link to the series button at the top and a link to th
|
||||
|
||||
## Changing the series drop-down color
|
||||
|
||||
The Bootstrap menu uses the `primary` class for styling. If you change this class in your theme, the Bootstrap menu should automatically change color as well. You can also just use another Bootstrap class in your button code. Instead of `btn-primary`, use `btn-info` or `btn-warning`. See {{doc_labels}} for more Bootstrap button classes.
|
||||
The Bootstrap menu uses the `primary` class for styling. If you change this class in your theme, the Bootstrap menu should automatically change color as well. You can also just use another Bootstrap class in your button code. Instead of `btn-primary`, use `btn-info` or `btn-warning`. See {{site.data.urls.doc_labels.link}} for more Bootstrap button classes.
|
||||
@ -5,7 +5,7 @@ series: "ACME series"
|
||||
weight: 1.0
|
||||
last_updated: August 12, 2015
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
{% include custom/doc/series_acme.html %}
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ series: "ACME series"
|
||||
weight: 1.1
|
||||
last_updated: August 12, 2015
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
{% include custom/doc/series_acme.html %}
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ series: "ACME series"
|
||||
weight: 1.2
|
||||
last_updated: August 12, 2015
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
{% include custom/doc/series_acme.html %}
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ series: "ACME series"
|
||||
weight: 1.3
|
||||
last_updated: August 12, 2015
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
{% include custom/doc/series_acme.html %}
|
||||
|
||||
|
||||
@ -5,10 +5,10 @@ last_updated: August 12, 2015
|
||||
keywords: shuffle, card layout, dynamic grid, doc portal, support portal
|
||||
summary: "This layout shows an example of a knowledge-base style navigation system, where there is no hierarchy, just groups of pages that have certain tags."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
{% if site.print == true %}
|
||||
{{note}} The content on this page doesn't display well on PDF, but I included it anyway so you could see the problems this layout poses if you're including it in PDF. {{end}}
|
||||
{{site.data.alerts.note}} The content on this page doesn't display well on PDF, but I included it anyway so you could see the problems this layout poses if you're including it in PDF. {{site.data.alerts.end}}
|
||||
{% endif %}
|
||||
|
||||
{% unless site.print == true %}
|
||||
@ -39,7 +39,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "getting-started" %}
|
||||
<li><a href="{{page.url}}">{{page.title}}</a></li>
|
||||
<li><a href="{{page.url | replace: '/',''}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
@ -60,7 +60,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "content-types" %}
|
||||
<li><a href="{{page.url}}">{{page.title}}</a></li>
|
||||
<li><a href="{{page.url | replace: '/',''}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
@ -79,15 +79,13 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
|
||||
<div class="panel-body">
|
||||
These topics get into formatting syntax, such as images and tables, that you'll use on each of your pages:
|
||||
<ul>
|
||||
<ul>
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "formatting" %}
|
||||
<li><a href="{{page.url}}">{{page.title}}</a></li>
|
||||
<li><a href="{{page.url | replace: '/',''}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
@ -103,7 +101,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "single-sourcing" %}
|
||||
<li><a href="{{page.url}}">{{page.title}}</a></li>
|
||||
<li><a href="{{page.url | replace: '/',''}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
@ -122,7 +120,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "publishing" %}
|
||||
<li><a href="{{page.url}}">{{page.title}}</a></li>
|
||||
<li><a href="{{page.url | replace: '/',''}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
@ -142,7 +140,7 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
|
||||
{% for page in site.pages %}
|
||||
{% for tag in page.tags %}
|
||||
{% if tag == "special-layouts" %}
|
||||
<li><a href="{{page.url}}">{{page.title}}</a></li>
|
||||
<li><a href="{{page.url | replace: '/',''}}">{{page.title}}</a></li>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
@ -161,6 +159,6 @@ summary: "This layout shows an example of a knowledge-base style navigation syst
|
||||
{% include initialize_shuffle.html %}
|
||||
{% endunless %}
|
||||
|
||||
{{note}} This was mostly an experiment to see if I could break away from the hierarchical TOC and provide a different way of arranging the content. However, this layout is somewhat problematic because it doesn't allow you to browse other navigation options on the side while viewing a topic.{{end}}
|
||||
{{site.data.alerts.note}} This was mostly an experiment to see if I could break away from the hierarchical TOC and provide a different way of arranging the content. However, this layout is somewhat problematic because it doesn't allow you to browse other navigation options on the side while viewing a topic.{{site.data.alerts.end}}
|
||||
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: sidebar, toc, table of contents, navigation
|
||||
last_updated: August 12, 2015
|
||||
summary: "The sidebar and top navigation bar read their values from yml files. The navigation components are one of the most unique parts of this theme, since the navigation components are only included if they meet all of the product, audience, version, etc., values as specified in the project settings."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Sidebar overview
|
||||
|
||||
|
||||
@ -5,24 +5,24 @@ keywords: layouts, information design, presentation
|
||||
last_updated: August 12, 2015
|
||||
summary: "This theme has a few special layouts. Special layouts include the JS files they need directly in the page. The JavaScript for each special layout does not load by default for every page in the site."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
{{note}} By "layout," I'm not referring to the layouts in \_layouts in the project files. I'm referring to special ways of presenting information on the same "page" layout. {{end}}
|
||||
|
||||
{{site.data.alerts.note}} By "layout," I'm not referring to the layouts in \_layouts in the project files. I'm referring to special ways of presenting information on the same "page" layout. {{site.data.alerts.end}}
|
||||
|
||||
## FAQ layout
|
||||
|
||||
See {{doc_faq}} for an example of the FAQ format, which follows an accordion, collapse/expand format. This code is from Bootstrap.
|
||||
See {{site.data.urls.doc_faq.link}} for an example of the FAQ format, which follows an accordion, collapse/expand format. This code is from Bootstrap.
|
||||
|
||||
## Knowledgebase layout
|
||||
|
||||
See {{doc_kb_layout}} for a possible layout for knowledge base articles. This layout looks for pages containing specific tags.
|
||||
See {{site.data.urls.doc_kb_layout.link}} for a possible layout for knowledge base articles. This layout looks for pages containing specific tags.
|
||||
|
||||
## Scroll layout
|
||||
|
||||
If you have a long JSON message you're documenting, see the {{doc_scroll}}. This layout adds a side pane showing links to pointers in the left pane.
|
||||
If you have a long JSON message you're documenting, see the {{site.data.urls.doc_scroll.link}}. This layout adds a side pane showing links to pointers in the left pane.
|
||||
|
||||
## Shuffle layout
|
||||
|
||||
If you want a dynamic card layout that allows you to filter the cards, see {{doc_shuffle}}. This uses the Shuffle JS library.
|
||||
If you want a dynamic card layout that allows you to filter the cards, see {{site.data.urls.doc_shuffle.link}}. This uses the Shuffle JS library.
|
||||
|
||||
|
||||
|
||||
@ -5,6 +5,6 @@ keywords: questions, troubleshooting, contact, support
|
||||
last_updated: August 12, 2015
|
||||
summary: "Contact me for any support issues."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
I'm actively developing this theme. Please let me know about any bugs or other issues that you find. Just email me at <a href="mailto:tomjohnson1492@gmail.com">tomjohnson1492@gmail.com</a>. You can also [create issues directly within the Github repository here](https://github.com/tomjohnson1492/jekyll-doc/issues).
|
||||
@ -5,7 +5,7 @@ keywords: features, capabilities, scalability, multichannel output, dita, hats,
|
||||
last_updated: August 12, 2015
|
||||
summary: "If you're not sure whether Jekyll and this theme will support your requirements, this list provides a semi-comprehensive overview of available features."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
Before you get into exploring Jekyll as a potential platform for help content, you may be wondering if it supports some basic features. The following table shows what is supported in Jekyll and this theme.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: rouge, pygments, prettify, color coding,
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can apply syntax highlighting to your code. This theme uses pygments and applies color coding based on the lexer you specify."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About syntax highlighting
|
||||
For syntax highlighting, use fenced code blocks optionally followed by the language syntax you want:
|
||||
@ -63,6 +63,7 @@ The keywords you must add to specify the highlighting (in the previous example,
|
||||
|
||||
* js
|
||||
* html
|
||||
* yaml
|
||||
* css
|
||||
* json
|
||||
* php
|
||||
|
||||
@ -6,7 +6,7 @@ last_updated: August 12, 2015
|
||||
datatable: true
|
||||
summary: "You can format tables using either multimarkdown syntax or HTML. You can also use jQuery datatables (a plugin) if you need more robust tables."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
{% unless site.print == true %}
|
||||
<script>
|
||||
@ -160,4 +160,4 @@ Notice a few features:
|
||||
|
||||
Read more of the [datatable documentation](https://www.datatables.net/manual/options) to get a sense of the options you can configure. You should probably only use datatables when you have long, massive tables full of information.
|
||||
|
||||
{{note}} Try to keep the columns to 3 or 4 columns only. If you add 5+ columns, your table may create horizontal scrolling with the theme.{{end}}
|
||||
{{site.data.alerts.note}} Try to keep the columns to 3 or 4 columns only. If you add 5+ columns, your table may create horizontal scrolling with the theme.{{site.data.alerts.end}}
|
||||
15
doc_tags.md
15
doc_tags.md
@ -6,7 +6,7 @@ last_updated: August 12, 2015
|
||||
keywords: tags, navigation, buttons, links, association
|
||||
summary: "Tags provide another means of navigation for your content. Unlike the table of contents, tags can show the content in a variety of arrangements and groupings. Implementing tags in this Jekyll theme is somewhat of a manual process."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Add a tag to a page
|
||||
You can add tags to pages by adding `tags` in the frontmatter with values inside brackets, like this:
|
||||
@ -21,13 +21,13 @@ tags: [formatting, single-sourcing]
|
||||
|
||||
## Tags overview
|
||||
{% if site.audience == "designers" %}
|
||||
{{note}} With posts, tags have a namespace that you can access with <code>posts.tags.tagname</code>, where <code>tagname</code> is the name of the tag. You can then list all posts in that tag namespace. But pages don't off this same tag namespace, so you could actually use another key instead of <code>tags</code>. Nevertheless, I'm using the same <code>tags</code> name here.{{end}}
|
||||
{{site.data.alerts.note}} With posts, tags have a namespace that you can access with <code>posts.tags.tagname</code>, where <code>tagname</code> is the name of the tag. You can then list all posts in that tag namespace. But pages don't off this same tag namespace, so you could actually use another key instead of <code>tags</code>. Nevertheless, I'm using the same <code>tags</code> name here.{{site.data.alerts.end}}
|
||||
{% endif %}
|
||||
|
||||
To prevent tags from getting out of control and inconsistent, first make sure the tag appears in the \date/tags_doc.yml file. If it's not there, the tag you add to a page won't be read. I added this check just to make sure I'm using the same tags consistently and not adding new tags that don't have tag archive pages.
|
||||
|
||||
{% if site.audience == "designers" %}
|
||||
{{note}} Unlike with WordPress, you have to build out the functionality for tags so that clicking a tag name shows you all pages with that tag. Tags in Jekyll are much more manual.{{end}}
|
||||
{{site.data.alerts.note}} Unlike with WordPress, you have to build out the functionality for tags so that clicking a tag name shows you all pages with that tag. Tags in Jekyll are much more manual.{{site.data.alerts.end}}
|
||||
{% endif %}
|
||||
|
||||
Additionally, you must create a tag archive page similar to the other pages named doc_tag-{tagname}.html folder. This theme doesn't auto-create tag archive pages.
|
||||
@ -75,7 +75,7 @@ Tags have a few components.
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
{{note}}In the \_includes folder, there's a taglogic.html file. This file (included in each tag archive file) has common logic for getting the tags and listing out the pages containing the tag in a table with summaries or truncated excerpts. You don't have to do anything with the file — just leave it there because the tag archive pages reference it.{{end}}
|
||||
{{site.data.alerts.note}}In the \_includes folder, there's a taglogic.html file. This file (included in each tag archive file) has common logic for getting the tags and listing out the pages containing the tag in a table with summaries or truncated excerpts. You don't have to do anything with the file — just leave it there because the tag archive pages reference it.{{site.data.alerts.end}}
|
||||
|
||||
5. Adjust button color or tag placement as desired.
|
||||
|
||||
@ -104,7 +104,7 @@ Tags have a few components.
|
||||
{% include custom/conditions.html %}
|
||||
{% for tag in page.tags %}
|
||||
{% if projectTags contains tag %}
|
||||
<a href="{{site.project}}_tag-{{tag}}.html"><button type="button" class="btn btn-info navbar-btn cursorNorm">{{page.tagName}}{{tag}}</button></a>{% unless forloop.last %}{% endunless%}
|
||||
<a class="noCrossRef" href="{{site.project}}_tag-{{tag}}.html"><button type="button" class="btn btn-info navbar-btn cursorNorm">{{page.tagName}}{{tag}}</button></a>{% unless forloop.last %}{% endunless%}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
@ -112,13 +112,12 @@ Tags have a few components.
|
||||
|
||||
Because this code appears on the \_layouts/page.html file by default, you don't need to do anything. However, if you want to alter the placement or change the button color, you can do so.
|
||||
|
||||
You can change the button color by changing the class on the button from `btn-info` to one of the other button classes bootstrap provides. See {{doc_labels}} for more options on button class names.
|
||||
You can change the button color by changing the class on the button from `btn-info` to one of the other button classes bootstrap provides. See {{site.data.urls.doc_labels.link}} for more options on button class names.
|
||||
|
||||
## Retrieving pages for a specific tag
|
||||
|
||||
If you want to retrieve pages outside of a particular doc_tag-archive page, you could use this code:
|
||||
|
||||
|
||||
```html
|
||||
{% raw %}
|
||||
Getting started pages:
|
||||
@ -201,5 +200,5 @@ If you don't want tags to appear at all on your page, remove the tags property f
|
||||
|
||||
Since you may have many tags and find it difficult to remember what tags are allowed, I recommend creating a template that prepopulates all your frontmatter with all possible tags. Then just remove the tags that don't apply.
|
||||
|
||||
See {{doc_webstorm_text_editor}} for tips on creating file templates in WebStorm.
|
||||
See {{site.data.urls.doc_webstorm_text_editor.link}} for tips on creating file templates in WebStorm.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: themes, styles, colors, css
|
||||
last_updated: August 12, 2015
|
||||
summary: "You can choose between two different themes (one green, the other blue) for your projects. The theme CSS is stored in the CSS folder and configured in the configuration file for each project."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Theme options
|
||||
You can choose a green or blue theme, or you can create your own. In the css folder, there are two theme files: theme-blue.css and theme-green.css. These files have the most common CSS elements extracted in their own CSS file. Just change the hex colors to the ones you want.
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: bootstrap, lists, drop-down, drop down navigation, top nav bar, topnav
|
||||
last_updated: August 12, 2015
|
||||
summary: "The top navigation provides either single links or a drop-down menu. There are some other features, such as a feedback email, custom menu, and popout link."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Changing the top navigation
|
||||
|
||||
@ -34,13 +34,11 @@ Included in the topnav.html file is an include to /doc/customMenu.html. The code
|
||||
<li {% if site.audience == "designers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../doc_designers/{{site.suffix}}">Designer doc</a> {% else %} ../doc_designers{{page.url}}">Designer docs</a>{% endif %}</li>
|
||||
```
|
||||
|
||||
{{note}} In the theme, the link to the customMenu.html include in the \_includes/topnav.html file is currently commented out. This is because this feature only works when you have multiple outputs hosted on the same server. Github Pages, where I'm publishing this theme, allows only one output per Github Pages directory. So rather than removing this customMenu feature from the theme, I've just commented it out so that it won't appear broken in the demo.{{end}}
|
||||
{{site.data.alerts.note}} In the theme, the link to the customMenu.html include in the \_includes/topnav.html file is currently commented out. This is because this feature only works when you have multiple outputs hosted on the same server. Github Pages, where I'm publishing this theme, allows only one output per Github Pages directory. So rather than removing this customMenu feature from the theme, I've just commented it out so that it won't appear broken in the demo.{{site.data.alerts.end}}
|
||||
|
||||
The current doc site is highlighted. If you select another doc site, the site switches to that doc site and goes to the same page on that doc site. This way, if you have a task such as "Configuring the license" in several different programming languages, users can switch to other programming languages to see the same page.
|
||||
|
||||
You need to have both the designers and writers sites deployed on a web server to see this in action. Go to the following link: <a href="http://idratherbetellingstories.com/documentation-theme-jekyll/doc_designers/" target="_blank">idratherbetellingstories.com/documentation-theme-jekyll/doc_designers/</a>.
|
||||
|
||||
Browse to any page in the navigation. Then go to the **Custom Menu** and select the **Writers** site. You'll go to the exact same page but on the Writers site.
|
||||
You need to have both the designers and writers sites deployed on a web server to see this in action. Once deployed, browse to any page in the navigation. Then go to the **Custom Menu** and select the **Writers** site. You'll go to the exact same page but on the Writers site.
|
||||
|
||||
If your current page doesn't have an equivalent in your other outputs, then put this in the frontmatter of the page:
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ keywords: trouble, problems, support, error messages, problems, failure, error,
|
||||
last_updated: August 12, 2015
|
||||
summary: "This page lists common errors and the steps needed to troubleshoot them."
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## Issues building the site
|
||||
|
||||
@ -56,7 +56,7 @@ chmod +x build_writer.sh
|
||||
|
||||
### Pygments not installed
|
||||
|
||||
The config file requires pygments for the highlighter. You must [download and install Pygments]([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`.
|
||||
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`.
|
||||
|
||||
### "page 0" cross references in the PDF
|
||||
|
||||
@ -76,7 +76,7 @@ The config file requires pygments for the highlighter. You must [download and in
|
||||
|
||||
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.
|
||||
|
||||
{{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.{{end}}
|
||||
{{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 has the right product, platform, audience, and version, then it gets displayed in the sidebar. If not, it get skipped.
|
||||
|
||||
|
||||
@ -6,7 +6,7 @@ last_updated: August 12, 2015
|
||||
summary: "You can embed files with a Video JS wrapper by adding 'video: true' in the frontmatter. Alternatively, you can just fall back on the default video wrapper in the browser."
|
||||
video: true
|
||||
---
|
||||
{% include linkrefs.html %}
|
||||
|
||||
|
||||
## About Video JS
|
||||
The theme has the [video.js](http://www.videojs.com/) player integrated. But the scripts only appear on a page or post if you have certain frontmatter in that page or post. If you want to embed a video in a page and use the Video JS player, add `video: true` in your frontmatter of a page or post, and then add code like this where you want the video to appear:
|
||||
@ -43,4 +43,4 @@ Your browser does not support the video tag.
|
||||
|
||||
However, I don't think the built-in browser video players work very well (you can't easily scrub around the video without seeing lots of buffering and other issues). But definitely compare the two. You may find that adding the Video JS wrapper is overkill.
|
||||
|
||||
{{warning}}Github wasn't designed to store video content. If you have an mp3 file, don't store it in your Github directory. Instead, put it on a web host using regular FTP methods, or stream the video from a video streaming service such as Youtube or Vimeo. Also, note that Github's Large File Storage (which does handle large files) isn't compatible with Github Pages.{{end}}
|
||||
{{site.data.alerts.warning}}Github wasn't designed to store video content. If you have an mp3 file, don't store it in your Github directory. Instead, put it on a web host using regular FTP methods, or stream the video from a video streaming service such as Youtube or Vimeo. Also, note that Github's Large File Storage (which does handle large files) isn't compatible with Github Pages.{{site.data.alerts.end}}
|
||||
@ -35,7 +35,7 @@ Since you'll be writing in Markdown, having color coding and other support for M
|
||||
| Command + 2 | Show Favorites pane |
|
||||
| Shift + Option + F | Add to Favorites |
|
||||
|
||||
{{tip}} If these shortcut keys aren't working for you, make sure you have the "Max OS X 10.5+" keymap selected. Go to <b>WebStorm > Preferences > Keymap</b> and select it there. {{end}}
|
||||
{{site.data.alerts.tip}} If these shortcut keys aren't working for you, make sure you have the "Max OS X 10.5+" keymap selected. Go to <b>WebStorm > Preferences > Keymap</b> and select it there. {{site.data.alerts.end}}
|
||||
|
||||
## Identifying changed files
|
||||
|
||||
|
||||
13197
doc_writers_pdf.pdf
13197
doc_writers_pdf.pdf
File diff suppressed because it is too large
Load Diff
39
index.md
39
index.md
@ -4,7 +4,40 @@ tags: [getting-started]
|
||||
type: first_page
|
||||
homepage: true
|
||||
---
|
||||
{% if site.project == "doc_designers" %}
|
||||
{% include custom/doc/doc_homepage.md %}
|
||||
{% endif %}
|
||||
## Overview
|
||||
|
||||
This site provides documentation, training, and other notes for the Jekyll Documentation theme. There's a lot of information about how to do a variety of things here, and it's not all unique to this theme. But by and large, understanding how to do things in Jekyll depends on how your theme is coded.
|
||||
|
||||
## Survey of features
|
||||
|
||||
Some of the more prominent features of this theme include the following:
|
||||
|
||||
* Bootstrap framework
|
||||
* Sidebar with page hierarchy and advanced toc
|
||||
* PDF generation (with Prince XML utility)
|
||||
* Notes, tips, and warning information notes
|
||||
* Tags
|
||||
* Single sourced outputs
|
||||
* Emphasis on pages, not posts
|
||||
* Relative (rather than absolute) link structure
|
||||
|
||||
I'm using this theme for my documentation projects, building about 15 different outputs for various products, versions, languages, and audiences from the same set of files. This single sourcing requirement has influenced how I constructed this theme.
|
||||
|
||||
For more discussion about the available features, see {{site.data.urls_d.doc_supported_features.link}}.
|
||||
|
||||
## Getting started
|
||||
|
||||
To get started, see these three topics:
|
||||
|
||||
1. {{site.data.urls.doc_getting_started.link}}
|
||||
2. {{site.data.urls.doc_configuration_settings.link}}
|
||||
3. {{site.data.urls.doc_customizing_the_theme.link}}
|
||||
|
||||
## PDF Download
|
||||
|
||||
If you would like to download this help file as a PDF, you can do so here. The PDF most of the same content as the online help, except that some elements (such as video or special layouts) don't translate the the print medium, so they're excluded.
|
||||
|
||||
<a target="_blank" class="noCrossRef" href="doc_{{site.audience}}_pdf.pdf"><button type="button" class="btn btn-default" aria-label="Left Align"><span class="glyphicon glyphicon-download-alt" aria-hidden="true"></span> PDF Download</button></a>
|
||||
|
||||
The PDF contains a timestamp in the header indicating when it was last generated. If you download a PDF, keep in mind that it may go out of date quickly. Always compare your PDF timestamp against the online help timestamp (which you can find in the footer).
|
||||
|
||||
|
||||
49
urls.txt
Normal file
49
urls.txt
Normal file
@ -0,0 +1,49 @@
|
||||
---
|
||||
layout: none
|
||||
search: exclude
|
||||
---
|
||||
{% include custom/conditions.html %}
|
||||
|
||||
{% for entry in sidebar %}
|
||||
{% for subcategory in entry.subcategories %}
|
||||
{% for item in subcategory.items %}
|
||||
{{item.url | replace: "/","" | replace: ".html", ""}}:
|
||||
title: "{{item.title}}"
|
||||
url: "{{item.url | replace: '/','' }}"
|
||||
link: "<a href='{{item.url | replace: "/","" }}'>{{item.title}}</a>"
|
||||
{% for thirdlevel in item.thirdlevel %}
|
||||
{% for deeplevel in thirdlevel.thirdlevelitems %}
|
||||
{{deeplevel.url | replace: "/","" | replace: ".html", ""}}:
|
||||
title: "{{deeplevel.title}}"
|
||||
url: "{{deeplevel.url | replace: '/','' }}"
|
||||
link: "<a href='{{deeplevel.url | replace: "/","" }}'>{{deeplevel.title}}</a>"
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
|
||||
|
||||
{% for entry in topnav %}
|
||||
{% for subcategory in entry.subcategories %}
|
||||
{% unless subcategory.external_url %}
|
||||
{{subcategory.url | replace: "/","" | replace: ".html", ""}}:
|
||||
title: "{{subcategory.title}}"
|
||||
url: "{{subcategory.url | replace: '/','' }}"
|
||||
link: "<a href='{{subcategory.url | replace: "/","" }}'>{{subcategory.title}}</a>"
|
||||
{% endunless %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
|
||||
{% for entry in topnav_dropdowns %}
|
||||
{% for subcategory in entry.subcategories %}
|
||||
{% for subitem in subcategory.items %}
|
||||
{% unless subitem.external_url %}
|
||||
{{subitem.url | replace: "/","" | replace: ".html", ""}}:
|
||||
title: "{{subitem.title}}"
|
||||
url: "{{subitem.url | replace: '/','' }}"
|
||||
link: "<a href='{{subitem.url | replace: "/","" }}'>{{subitem.title}}</a>"
|
||||
{% endunless %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
Loading…
x
Reference in New Issue
Block a user