Flesh out template as an 18F Guides Guide

README.md

@@ -1,19 +1,31 @@
 ## 18F Guides Template
 
-This is a skeleton repo containing the DOCter-based Jekyll template for 18F
-Guides.
+This is a skeleton repo containing the
+[CFPB/DOCter](https://github.com/CFPB/DOCter)-based
+[Jekyll](http://jekyllrb.com/) template for
+[18F Guides](http://18f.github.io/guides/).
 
 ### Generating the site/hosting locally
 
 You will need [Ruby](https://www.ruby-lang.org) ( > version 2.1.5 ). You may
-also consider using a Ruby version manager such as
-[rbenv](https://github.com/sstephenson/rbenv) to help ensure that Ruby version
-upgrades don't mean all your [gems](https://rubygems.org/) will need to be
-rebuilt.
+consider using a Ruby version manager such as
+[rbenv](https://github.com/sstephenson/rbenv) or [rvm](https://rvm.io/) to
+help ensure that Ruby version upgrades don't mean all your
+[gems](https://rubygems.org/) will need to be rebuilt.
+
+On OS X, you can use [Homebrew](http://brew.sh/) to install Ruby in
+`/usr/local/bin`, which may require you to update your `$PATH` environment
+variable:
+
+```shell
+$ brew update
+$ brew install ruby
+```
 
-To run your own local instance:
+To create a new guide and serve it locally, where `MY-NEW-GUIDE` is the name
+of your new repository:
 
-```
+```shell
 $ git clone git@github.com:18F/guides-template.git MY-NEW-GUIDE
 $ cd MY-NEW-GUIDE
 $ ./go init
@@ -22,8 +34,10 @@ $ ./go serve
 
 This will check that your Ruby version is supported, install the [Bundler
 gem](http://bundler.io/) if it is not yet installed, install all the gems
-needed by the playbook, and launch a running instance on
-`http://localhost:4000/guide/`.
+needed by the template, and launch a running instance on
+`http://localhost:4000/guide/`. (Make sure to include the `/`! The built-in
+Jekyll webserver doesn't redirect to it.) That page contains further
+instructions on how to adapt the template to a new guide repository.
 
 After going through these steps, run `./go` to see a list of available
 commands. The `serve` command is the most common for routine development.

_config.yml

@@ -1,4 +1,4 @@
-baseurl: /guide
+baseurl: /guides-template
 markdown: redcarpet
 name: 18F Guides Template
 
@@ -11,14 +11,29 @@ author:
 
 # Point the logo URL at a file in your repo or hosted elsewhere by your organization
 logourl: /assets/img/18f-logo.png
-logoalt: 18f logo
+logoalt: 18F logo
 
 # Navigation
 # List links that should appear in the site sidebar here
 navigation:
 - text: Home
   url: index.html
   internal: true
+- text: Adding a New Page
+  url: adding-a-new-page/
+  internal: true
+- text: Adding Images
+  url: adding-images/
+  internal: true
+- text: Updating the Config File
+  url: updating-the-config-file/
+  internal: true
+- text: GitHub Setup
+  url: github-setup/
+  internal: true
+- text: Post Your Guide
+  url: post-your-guide/
+  internal: true
 
 repos:
 - name: Guides Template

index.md

@@ -1,9 +1,29 @@
 ---
-published: true
 permalink: /
 layout: default
-filename: index.md
 title: Home
-page_title: Home
 ---
-This is the template used for the [Jekyll](http://jekyll.io)-based [18F Guides](http://18f.github.io/guides).
+This is the template used for the [Jekyll](http://jekyllrb.com/)-based [18F
+Guides](http://18f.github.io/guides), derived from
+[CFPB/DOCter](https://github.com/CFPB/DOCter). It is structured to act as an
+18F Guides Guide. The repository for this template is
+[18F/guides-template](https://github.com/18F/guides-template/).
+
+## Creating a guide
+
+To create a brand new guide, first follow the instructions in the
+[README.md](https://github.com/18F/guides-template/blob/master/README.md) file
+of this guide's GitHub repository to create a local clone of this template.
+
+Once you've created a new clone, click the _Adding a New Page_ entry in the
+table of contents.
+
+## Updating an existing guide
+
+Copy the `_includes`, `_layouts`, and `assets` directories from this template
+and follow the instructions in _Updating the Config File_ to update your
+`_config.yml` accordingly.
+
+You may also need to consult the _GitHub Setup_ and _Post Your Guide_ chapters
+to ensure your guide is correctly published to `18f.github.io` and linked from
+the main [18F Guides](http://18f.github.io/guides/) site.

pages/config.md

@@ -0,0 +1,60 @@
+---
+permalink: /updating-the-config-file/
+layout: default
+title: Updating the Config File
+---
+- [Set the base URL and guide name](#set-baseurl-and-name)
+- [Register new pages](#register-new-pages)
+- [Update the repository list](#update-repository-list)
+
+Once you're finished updating the config file, click the _GitHub Setup_
+entry in the table of contents.
+
+## <a name="set-baseurl-and-name"></a>Set the base URL and guide name
+
+The configuration file is called `_config.yml`. The first properties to update
+are `baseurl:`, which determines the top-level URL of your guide relative to
+the host; and `name:`, which appears as the guide's overall title. Make sure to
+set `baseurl:` to the same name as your new guide's repository; this is
+important to ensure that it will be published correctly. For example, for this
+template, these values are set to:
+
+```yaml
+baseurl: {{site.baseurl}}
+name: {{site.name}}
+```
+
+When run locally, the URL for this guide is
+`http://localhost:4000{{site.baseurl}}/`. _Remember to include the trailing
+`/` when serving locally!_ The Jekyll built-in webserver doesn't redirect to
+it automatically.
+
+The URLs of the individual section pages are relative to the `baseurl:`. For
+example, the `permalink:` of this page is `{{page.permalink}}`. The full local
+URL is `http://localhost:4000{{site.baseurl}}{{page.permalink}}`.
+
+## <a name="register-new-pages"></a>Register new pages
+
+The `navigation:` list is used to generate the table of contents. Add a new
+entry for any new page added. For example, the `navigation:` section of this
+guide contains:
+
+```yaml
+{% for i in site.navigation %}- text: {{ i.text }}
+  url: {{ i.url }}
+  internal: {{ i.internal }}
+{% endfor %}```
+
+## <a name="update-repository-list"></a>Update the repository list
+
+You will also need to update the `repos:` list to reflect the GitHub
+repository containing your guide. The `repos:` entry of this template
+contains:
+
+```yaml
+repos:{% for i in site.repos %}
+- name: {{ i.name }}
+  description: {{ i.description }}
+  url: {{ i.url }}
+{% endfor %}
+```

pages/github.md

@@ -0,0 +1,50 @@
+---
+permalink: /github-setup/
+layout: default
+title: GitHub Setup
+---
+- [Create a new local repository](#create-local-repo)
+- [Create a new 18F GitHub repository](#create-18f-repo)
+
+Once you're finished pushing to your new 18F guide repo on GitHub, click the
+_Post Your Guide_ entry in the table of contents for the final steps to
+publish your guide.
+
+## <a name="create-local-repo"></a>Create a new local repository
+
+Once you've got the `_config.yml` file up-to-date, execute the following to
+detach from the the original template repository and create a new one for your
+guide:
+
+```
+$ rm -rf .git
+$ git init
+$ git add .
+$ git commit -m 'Initial commit'
+```
+
+## <a name="create-18f-repo"></a>Create a new 18F GitHub repository
+
+Now you're ready to [create a new 18F GitHub
+repository](https://github.com/organizations/18F/repositories/new). You'll
+want to set the `Public` attribute under the **Team** section and add a
+fitting `Description`.
+
+Do _not_ select **Initialize this repository with a README**. Instead, update
+the `README.md` file in your own local repository as necessary.
+
+After submitting the form to create a new repository, you will see GitHub's
+instructions to create a local repository and push your changes up to it. At
+this point, do the following, replacing `MY-NEW-GUIDE` with the name of your
+guide's repository:
+
+```
+$ git remote add origin git@github.com:18F/MY-NEW-GUIDE.git
+$ git push -u origin master
+```
+
+Note that you can update the description and add a website link to the
+repository after creating it:
+
+<img src="{{site.baseurl}}/images/description.png" alt="Setting the
+description and website of the GitHub repository">

pages/images.md

@@ -0,0 +1,23 @@
+---
+permalink: /adding-images/
+layout: default
+title: Adding Images
+---
+To add images to your guide, first create an `images/` directory and place
+your images inside. You may want to use
+[jpegoptim](https://github.com/tjko/jpegoptim) or
+[optipng](http://optipng.sourceforge.net/) to optimize your images. (On OS X,
+both are available via [Homebrew](http://brew.sh/).)
+
+Then, from your documents, you can reference your images like so (abiding by
+the advice in the [Accessibility
+Guide](http://18f.github.io/accessibility/images/)):
+
+```
+<img src="{%raw%}{{site.baseurl}}{%endraw%}/images/images.png" alt="Example of
+an included image">
+```
+
+<img src="{{site.baseurl}}/images/images.png" alt="Example of an included image">
+
+Now click on the _Updating the Config File_ entry in the table of contents.

pages/new-page.md

@@ -0,0 +1,28 @@
+---
+permalink: /adding-a-new-page/
+layout: default
+title: Adding a New Page
+---
+To add new pages to the guide, first create a new
+[Markdown](http://daringfireball.net/projects/markdown/syntax) file in the
+`pages/` directory of the repository. As an example, the Markdown text for
+this page is
+[`pages/new-page.md`](https://github.com/18F/guides-template/blob/master/pages/new-page.md).
+
+The Markdown document begins with this [YAML front
+matter](http://jekyllrb.com/docs/frontmatter/):
+
+```yaml
+---
+permalink: {{ page.permalink }}
+layout: {{ page.layout }}
+title: {{ page.title }}
+---
+```
+
+_The `/` at the end of the `permalink:` attribute is important!_ It ensures
+the page is generated as `{{ page.permalink }}index.html`. Without it, it would
+be generated as `{{ page.permalink | remove_first: '/' | replace:'/','.'}}html`.
+
+Now click on the _Adding Images_ entry in the table of contents to learn how
+to add images to your guide.

pages/posting.md

@@ -0,0 +1,45 @@
+---
+permalink: /post-your-guide/
+layout: default
+title: Post Your Guide
+---
+**NOTICE:** This chapter reflects the _current_ method of publishing and
+posting 18F Guides. This may change in the near future; stay tuned.
+
+- [Create the `gh-pages` branch](#create-gh-pages-branch)
+- [Set the default branch](#set-default-branch)
+- [Add the new guide to 18F Guides](#add-new-guide)
+
+## <a name="#create-gh-pages-branch"></a>Create the `gh-pages` branch
+
+In order to publish your guide automatically to `18f.github.io`, you will need
+to create a `gh-pages` branch. You can do this using the GitHub interface by
+clicking the **branch: master** button and entering `gh-pages` in the **Switch
+branches/tags** drop-down box:
+
+<img src="{{site.baseurl}}/images/gh-pages.png" alt="GitHub branch creation
+interface">
+
+## <a name="#set-default-branch"></a>Set the default branch
+
+You also need to set `gh-pages` branch as the default. First, click the **Settings** page button (on the right side of the screen):<br/>
+<img src="{{site.baseurl}}/images/gh-settings-button.png" alt="GitHub settings page button">
+
+This will present you with the **Options** page. In the **Settings** section, select `gh-pages` from the **Default branch** drop-down menu:<br/>
+<img src="{{site.baseurl}}/images/gh-default-branch.png" alt="GitHub default branch option">
+
+Deleting the original `master` branch, both on GitHub and locally, is left as
+an exercise for the reader. Doing so will help avoid confusion in the long run,
+but is not strictly necessary.
+
+## <a name="https://github.com/CFPB/DOCter"></a>Add the new guide to 18F Guides
+
+Now for the final step: Add an entry to the list of [18F
+Guides](http://18f.github.io/guides/) linking to your new guide. You can [use
+this link to edit the file directly in
+GitHub](https://github.com/18F/guides/edit/gh-pages/index.md):
+
+<img src="{{site.baseurl}}/images/gh-add-guide.png" alt="Add the new guide to 18F Guides using the GitHub text editor">
+
+Congratulations! Your guide should now be published and accessible to the world
+as one of the few, the proud, the [18F Guides](http://18f.github.io/guides)!