Merge pull request #244 from alphagov/docs_app

Create demo app and move documentation to sub-app

Gruntfile.js

@@ -19,6 +19,13 @@ module.exports = function (grunt) {
           src: ['*.scss'],
           dest: 'public/stylesheets/',
           ext: '.css'
+        },
+        {
+          expand: true,
+          cwd: 'docs/assets/sass',
+          src: ['*.scss'],
+          dest: 'public/stylesheets/',
+          ext: '.css'
         }]
       }
     },
@@ -31,6 +38,11 @@ module.exports = function (grunt) {
           cwd: 'app/assets/',
           src: ['**/*', '!sass/**'],
           dest: 'public/'
+        }, {
+          expand: true,
+          cwd: 'docs/assets/',
+          src: ['**/*', '!sass/**'],
+          dest: 'public/'
         }],
         ignoreInDest: '**/stylesheets/**',
         updateAndDelete: true

app/config.js

@@ -12,6 +12,9 @@ module.exports = {
   // Enable or disable password protection on production
   useAuth: 'true',
 
+  // Enable or disable built-in docs and examples.
+  useDocumentation: 'true',
+
   // Force HTTP to redirect to HTTPs on production
   useHttps: 'true',
 

app/routes.js

@@ -1,33 +1,11 @@
 var express = require('express')
 var router = express.Router()
 
+// Route index page
 router.get('/', function (req, res) {
   res.render('index')
 })
 
-// Example routes - feel free to delete these
-
-// Passing data into a page
-
-router.get('/examples/template-data', function (req, res) {
-  res.render('examples/template-data', { 'name': 'Foo' })
-})
-
-// Branching
-
-router.get('/examples/over-18', function (req, res) {
-  // get the answer from the query string (eg. ?over18=false)
-  var over18 = req.query.over18
-
-  if (over18 === 'false') {
-    // redirect to the relevant page
-    res.redirect('/examples/under-18')
-  } else {
-    // if over18 is any other value (or is missing) render the page requested
-    res.render('examples/over-18')
-  }
-})
-
 // add your routes here
 
 module.exports = router

app/views/index.html

@@ -13,7 +13,7 @@
       <h1 class="heading-xlarge">
         The GOV.UK prototype kit
         <span class="heading-secondary">{{releaseVersion}}</span>
-      </h1>
+      </h1>{{releaseVersion | log }}
       <p>
         This kit lets you rapidly create HTML prototypes of GOV.UK services.
       </p>
@@ -31,9 +31,8 @@ <h2 class="heading-medium">About this page</h2>
 			<h2 class="heading-medium">Examples and documentation</h2>
 
 			<ul class="list list-bullet">
-				<li><a href="/examples">Example pages and patterns</a></li>
-				<li><a href="https://github.com/alphagov/govuk_prototype_kit/tree/master/docs">
-						Read the full documentation</a></li>
+				<li><a href="/docs/tutorials-and-examples">Example pages and documentation</a></li>
+				<li><a href="https://github.com/alphagov/govuk_prototype_kit">GitHub</a></li>
 			</ul>
 
       <h2 class="heading-medium">Other resources</h2>

docs/assets/javascripts/docs.js

@@ -0,0 +1,28 @@
+/* global $ */
+/* global GOVUK */
+
+// Warn about using the kit in production
+if (
+  window.sessionStorage && window.sessionStorage.getItem('prototypeWarning') !== 'false' &&
+  window.console && window.console.info
+) {
+  window.console.info('GOV.UK Prototype Kit - do not use for production')
+  window.sessionStorage.setItem('prototypeWarning', true)
+}
+
+$(document).ready(function () {
+  // Use GOV.UK selection-buttons.js to set selected
+  // and focused states for block labels
+  var $blockLabels = $(".block-label input[type='radio'], .block-label input[type='checkbox']")
+  new GOVUK.SelectionButtons($blockLabels) // eslint-disable-line
+
+  // Use GOV.UK shim-links-with-button-role.js to trigger a link styled to look like a button,
+  // with role="button" when the space key is pressed.
+  GOVUK.shimLinksWithButtonRole.init()
+
+  // Show and hide toggled content
+  // Where .block-label uses the data-target attribute
+  // to toggle hidden content
+  var showHideContent = new GOVUK.ShowHideContent()
+  showHideContent.init()
+})

docs/assets/sass/docs.scss

@@ -0,0 +1,52 @@
+@import "govuk-elements";
+
+.markdown {
+	h1 {
+		@extend .heading-xlarge;
+	}
+
+	h2 {
+		@extend .heading-large;
+	}
+
+	h3 {
+		@extend .heading-medium;
+	}
+
+	h4 {
+		@extend .heading-small;
+	}
+
+	code {
+		background: $grey-4;
+		padding: 3px;
+		font-size: 1em;
+	}
+
+	pre > code {
+		@extend .code;
+		display: block;
+		@extend .panel;
+		@extend .panel-border-wide;
+		margin-bottom: 15px;
+	}
+
+	img {
+		max-width: 100%;
+	}
+
+	ul {
+		@extend .list;
+		@extend .list-bullet;
+	}
+
+	blockquote {
+		@extend .panel;
+		@extend .panel-border-wide;
+	}
+
+	strong {
+		font-weight: 700;
+	}
+}
+

docs/install/install-the-kit.md → docs/documentation/install/install-the-kit.md

@@ -12,7 +12,7 @@ We recommend keeping all your prototypes in one folder called `projects`.
 
 Create a folder called `projects` in your home folder. You can open your home folder by opening a new finder window, and selecting `go > home` from the top menu.
 
-![Screenshot of a 'projects' folder in the mac home folder](../assets/images/mac-home-folder-projects.png)
+![Screenshot of a 'projects' folder in the mac home folder](/public/images/docs/mac-home-folder-projects.png)
 
 #### Windows users
 
@@ -87,10 +87,4 @@ npm install
 ```
 The install may take up to a minute. Whilst installing it may `WARN` about some items - this is ok. As long as there are no `ERROR`s you can continue.
 
----
-[Previous page (requirements)](requirements.md)
-
-[Next page (run the kit)](run-the-kit.md)
-
----
-[Documentation index](../README.md)
+<a href="run-the-kit.md" class="button">Next (run the kit)</a>

docs/install/introduction.md → docs/documentation/install/introduction.md

@@ -12,10 +12,8 @@ If you’re comfortable using git and the terminal, you may prefer the [develope
 
 The prototype kit provides a simple way to make interactive prototypes that look and feel like pages on GOV.UK. These prototypes can be used to design and lay out pages, and to use in user research.
 
-You’ll use a copy of the kit for each different prototype you want to make - they’re self contained. Once installed, the kit uses about 100mb.
 
----
-[Next page (requirements)](requirements.md)
 
----
-[Documentation index](../README.md)
+You’ll use a copy of the kit for each different prototype you want to make - they’re self contained. Once installed, the kit uses about 100mb.
+
+<a href="requirements.md" class="button">Next (requirements)</a>

docs/install/requirements.md → docs/documentation/install/requirements.md

@@ -97,14 +97,8 @@ xcode-select --install
 ```
 If you already have command line tools, this will display `xcode-select: error: command line tools are already installed, use "Software Update" to install updates`.
 
-![Screenshot of Command line tools popup message](../assets/images/installing-mavericks-popup.png)
+![Screenshot of Command line tools popup message](/public/images/docs/installing-mavericks-popup.png)
 
 If you don’t have command line tools, it will open an installer. Follow the instructions to install the command line tools.
 
----
-[Previous page (introduction)](introduction.md)
-
-[Next page (install the kit)](install-the-kit.md)
-
----
-[Documentation index](../README.md)
+<a href="install-the-kit.md" class="button">Next (install the kit)</a>

docs/install/run-the-kit.md → docs/documentation/install/run-the-kit.md

@@ -24,7 +24,7 @@ In your web browser, visit <a href="http://localhost:3000" target="_blank">http:
 
 You should see the prototype welcome page.
 
-![Screenshot of the prototype kit homepage](../assets/images/prototype_kit_homepage.png)
+![Screenshot of the prototype kit homepage](/public/images/docs/prototype-kit-homepage.png)
 
 ## Quitting the kit
 
@@ -38,8 +38,4 @@ In terminal press the `ctrl` and `c` keys together.
 
 The kit is now installed. Congratulations!
 
----
-[Previous page (install the kit)](install-the-kit.md)
-
----
-[Documentation index](../README.md)
+<!-- <a href="../../readme.md" class="button">Return to Getting Started</a> -->

docs/guides/publishing-on-heroku.md → docs/documentation/publishing-on-heroku.md

@@ -66,7 +66,3 @@ After your work is deployed, you will be able to view it on the web by visiting
 You can run `heroku open` to open your prototype in a browser.
 
 > Heroku puts apps to sleep that haven’t been accessed in a while - so if you’ve not visited your prototype for a while it may take a few seconds to open.
-
-
----
-[Documentation index](../README.md)

docs/guides/setting-up-git.md → docs/documentation/setting-up-git.md

@@ -6,7 +6,7 @@ This guide will walk you through setting up a git repo (repository) and committi
 
 > You don’t *have* to use Git to use the prototype kit, but it will be really useful if you learn some basics.
 
-> Git is not the same as GitHub. Git stores versions of your work, and lets you collaborate more easily with others. Github puts it all online with a nice web interface.
+> Git is not the same as GitHub. Git stores versions of your work, and lets you collaborate more easily with others. GitHub puts it all online with a nice web interface.
 
 You'll need to install Git first. Installation instructions for Mac, Windows, and Linux can be found [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). Once you've done that, read below to get set up.
 
@@ -22,7 +22,7 @@ git config --global user.email "YOUR EMAIL ADDRESS"
 
 For example,  `git config --global user.name "John Smith"`
 
-If you have an account on Github, use the *same* email address for both.
+If you have an account on GitHub, use the *same* email address for both.
 
 ## 2) Initialise a Git repo
 
@@ -85,14 +85,8 @@ Run `git status` again and it should say `Nothing to commit` - all the changes y
 
 We recommend doing a tutorial on Git basics. Once you’ve done that, the best thing is to keep using Git each day (commit at least one change, etc) so it becomes familiar to you. Ask developers on your team to help you until you’re comfortable on your own.
 
-[Github tutorial on git](https://try.github.io/levels/1/challenges/1)
+[GitHub tutorial on git](https://try.github.io/levels/1/challenges/1)
 
 [Advanced git tutorial](http://think-like-a-git.net/)
 
 > Git can be used via the command line or using an app. It’s up to you which you learn. Most developers use the command line, so if you’d like help from them, it’s often better to use that.
-
----
-[Next guide (publishing on Heroku)](publishing-on-heroku.md)
-
----
-[Documentation index](../README.md)

docs/documentation_routes.js

@@ -0,0 +1,66 @@
+var express = require('express')
+var fs = require('fs')
+var marked = require('marked')
+var path = require('path')
+var router = express.Router()
+var utils = require('../lib/utils.js')
+
+// Page routes
+
+// Docs index
+router.get('/', function (req, res) {
+  res.render('index')
+})
+
+router.get('/install', function (req, res) {
+  var url = utils.getLatestRelease()
+  res.render('install', { 'releaseURL': url })
+})
+
+// Pages in install folder are markdown
+router.get('/install/:page', function (req, res) {
+  redirectMarkdown(req.params.page, res)
+  var doc = fs.readFileSync(path.join(__dirname, '/documentation/install/', req.params.page + '.md'), 'utf8')
+  var html = marked(doc)
+  res.render('install_template', {'document': html})
+})
+
+// Examples - exampes post here
+router.post('/tutorials-and-examples', function (req, res) {
+  res.redirect('tutorials-and-examples')
+})
+
+// Example routes
+
+// Passing data into a page
+
+router.get('/examples/template-data', function (req, res) {
+  res.render('examples/template-data', { 'name': 'Foo' })
+})
+
+// Branching
+
+router.get('/examples/over-18', function (req, res) {
+  // get the answer from the query string (eg. ?over18=false)
+  var over18 = req.query.over18
+
+  if (over18 === 'false') {
+    // redirect to the relevant page
+    res.redirect('/docs/examples/under-18')
+  } else {
+    // if over18 is any other value (or is missing) render the page requested
+    res.render('examples/over-18')
+  }
+})
+
+module.exports = router
+
+// Strip off markdown extensions if present and redirect
+var redirectMarkdown = function (requestedPage, res) {
+  if (requestedPage.slice(-3).toLowerCase() === '.md') {
+    res.redirect(requestedPage.slice(0, -3))
+  }
+  if (requestedPage.slice(-9).toLowerCase() === '.markdown') {
+    res.redirect(requestedPage.slice(0, -9))
+  }
+}

docs/views/about.html

@@ -0,0 +1,68 @@
+{% extends "layout.html" %}
+
+{% block page_title %}
+About - GOV.UK Prototype kit
+{% endblock %}
+
+{% block content %}
+
+<main id="content" role="main">
+  <div class="grid-row">
+    <div class="column-two-thirds">
+      <div class="breadcrumbs">
+        <ol>
+          <li><a href="/docs">GOV.UK Prototype kit</a></li>
+        </ol>
+      </div>
+      <h1 class="heading-xlarge">About</h1>
+
+      <p class="lede">
+        The prototype kit provides a simple way to make interactive prototypes that look like pages on GOV.UK. These prototypes can be used to show ideas to people you work with, and to do user research
+      </p>
+
+      <h2 class="heading-medium">Community</h2>
+
+      <p>We have two Slack channels for the Prototype kit. You'll need a government email address to join.</p>
+      <ul class="list list-bullet">
+        <li><a href="https://ukgovernmentdigital.slack.com/messages/prototype-kit/">Slack channel for users of the prototype kit</a></li>
+        <li><a href="https://ukgovernmentdigital.slack.com/messages/prototype-kit-dev/">Slack channel for developers of the prototype kit</a></li>
+      </ul>
+
+
+      <h2 class="heading-medium">Principles</h2>
+
+      <p>The prototype kit:</p>
+      <ul class="list list-bullet">
+        <li>is designed for prototyping, not for production code</li>
+        <li>requires minimal skills to get started: HTML, CSS</li>
+        <li>should be fully documented in a way that is accessible to the target audience</li>
+        <li>
+          makes use of existing GOV.UK tools and templates; the <a href="https://github.com/alphagov/govuk_template">GOV.UK template</a>, <a href="https://github.com/alphagov/govuk_frontend_toolkit">GOV.UK front end toolkit</a> and <a href="https://github.com/alphagov/govuk_elements">GOV.UK elements</a>
+        </li>
+        <li>allows for server-side code</li>
+        <li>can be extended - for example using NPM to install a module, access datastores, etc</li>
+        <li>makes it easy to share prototypes with others online</li>
+
+      </ul>
+
+
+      <h2 class="heading-medium">Privacy</h2>
+
+
+      <p>You must protect user privacy at all times, even when using prototypes. Prototypes made with the kit look like GOV.UK, but do not have the same security provisions. Always make sure you are handling user data appropriately.</p>
+
+
+
+      <h2 class="heading-medium">The kit is not a production framework</h2>
+
+      <p>Things made with the kit may look like GOV.UK, but do not have production code and likely aren't fully accessible. Don't use the kit as a base for a production service.</p>
+
+    </div>
+
+
+  </div>
+
+
+</main>
+
+{% endblock %}

docs/views/documentation_template.html

@@ -0,0 +1,29 @@
+{% extends "layout.html" %}
+
+{% block pageTitle %}
+Documentation - GOV.UK Prototype kit
+{% endblock %}
+
+{% block content %}
+
+<main id="content" role="main" class="docs markdown">
+	<div class="breadcrumbs">
+	  <ol role="breadcrumbs">
+	    <li><a href="/docs">GOV.UK prototype kit</a></li>
+	    <li><a href="/docs/tutorials-and-examples">Tutorials and examples</a></li>
+	  </ol>
+	</div>
+
+	<div class="grid-row">
+
+		<div class="column-two-thirds">
+
+			{{document | safe}}
+
+		</div>
+
+	</div>
+
+</main>
+
+{% endblock %}

app/views/examples/branching.html → docs/views/examples/branching.html

@@ -12,7 +12,7 @@
   <div class="grid-row">
     <div class="column-two-thirds">
 
-      <form action="/examples/over-18" method="get" class="form">
+      <form action="/docs/examples/over-18" method="get" class="form">
 
         <h1 class="heading-xlarge">
           Branching

app/views/examples/elements/forms.html → docs/views/examples/elements/forms.html

@@ -9,7 +9,7 @@
 
   {% include "includes/breadcrumb_examples.html" %}
 
-  <form action="/" method="post" class="form">
+  <form action="/docs/tutorials-and-examples" method="post" class="form">
 
     <h1 class="form-title heading-large">
       Your details

app/views/examples/over-18.html → docs/views/examples/over-18.html

@@ -21,7 +21,7 @@ <h1 class="heading-xlarge">
         </p>
 
         <p>
-          <a href="/examples/branching">Back to the branching example</a>
+          <a href="/docs/examples/branching">Back to the branching example</a>
         </p>
 
     </div>

app/views/examples/template-data.html → docs/views/examples/template-data.html

@@ -17,11 +17,11 @@ <h1 class="heading-xlarge">
       </h1>
 
       <p>
-        The example route defined in <code class="code">/routes.js</code> is passing the string '{{ name }}' to this page, via the variable called 'name'.
+        The example route defined in <code class="code">/docs/documentation_routes.js</code> is passing the string '{{ name }}' to this page, via the variable called 'name'.
       </p>
 
       <p>
-        Have a look at the source for this page in your text editor to see how it works: <code class="code">/app/views/examples/template-data.html</code>
+        Have a look at the source for this page in your text editor to see how it works: <code class="code">/docs/views/examples/template-data.html</code>
       </p>
 
     </div>

app/views/examples/under-18.html → docs/views/examples/under-18.html

@@ -21,7 +21,7 @@ <h1 class="heading-xlarge">
         </p>
 
         <p>
-          <a href="/examples/branching">Back to the branching example</a>
+          <a href="/docs/examples/branching">Back to the branching example</a>
         </p>
 
     </div>

docs/views/includes/breadcrumb_examples.html

@@ -0,0 +1,6 @@
+<div class="breadcrumbs">
+  <ol>
+    <li><a href="/docs">GOV.UK prototype kit</a></li>
+    <li><a href="/docs/tutorials-and-examples">Tutorials and examples</a></li>
+  </ol>
+</div>

docs/views/includes/head.html

@@ -0,0 +1,2 @@
+<link href="/public/stylesheets/application.css" media="screen" rel="stylesheet" type="text/css" />
+<link href="/public/stylesheets/docs.css" media="screen" rel="stylesheet" type="text/css" />

docs/views/includes/phase_banner_alpha.html

@@ -0,0 +1,6 @@
+<div class="phase-banner-alpha">
+  <p>
+    <strong class="phase-tag">ALPHA</strong>
+    <span>This is a new service – your <a href="#">feedback</a> will help us to improve it.</span>
+  </p>
+</div>

docs/views/includes/phase_banner_beta.html

@@ -0,0 +1,6 @@
+<div class="phase-banner-beta">
+  <p>
+    <strong class="phase-tag">BETA</strong>
+    <span>This is a new service – your <a href="#">feedback</a> will help us to improve it.</span>
+  </p>
+</div>

docs/views/includes/propositional_navigation.html

@@ -0,0 +1,14 @@
+<div class="header-proposition">
+  <div class="content">
+    <a href="#proposition-links" class="js-header-toggle menu">Menu</a>
+    <nav id="proposition-menu">
+      <a href="/" id="proposition-name">{% if serviceName %} {{ serviceName }} {% endif %}</a>
+      <!--
+      <ul id="proposition-links">
+        <li><a href="url-to-page-1" class="active">Navigation item #1</a></li>
+        <li><a href="url-to-page-2">Navigation item #2</a></li>
+      </ul>
+      -->
+    </nav>
+  </div>
+</div>

docs/views/includes/propositional_navigation_alpha.html

@@ -0,0 +1,12 @@
+<div class="header-proposition">
+  <div class="content">
+    <a href="#proposition-links" class="js-header-toggle menu">Menu</a>
+    <nav id="proposition-menu">
+      <a href="/" id="proposition-name">Service Name <span class="alpha-tag">Alpha</span></a>
+      <ul id="proposition-links">
+        <li><a href="url-to-page-1" class="active">Navigation item #1</a></li>
+        <li><a href="url-to-page-2">Navigation item #2</a></li>
+      </ul>
+    </nav>
+  </div>
+</div>

docs/views/includes/prototype_kit_navigation.html

@@ -0,0 +1,16 @@
+<div class="header-proposition">
+  <div class="content">
+    <a href="#proposition-links" class="js-header-toggle menu">Menu</a>
+    <nav id="proposition-menu">
+      <a href="/docs" id="proposition-name">Prototype kit</a>
+
+      <ul id="proposition-links">
+        <li><a href="/docs/install">Install</a></li>
+        <li><a href="/docs/tutorials-and-examples">Tutorials and examples</a></li>
+        <li><a href="/docs/about">About</a></li>
+        <li><a href="https://github.com/alphagov/govuk_prototype_kit">GitHub</a></li>
+      </ul>
+
+    </nav>
+  </div>
+</div>

docs/views/includes/scripts.html

@@ -0,0 +1,7 @@
+<!-- Javascript -->
+<script src="/public/javascripts/details.polyfill.js"></script>
+<script src="/public/javascripts/jquery-1.11.3.js"></script>
+<script src="/public/javascripts/govuk/selection-buttons.js"></script>
+<script src="/public/javascripts/govuk/shim-links-with-button-role.js"></script>
+<script src="/public/javascripts/govuk/show-hide-content.js"></script>
+<script src="/public/javascripts/docs.js"></script>

docs/views/index.html

@@ -0,0 +1,73 @@
+{% extends "layout.html" %}
+
+{% block page_title %}
+GOV.UK prototype kit
+{% endblock %}
+
+{% block proposition_header %}
+  {% include "includes/prototype_kit_navigation.html" %}
+{% endblock %}
+
+{% block content %}
+
+<main id="content" role="main">
+  <div class="grid-row">
+    <div class="column-two-thirds">
+
+      <h1 class="heading-xlarge">GOV.UK prototype kit</h1>
+
+      <p class="lede">
+        Rapidly create HTML prototypes of GOV.UK services.
+      </p>
+{{releaseVersion | log }}
+    </div>
+
+
+  </div>
+
+  <div class="grid-row">
+
+        <div class="column-third">
+
+          <h2 class="heading-medium"><a href="/docs/install">Install</a></h2>
+          <p>
+            Download and installation instructions.
+          </p>
+
+        </div>
+        <div class="column-third">
+
+          <h2 class="heading-medium"><a href="/docs/tutorials-and-examples">Tutorials and examples</a></h2>
+          <p>
+            Tutorials, examples and templates.
+          </p>
+
+        </div>
+        <div class="column-third">
+
+          <h2 class="heading-medium"><a href="/docs/about">About</a></h2>
+          <p>
+            About the kit, principles, privacy.
+          </p>
+
+        </div>
+
+      </div>
+      <div class="grid-row">
+
+        <div class="column-third">
+
+          <h2 class="heading-medium"><a href="https://github.com/alphagov/govuk_prototype_kit">GitHub</a></h2>
+          <p>
+            Source code, contributing, bugs.
+          </p>
+
+        </div>
+
+
+      </div>
+</main>
+
+{% endblock %}
+
+

docs/views/install.html

@@ -0,0 +1,43 @@
+{% extends "layout.html" %}
+
+{% block page_title %}
+Getting started - GOV.UK Prototype kit
+{% endblock %}
+
+{% block content %}
+
+<main id="content" role="main">
+  <div class="grid-row">
+    <div class="column-two-thirds">
+
+      <div class="breadcrumbs">
+        <ol>
+          <li><a href="/docs">GOV.UK prototype kit</a></li>
+        </ol>
+      </div>
+
+      <h1 class="heading-xlarge">Installing the kit</h1>
+
+      <p class="lede">
+        Get up and running with the kit in 30 minutes.
+      </p>
+
+      <h2 class="heading-medium">1. Download the kit</h2>
+      <a href="{{releaseURL}}" class="">Download (zip)</a>
+      <h2 class="heading-medium">2. Install the kit</h2>
+
+      <p>Choose from:</p>
+      <ul class="list list-bullet">
+        <li><a href="/docs/install/introduction">simple install guide</a><br>for users new to Node.js, Git or the terminal</li>
+        <li><a href="/docs/install/developer-install-instructions">advanced install guide</a><br>for users familiar with Node.js, Git and the terminal</li>
+      </ul>
+
+  </div>
+
+
+</div>
+
+
+</main>
+
+{% endblock %}

docs/views/install_template.html

@@ -0,0 +1,29 @@
+{% extends "layout.html" %}
+
+{% block pageTitle %}
+Install - GOV.UK Prototype kit
+{% endblock %}
+
+{% block content %}
+
+<main id="content" role="main" class="docs markdown">
+	<div class="breadcrumbs">
+	  <ol>
+	    <li><a href="/docs">GOV.UK prototype kit</a></li>
+	    <li><a href="/docs/install">Install</a></li>
+	  </ol>
+	</div>
+
+	<div class="grid-row">
+
+		<div class="column-two-thirds">
+
+			{{document | safe}}
+
+		</div>
+
+	</div>
+
+</main>
+
+{% endblock %}

docs/views/layout.html

@@ -0,0 +1,22 @@
+{% extends "govuk_template.html" %}
+
+{% block head %}
+  {% include "includes/head.html" %}
+{% endblock %}
+
+{% block cookie_message %}
+  <p>{{cookieText | safe }}</p>
+{% endblock %}
+
+{% block proposition_header %}
+  {% include "includes/prototype_kit_navigation.html" %}
+{% endblock %}
+
+{% block header_class %}
+  with-proposition
+{% endblock %}
+
+{% block body_end %}
+  {% include "includes/scripts.html" %}
+  <!-- GOV.UK Prototype kit {{releaseVersion}} -->
+{% endblock %}

docs/views/tutorials-and-examples.html

@@ -0,0 +1,160 @@
+{% extends "layout.html" %}
+
+{% block page_title %}
+  GOV.UK prototype kit
+{% endblock %}
+
+{% block content %}
+
+<main id="content" role="main">
+
+  <div class="breadcrumbs">
+    <ol>
+      <li><a href="/docs">GOV.UK prototype kit</a></li>
+    </ol>
+  </div>
+
+  <h1 class="heading-xlarge">Tutorials and examples</h1>
+
+  <div class="grid-row">
+
+    <div class="column-two-thirds">
+      <h2 class="heading-medium">Tutorials</h2>
+      <p>These tutorials are being actively developed. If you have suggestions for improvements, we'd love to hear from you.</p>
+    </div>
+  </div>
+  <div class="grid-row">
+    <div class="column-third">
+      <h3 class="heading-small">Getting started</h3>
+      <ul class="list list-bullet">
+        <li><a href="/prototype-admin/download-latest">Download kit (zip)</a></li>
+        <li><a href="/docs/install/introduction">Simple install guide</a>
+          <ol class="list list-number">
+            <li><a href="/docs/install/requirements">Kit requirements</a></li>
+            <li><a href="/docs/install/install-the-kit">Install the kit</a></li>
+            <li><a href="/docs/install/run-the-kit">Run the kit</a></li>
+          </ol>
+        </li>
+        <li><a href="/docs/install/developer-install-instructions">Advanced install guide</a></li>
+      </ul>
+
+
+    </div>
+    <div class="column-third">
+      <h3 class="heading-small">Basic usage</h3>
+      <ul class="list list-bullet">
+        <li><a href="/docs/making-pages">Making pages</a></li>
+        <li><a href="/docs/writing-css">Writing CSS</a></li>
+        <li><a href="/docs/setting-up-git">Setting up Git</a></li>
+        <li><a href="/docs/publishing-on-heroku">Publishing on the web (Heroku)</a></li>
+        <li><a href="/docs/examples/template-data">Passing data into a template</a></li>
+        <li><a href="/docs/tips-and-tricks">Tips and tricks</a></li>
+        <li><a href="/docs/updating-the-kit">Updating the kit</a></li>
+      </ul>
+    </div>
+    <div class="column-third">
+      <h3 class="heading-small">Advanced usage</h3>
+      <ul class="list list-bullet">
+        <li><a href="/docs/examples/branching">Branching</a>
+          <p class="font-xsmall">(Showing a different page based on user input)</p>
+        </li>
+        <li><a href="/docs/creating-routes">Creating routes (server side programming)</a></li>
+        <li><a href="/docs/session">Storing data in session</a></li>
+        <li><a href="/docs/using-verify">Using GOV.UK Verify</a></li>
+
+      </ul>
+    </div>
+  </div>
+
+  <div class="grid-row">
+    <div class="column-two-thirds">
+      <h2 class="heading-medium">Page templates</h2>
+      <p class="text">
+        Use these as the basis for your prototypes.
+        We recommend making copies the files rather than directly editing them.
+      </p>
+
+    </div>
+  </div>
+
+  <div class="grid-row">
+
+
+    <div class="column-third">
+      <h3 class="heading-small">Components</h3>
+      <ul class="list list-bullet">
+        <li>
+          <a href="/docs/examples/elements/grid-layout">
+            Grid layout
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/elements/typography">
+            Typography
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/elements/forms">
+            Basic form example
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/elements/radio-buttons-checkboxes">
+            Radio buttons and checkboxes
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/elements/toggled-content">
+            Toggling content
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/template-partial-areas">
+            Template partial areas
+          </a>
+        </li>
+      </ul>
+    </div>
+
+    <div class="column-third">
+
+      <h3 class="heading-small">Entire pages</h3>
+      <ul class="list list-bullet">
+        <li>
+          <a href="/docs/examples/blank-govuk">
+            Blank
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/blank-unbranded">
+            Blank (non-GOV.UK)
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/start-page">
+            Start
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/question-page">
+            Question
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/check-your-answers-page">
+            Check your answers
+          </a>
+        </li>
+        <li>
+          <a href="/docs/examples/confirmation-page">
+            Confirmation
+          </a>
+        </li>
+      </ul>
+    </div>
+
+  </div>
+
+</main>
+
+{% endblock %}

lib/utils.js

@@ -1,9 +1,26 @@
-var path = require('path')
 var basicAuth = require('basic-auth')
 var config = require('../app/config.js')
 var fs = require('fs')
+var marked = require('marked')
+var path = require('path')
 var portScanner = require('portscanner')
 var prompt = require('prompt')
+var request = require('sync-request')
+
+// Variables
+var releaseUrl = null
+
+// require core and custom filters, merges to one object
+// and then add the methods to nunjucks env obj
+exports.addNunjucksFilters = function (env) {
+  var coreFilters = require('./core_filters.js')(env)
+  var customFilters = require('../app/filters.js')(env)
+  var filters = Object.assign(coreFilters, customFilters)
+  Object.keys(filters).forEach(function (filterName) {
+    env.addFilter(filterName, filters[filterName])
+  })
+  return
+}
 
 /**
  * Simple basic auth middleware for use with Express 4.x.
@@ -17,6 +34,7 @@ var prompt = require('prompt')
  * @param   {string}   password Expected password
  * @returns {function} Express 4 middleware requiring the given credentials
  */
+
 exports.basicAuth = function (username, password) {
   return function (req, res, next) {
     if (!username || !password) {
@@ -96,3 +114,70 @@ exports.forceHttps = function (req, res, next) {
   }
   next()
 }
+
+// Synchronously get the url for the latest release on github and store
+exports.getLatestRelease = function () {
+  var url = ''
+
+  if (releaseUrl !== null) {
+    // Release url already exists
+    console.log('Release url cached:', releaseUrl)
+    return releaseUrl
+  } else {
+    // Release url doesn't exist
+    var options = {
+      headers: {'user-agent': 'node.js'}
+    }
+    var gitHubUrl = 'https://api.github.com/repos/alphagov/govuk_prototype_kit/releases/latest'
+    try {
+      console.log('Getting latest release from github')
+
+      var res = request('GET', gitHubUrl, options)
+      var data = JSON.parse(res.getBody('utf8'))
+      var zipballUrl = data['zipball_url']
+      var releaseVersion = zipballUrl.split('/').pop()
+      var urlStart = 'https://github.com/alphagov/govuk_prototype_kit/archive/'
+      var urlEnd = '.zip'
+      var zipUrl = urlStart + releaseVersion + urlEnd
+
+      console.log('Release url is', zipUrl)
+      releaseUrl = zipUrl
+      url = releaseUrl
+    } catch (err) {
+      url = 'https://github.com/alphagov/govuk_prototype_kit/releases/latest'
+      console.log("Couldn't retrieve release url")
+    }
+  }
+  return url
+}
+
+// Matches routes
+exports.matchRoutes = function (req, res) {
+  var path = (req.params[0])
+  res.render(path, function (err, html) {
+    if (err) {
+      res.render(path + '/index', function (err2, html) {
+        if (err2) {
+          res.status(404).send(err + '<br>' + err2)
+        } else {
+          res.end(html)
+        }
+      })
+    } else {
+      res.end(html)
+    }
+  })
+}
+
+exports.matchMdRoutes = function (req, res) {
+  var docsPath = '/../docs/documentation/'
+  var filePath = path.join(__dirname, docsPath, req.params[0] + '.md')
+  console.log('file path is:', filePath)
+  if (fs.existsSync(path.join(__dirname, docsPath, req.params[0] + '.md'), 'utf8')) {
+    var doc = fs.readFileSync(path.join(__dirname, docsPath, req.params[0] + '.md'), 'utf8')
+    var html = marked(doc)
+    res.render('documentation_template', {'document': html})
+    return true
+  }
+  return false
+}

package.json

@@ -18,7 +18,6 @@
     "browser-sync": "^2.11.1",
     "consolidate": "0.x",
     "express": "4.13.3",
-    "express-nunjucks": "^0.9.3",
     "express-session": "^1.13.0",
     "express-writer": "0.0.4",
     "govuk-elements-sass": "2.0.0",
@@ -32,11 +31,14 @@
     "grunt-sass": "^1.1.0",
     "grunt-sync": "^0.5.1",
     "hogan.js": "3.0.2",
+    "marked": "^0.3.6",
     "minimist": "0.0.8",
+    "nunjucks": "^2.4.2",
     "portscanner": "^1.0.0",
     "prompt": "^0.2.14",
     "readdir": "0.0.6",
     "serve-favicon": "2.3.0",
-    "standard": "^7.1.2"
+    "standard": "^7.1.2",
+    "sync-request": "^3.0.1"
   }
 }

server.js

@@ -1,10 +1,12 @@
 var path = require('path')
 var express = require('express')
 var session = require('express-session')
-var nunjucks = require('express-nunjucks')
+var nunjucks = require('nunjucks')
 var routes = require('./app/routes.js')
+var documentationRoutes = require('./docs/documentation_routes.js')
 var favicon = require('serve-favicon')
 var app = express()
+var documentationApp = express()
 var bodyParser = require('body-parser')
 var browserSync = require('browser-sync')
 var config = require('./app/config.js')
@@ -23,33 +25,37 @@ env = env.toLowerCase()
 useAuth = useAuth.toLowerCase()
 useHttps = useHttps.toLowerCase()
 
+var useDocumentation = (config.useDocumentation === 'true')
+
+// Promo mode redirects the root to /docs - so our landing page is docs when published on heroku
+var promoMode = process.env.PROMO_MODE || 'false'
+promoMode = promoMode.toLowerCase()
+
+// Disable promo mode if docs aren't enabled
+if (!useDocumentation) promoMode = 'false'
+
 // Authenticate against the environment-provided credentials, if running
 // the app in production (Heroku, effectively)
 if (env === 'production' && useAuth === 'true') {
   app.use(utils.basicAuth(username, password))
 }
 
-// Application settings
-app.set('view engine', 'html')
-app.set('views', [path.join(__dirname, '/app/views'), path.join(__dirname, '/lib/')])
+// Set up App
+var appViews = [path.join(__dirname, '/app/views/'), path.join(__dirname, '/lib/')]
 
-nunjucks.setup({
+var nunjucksAppEnv = nunjucks.configure(appViews, {
   autoescape: true,
-  watch: true,
-  noCache: true
-}, app)
-
-// require core and custom filters, merges to one object
-// and then add the methods to nunjucks env obj
-nunjucks.ready(function (nj) {
-  var coreFilters = require(path.join(__dirname, '/lib/core_filters.js'))(nj)
-  var customFilters = require(path.join(__dirname, '/app/filters.js'))(nj)
-  var filters = Object.assign(coreFilters, customFilters)
-  Object.keys(filters).forEach(function (filterName) {
-    nj.addFilter(filterName, filters[filterName])
-  })
+  express: app,
+  noCache: true,
+  watch: true
 })
 
+// Nunjucks filters
+utils.addNunjucksFilters(nunjucksAppEnv)
+
+// Set views engine
+app.set('view engine', 'html')
+
 // Middleware to serve static assets
 app.use('/public', express.static(path.join(__dirname, '/public')))
 app.use('/public', express.static(path.join(__dirname, '/govuk_modules/govuk_template/assets')))
@@ -59,6 +65,23 @@ app.use('/public/images/icons', express.static(path.join(__dirname, '/govuk_modu
 // Elements refers to icon folder instead of images folder
 app.use(favicon(path.join(__dirname, 'govuk_modules', 'govuk_template', 'assets', 'images', 'favicon.ico')))
 
+// Set up documentation app
+if (useDocumentation) {
+  var documentationViews = [path.join(__dirname, '/docs/views/'), path.join(__dirname, '/lib/')]
+
+  var nunjucksDocumentationEnv = nunjucks.configure(documentationViews, {
+    autoescape: true,
+    express: documentationApp,
+    noCache: true,
+    watch: true
+  })
+  // Nunjucks filters
+  utils.addNunjucksFilters(nunjucksDocumentationEnv)
+
+  // Set views engine
+  documentationApp.set('view engine', 'html')
+}
+
 // Support for parsing data in POSTs
 app.use(bodyParser.json())
 app.use(bodyParser.urlencoded({
@@ -103,6 +126,14 @@ app.get('/robots.txt', function (req, res) {
   res.send('User-agent: *\nDisallow: /')
 })
 
+// Redirect root to /docs when in promo mode.
+if (promoMode === 'true') {
+  console.log('Prototype kit running in promo mode')
+  app.get('/', function (req, res) {
+    res.redirect('/docs')
+  })
+}
+
 // routes (found in app/routes.js)
 if (typeof (routes) !== 'function') {
   console.log(routes.bind)
@@ -112,6 +143,20 @@ if (typeof (routes) !== 'function') {
   app.use('/', routes)
 }
 
+// Returns a url to the zip of the latest release on github
+app.get('/prototype-admin/download-latest', function (req, res) {
+  var url = utils.getLatestRelease()
+  res.redirect(url)
+})
+
+if (useDocumentation) {
+  // Create separate router for docs
+  app.use('/docs', documentationApp)
+
+  // Docs under the /docs namespace
+  documentationApp.use('/', documentationRoutes)
+}
+
 // Strip .html and .htm if provided
 app.get(/\.html?$/i, function (req, res) {
   var path = req.path
@@ -121,25 +166,21 @@ app.get(/\.html?$/i, function (req, res) {
   res.redirect(path)
 })
 
-// auto render any view that exists
+// Auto render any view that exists
+
+// App folder routes get priority
 app.get(/^\/([^.]+)$/, function (req, res) {
-  var path = (req.params[0])
-
-  res.render(path, function (err, html) {
-    if (err) {
-      res.render(path + '/index', function (err2, html) {
-        if (err2) {
-          console.log(err)
-          res.status(404).send(err + '<br>' + err2)
-        } else {
-          res.end(html)
-        }
-      })
-    } else {
-      res.end(html)
+  utils.matchRoutes(req, res)
+})
+
+if (useDocumentation) {
+  // Documentation  routes
+  documentationApp.get(/^\/([^.]+)$/, function (req, res) {
+    if (!utils.matchMdRoutes(req, res)) {
+      utils.matchRoutes(req, res)
     }
   })
-})
+}
 
 console.log('\nGOV.UK Prototype kit v' + releaseVersion)
 // Display warning not to use kit for production services.