From e17e8021141c4f8eefdda506957438d569df0de3 Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Wed, 5 Jun 2013 10:47:30 -0400 Subject: [PATCH 01/26] Add baseurl for gh-pages --- _config.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_config.yml b/_config.yml index b26cc103..67979246 100644 --- a/_config.yml +++ b/_config.yml @@ -9,6 +9,8 @@ sections: [ ['post', 'Posts'] ] +baseurl: '/jekyll-docs-template/' + pygments: true future: false From 3e62369d8006ca1c964b3c1b307de12a52183d8d Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Thu, 6 Jun 2013 09:54:26 -0400 Subject: [PATCH 02/26] Add documentation --- _posts/2013-06-03-contributing.md | 30 ++++++++++++++++++++++++ _posts/2013-06-05-changelog.md | 9 +++++++ _posts/2013-06-05-license.md | 31 ++++++++++++++++++++++++ _posts/2013-06-06-usage.md | 39 +++++++++++++++++++++++++++++++ index.md | 16 ++++++++----- 5 files changed, 119 insertions(+), 6 deletions(-) create mode 100644 _posts/2013-06-03-contributing.md create mode 100644 _posts/2013-06-05-changelog.md create mode 100644 _posts/2013-06-05-license.md create mode 100644 _posts/2013-06-06-usage.md diff --git a/_posts/2013-06-03-contributing.md b/_posts/2013-06-03-contributing.md new file mode 100644 index 00000000..78d69bd7 --- /dev/null +++ b/_posts/2013-06-03-contributing.md @@ -0,0 +1,30 @@ +--- +layout: page +title: Contributing +date: 2013-06-03 21:12:57 +category: dev +--- + +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..b99f3545 --- /dev/null +++ b/_posts/2013-06-05-changelog.md @@ -0,0 +1,9 @@ +--- +layout: page +title: "Changelog" +category: dev +--- + +#### 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..0db39ff8 --- /dev/null +++ b/_posts/2013-06-05-license.md @@ -0,0 +1,31 @@ +--- +layout: page +title: "License" +category: dev +--- +``` +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-usage.md b/_posts/2013-06-06-usage.md new file mode 100644 index 00000000..6851ff62 --- /dev/null +++ b/_posts/2013-06-06-usage.md @@ -0,0 +1,39 @@ +--- +layout: page +title: "Usage" +category: doc +date: 2013-06-06 08:55:36 +--- + +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 +--- +``` diff --git a/index.md b/index.md index 783a5ce5..51155d34 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. From 218cc95cd889f151d47c5bcee6a870a83c20450b Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Thu, 6 Jun 2013 10:03:55 -0400 Subject: [PATCH 03/26] Add link to Github repo --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 51155d34..a36ea73e 100644 --- a/index.md +++ b/index.md @@ -19,4 +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 ``` -Read more [Usage]({{ site.baseurl }}{% post_url 2013-06-06-usage %}) page for more details. +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/) From 42a39fd17cca33e4144ac9f8957f5b5315ae1488 Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Thu, 6 Jun 2013 11:17:01 -0400 Subject: [PATCH 04/26] Add install & setup page --- _posts/2013-06-06-install-setup.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 _posts/2013-06-06-install-setup.md diff --git a/_posts/2013-06-06-install-setup.md b/_posts/2013-06-06-install-setup.md new file mode 100644 index 00000000..3c2a5684 --- /dev/null +++ b/_posts/2013-06-06-install-setup.md @@ -0,0 +1,17 @@ +--- +layout: page +title: "Install & Setup" +category: doc +date: 2013-06-06 11:01:37 +--- + +#### 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/). From 452f470c17e903e93a57c86fcebaf32f88335f95 Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Wed, 12 Jun 2013 15:15:48 -0400 Subject: [PATCH 05/26] Document navigation order usage Add order to posts --- _posts/2013-06-03-contributing.md | 1 + _posts/2013-06-05-changelog.md | 1 + _posts/2013-06-05-license.md | 2 ++ _posts/2013-06-06-install-setup.md | 1 + _posts/2013-06-06-usage.md | 23 ++++++++++++++++++++++- 5 files changed, 27 insertions(+), 1 deletion(-) diff --git a/_posts/2013-06-03-contributing.md b/_posts/2013-06-03-contributing.md index 78d69bd7..36802317 100644 --- a/_posts/2013-06-03-contributing.md +++ b/_posts/2013-06-03-contributing.md @@ -3,6 +3,7 @@ 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). diff --git a/_posts/2013-06-05-changelog.md b/_posts/2013-06-05-changelog.md index b99f3545..591e3e9a 100644 --- a/_posts/2013-06-05-changelog.md +++ b/_posts/2013-06-05-changelog.md @@ -2,6 +2,7 @@ layout: page title: "Changelog" category: dev +order: 1 --- #### 2013-06-05 diff --git a/_posts/2013-06-05-license.md b/_posts/2013-06-05-license.md index 0db39ff8..e8fe2200 100644 --- a/_posts/2013-06-05-license.md +++ b/_posts/2013-06-05-license.md @@ -2,7 +2,9 @@ layout: page title: "License" category: dev +order: 2 --- + ``` Copyright (c) 2013 Byron Ruth diff --git a/_posts/2013-06-06-install-setup.md b/_posts/2013-06-06-install-setup.md index 3c2a5684..3295b256 100644 --- a/_posts/2013-06-06-install-setup.md +++ b/_posts/2013-06-06-install-setup.md @@ -3,6 +3,7 @@ layout: page title: "Install & Setup" category: doc date: 2013-06-06 11:01:37 +order: 0 --- #### Install diff --git a/_posts/2013-06-06-usage.md b/_posts/2013-06-06-usage.md index 6851ff62..f6ae3039 100644 --- a/_posts/2013-06-06-usage.md +++ b/_posts/2013-06-06-usage.md @@ -3,6 +3,7 @@ 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`): @@ -27,7 +28,7 @@ where `title` is the title of page, `category` is one of the categories defined ./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: +Will produce a file `_posts/2013-06-05-my-new-page.md` with the [front-matter](http://jekyllrb.com/docs/frontmatter/) already defined: ```html --- @@ -37,3 +38,23 @@ 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. From 5643313219bcf06ffcedf944724a46392ff31ae2 Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Fri, 12 Jul 2013 09:21:52 -0400 Subject: [PATCH 06/26] Update changelog --- _posts/2013-06-05-changelog.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/_posts/2013-06-05-changelog.md b/_posts/2013-06-05-changelog.md index 591e3e9a..803bbaf7 100644 --- a/_posts/2013-06-05-changelog.md +++ b/_posts/2013-06-05-changelog.md @@ -5,6 +5,24 @@ category: dev order: 1 --- +#### 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 From e8f11b81552081de856bba03a831dd9125549188 Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Mon, 15 Jul 2013 12:54:44 -0400 Subject: [PATCH 07/26] Update changelog --- _posts/2013-06-05-changelog.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_posts/2013-06-05-changelog.md b/_posts/2013-06-05-changelog.md index 803bbaf7..f06fc4d2 100644 --- a/_posts/2013-06-05-changelog.md +++ b/_posts/2013-06-05-changelog.md @@ -5,6 +5,12 @@ category: dev order: 1 --- +#### 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 From 717e2d3a5f4bc01d8c302e1b4f542ea7ccf221cc Mon Sep 17 00:00:00 2001 From: Byron Ruth Date: Mon, 10 Feb 2014 10:54:43 -0500 Subject: [PATCH 08/26] Default to using native textContent property innerText is an IE-specific property that certain browsers support (Chrome) for cross-compatibility. Fix #7 --- _layouts/default.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_layouts/default.html b/_layouts/default.html index bfad2d6d..da45dbcd 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -63,7 +63,7 @@ var order, li = navLis[i]; if (li.classList.contains('nav-header')) { - section = li.innerText; + section = li.textContent || li.innerText; sections.push(section); headers[section] = li; continue; From 04ed3ef918124eac8659086b2cfecc0a0283055e Mon Sep 17 00:00:00 2001 From: "R.I.Pienaar"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.
+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`): From 87809fd16e061b982bcc7382909f9df314c624d7 Mon Sep 17 00:00:00 2001 From: rallech