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

fixing sidebar title issue, also added more links and refinement to getting started page in doc

Browse Source
This commit is contained in:
tomjohnson1492 2016-03-23 10:21:15 -07:00
parent f5c8872d2f
commit 8c4de1ce49
6 changed files with 252 additions and 246 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
_data/sidebars/mydoc_sidebar.yml
View File

@ -25,6 +25,7 @@ entries:
- title: Get started
url: /
type: homepage
output: web, pdf
- title: 5.0 Release notes

340
_data/urls.yml
View File

@ -4,43 +4,38 @@
mydoc_release_notes_50:
title: "5.0 Release notes"
url: "/documentation-theme-jekyll/mydoc_release_notes_50/"
link: "<a href='/documentation-theme-jekyll/mydoc_release_notes_50/'>5.0 Release notes</a>"
mydoc_introduction:
title: "Introduction"
url: "mydoc_introduction"
link: "<a href='/mydoc_introduction/'>Introduction</a>"
url: "/documentation-theme-jekyll/mydoc_introduction/"
link: "<a href='/documentation-theme-jekyll/mydoc_introduction/'>Introduction</a>"
mydoc_supported_features:
title: "Supported features"
url: "mydoc_supported_features"
link: "<a href='/mydoc_supported_features/'>Supported features</a>"
mydoc_getting_started:
title: "Get started"
url: "mydoc_getting_started"
link: "<a href='/mydoc_getting_started/'>Get started</a>"
url: "/documentation-theme-jekyll/mydoc_supported_features/"
link: "<a href='/documentation-theme-jekyll/mydoc_supported_features/'>Supported features</a>"
mydoc_about:
title: "About the theme author"
url: "mydoc_about"
link: "<a href='/mydoc_about/'>About the theme author</a>"
url: "/documentation-theme-jekyll/mydoc_about/"
link: "<a href='/documentation-theme-jekyll/mydoc_about/'>About the theme author</a>"
mydoc_support:
title: "Support"
url: "mydoc_support"
link: "<a href='/mydoc_support/'>Support</a>"
url: "/documentation-theme-jekyll/mydoc_support/"
link: "<a href='/documentation-theme-jekyll/mydoc_support/'>Support</a>"
@ -48,43 +43,43 @@ mydoc_support:
mydoc_pages:
title: "Pages"
url: "mydoc_pages"
link: "<a href='/mydoc_pages/'>Pages</a>"
url: "/documentation-theme-jekyll/mydoc_pages/"
link: "<a href='/documentation-theme-jekyll/mydoc_pages/'>Pages</a>"
mydoc_posts:
title: "Posts"
url: "mydoc_posts"
link: "<a href='/mydoc_posts/'>Posts</a>"
url: "/documentation-theme-jekyll/mydoc_posts/"
link: "<a href='/documentation-theme-jekyll/mydoc_posts/'>Posts</a>"
mydoc_webstorm_text_editor:
title: "WebStorm Text Editor"
url: "mydoc_webstorm_text_editor"
link: "<a href='/mydoc_webstorm_text_editor/'>WebStorm Text Editor</a>"
url: "/documentation-theme-jekyll/mydoc_webstorm_text_editor/"
link: "<a href='/documentation-theme-jekyll/mydoc_webstorm_text_editor/'>WebStorm Text Editor</a>"
mydoc_conditional_logic:
title: "Conditional logic"
url: "mydoc_conditional_logic"
link: "<a href='/mydoc_conditional_logic/'>Conditional logic</a>"
url: "/documentation-theme-jekyll/mydoc_conditional_logic/"
link: "<a href='/documentation-theme-jekyll/mydoc_conditional_logic/'>Conditional logic</a>"
mydoc_content_reuse:
title: "Content reuse"
url: "mydoc_content_reuse"
link: "<a href='/mydoc_content_reuse/'>Content reuse</a>"
url: "/documentation-theme-jekyll/mydoc_content_reuse/"
link: "<a href='/documentation-theme-jekyll/mydoc_content_reuse/'>Content reuse</a>"
mydoc_collections:
title: "Collections"
url: "mydoc_collections"
link: "<a href='/mydoc_collections/'>Collections</a>"
url: "/documentation-theme-jekyll/mydoc_collections/"
link: "<a href='/documentation-theme-jekyll/mydoc_collections/'>Collections</a>"
@ -92,29 +87,29 @@ mydoc_collections:
mydoc_sidebar_navigation:
title: "Sidebar navigation"
url: "mydoc_sidebar_navigation"
link: "<a href='/mydoc_sidebar_navigation/'>Sidebar navigation</a>"
url: "/documentation-theme-jekyll/mydoc_sidebar_navigation/"
link: "<a href='/documentation-theme-jekyll/mydoc_sidebar_navigation/'>Sidebar navigation</a>"
mydoc_yaml_tutorial:
title: "YAML tutorial in the context of Jekyll"
url: "mydoc_yaml_tutorial"
link: "<a href='/mydoc_yaml_tutorial/'>YAML tutorial in the context of Jekyll</a>"
url: "/documentation-theme-jekyll/mydoc_yaml_tutorial/"
link: "<a href='/documentation-theme-jekyll/mydoc_yaml_tutorial/'>YAML tutorial in the context of Jekyll</a>"
mydoc_tags:
title: "Tags"
url: "mydoc_tags"
link: "<a href='/mydoc_tags/'>Tags</a>"
url: "/documentation-theme-jekyll/mydoc_tags/"
link: "<a href='/documentation-theme-jekyll/mydoc_tags/'>Tags</a>"
mydoc_series:
title: "Series"
url: "mydoc_series"
link: "<a href='/mydoc_series/'>Series</a>"
url: "/documentation-theme-jekyll/mydoc_series/"
link: "<a href='/documentation-theme-jekyll/mydoc_series/'>Series</a>"
@ -122,71 +117,64 @@ mydoc_series:
mydoc_adding_tooltips:
title: "Tooltips"
url: "mydoc_adding_tooltips"
link: "<a href='/mydoc_adding_tooltips/'>Tooltips</a>"
url: "/documentation-theme-jekyll/mydoc_adding_tooltips/"
link: "<a href='/documentation-theme-jekyll/mydoc_adding_tooltips/'>Tooltips</a>"
mydoc_alerts:
title: "Alerts"
url: "mydoc_alerts"
link: "<a href='/mydoc_alerts/'>Alerts</a>"
url: "/documentation-theme-jekyll/mydoc_alerts/"
link: "<a href='/documentation-theme-jekyll/mydoc_alerts/'>Alerts</a>"
mydoc_icons:
title: "Icons"
url: "mydoc_icons"
link: "<a href='/mydoc_icons/'>Icons</a>"
url: "/documentation-theme-jekyll/mydoc_icons/"
link: "<a href='/documentation-theme-jekyll/mydoc_icons/'>Icons</a>"
mydoc_images:
title: "Images"
url: "mydoc_images"
link: "<a href='/mydoc_images/'>Images</a>"
url: "/documentation-theme-jekyll/mydoc_images/"
link: "<a href='/documentation-theme-jekyll/mydoc_images/'>Images</a>"
mydoc_labels:
title: "Labels"
url: "mydoc_labels"
link: "<a href='/mydoc_labels/'>Labels</a>"
url: "/documentation-theme-jekyll/mydoc_labels/"
link: "<a href='/documentation-theme-jekyll/mydoc_labels/'>Labels</a>"
mydoc_hyperlinks:
title: "Links"
url: "mydoc_hyperlinks"
link: "<a href='/mydoc_hyperlinks/'>Links</a>"
url: "/documentation-theme-jekyll/mydoc_hyperlinks/"
link: "<a href='/documentation-theme-jekyll/mydoc_hyperlinks/'>Links</a>"
mydoc_navtabs:
title: "Navtabs"
url: "mydoc_navtabs"
link: "<a href='/mydoc_navtabs/'>Navtabs</a>"
mydoc_video_embeds:
title: "Video embeds"
url: "mydoc_video_embeds"
link: "<a href='/mydoc_video_embeds/'>Video embeds</a>"
url: "/documentation-theme-jekyll/mydoc_navtabs/"
link: "<a href='/documentation-theme-jekyll/mydoc_navtabs/'>Navtabs</a>"
mydoc_tables:
title: "Tables"
url: "mydoc_tables"
link: "<a href='/mydoc_tables/'>Tables</a>"
url: "/documentation-theme-jekyll/mydoc_tables/"
link: "<a href='/documentation-theme-jekyll/mydoc_tables/'>Tables</a>"
mydoc_syntax_highlighting:
title: "Syntax highlighting"
url: "mydoc_syntax_highlighting"
link: "<a href='/mydoc_syntax_highlighting/'>Syntax highlighting</a>"
url: "/documentation-theme-jekyll/mydoc_syntax_highlighting/"
link: "<a href='/documentation-theme-jekyll/mydoc_syntax_highlighting/'>Syntax highlighting</a>"
@ -194,8 +182,8 @@ mydoc_syntax_highlighting:
mydoc_commenting_on_files:
title: "Commenting on files"
url: "mydoc_commenting_on_files"
link: "<a href='/mydoc_commenting_on_files/'>Commenting on files</a>"
url: "/documentation-theme-jekyll/mydoc_commenting_on_files/"
link: "<a href='/documentation-theme-jekyll/mydoc_commenting_on_files/'>Commenting on files</a>"
@ -203,71 +191,71 @@ mydoc_commenting_on_files:
mydoc_build_arguments:
title: "Build arguments"
url: "mydoc_build_arguments"
link: "<a href='/mydoc_build_arguments/'>Build arguments</a>"
url: "/documentation-theme-jekyll/mydoc_build_arguments/"
link: "<a href='/documentation-theme-jekyll/mydoc_build_arguments/'>Build arguments</a>"
mydoc_themes:
title: "Themes"
url: "mydoc_themes"
link: "<a href='/mydoc_themes/'>Themes</a>"
mydoc_link_validation:
title: "Link validation"
url: "mydoc_link_validation"
link: "<a href='/mydoc_link_validation/'>Link validation</a>"
url: "/documentation-theme-jekyll/mydoc_themes/"
link: "<a href='/documentation-theme-jekyll/mydoc_themes/'>Themes</a>"
mydoc_title_checker:
title: "Check page title consistency"
url: "mydoc_title_checker"
link: "<a href='/mydoc_title_checker/'>Check page title consistency</a>"
url: "/documentation-theme-jekyll/mydoc_title_checker/"
link: "<a href='/documentation-theme-jekyll/mydoc_title_checker/'>Check page title consistency</a>"
mydoc_generating_pdfs:
title: "Generating PDFs"
url: "mydoc_generating_pdfs"
link: "<a href='/mydoc_generating_pdfs/'>Generating PDFs</a>"
url: "/documentation-theme-jekyll/mydoc_generating_pdfs/"
link: "<a href='/documentation-theme-jekyll/mydoc_generating_pdfs/'>Generating PDFs</a>"
mydoc_help_api:
title: "Help APIs and UI tooltips"
url: "mydoc_help_api"
link: "<a href='/mydoc_help_api/'>Help APIs and UI tooltips</a>"
url: "/documentation-theme-jekyll/mydoc_help_api/"
link: "<a href='/documentation-theme-jekyll/mydoc_help_api/'>Help APIs and UI tooltips</a>"
mydoc_search_configuration:
title: "Search configuration"
url: "mydoc_search_configuration"
link: "<a href='/mydoc_search_configuration/'>Search configuration</a>"
url: "/documentation-theme-jekyll/mydoc_search_configuration/"
link: "<a href='/documentation-theme-jekyll/mydoc_search_configuration/'>Search configuration</a>"
mydoc_iterm_profiles:
title: "iTerm profiles"
url: "mydoc_iterm_profiles"
link: "<a href='/mydoc_iterm_profiles/'>iTerm profiles</a>"
url: "/documentation-theme-jekyll/mydoc_iterm_profiles/"
link: "<a href='/documentation-theme-jekyll/mydoc_iterm_profiles/'>iTerm profiles</a>"
mydoc_push_build_to_server:
title: "Pushing builds to server"
url: "mydoc_push_build_to_server"
link: "<a href='/mydoc_push_build_to_server/'>Pushing builds to server</a>"
url: "/documentation-theme-jekyll/mydoc_push_build_to_server/"
link: "<a href='/documentation-theme-jekyll/mydoc_push_build_to_server/'>Pushing builds to server</a>"
mydoc_no_password_prompts_scp:
title: "Getting around the password prompts in SCP"
url: "mydoc_no_password_prompts_scp"
link: "<a href='/mydoc_no_password_prompts_scp/'>Getting around the password prompts in SCP</a>"
url: "/documentation-theme-jekyll/mydoc_no_password_prompts_scp/"
link: "<a href='/documentation-theme-jekyll/mydoc_no_password_prompts_scp/'>Getting around the password prompts in SCP</a>"
mydoc_publishing_github_pages:
title: "Publishing on Github Pages"
url: "/documentation-theme-jekyll/mydoc_publishing_github_pages/"
link: "<a href='/documentation-theme-jekyll/mydoc_publishing_github_pages/'>Publishing on Github Pages</a>"
@ -275,15 +263,22 @@ mydoc_no_password_prompts_scp:
mydoc_kb_layout:
title: "Knowledge-base layout"
url: "mydoc_kb_layout"
link: "<a href='/mydoc_kb_layout/'>Knowledge-base layout</a>"
url: "/documentation-theme-jekyll/mydoc_kb_layout/"
link: "<a href='/documentation-theme-jekyll/mydoc_kb_layout/'>Knowledge-base layout</a>"
mydoc_glossary:
title: "Glossary layout"
url: "mydoc_glossary"
link: "<a href='/mydoc_glossary/'>Glossary layout</a>"
url: "/documentation-theme-jekyll/mydoc_glossary/"
link: "<a href='/documentation-theme-jekyll/mydoc_glossary/'>Glossary layout</a>"
mydoc_faq_layout:
title: "FAQ layout"
url: "/documentation-theme-jekyll/mydoc_faq_layout/"
link: "<a href='/documentation-theme-jekyll/mydoc_faq_layout/'>FAQ layout</a>"
@ -291,15 +286,15 @@ mydoc_glossary:
mydoc_troubleshooting:
title: "Troubleshooting"
url: "mydoc_troubleshooting"
link: "<a href='/mydoc_troubleshooting/'>Troubleshooting</a>"
url: "/documentation-theme-jekyll/mydoc_troubleshooting/"
link: "<a href='/documentation-theme-jekyll/mydoc_troubleshooting/'>Troubleshooting</a>"
mydoc_install_dependencies:
title: "Adding all project dependencies"
url: "mydoc_install_dependencies"
link: "<a href='/mydoc_install_dependencies/'>Adding all project dependencies</a>"
url: "/documentation-theme-jekyll/mydoc_install_dependencies/"
link: "<a href='/documentation-theme-jekyll/mydoc_install_dependencies/'>Adding all project dependencies</a>"
@ -307,51 +302,51 @@ mydoc_install_dependencies:
mydoc_tag_archives_overview:
title: "Tag archives overview"
url: "mydoc_tag_archives_overview"
link: "<a href='/mydoc_tag_archives_overview/'>Tag archives overview</a>"
url: "/documentation-theme-jekyll/mydoc_tag_archives_overview/"
link: "<a href='/documentation-theme-jekyll/mydoc_tag_archives_overview/'>Tag archives overview</a>"
tag_getting_started:
title: "Getting started pages"
url: "tag_getting_started"
link: "<a href='/tag_getting_started/'>Getting started pages</a>"
tag_formatting:
title: "Formatting pages"
url: "tag_formatting"
link: "<a href='/tag_formatting/'>Formatting pages</a>"
url: "/documentation-theme-jekyll/tag_formatting/"
link: "<a href='/documentation-theme-jekyll/tag_formatting/'>Formatting pages</a>"
tag_navigation:
title: "Navigation pages"
url: "tag_navigation"
link: "<a href='/tag_navigation/'>Navigation pages</a>"
url: "/documentation-theme-jekyll/tag_navigation/"
link: "<a href='/documentation-theme-jekyll/tag_navigation/'>Navigation pages</a>"
tag_content_types:
title: "Content types pages"
url: "tag_content_types"
link: "<a href='/tag_content_types/'>Content types pages</a>"
url: "/documentation-theme-jekyll/tag_content_types/"
link: "<a href='/documentation-theme-jekyll/tag_content_types/'>Content types pages</a>"
tag_publishing:
title: "Publishing pages"
url: "tag_publishing"
link: "<a href='/tag_publishing/'>Publishing pages</a>"
url: "/documentation-theme-jekyll/tag_publishing/"
link: "<a href='/documentation-theme-jekyll/tag_publishing/'>Publishing pages</a>"
tag_special_layouts:
title: "Special layout pages"
url: "tag_special_layouts"
link: "<a href='/tag_special_layouts/'>Special layout pages</a>"
url: "/documentation-theme-jekyll/tag_special_layouts/"
link: "<a href='/documentation-theme-jekyll/tag_special_layouts/'>Special layout pages</a>"
tag_collaboration:
title: "Collaboration pages"
url: "tag_collaboration"
link: "<a href='/tag_collaboration/'>Collaboration pages</a>"
url: "/documentation-theme-jekyll/tag_collaboration/"
link: "<a href='/documentation-theme-jekyll/tag_collaboration/'>Collaboration pages</a>"
tag_troubleshooting:
title: "Troubleshooting pages"
url: "/documentation-theme-jekyll/tag_troubleshooting/"
link: "<a href='/documentation-theme-jekyll/tag_troubleshooting/'>Troubleshooting pages</a>"
@ -374,29 +369,29 @@ tag_collaboration:
p1_landing_page:
title: "Product 1 home"
url: "p1_landing_page"
link: "<a href='/p1_landing_page/'>Product 1 home</a>"
url: "/documentation-theme-jekyll/p1_landing_page/"
link: "<a href='/documentation-theme-jekyll/p1_landing_page/'>Product 1 home</a>"
p1_sample1:
title: "Sample 1"
url: "p1_sample1"
link: "<a href='/p1_sample1/'>Sample 1</a>"
url: "/documentation-theme-jekyll/p1_sample1/"
link: "<a href='/documentation-theme-jekyll/p1_sample1/'>Sample 1</a>"
p1_sample2:
title: "Sample 2"
url: "p1_sample2"
link: "<a href='/p1_sample2/'>Sample 2</a>"
url: "/documentation-theme-jekyll/p1_sample2/"
link: "<a href='/documentation-theme-jekyll/p1_sample2/'>Sample 2</a>"
p1_sample3:
title: "Sample 3"
url: "p1_sample3"
link: "<a href='/p1_sample3/'>Sample 3</a>"
url: "/documentation-theme-jekyll/p1_sample3/"
link: "<a href='/documentation-theme-jekyll/p1_sample3/'>Sample 3</a>"
@ -404,29 +399,29 @@ p1_sample3:
p1_sample4:
title: "Sample 4"
url: "p1_sample4"
link: "<a href='/p1_sample4/'>Sample 4</a>"
url: "/documentation-theme-jekyll/p1_sample4/"
link: "<a href='/documentation-theme-jekyll/p1_sample4/'>Sample 4</a>"
p1_sample5:
title: "Sample 5"
url: "p1_sample5"
link: "<a href='/p1_sample5/'>Sample 5</a>"
url: "/documentation-theme-jekyll/p1_sample5/"
link: "<a href='/documentation-theme-jekyll/p1_sample5/'>Sample 5</a>"
p1_sample6:
title: "Sample 6"
url: "p1_sample6"
link: "<a href='/p1_sample6/'>Sample 6</a>"
url: "/documentation-theme-jekyll/p1_sample6/"
link: "<a href='/documentation-theme-jekyll/p1_sample6/'>Sample 6</a>"
p1_sample7:
title: "Sample 7"
url: "p1_sample7"
link: "<a href='/p1_sample7/'>Sample 7</a>"
url: "/documentation-theme-jekyll/p1_sample7/"
link: "<a href='/documentation-theme-jekyll/p1_sample7/'>Sample 7</a>"
@ -450,22 +445,22 @@ p1_sample7:
p2_landing_page:
title: "Product 2 home"
url: "p2_landing_page"
link: "<a href='/p2_landing_page/'>Product 2 home</a>"
url: "/documentation-theme-jekyll/p2_landing_page/"
link: "<a href='/documentation-theme-jekyll/p2_landing_page/'>Product 2 home</a>"
p2_sample1:
title: "Sample 1"
url: "p2_sample1"
link: "<a href='/p2_sample1/'>Sample 1</a>"
url: "/documentation-theme-jekyll/p2_sample1/"
link: "<a href='/documentation-theme-jekyll/p2_sample1/'>Sample 1</a>"
p2_sample2:
title: "Sample 2"
url: "p2_sample2"
link: "<a href='/p2_sample2/'>Sample 2</a>"
url: "/documentation-theme-jekyll/p2_sample2/"
link: "<a href='/documentation-theme-jekyll/p2_sample2/'>Sample 2</a>"
@ -473,15 +468,15 @@ p2_sample2:
p2_sample3:
title: "Sample 3"
url: "p2_sample3"
link: "<a href='/p2_sample3/'>Sample 3</a>"
url: "/documentation-theme-jekyll/p2_sample3/"
link: "<a href='/documentation-theme-jekyll/p2_sample3/'>Sample 3</a>"
p2_sample4:
title: "Sample 4"
url: "p2_sample4"
link: "<a href='/p2_sample4/'>Sample 4</a>"
url: "/documentation-theme-jekyll/p2_sample4/"
link: "<a href='/documentation-theme-jekyll/p2_sample4/'>Sample 4</a>"
@ -489,22 +484,22 @@ p2_sample4:
p2_sample5:
title: "Sample 5"
url: "p2_sample5"
link: "<a href='/p2_sample5/'>Sample 5</a>"
url: "/documentation-theme-jekyll/p2_sample5/"
link: "<a href='/documentation-theme-jekyll/p2_sample5/'>Sample 5</a>"
p2_sample6:
title: "Sample 6"
url: "p2_sample6"
link: "<a href='/p2_sample6/'>Sample 6</a>"
url: "/documentation-theme-jekyll/p2_sample6/"
link: "<a href='/documentation-theme-jekyll/p2_sample6/'>Sample 6</a>"
p2_sample7:
title: "Sample 7"
url: "p2_sample7"
link: "<a href='/p2_sample7/'>Sample 7</a>"
url: "/documentation-theme-jekyll/p2_sample7/"
link: "<a href='/documentation-theme-jekyll/p2_sample7/'>Sample 7</a>"
@ -517,3 +512,50 @@ p2_sample7:
news:
title: "News"
url: "news"
link: "<a href='/news/'>News</a>"
mydoc_introduction:
title: "Jekyll Documentation Theme"
url: "mydoc_introduction"
link: "<a href='/mydoc_introduction/'>Jekyll Documentation Theme</a>"
p1_landing_page:
title: "Product 1"
url: "p1_landing_page"
link: "<a href='/p1_landing_page/'>Product 1</a>"
p2_landing_page:
title: "Product 2"
url: "p2_landing_page"
link: "<a href='/p2_landing_page/'>Product 2</a>"

