GitHub Setup

Work your way through these steps to prepare your GitHub repository:

Create a new local repository

Once you’ve got the _config.yml file up to date, detach your new guide’s history from the template’s. Do this by replacing the original local Git repository — the one your guide inherited — from the template with a completely new local repository, which won’t contain the history from the template and will become the starting point for your new GitHub repository.

When you are ready, execute the following commands to create your new guide:

$ git add .
$ git commit -m 'Initial commit'

You can also do all of the above in one step by running the following command from the top-level directory of your repository:

$ ./go create_guide

To preview your guide locally before making any commits, run the following from the same directory and point your web browser to http://localhost:4000/:

$ ./go serve

Set up SSH access to GitHub

You may want to set up SSH access to GitHub if you haven’t already— this way you won’t need to enter your password and two-factor authentication code every time you push changes to GitHub. Otherwise, you can use https://github.com/DCgov/ URLs to access 18F repos.

Create a new GitHub repository

Now you’re ready to create a new GitHub repository. 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, Add .gitignore, or Add a license. Instead, update the README.md file in your own, local repository, as necessary. Your local repository also already has .gitignore and LICENSE.md files.

After submitting the form to create a new repository, you’ll see GitHub’s instructions to create a local repository and push your changes up to it. You can ignore these instructions. Instead, do the following, replacing MY-NEW-GUIDE with the name of your guide’s repository:

# If you have SSH set up:
$ git remote add origin git@github.com:DCgov/MY-NEW-GUIDE.git

# Otherwise:
$ git remote add origin https://github.com/DCgov/MY-NEW-GUIDE.git

$ git push -u origin gh-pages

Note that you can update the description and add a website link to the repository after creating it.

You will now be able to see your repository at https://dcgov.github.io/MY-NEW-GUIDE.

Close

Glossary of Terms

  • A glossary term

    To add glossary terms, edit the glossary.yaml file in the _data folder.

  • Another term

    Glossary terms need a term, slug, and definition attribute. The term attribute will appear above the definition. The slug is a unique identifier for the term. It should be lowercase, with no special characters or punctuation, and any spaces replaced with a dash.

  • Yet another term

    Want to link to a specific glossary term in your text, like this one here? You will need to edit your markdown like so:

    [this one here](#glossary){:define="yet-another-term"}
    

    Just place the text you want linked in the brackets and the correct slug within the quotes.