18f/guides-template

Jekyll template for 18F Guides, based on CFPB/DOCter

18F Guides Template

This is a skeleton repo containing the CFPB/DOCter-based Jekyll template for 18F Guides.

Getting started

Installing Ruby

You will need Ruby ( > version 2.2.4 ). To check whether it's already installed on a UNIX-like system, open up a terminal window (e.g. Terminal on OS X) and type ruby -v at the command prompt. For example, you should see something similar to the following:

$ ruby -v
ruby 2.2.4p230 (2015-12-16 revision 53155) [x86_64-darwin15]

If the version number is less than 2.2.4, or instead you see something like:

$ ruby -v
-bash: ruby: command not found

Then Ruby is not installed, and you should choose one of the installation methods below. The "Installing Ruby" page of the official Ruby language web site explains how to do this in a number of ways across many different systems.

Quickest Ruby install/upgrade for OS X

On OS X, you can use Homebrew to install Ruby in /usr/local/bin, which may require you to update your $PATH environment variable:

$ brew update
$ brew install ruby

Optional: using a version manager

Whether or not Ruby is already installed, we strongly recommend using a Ruby version manager such as rbenv or rvm to help ensure that Ruby version upgrades don't mean all your gems will need to be rebuilt.

Cloning and serving the Guides Template locally

To create a new guide and serve it locally, where MY-NEW-GUIDE is the name of your new repository:

$ git clone https://github.com/18F/guides-template.git MY-NEW-GUIDE
$ cd MY-NEW-GUIDE
$ ./go serve

The ./go script will check that your Ruby version is supported, install the Bundler gem if it is not yet installed, install all the gems needed by the template, and launch a running instance on http://localhost:4000/.

Follow the template instructions

The Guides Template (either running locally or the published version) will walk you through the rest of the steps to edit and publish your guide.

Public domain

This project is in the worldwide public domain. As stated in CONTRIBUTING:

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.

guides-template's Issues

figure out how to share templates

As this is currently structured, the template being updated won't be reflected in the individual guides.

There is a maximum number of child stories that can be under a parent story and no way to scroll through more of them.

It appears that you can only place 12 child stories under a parent story. There is currently no way to scroll down to see more of them. (There are 15 child stories under the parent in this example.)

Hi! I am using the templates for another technical guides in my organization. However, I need to remove the favicon of the fornt page. How can I remove it?

give guidance about how to include custom scripts/stylesheets

For the Before You Ship site, which uses this gem, I was trying to figure out a good way to include a script on every page of the site. Since the layout is embedded in the gem, I wasn't able to modify it directly. I ended up figuring out a workaround using a nested layout (see _config.yml and _layouts/default.html in 18F/before-you-ship#71), but it feels like a bit of a hack. Curious if there are other ideas about how to accomplish this?

/cc @fureigh

Accessibility wrt color

From an email I received about the content guide:

I like the 18F content style guide very much. I just wish it was easier to read.

I know that the Federal government is not required to follow WCAG 2.0 accessibility standards yet, but designers could still have some compassion for those of us with aging eyes.

The WCAG 2.0 guideline for contrast is a ratio of 4.5:1. The contrast in the left navigation bar is 1.9:1. The text is better but still difficult to read without effort.

This fad of minimalist sites with grey on white can't end soon enough for me.

Blue highlight for menu not showing up

on https://pages.18f.gov/joining-18f/ theres an issue with the menu. I noticed that when there are highlighted lists like job descriptions or interview breakdowns, the blue highlight on the menu disappears. This makes it particularly difficult if you're looking at in on the phone. Any help in fixing this, I would be much obliged!

update for a post-Pages world

• Use master instead of 18f-pages
• Update references to 18f-pages and Pages in this repo
• Include new publishing step of adding the site to Federalist
• Consolidate the instructions living in a few places
  • https://pages.18f.gov/guides-template/post-your-guide/
  • https://github.com/18F/guides-template/#readme
  • https://github.com/18f/pages#publishing-to-pages18fgov

Add a way to submit an issue at the bottom of each page next to "edit this page"

Referenced here: 18F/open-source-guide#10

Govfresh published an article about the open source guide and suggested that we include a "Submit feedback" on each page- which would direct people to the repo's issues next to "edit this page", which directs people to the edit function for each page. I think this would be a good addition to the guides.

18F favicon

Can we add the 18F favicon to the template so whenever a new guide is created, it has the 18F icon on tabs?

Add a way to access the 18F Guides home page from each guide

