GOV.UK markdown prototype kit

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.

What is govuk_markdown?

govuk_markdown is a markdown renderer that supports a subset of the GOV.UK Design System's text formatting options, namely inset text and details.

Requirements

• Ruby
• NPM

Getting started

Clone this app, cd to the repo's root directory and run:

$ npm install
$ bundle install

If that succeeded, we can start the app and have it live reload our changes:

$ bundle exec nanoc live

Navigate to http://localhost:3000 and if you see this, it worked!

Publishing content

GOV.UK PaaS

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

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'.

Adding content

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

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 template.

Nesting pages

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.

Level one headings (or lack thereof)

This kit 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.

Contributing

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.

Support

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.