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

improved installation instructions

Browse Source
This commit is contained in:
tomjohnson1492
2016-10-07 18:58:20 -07:00
parent bbd495a3ec
commit b69693e0fb
18 changed files with 124 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
index.md
View File

@ -7,52 +7,66 @@ permalink: index.html
summary: These brief instructions will help you get started quickly with the theme. The other topics in this help provide additional information and detail about working with other aspects of this theme and Jekyll.
---
## Download or clone the theme
## Download the theme
First download or clone the theme from the [Github repo](https://github.com/tomjohnson1492/documentation-theme-jekyll). Most likely you won't be pulling in updates once you start customizing the theme, so downloading the theme (instead of cloning it) probably makes the most sense.
First download or clone the theme from the [Github repo](https://github.com/tomjohnson1492/documentation-theme-jekyll). Most likely you won't be pulling in updates once you start customizing the theme, so downloading the theme (instead of cloning it) probably makes the most sense. In Github, click the **Clone or download** button, and then click **Download ZIP**.
## Build this theme
## Install Jekyll
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:
If you've never installed or run a Jekyll site locally on your computer, follow these instructions to install Jekyll:
* [Install Jekyll on Mac][mydoc_install_jekyll_on_mac]
* [Install Jekyll on Windows][mydoc_install_jekyll_on_windows]
## Customize the Gemfile
## Install Bundler
The Gemfile is how project dependencies are managed. This project doesn't have any dependencies beyond core Jekyll.
Open the Gemfile (in any text editor) in the Jekyll doc theme project with the following command:
In case you haven't installed Bundler, install it:
```
open Gemfile
gem install bundler
```
The theme's gemfile looks as follows:
You'll want [Bundler](http://bundler.io/) to make sure all the Ruby gems needed work well with your project. Bundler sorts out dependencies and installs missing gems or matches up gems with the right versions based on gem dependencies.
## Remove the Gemfiles
The Gemfile is how project dependencies are managed. Although this project includes a Gemfile, this theme doesn't have any dependencies beyond core Jekyll. The Gemfile is used to specify gems needed for publishing on Github Pages. If you're not planning to have Github Pages build your Jekyll project, delete these two files from the theme's root directory:
* Gemfile
* Gemfile.lock
## Build the Project (not with the Github Pages gem)
If you've never run Jekyll on your computer (you can check with `jekyll --version`), you may need to install the jekyll gem:
```
# A sample Gemfile
source "https://rubygems.org"
# gem "rails"
gem 'github-pages'
gem 'jekyll'
gem install 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:
Now run Jekyll serve (first change directories (`cd`) to where you downloaded the project):
```
jekyll serve
```
## Build the Project (with the Github Pages gem)
If you *are* in fact publishing on Github Pages, leave the Gemfile and Gemfile.lock files in the theme, along with the Github Pages gem specified in the Gemfile (`gem 'github-pages', group: :jekyll_plugins`). However, note that you cannot use the normal `jekyll serve` command with this gem due to dependency conflicts between the latest version of Jekyll and Github Pages (which are noted [briefly here](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/).
You need Bundler to resolve these dependency conflicts. Use Bundler to install all the needed Ruby gems:
```
bundle update
```
Then *always* use this command to build Jekyll:
```
bundle exec jekyll serve
```
(If you want to shorten this long command, you can put this code in a file such as jekyll.sh (on a Mac) and then simply type `. jekyll.sh` to build Jekyll.)
## 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/).)