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

updated install instructions

Browse Source
This commit is contained in:
tomjohnson1492
2016-05-30 16:53:12 -07:00
parent fc1efd12b8
commit 1f4bf78619
14 changed files with 216 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
index.md
View File

@@ -11,11 +11,47 @@ These brief instructions will help you get started quickly with the theme. The o
## Build this theme
If you're used to running Jekyll sites, you can type the normal jekyll command, `jekyll serve`, to run this site. However, if you're a new Jekyll user or if you run into issues, see the following two topics:
If you're used to running Jekyll sites, you can type the normal jekyll command, `jekyll serve`, to build the Jekyll theme. However, if you're a new Jekyll user or if you run into issues, see the following two topics:
* {{site.data.urls.mydoc_install_jekyll_on_mac.link}}
* {{site.data.urls.mydoc_install_jekyll_on_windows.link}}
## Customize the Gemfile
##
Open the Gemfile (in any text editor) in the Jekyll doc theme project:
```
open Gemfile
```
The theme's gemfile looks as follows:
```
# A sample Gemfile
source "https://rubygems.org"
# gem "rails"
gem 'github-pages'
gem 'jekyll'
```
If you're publishing on Github Pages, leave the `github-pages` gem there. But if not, remove `github-pages` because Github sometimes has dependencies that conflict with the latest versions of the Jekyll gem and Kramdown, which can be frustrating.
Use Bundler to install all the needed Ruby gems:
```
bundle install
```
Now run Jekyll serve to build the theme:
```
jekyll serve
```
## Configure the sidebar
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/).)
@@ -135,7 +171,7 @@ For more detail on the sidebar, see {{site.data.urls.mydoc_sidebar_navigation.li
## Page frontmatter
When you write pages, include this same frontmatter in each page:
When you write pages, include these same frontmatter keys with each page:
```yaml
---
@@ -149,20 +185,21 @@ permalink: /yoururl/
---
```
(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.)
(You will customize the values for each of these keys, of course.)
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.
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.
Keywords get populated into the metadata of the page for SEO.
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. If you have a quotation mark within the title, escape it first with a backlash `\`.
Tags must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.)
Values for `keywords` get populated into the metadata of the page for SEO.
Values for `tags` must be defined in your \_data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll wont auto-create these tag files.)
```
If you don't want the mini-TOC to show on a page (such as for the homepage or landing pages), add `toc: 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.
@@ -179,7 +216,6 @@ 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.
@@ -227,7 +263,7 @@ See the topics under "Formatting" in the sidebar for more information.
## Managing links
If you want to use a simple system for managing links, see the "Managed Links" section in {{site.data.urls.mydoc_hyperlinks.link}}.
If you want to use a simple system for managing links, see the "Managed Links" section in {{site.data.urls.mydoc_hyperlinks.link | append: "#managed-links"}}.
## Other instructions