This repository has been archived by the owner. It is now read-only.
Permalink
Browse files

Remove steps for posting to 18f-pages and add steps to post to Federa…

…list

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 b1660dd86120f170e2b87508e1e4fa6249283bab
@@ -72,13 +72,6 @@ The Guides Template (either [running locally](http://localhost:4000) or the
[published version](https://pages.18f.gov/guides-template/)) 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
`https://pages-staging.18f.gov/MY-NEW-GUIDE`, which is identical to
`https://pages.18f.gov/` but provides authenticated access.
### Public domain
This project is in the worldwide [public domain](LICENSE.md). As stated in [CONTRIBUTING](CONTRIBUTING.md):
@@ -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 `https://pages.18f.gov/MY-SITE/build.log`, where `MY-SITE` is the name of
your Guide's repository. For example, the latest build log for this site is
[`https://pages.18f.gov/guides-template/build.log`](https://pages.18f.gov/guides-template/build.log).
on Federalist. Go to [federalist.18f.gov](https://federalist.18f.gov). Login
and select your site from the list of sites. Then select "builds" from the
sidebar.
### Server-generated defaults
### Branch previews
The [18F Pages Server](https://www.npmjs.com/package/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
`https://pages.18f.gov/guides-template/`. 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 `https://pages.18f.gov/`, 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
`https://pages.18f.gov/guides-template` 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
[federalist.18f.gov](https://federalist.18f.gov) 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
@@ -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
branches:
- **`18f-pages-staging`**: publishes to `https://pages-staging.18f.gov/`
- **`18f-pages-internal`**: publishes to `https://pages-internal.18f.gov/`
- **`18f-pages-dev`**: publishes to `https://pages-dev.18f.gov/`
There is one other internal host, `https://pages-releases.18f.gov/`, 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
`https://pages-releases.18f.gov/guides-template/v0.9.x`.
### 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 `https://pages-internal.18f.gov/` as well as
`https://pages.18f.gov`. If the contents of this file contain:
```yaml
internal: true
```
then you can ensure that sections formatted with the following markup only appear on
`pages-internal.18f.gov`, and are stripped out of the public-facing
`pages.18f.gov`:
<pre>
{% raw %}{% if site.internal %}TEXT TO BE REDACTED FROM PUBLIC PRODUCTION + STAGING{% endif %}{% endraw %}
</pre>
For more details, see the [`18f-pages-server`
README](https://github.com/18F/pages-server#publishing-to-internal-and-external-sites-from-the-same-branch).
@@ -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.
```
@@ -66,7 +64,7 @@ $ git remote add origin git@github.com:18F/MY-NEW-GUIDE.git
# Otherwise:
$ git remote add origin https://github.com/18F/MY-NEW-GUIDE.git
$ 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
@@ -13,7 +13,7 @@ It uses [Jekyll](http://jekyllrb.com/) 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](https://github.com/18F/guides-template/#getting-started) to create
a local clone of this template.
@@ -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`
branch.__
using the `guides_style_18f` gem.__
Add the [`guides_style_18f` gem](https://github.com/18F/guides-style) to your
guide's `Gemfile`, if it's not already present. You may also wish to copy the
@@ -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`
manually.)
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
@@ -4,65 +4,51 @@ title: Post your guide
Work your way through these steps to set up automated publishing to [18F
Pages](https://pages.18f.gov/) 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](https://federalist.18f.gov/).
Federalist will host your guide on [18F-pages](https://pages.18f.gov), and
automatically re-build the guide in response to changes in its GitHub repository.
To publish your guide automatically to `pages.18f.gov`, 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 [federalist.18f.gov](htttps://federalist.18f.gov)
and login. After you've logged in, click the "Add Website" button.
<img src="{{site.baseurl}}/images/18f-pages.png" alt="GitHub branch creation
interface">
<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
Federalist.
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](https://github.com/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.
```yaml
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 `https://pages.18f.gov/deploy`, 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
`https://pages.18f.gov/MY-NEW-GUIDE`. Your guide is now live!
When the `baseurl` is set, Federalist will post guide to
`https://pages.18f.gov/<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
@@ -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)
@@ -91,7 +91,7 @@ The `url:` should be `https://github.com/18F/MY-NEW-GUIDE`, 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:
BIN -23.4 KB images/18f-pages.png
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
BIN -50.5 KB images/gh-webhook.png
Binary file not shown.

0 comments on commit b1660dd

Please sign in to comment.