People who are reading one guide might not know that we have other handy documents on different topics. It would be nice to have a away back to the main guide list page (https://pages.18f.gov/guides/) from any interior page of any guide, but certainly from the landing page for each guide (https://pages.18f.gov/agile/ https://pages.18f.gov/content-guide/ etc).

Perhaps it could go either in the footer, or up top under the blue header line?

The style should probably be the same as for the team page:

Website not available

See: https://pages.18f.gov/guides-template/

provide instructions for GitHub for Mac

I imagine a lot of (people we want to be) Guide creators won't be comfortable with the command line...would be good to provide a less intimidating path for them.

One button PDF download of guides

Add an optional function that would allow guide content to be downloaded as a single, well-formatted PDF. This has been requested by users as a way to bring guides to management in meetings who wouldn't see them otherwise.

Vertical height triggers switch to mobile view

Whenever I make my browser window shorter, it switches to mobile view, which I don't want. Most of the times this is an issue when I open up web inspector on the page.

Can we remove this vertical media query?

This is what it looks like:

`copy-template` doesn't include .gitignore

Nav highlighting is fragile and breaks easily

Could not find blankslate-2.1.2.4 in any of the sources

Got this when running ./go serve.

Corrected by running bundle install.

Nav menu can only hold so many elements

Basically, it can't scroll.

via Control Masonry

---

Chrome is showing .nav-children with a max-hight: 400px;. This is limiting the number of controls showing up in the rendered pages. There is currently no overflow setting, either. The end result is it appears many controls are missing after the page generation.

.nav-children {
    display: block;
    max-height: 400px;
    opacity: 1;
    -webkit-transition: max-height .2s, opacity .2s;
    -moz-transition: max-height .2s, opacity .2s;
    -o-transition: max-height .2s, opacity .2s;
    transition: max-height .2s, opacity .2s;
}

Best solution might be an overflow: scroll;.

---

Compatibility with the US Web Design Standards?

Hi Folks - Curious if anyone knows of a similar "guide" template that has the Web Design standards baked in? It seems the Design Standards docs themselves are largely modeled on this theme.

Basically, I'm looking to create up a content-focused Jekyll site that matches the styles of the Design Standards docs. Forking the design standards is one way forward, but I'd prefer to start with a "blank slate" that is similar to this template. Thanks for any pointers!

Agile Guide Update

We rewrote the Agile guide (agile.18F.gov). What do I do to replace what's there now?

User Story!

Start at https://pages.18f.gov/guides/, see the link, go to the link to the template.

On https://pages.18f.gov/guides-template/, most of the stuff in the introduction doesn't make sense to me. Do I need to know it? It's also confusing why there are so many instructions to update an existing guide (unless the issue is that old guides don't have the new fancy stuff). In any case, I see that I should go to the Readme and go there!

On https://github.com/18F/guides-template/blob/18f-pages/README.md, is there a way to check if I have Ruby? (Will knows he has Ruby , is not sure if others will). It's also not clear if I can do the same by forking the repo on GitHub - will that work? (Discussion ensued on Slack, this is addressed later in the process but an update to instructions might be helpful?)

(Run the brew commands, get slightly freaked out by the number of edited formulas)

Hit an error when trying to clone, #42 addresses this.

I think access Localhost and am a little confused that I am now supposed to work down the side lists (vs "updating an existing guide" - I wonder if that is the next step since my guide exists. However, I figure it out and start working my way down the lieft hand columns

https://pages.18f.gov/guides-template/adding-a-new-page/ is not newbie friendly, but I think that's ok given the fact that this isn't a training on "how to work a GitHub repo". I do just fine.

https://pages.18f.gov/guides-template/updating-the-config-file/ is slightly confusing because the "Once you're finished updating the config file, click the GitHub Setup entry in the table of contents." text is above everything else. I'll submit a PR to clarify that: #44

Also on that page, I am not sure what the description of my repo should be (also, at that point, I might not know the URL). Maybe add a note that explains that the user can some back to this after publishing on GitHub, or to use their repo's name as the root?

I also think we should add instructions to modify the "back link" if appropriate since this should fall under 18F Pages, not 18F Guides. And, the Google Analytics link was already set - can that instruction be removed?

On https://pages.18f.gov/guides-template/updating-the-config-file/understanding-baseurl/, it's not clear me when this should come up - when I'm creating new pages? I haven't made a new page yet, so this is confusing.

On https://pages.18f.gov/guides-template/github-setup/, same issue as config file - the top bit is a bit clearer though. I think the command to run ./go create_repo is confusing because I thought I already had a repo....oh, now I see in doing it that it creates a whole new one! Neat!

As I create my new repo, I don't know if I should edit .gitignore or "add a license." I will assume not. I make the new repo an ignore the instructions (that part isn't quite clear, that I can ignore everything on that page)

Everything works great for putting the repo on the 18F org and adding the webhook. I make some local changes (and run into an issue where I don't have a contributing.md file - Mike B is fixing in #46). I also delete most of the content on index.md and push a commit up using GitHub for Mac! It all worked!

Make the left nav a numbered list

Since this is a guide that must be followed in order and with every step, I think the left nav should be an ordered list and then we can remove the "Now go to the next step" from the bottom of each section. Thoughts?