3
_includes/sidebar.html
View File

@ -1,7 +1,8 @@
{% include custom/sidebarconfigs.html %}
<div class="sidebarTitle">{{sidebar[0].product}} {{sidebar[0].version}}</div>
<ul id="mysidebar" class="nav">
<div class="sidebarTitle">{{sidebar[0].product}} {{sidebar[0].version}}</div>
{% for entry in sidebar %}
{% for subcategory in entry.subcategories %}
{% if subcategory.output contains "web" %}

91
index.md
View File

@ -2,33 +2,31 @@
title: Getting started
tags: [getting_started]
sidebar: mydoc_sidebar
type: homepage
---
These instructions will help you get started quickly with the theme. The other topics in this help provide additional information and notes about working with other aspects of this theme and Jekyll.
## Make sure you can build a vanilla Jekyll site first
To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/).
If you're in Windows, you might want to [install Jekyll using Chocolately](https://www.google.com/search?q=install+jekyll+using+chocolately).
To get up and running with this theme, make sure you can build a vanilla jekyll site first. See the [Jekyll docs](http://jekyllrb.com/). If you're in Windows, you might want to [install Jekyll using Chocolately](https://www.google.com/search?q=install+jekyll+using+chocolately).
## Build this theme
1. Download the theme from the [Github repo for the Jekyll doc theme](https://github.com/tomjohnson1492/documentation-theme-jekyll).
2. Delete the Gemfile and Gemfile.lock files in the theme (unless you're planning to publish on Github Pages. If that's the case, see <a href="{{ "/mydoc_publishing_github_pages" | prepend: site.baseurl }}">Publishing on Github Pages</a>.
3. Customize the values in the \_config.yml file following the documentation included in that file).
3. Build the site using the usual Jekyll command: `jekyll serve`.
2. Delete the Gemfile and Gemfile.lock files in the theme (unless you're planning to publish on Github Pages. If that's the case, see <a href="{{ "/mydoc_publishing_github_pages" | prepend: site.baseurl }}">Publishing on Github Pages</a>).
3. Customize the values in the \_config.yml file following the documentation included in that file.
3. Build the site using the usual Jekyll command: `jekyll serve`
## Configuring the theme
For more information about build arguments in general with Jekyll, see {{site.data.urls.mydoc_build_arguments.link}}.
There are several products in this theme. Each product uses a different sidebar. This is the essence of what makes this theme unique -- different sidebars for different product documentation. The idea is that when users are reading documentation for a specific product, the sidebar navigation should be specific to that product. The top navigation remains the same, because it allows users to navigate across products. But the sidebar navigation adapts to the product.
## Configure the sidebar
## Where to store your documentation topics
There are several products in this theme. Each product uses a different sidebar. This is the essence of what makes this theme unique -- different sidebars for different product documentation. The idea is that when users are reading documentation for a specific product, the sidebar navigation should be specific to that product. (You can read more of my thoughts on why multiple sidebars are important in this [blog post](http://idratherbewriting.com/2016/03/23/release-of-documentation-theme-for-jekyll-50/).)
Store your files for each product inside subfolders following the pattern shown in the theme. For example, product1, product2, etc. You can store your topics inside sub-subfolders to your heart's content. When Jekyll builds your site, it will pull the topics into the root directory and use the permalink for the URL.
The top navigation remains the same, because it allows users to navigate across products. But the sidebar navigation adapts to the product.
## Configuring the sidebar
Because each product uses a different sidebar, you'll need to set up your sidebars. There's a file inside \_includes/custom called "sidebarconfigs.html". This file controls which sidebar gets associated with which product.
Because each product uses a different sidebar, you'll need to set up your sidebars. There's a file inside \_includes/custom called "sidebarconfigs.html". This file controls which sidebar gets associated with which product. Open up this file to see its contents.
The sidebarconfigs.html file uses simple `if elsif` logic to set a variable that the sidebar.html file uses to read the sidebar data file. The code in sidebarconfigs.html looks like this:
@ -57,7 +55,7 @@ The sidebarconfigs.html file uses simple `if elsif` logic to set a variable that
In each page's frontmatter, you must specify the sidebar you want that page to use. Here's an example of the page frontmatter showing the sidebar property:
```
```yaml
---
title: Alerts
tags: [formatting]
@ -75,17 +73,19 @@ If no sidebar assignment is found in the page frontmatter, the default sidebar (
Note that your sidebar can only have 2 levels. Given that each product has its own sidebar, this depth should be sufficient. Deeper nesting goes against usability recommendations.
For more detail on the sidebar, see {{site.data.urls.mydoc_sidebar_navigation.link}}.
## Sidebar syntax
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown:
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown. For example:
```yaml
- title: Overview
output: web, pdf
items:
- title: Mydoc home
url: /mydoc_landing_page/
output: web
- title: Overview
output: web, pdf
items:
- title: Get started
url: /mydoc_getting_started.md
output: web, pdf
```
Each heading must contain a title and output property. Each item must contain a title, url, and output property.
@ -97,21 +97,23 @@ The YAML syntax depends on exact spacing, so make sure you follow the pattern sh
To accommodate the title page and table of contents in PDF outputs, each product sidebar must list these pages before any other:
```yaml
- title:
output: pdf
type: frontmatter
items:
- title:
url: /titlepage/
output: pdf
type: frontmatter
- title:
url: /tocpage/
output: pdf
type: frontmatter
- title:
output: pdf
type: frontmatter
items:
- title:
url: /titlepage/
output: pdf
type: frontmatter
- title:
url: /tocpage/
output: pdf
type: frontmatter
```
Leave the output as `output: pdf` so that they don't appear in the web output.
Leave the output as `output: pdf` for these frontmatter pages so that they don't appear in the web output.
For more detail on the sidebar, see {{site.data.urls.mydoc_sidebar_navigation.link}} and {{site.data.urls.mydoc_yaml_tutorial.link}}.
## Page frontmatter
@ -129,7 +131,7 @@ permalink: /yoururl/
---
```
(If you're using Webstorm, you can set up a template to auto-populate this code when you create a new file.)
(If you're using [Webstorm]({{site.data.urls.mydoc_webstorm_text_editor.url}}), you can set up a template to auto-populate this code when you create a new file.)
For titles, surrounding the title in quotes is optional, but if you have a colon in the title, you must surround the title with quotation marks.
@ -140,6 +142,17 @@ Tags must be defined in your \_data/tags.yml list. You also need a corresponding
If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: false` in the frontmatter.
For more detail, see {{site.data.urls.mydoc_pages.link}}.
## Where to store your documentation topics
Store your files for each product inside subfolders following the pattern shown in the theme. For example, product1, product2, etc. You can store your topics inside sub-subfolders or sub-sub-folders to your heart's content. When Jekyll builds your site, it will pull the topics into the root directory and use the permalink for the URL.
Note that product1, product2, and mydoc are all just sample content to demonstrate how to add multiple products into the theme. You can freely delete that content.
For more information, see {{site.data.urls.mydoc_pages.link}} and {{site.data.urls.mydoc_posts.link}}.
## Configure the top navigation
The top navigation bar's menu items are set through the _data/topnav.yml file. Use the top navigation bar to provide links for navigating from one product to another, or to navigate to external resources.
@ -148,13 +161,14 @@ For external URLs, use `external_url` in the item property, as shown in the exam
Note that the topnav has two sections: topnav and topnav_dropdowns. The topnav section contains single links, while the topnav_dropdowns section contains dropdown menus. The two sections are independent of each other.
## Generating PDF
If you want to generate PDF, you'll need a license for [Prince XML](http://www.princexml.com/). You will also need to [install Prince](http://www.princexml.com/doc/installing/). You can generate PDFs by product (but not for every product on the site combined together into one massive PDF). Prince will work even without a license, but it will imprint a small Prince image on the first page.
Open up the css/printstyles.css file and customize the email address (`youremail@domain.com`) that is listed there. This email address appears in the bottom left footer of the PDF output. You'll also need to create a PDF configuration file following the examples shown in the pdfconfigs folder, and also customize some build scripts following the same pattern shown in the root: pdf-product1.sh
See the section on [generating PDFs](mydoc_generating_pdfs) for more details about setting the theme up for this output.
See the section on {{site.data.urls.mydoc_generating_pdfs.link}} for more details about setting the theme up for this output.
## Blogs / News
@ -162,10 +176,11 @@ For blog posts, create your markdown files in the \_posts folder following the s
The news/news.html file displays the posts, and the news_archive.html file shows a yearly history of posts. In documentation, you might use the news to highlight product features outside of your documentation, or to provide release notes and other updates.
See {{site.data.urls.mydoc_posts}} for more information.
## Markdown
This theme uses Kramdown markdown. Kramdown is similar to Github-flavored Markdown, except that when you have text that intercepts list items, the spacing of the intercepting text must align with the spacing of the first character after the space of a numbered list item.
This theme uses Kramdown markdown. Kramdown is similar to Github-flavored Markdown, except that when you have text that intercepts list items, the spacing of the intercepting text must align with the spacing of the first character after the space of a numbered list item. See the topics under "Formatting" in the sidebar for more information.
## Other instructions

10
mydoc/mydoc_generating_pdfs.md
View File

@ -34,7 +34,7 @@ You can install a fully functional trial version. The only difference is that th
The PDF configuration file will build on the settings in the regular configuration file but will some additional fields. Here's the configuration file for the mydoc product within this theme. This configuration file is located in the pdfconfigs folder.
```
```yaml
destination: _site/
url: "http://127.0.0.1:4010"
baseurl: "/mydoc-pdf"
@ -72,7 +72,7 @@ There are two template pages in the root directory that are critical to the PDF:
These pages should appear in your sidebar YML file (in this product, mydoc_sidebar.yml):
```json
```yaml
- title:
output: pdf
type: frontmatter
@ -145,7 +145,7 @@ To set a specific style property for a particular page, you have to name the pag
First you add frontmatter to the page that specifies the type. For the titlepage.html, here's the frontmatter:
```
```yaml
---
type: title
---
@ -153,7 +153,7 @@ type: title
For the tocpage, here's the frontmatter:
```
```yaml
---
type: frontmatter
---
@ -161,7 +161,7 @@ type: frontmatter
For the index.html page, we have this type tag (among others):
```
```yaml
---
type: first_page
---

53
mydoc/mydoc_top_navigation_deep_dive.md
View File

@ -1,53 +0,0 @@
---
title: Top navigation
tags:
- navigation
keywords: "custom menu, custom_menu, pop-out, frameescape, frame escape, top nav bar, topnav"
last_updated: "November 30, 2016"
summary: "The top navigation provides some additional features involving a custom menu and pop-out link that you can customize."
sidebar: mydoc_sidebar
permalink: /mydoc_top_navigation_deep_dive/
---
{{site.data.alerts.note}} For basic information about configuring the top navigation, see {{site.data.mydoc_urls.mydoc_top_navigation.link}}. This section gets into the top navigation in more depth. {{site.data.alerts.end}}
## Custom Menu
It's common to publish multiple sites. If you want to link the multiple together, you could simply list links to the other doc sites in a drop-down menu configured in the topnav_dropdowns section in the topnav_doc.yml file. However, suppose you want to do something more fancy.
Included in the topnav.html file is an include to /doc/custom_menu.html. The code in custom_menu.html is as follows:
{% raw %}
```html
<li class="dropdown">
<a href="#" class="dropdown-toggle otherProgLangs" data-toggle="dropdown">Custom Menu<b class="caret"></b></a>
<ul class="dropdown-menu">
<li {% if site.audience == "writers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../mydoc_writers/">Writer docs</a> {% else %} ../mydoc_writers{{page.url}}">Writer docs</a>{% endif %}</li>
<li {% if site.audience == "designers" %}class="dropdownActive"{% endif %}><a href="{% if page.homepage == true or page.switch == false %}../mydoc_designers/">Designer docs</a> {% else %} ../mydoc_designers{{page.url}}">Designer docs</a>{% endif %}</li>
</ul>
</li>
```
{% endraw %}
{{site.data.alerts.note}} In the theme, the link to the custom_menu.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 custom_menu 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. 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:
```
switch: false
```
This Custom Menu may not be something you want, and if so, just remove the include from the sidebar.html file. But if you're outputting multiple sites, it may be something valuable. You will need to customize the previous code sample to be specific to your project names.
## Pop-out link
The topnav.html file also has an include to frameescape.html (which is also commented out). What does this file do? If the site is embedded inside a frame, a link on the top navigation bar appears that says Pop-out, and it will open the site in a new window.
In most cases, you'll want to simply remove this include. I added this because some of my doc sites are delivered through a Salesforce Community and are embedded inside another page in a small area. This pop-out link is a way of liberating the site from these embedded page scenarios. If your site isn't embedded in an iframe, the Pop-out link doesn't appear. (Also, because it is commented out, it won't appear.) You can remove this part of the theme.