diff --git a/_config.yml b/_config.yml index b2c1e40f..ae93509f 100644 --- a/_config.yml +++ b/_config.yml @@ -1,5 +1,5 @@ # Site title and subtitle. This is used in _includes/header.html -title: 'jekyll-docs-template' +title: 'rallech test' subtitle: 'Painless documentation for your projects' # if you wish to integrate disqus on pages set your shortname here @@ -15,7 +15,7 @@ google_analytics_id: '' navigation: 2 # URL to source code, used in _includes/footer.html -codeurl: 'https://github.com/bruth/jekyll-docs-template' +codeurl: 'https://github.com/rallech/jekyll-docs-template-test' # Default categories (in order) to appear in the navigation sections: [ diff --git a/_posts/2013-06-03-contributing.md b/_posts/2013-06-03-contributing.md new file mode 100644 index 00000000..36802317 --- /dev/null +++ b/_posts/2013-06-03-contributing.md @@ -0,0 +1,31 @@ +--- +layout: page +title: Contributing +date: 2013-06-03 21:12:57 +category: dev +order: 0 +--- + +The first step in contributing to the code base is [forking the repo](https://help.github.com/articles/fork-a-repo). + +If you have an existing fork, make the repo is up-to-date. Always create the +branch off the actively developed branch (typically `develop` or `master`) + +**For bug fixes:** + +- Create a branch +- Once the bug has been fixed with sufficient testing submit a [pull request](https://help.github.com/articles/using-pull-requests) +- If there is an existing open issue, reference the issue number in the pull request description. + +**For new features:** + +Open a ticket thoroughly describing the feature. The more detail you provide, the better. After at least one of core developers responds or triages the ticket and says it's a go, follow the steps: + +- Create a branch +- Once implemented with tests and documentation, submit a pull request +referencing the open ticket. + +**For documentation:** + +- Create a branch or [edit the file](https://help.github.com/articles/creating-and-editing-files-in-your-repository#changing-files-you-dont-own) +- Submit a pull request diff --git a/_posts/2013-06-05-changelog.md b/_posts/2013-06-05-changelog.md new file mode 100644 index 00000000..f5807827 --- /dev/null +++ b/_posts/2013-06-05-changelog.md @@ -0,0 +1,42 @@ +--- +layout: page +title: "Changelog" +category: dev +order: 1 +--- + +#### 2015-01-27 + +- Add Google Analytics support + +#### 2015-01-26 + +- Add disqus support + +#### 2013-07-15 + +- Add support hiding the navigation for single-page sites + - If no posts have been created, the navigation will be hidden + - There is an option to explicitly show or hide the navigation + +#### 2013-07-12 + +- Add support for the `codeurl` site variable (defined in `_config.yml`) for linking back to the source code in the footer + +#### 2013-06-12 + +- Add JavaScript-based ordering of navigation + - This utilizes the `order` number defined in a posts Front-Matter + +#### 2013-06-09 + +- Add convenience _short-linking_ of posts in `_posts` directory + - This simply more easily enables referring to and opening files without needing to remember the date, e.g. 2013-06-03-some-post-name.md => some-post-name.md + +#### 2013-06-06 + +- Add convenience [script](http://bruth.github.io/jekyll-docs-template/doc/usage.html) for creating new pages by name within a category + +#### 2013-06-05 + +- Initial Release diff --git a/_posts/2013-06-05-license.md b/_posts/2013-06-05-license.md new file mode 100644 index 00000000..e8fe2200 --- /dev/null +++ b/_posts/2013-06-05-license.md @@ -0,0 +1,33 @@ +--- +layout: page +title: "License" +category: dev +order: 2 +--- + +``` +Copyright (c) 2013 Byron Ruth + +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``` diff --git a/_posts/2013-06-06-install-setup.md b/_posts/2013-06-06-install-setup.md new file mode 100644 index 00000000..3295b256 --- /dev/null +++ b/_posts/2013-06-06-install-setup.md @@ -0,0 +1,18 @@ +--- +layout: page +title: "Install & Setup" +category: doc +date: 2013-06-06 11:01:37 +order: 0 +--- + +#### Install + +There are two methods: + +- Fork the [repo](https://github.com/bruth/jekyll-docs-template/) and clone it +- [Download](https://github.com/bruth/jekyll-docs-template/archive/master.zip) and unzip + +#### Setup + +There is none! It's just a Jekyll template. Read how to [make use of this template]({{ site.baseurl }}{% post_url 2013-06-06-usage %}). For general information on Jekyll, refer to the [Jekyll docs](http://jekyllrb.com/docs/home/). diff --git a/_posts/2013-06-06-usage.md b/_posts/2013-06-06-usage.md new file mode 100644 index 00000000..2e19bcbf --- /dev/null +++ b/_posts/2013-06-06-usage.md @@ -0,0 +1,94 @@ +--- +layout: page +title: "Usage" +category: doc +date: 2013-06-06 08:55:36 +order: 1 +--- + +The template follows a very simple convention of defining categories that correspond to sections in the navigation. Here are the default ones (they are listed in the `_config.yml`): + +- `doc` - Documentation +- `ref` - Reference +- `tut` - Tutorial +- `dev` - Developers +- `post` - Posts + +Since Jekyll is more geared towards blog posts, specifiying a date and setting up the front-matter can get tedious. Supplied in the `bin` directory is a simple Ruby scripy for creating a new _page_: + +```bash +ruby bin/jekyll-page title category [filename] [--edit] +``` + +where `title` is the title of page, `category` is one of the categories defined in the `_config.yml`. By default the `filename` will be derived from the `title`, but you can specify an explicit filename (without the date) by passing the third agument. Finally the `--edit` (or just `-e`) will launch the editor defined by the `$EDITOR` environment variable. + +#### Example + +```bash +./bin/jekyll-page "My New Page" ref +``` + +Will produce a file `_posts/2013-06-05-my-new-page.md` with the [front-matter](http://jekyllrb.com/docs/frontmatter/) already defined: + +```html +--- +layout: page +title: "My New Page" +category: ref +date: 2013-06-05 12:00:00 +--- +``` + +### Navigation Order + +Simply add an `order` attribute to the front-matter of the page and the navigation links will be sorted accordingly (within it's section). + +```html +--- +layout: page +title: "My New Page" +category: ref +date: 2013-06-05 12:00:00 +order: 1 +--- +``` + +_Note: currently there is no way to arbitrarily order pages in Jekyll without the use of plugins. However, since deploying Jekyll sites to GitHub Pages is a common practice, we cannot rely on third-party plugins [since they are disabled](https://help.github.com/articles/pages-don-t-build-unable-to-run-jekyll#unsafe-plugins). This solution relies on JavaScript to sort the navigation after it has been rendered, so if JavaScript is disabled on the browser, the client is out of luck._ + +### Symlinks + +For convenience, a new directory will be created called `_pages` which contains symlinks to the posts without the data prefix, e.g. `2013-04-13-foo.md` → `foo.md`. This makes it a tad easier when opening files to edit. + +### Disqus + +You can enable disqus comments on any page. Configure your disqus shortname in the main ```_config.yaml```, you get the shortname during the signup process at Disqus: + +```html +disqus_shortname: your_disqus +``` + +You can now enable it on a per-page basis in the YAML pre-amble of the page: + +```html +--- +layout: page +title: "My New Page" +category: ref +date: 2013-06-05 12:00:00 +disqus: 1 +--- +``` + +### Google Analytics + +You can use Google Analytics to track visits to your site, once you configured your site at Google you'll get a site ID that looks something like ```UA-99999999-9```, to activate it on all your pages configure the ```_config.yaml```: + +```html +google_analytics_id: 'UA-99999999-9' +``` + +If you do not wish this feature enabled you must set it to an empty string: + +```html +google_analytics_id: '' +``` diff --git a/index.md b/index.md index 783a5ce5..81c32f70 100644 --- a/index.md +++ b/index.md @@ -3,7 +3,15 @@ layout: default title: "Jekyll Docs Template" --- -### Get Started +

Tired of long and unmanageable single-page READMEs deployed as your project's documentation? This minimal Jekyll project template is specifically intended for simple static documentation sites deployable on GitHub Pages.

+ +The template follows a very simple convention of defining categories that correspond to sections in the navigation. Here are the default ones (they are listed in the `_config.yml`): + +- `doc` - Documentation +- `ref` - Reference +- `tut` - Tutorial +- `dev` - Developers +- `post` - Posts Start by [creating a new post](http://jekyllrb.com/docs/posts/) one of the categories listed in `_config.yml`. It will appear in the navigation on the left once recompiled. Or use the supplied script to make creating pages easier: @@ -11,8 +19,4 @@ Start by [creating a new post](http://jekyllrb.com/docs/posts/) one of the categ ruby bin/jekyll-page "Some Page Title" ref ``` -#### Don't Forget - -- Add your own content to this page (i.e. `index.md`) and change the `title` -- Change `title` and `subtitle` defined in `config.yml` for your site -- Set the `baseurl` in `_config.yml` for your repo if deploying to GitHub pages +Read more [Usage]({{ site.baseurl }}{% post_url 2013-06-06-usage %}) page for more details or view the project [on GitHub](https://github.com/bruth/jekyll-docs-template/)