Merge pull request #67 from alphagov/add_using_nunjucks_docs

Add docs on using Nunjucks macros

source/installing-with-npm/index.html.md.erb

@@ -24,7 +24,7 @@ weight: 10
 
     GOV.UK Frontend also works with Ruby Sass version 3.4.0 or higher, but we recommend you do not use Ruby Sass because it's been deprecated.
 
-You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend's Nunjucks macros](https://design-system.service.gov.uk/get-started/production/#using-nunjucks-macros).
+You can also [install Nunjucks v3.0.0 or later](https://www.npmjs.com/package/nunjucks) if you want to [use GOV.UK Frontend's Nunjucks macros](/use-nunjucks/).
 
 ## Install GOV.UK Frontend
 

source/migrating-from-legacy-products/index.html.md.erb

@@ -34,7 +34,7 @@ If you use macros, your project will be:
 - easier to migrate, because your project will be organised the same way we organise the GOV.UK Design System
 - easier to update when new versions of GOV.UK Frontend are released
 
-If you're using Node.js, you can use [our Nunjucks macros](https://design-system.service.gov.uk/styles/page-template/#nunjucks). You'll need to [install Nunjucks](https://mozilla.github.io/nunjucks/getting-started.html) first.
+If you're using Node.js, you can [use our Nunjucks macros](/use-nunjucks/).
 
 Each [component page](https://design-system.service.gov.uk/components/) on the GOV.UK Design System website has example Nunjucks macros and a table of macro options.
 

source/use-nunjucks/index.html.md.erb

@@ -0,0 +1,70 @@
+---
+title: Use Nunjucks
+weight: 45
+---
+
+# Use Nunjucks
+
+You can use our Nunjucks code to generate the HTML for pages and components.
+
+You can also change the HTML that's generated by passing options into the Nunjucks code.
+
+If you use Nunjucks, your application will be easier to update when a new version of GOV.UK Frontend is released.
+
+To use Nunjucks, your application and any frameworks that support your application must use Node.js.
+
+You do not need to follow this guidance to [use Nunjucks macros in the GOV.UK Prototype Kit](https://design-system.service.gov.uk/get-started/prototyping/#using-nunjucks-macros).
+
+## Before you start
+
+You must first:
+
+- [install GOV.UK Frontend with Node.js package manager (npm)](/installing-with-npm/)
+- make sure you’ve installed Nunjucks so it’s working in your environment
+
+## Set up Nunjucks and use the page template
+
+1. Add `node_modules/govuk-frontend/` to your list of Nunjucks paths, so Nunjucks knows where to find the GOV.UK Frontend template and components.
+
+    For example:
+
+    ```javascript
+        nunjucks.configure([
+          "node_modules/govuk-frontend/",
+          "YOUR-VIEWS-FOLDER"
+        ])
+    ```
+
+2. Use the GOV.UK Frontend template by adding the following at the top of your view file:
+
+    ```javascript
+    {% extends "govuk/template.njk" %}
+    ```
+
+3. Go to the [default page template example](https://design-system.service.gov.uk/styles/page-template/#default) on the GOV.UK Design System website, then copy the Nunjucks code into your view file.
+
+You may need to change the paths in the Nunjucks code to [get the CSS, assets and JavaScript working](/importing-css-assets-and-javascript).
+
+Find out how to [change how the page template works](https://design-system.service.gov.uk/styles/page-template/#changing-template-content).
+
+## Adding a component
+
+Go to any component page on the Design System website, then copy the Nunjucks macro code from the **Nunjucks** tab of any example.
+
+For example, to add the breadcrumbs component to your page, copy the code from the **Nunjucks** tab in the first example on the [breadcrumbs component page](https://design-system.service.gov.uk/components/breadcrumbs/).
+
+## Changing a component
+
+You can use options to change how a component looks or behaves.
+
+For example, use the `text` option to change the text on a [button](https://design-system.service.gov.uk/components/button/):
+
+```javascript
+{{ govukButton({
+    text: "Example button text"
+}) }}
+```
+
+To see the options for a component, select the **Nunjucks** tab of the component example on any Design System website page, then select **Nunjucks macro options**.
+
+You must sanitise any HTML you pass in to Nunjucks macros you’re using in your live application to protect your website against cross-site scripting (XSS) attacks. You can read more about [XSS](https://developer.mozilla.org/en-US/docs/Web/Security/Types_of_attacks#Cross-site_scripting_XSS) on the MDN website.