Skip to content
This repository has been archived by the owner on Jul 12, 2018. It is now read-only.


Remove steps for posting to 18f-pages and add steps to post to Federa…
Browse files Browse the repository at this point in the history

This commit removes all of the instructions that described the process for adding a guide to the now defunct pages server. These instructions are replaced with instructions that describe the process for adding a guide to Federalist.

Ref #90
  • Loading branch information
jmhooper committed Jan 20, 2017
1 parent 79c3581 commit b1660dd
Show file tree
Hide file tree
Showing 14 changed files with 46 additions and 134 deletions.
7 changes: 0 additions & 7 deletions
Original file line number Diff line number Diff line change
Expand Up @@ -72,13 +72,6 @@ The Guides Template (either [running locally](http://localhost:4000) or the
[published version]( will walk you
through the rest of the steps to edit and publish your guide.

### Staging version (for 18F team members)

In addition to the `18f-pages` branch, you can create an `18f-pages-staging`
branch and changes to that branch will be published to
``, which is identical to
`` but provides authenticated access.

### Public domain

This project is in the worldwide [public domain]( As stated in [CONTRIBUTING](
Expand Down
76 changes: 10 additions & 66 deletions _pages/
Original file line number Diff line number Diff line change
Expand Up @@ -7,38 +7,18 @@ need them.
### Checking the build log

If your site did not rebuild after pushing an update, see the latest build log
at ``, where `MY-SITE` is the name of
your Guide's repository. For example, the latest build log for this site is
on Federalist. Go to []( Login
and select your site from the list of sites. Then select "builds" from the

### Server-generated defaults
### Branch previews

The [18F Pages Server]( will
generate an additional configuration file, `_config_18f_pages.yml`, that will
contain the following configuration values:

* **baseurl:** This sets `{% raw %}{{ site.baseurl }}{% endraw %}` to the
repository name without the organization prefix, e.g. `/guides-template`
for the `18F/guides-template` repo, resulting in
``. See the
[Understanding the `baseurl:` property](/update-the-config-file/understanding-baseurl/)
section for details.
* **asset_root:** This sets the location from which the guide will load its
CSS and JavaScript assets.

### Understanding `asset_root`

When developing locally, this value is empty, so your assets are loaded from
your local instance. When hosted on ``, this value is
set as `/guides-template`. This allows all pages on the host that use this
style template to receive CSS and JavaScript updates automatically whenever
`` is updated.

### Overriding server-generated defaults

If you _really_ want, you can prevent the 18F Pages server from generating its
own configuration by adding a `_config_18f_pages.yml` file to your site. The
18F Pages server will use that file instead of generating its own.
When you push a new branch to GitHub, Federalist will build a preview of that
branch. To see branch previews, login at
[]( and select your guide from the
list of sites. Select "Settings" in the sidebar and you'll see a table of all of
the branches Federalist knows about. There you have the option to view a preview
of a given branch.

### Additional scripts and styles

Expand Down Expand Up @@ -72,40 +52,4 @@ Then run `bundle install` and `./go serve` to begin using the local version of
`guides_style_18f`. Any changes within your `guides-style` clone will appear
in your locally-hosted guide upon reload.

### Publishing to internal sites

There are several 18F Pages hosts that require OAuth2 authentication to
access. To publish to one of these hosts, push changes to the following

- **`18f-pages-staging`**: publishes to ``
- **`18f-pages-internal`**: publishes to ``
- **`18f-pages-dev`**: publishes to ``

There is one other internal host, ``, which
does something special. If you publish to a branch matching the pattern
`v[0-9]+.[0-9]+.[0-9]*[a-z]+`, your site will appear on this host with
`baseurl` set to `REPOSITORY/BRANCH`. For example, pushing to a branch called
`v0.9.x` within `18F/guides-template` would publish

### Publishing to internal and external sites from the same branch

By adding an optional `_config_internal.yml` file to your guide, your site
will appear at `` as well as
``. If the contents of this file contain:

internal: true

then you can ensure that sections formatted with the following markup only appear on
``, and are stripped out of the public-facing

{% raw %}{% if site.internal %}TEXT TO BE REDACTED FROM PUBLIC PRODUCTION + STAGING{% endif %}{% endraw %}

For more details, see the [`18f-pages-server`
4 changes: 1 addition & 3 deletions _pages/
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,6 @@ Removing `:create_repo` command from the `./go` script.
Removing old git repository.
Creating a new git repository.
Initialized empty Git repository in .../MY-NEW-GUIDE/.git/
Creating 18f-pages branch.
Switched to a new branch '18f-pages'
Adding files for initial commit.
All done! Run 'git commit' to create your first commit.
Expand Down Expand Up @@ -66,7 +64,7 @@ $ git remote add origin
# Otherwise:
$ git remote add origin
$ git push -u origin 18f-pages
$ git push -u origin master

Note that you can update the description and add a website link to the
Expand Down
13 changes: 2 additions & 11 deletions _pages/
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ It uses [Jekyll]( as the rendering engine.

### Create a new guide/document

To get started on a new guide (or other document based on this theme),
To get started on a new guide (or other document based on this theme),
follow [the "Getting started" instructions in the 18F/guides-template GitHub
repository]( to create
a local clone of this template.
Expand All @@ -24,8 +24,7 @@ contents to begin the rest of the steps.
### Update an existing guide/document

__Note: You need to do this only if your existing guide or document is not already
using the `guides_style_18f` gem or if it does not have an `18f-pages`
using the `guides_style_18f` gem.__

Add the [`guides_style_18f` gem]( to your
guide's `Gemfile`, if it's not already present. You may also wish to copy the
Expand All @@ -36,14 +35,6 @@ with them, you will need to run `./go update_theme`. Or — if you aren't using
a `./go` script — you can run `bundle update --source guides_style_18f`

If your repository already has a `gh-pages` branch, you can create an
`18f-pages` branch from it by running these commands:

$ git checkout -b 18f-pages gh-pages
$ git push origin 18f-pages

Follow the instructions in _Update 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
Expand Down
76 changes: 31 additions & 45 deletions _pages/
Original file line number Diff line number Diff line change
Expand Up @@ -4,65 +4,51 @@ title: Post your guide
Work your way through these steps to set up automated publishing to [18F
Pages]( for your new guide:

- [Create the `18f-pages` branch.](#create-18f-pages-branch)
- [Set the default branch.](#set-default-branch)
- [Create the publishing webhook.](#set-webhook)
- [Trigger a build.](#trigger-a-build)
- [Add the guide to Federalist](#federalist)
- [Set the `baseurl` configuration for Federalist builds](#set-baseurl)
- [Add the new guide to 18F Guides.](#add-new-guide)

### <a name="create-18f-pages-branch"></a>Create the `18f-pages` branch
### <a name="federalist"></a>Add the site to Federalist

**If you ran the `./go create_repo` command from the _GitHub setup_ chapter,
you can skip ahead to the [Create the publishing webhook](#set-webhook)
section. Otherwise, keep reading.**
The first step is to add your guide to [Federalist](
Federalist will host your guide on [18F-pages](, and
automatically re-build the guide in response to changes in its GitHub repository.

To publish your guide automatically to ``, you'll need
to create an `18f-pages` branch. You can do this using the GitHub interface by
clicking the **branch: master** button and entering `18f-pages` in the **Switch
branches/tags** drop-down box:
To get started, navigate to [](htttps://
and login. After you've logged in, click the "Add Website" button.

<img src="{{site.baseurl}}/images/18f-pages.png" alt="GitHub branch creation
<img src="{{site.baseurl}}/images/federalist-add-website.png" alt="The button for adding a website to Federalist">

### <a name="set-default-branch"></a>Set the default branch
On the next page, enter "18f" in the text field for the "Repository Owner's
Name" and the name of your guide's GitHub repository in the text field for the
"Repository's Name". It is important that you type "18f" with a lowercase "f",
or Federalist will not publish the guide to 18F pages.

_Note: If your repository is not just a Jekyll site — for example, if it's a project
repository with a `gh-pages` or `18f-pages` branch for documentation — you can
ignore this step._
<img src="{{site.baseurl}}/images/federalist-add-repository.png" alt="Federalist's interface for adding a new site">

You also need to set `18f-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">
When you click "Submit repository-based site", your guide will be added to

This will present you with the **Options** page. In the **Settings** section, select `18f-pages` from the **Default branch** drop-down menu:<br/>
<img src="{{site.baseurl}}/images/gh-default-branch.png" alt="GitHub default branch option">
### <a name="set-baseurl"></a>Set the `baseurl` configuration for Federalist builds

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 isn't strictly necessary.
Now that Federalist knows about your site, it's time to set the `baseurl`.
Click on your guide in the site list and then select "Settings" from the
sidebar. Scroll down the page until you see a text area for "Custom
Configuration". Here you will set the `baseurl` for your guide.

### <a name="set-webhook"></a>Create the publishing webhook
<img src="{{site.baseurl}}/images/federalist-custom-config.png" alt="Federalist's interface for adding custom configs to a site">

**18F Team members can skip this step!** Our pages are now building via an
organization-wide GitHub webhook. There is no need to set up a repo-specific
webhook anymore.
The value of the `baseurl` will be the name of the GitHub repository where your
guide lives.

**Other users running their own [18F/pages](
instance:** You can either set up a webhook for your organization, or you can
add it per-repository as described below. The steps are nearly identical in
either case.
baseurl: my-github-repo-name

Go into the **Webhooks & Services** section of the **Settings** section
and click the **Add webhook** button. On the following screen, set the
**Payload URL** to ``, leave the **Secret** field
blank, and click **Update webhook**:

<img src="{{site.baseurl}}/images/gh-webhook.png" alt="Set the GitHub webhook">

### <a name="trigger-a-build"></a>Trigger a build

With the webhook in place, push any update to your `18f-pages` branch to your
GitHub repository. Within seconds, your guide should appear at
``. Your guide is now live!
When the `baseurl` is set, Federalist will post guide to
`<your-repo-name>`. This may take up to 5 to 10 minutes.
If you have any difficulty adding your guide, don't hesitate to head over to the
`#federalist-support` Slack channel to ask for help.

### <a name="add-new-guide"></a>Add the new guide to 18F Guides

Expand Down
4 changes: 2 additions & 2 deletions _pages/
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
title: Update the config file
Work your way through these steps to update
Work your way through these steps to update
the `_config.yml` file — this configures the 18F style template for your specific guide:

- [Set the guide name.](#set-name)
Expand Down Expand Up @@ -91,7 +91,7 @@ The `url:` should be ``, where
repository. For the `description:` property, it's OK to enter something
generic like "main repository." However, if you aren't certain about either
value, it's also OK to enter placeholder text for these properties and change
them later, ideally before posting to the 18F Pages server.
them later, ideally before posting to Federalist.

The `repos:` entry of this template contains:

Expand Down
Binary file removed images/18f-pages.png
Binary file not shown.
Binary file added images/federalist-add-repository.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/federalist-add-website.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/federalist-custom-config.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed images/gh-branches-link.png
Binary file not shown.
Binary file removed images/gh-default-branch.png
Binary file not shown.
Binary file removed images/gh-settings-button.png
Binary file not shown.
Binary file removed images/gh-webhook.png
Binary file not shown.

0 comments on commit b1660dd

Please sign in to comment.