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

added instructions for publishing with github pages. also added more detail on install page and in config file -- just documentation

Browse Source
This commit is contained in:
tomjohnson1492
2016-03-22 15:42:02 -07:00
parent 5012328645
commit b630fdd21c
4 changed files with 115 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
_config.yml
View File

@ -1,35 +1,50 @@
permalink: /:year/:month/:day/:title/
# this sets the style for permalinks. The date formatting (/:year/:month/:day/) will only apply to blog posts, while the pages will just show the title.
url: http://idratherbewriting.com
# where you plan to publish your site
baseurl: "/documentation-theme-jekyll"
# any subdirectory that appears after the domain where you're publishing your site
output: web
# this property is useful for conditional filtering of content that is separate from the PDF.
topnav_title: Jekyll Documentation Theme
# this appears on the top navigation bar next to the home button
site_title: Jekyll theme for designers
# this appears in the html browser tab for the site title (seen mostly by search engines, not users)
company_name: Your company
# this appears in the footer
github_editme_path: tomjohnson1492/documentation-theme-jekyll/edit/reviews
# if you're using Github, provide the basepath to the branch you've created for reviews, following the sample here. if not, leave this value blank.
disqus_shortname: idrbwjekyll
# if you're using disqus for comments, add the shortname here. if not, leave this value blank.
host: 127.0.0.1
# the preview server used. Leave as is.
port: 4009
# the port where the preview is rendered. You can leave this as is unless you have other Jekyll builds using this same port that might cause conflicts.
exclude:
- _site
- _drafts
- configs/
- _drafts/
- .idea/
# these are the files and directories that jekyll will exclude from the build
feedback_email: tomjohnson1492@gmail.com
# used as a contact email for the Feedback link in the top navigation bar
highlighter: rouge
# library used for syntax highlighting
markdown: kramdown
kramdown:
input: GFM
auto_ids: true
hard_wrap: false
syntax_highlighter: rouge
# filter used to process markdown. note that kramdown differs from github-flavored markdown in some subtle ways
collections:
tooltips:
output: false
# collection declared here. this renders the content in _tooltips and processes it, but doesn't output it as actual files in the output.
defaults:
-
@ -61,7 +76,8 @@ defaults:
search: true
sidebar: tags_sidebar
# these are defaults used for the frontmatter for these file types
# the description is used in the feed.xml file
description: "Intended as a documentation theme based on Jekyll for technical writers documenting software and other technical products, this theme has all the elements you would need to handle multiple products with both multi-level sidebar navigation, tags, and other documentation features."
# the description is used in the feed.xml file

6
_data/sidebars/mydoc_sidebar.yml
View File

@ -30,7 +30,7 @@ entries:
- title: 5.0 Release notes
url: /mydoc_release_notes_50/
output: web, pdf
- title: Introduction
url: /mydoc_introduction/
output: web, pdf
@ -187,6 +187,10 @@ entries:
url: /mydoc_no_password_prompts_scp/
output: web, pdf
- title: Publishing on Github Pages
url: /mydoc_publishing_github_pages/
output: web, pdf
- title: Special layouts
output: web, pdf

9
index.md
View File

@ -5,13 +5,18 @@ sidebar: mydoc_sidebar
---
## Getting up and running
## 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).
After ensuring you can run Jekyll on your machine, you can build this site using the usual Jekyll command: `jekyll serve`.
## 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`.
## Configuring the theme

82
mydoc/mydoc_publishing_github_pages.md Normal file
View File

@ -0,0 +1,82 @@
---
title: Publishing on Github Pages
sidebar: mydoc_sidebar
permalink: /mydoc_github_pages/
summary: "You can publish your project on Github Pages, which is a free web hosting service provided by Github. All you need is to put your content into a Github repo branch called gh-pages and make this your default branch in your repo. With a Jekyll site, you just commit your entire project into the gh-pages branch and Github Pages will build the site for you."
---
## Set up your Github repo
1. Make sure you have Git installed. You can download and install [Git for Windows here](https://git-scm.com/download/win) and [Git for Mac here](https://git-scm.com/download/mac). If you're on a Mac, chances are you might already have git installed. You can check by opening up a terminal and typing `which git`.{{end}}
1. Go to [Github.com](http://github.com) and sign up for an account.
2. Click the **+** button in the upper-right corner and select **New repository**.
3. Name the repository something like **mydoctheme**.
4. Type a description..
5. Select the **Initialize this repository with a README** check box.
6. Add a license if desired.
7. Leave the other options at the defaults and click **Create repository**.
8. Click the **Settings** button.
<img src="{{ "/images/publishingapidocs/githubreposettings.png" | prepend: site.baseurl }}" alt="Github repo settings" />
9. Go to your repository's home page, and click the branch drop-down menu.
10. Create a new branch called **gh-pages**.
<img src="{{ "/images/publishingapidocs/ghpages.png" | prepend: site.baseurl }}" alt="Creating a Github Pages branch" />
11. Click **Settings** and change the default branch to **gh-pages**.
11. Go back to your repository's homepage. With the gh-pages branch selected, copy the **https clone url**:
<img src="{{ "/images/publishingapidocs/cloneurl.png" | prepend: site.baseurl }}" alt="clone URL" />
12. Open a terminal, browse to a convenient location for your project, and type `git clone https://github.com/tomjohnson1492/myreponame.git`, replacing the `https://github.com/tomjohnson1492/myreponame.git` with your repository's https clone URL that you copied.
13. Move the jekyll theme files into this new folder that you just created in the previous step.
14. Open the _config.yml file and add the following:
```
url: tomjohnson1492.github.io
baseurl: /myreponame
```
Change the url to your github account name, and the baseurl to your repo name.
## Install Bundler
Bundler is a package manager for Ruby that will install all dependencies you might need to build your site locally. I recommend installing Bundler through homebrew. (Sorry, these instructions apply to Mac only.)
1. Install [homebrew](http://brew.sh/):
```
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```
2. Install Bundler:
```
brew install bundler
```
## Add the github pages gem
1. In terminal, browse to your Jekyll project directory.
2. Type `bundle init`. This creates a Gemfile and Gemfile.lock in your project.
3. Type `open gemfile`. This opens the gemfile in your default text editor.
4. Add the following in the gemfile (replacing the existing contents):
```
source 'https://rubygems.org'
gem 'github-pages'
```
5. Run `bundle install`.
14. Add the new jekyll files to git: `git add --all`.
15. Commit the files: `git commit -m "committing my jekyll theme"`.
16. Push the files up to your github repo: `git push`.
Github Pages will now automatically build your site. Wait a minute or two, and then visit tomjohnson1492.github.io/yourreponame, replacing this path with your github account and branch.
## Customize your URL
You can also customize your Github URL. More instructions on this later....