This is a minimal prototype kit aimed at testing and researching content that's intended to be published via the Whitehall Publisher.
It uses Nanoc, a static site generator written in Ruby.
Govspeak is a simplified 'markup' language based on Markdown. It's designed to be as easy-to-read and easy-to-write as possible.
Clone this app, cd to the repo's root directory and run:
$ npm install
$ bundle installIf that succeeded, we can start the app and have it live reload our changes:
$ bundle exec nanoc liveNavigate to http://localhost:3000 and if you see this, it worked!
Providing you have a GOV.UK PaaS and have
been allocated a space, this prototype is ready to publish. We just need to
give the app a name (see manifest.yml), log in (cf login) and push (cf push).
If you want your prototype to be protected by Basic authentication
you need to add a Staticfile.auth. CloudFoundry's documentation covers the process in
plenty of detail.
Netlify is the easiest way to publish your content on the web and its integration with GitHub is preconfigured - all you need to do is sign up for Netlify, connect your GitHub account, click the 'New site from Git' button, pick your repository and configure these settings:
- Build command:
bundle exec nanoc - Publish directory:
output
After a minute or two your site will be live! The URL will be displayed at the top of the page in the Netlify admin panel and you can change the randomly-generated identifier to something a bit more user-friendly by going into the 'Site details' settings and clicking 'Change site name'.
To add a new page create a .md file in the content directory,
content/example.md for example. The page will now be visible at
http://localhost:3000/example.
For consistency, keep your filenames lower case, avoid non-alphanumeric characters and use dashes instead of spaces.
Frontmatter is a block of YAML at the top of a file that contains metadata. By default, this app only makes use of the title, but any structured data can added.
---
title: "My amazing page"
---
View the included index file content/index.md for an example of using
metadata in a govspeak template.
A hierarchy of content can be created using directories. Each directory should have
a corresponding index, so the hello/ directory should be placed alongside hello.md.
| File | Path |
|---|---|
content/hello.md |
http://localhost:3000/hello |
content/hello/world.md |
http://localhost:3000/hello/world |
content/hello/nice-to-meet-you.md |
http://localhost:3000/hello/nice-to-meet-you |
Routing and breadcrumbs are automatically handled.
Govspeak does not support level one
headings by choice. The
document's title will be displayed in a <h1> tag at the top of the page, all
subsequent headings should be <h2>-<h6>.
The default styling for additional <h1> tags is intentionally ugly to
discourage their use.
Contributions are always welcome. If you're able to, raising a PR is the preferred method. If we've missed something or you have a suggestion for a new feature suggest it in a GitHub issue.
If something isn't working or doesn't make sense you can ask a question via a GitHub issue. For more general framework support see Nanoc's official documentation.