Re-organise documentation site

README.md

@@ -1,3 +1,43 @@
 # GOV.UK Prototype Components · [![test](https://github.com/x-govuk/govuk-prototype-components/actions/workflows/test.yml/badge.svg)](https://github.com/x-govuk/govuk-prototype-components/actions/workflows/test.yml)
 
-See [GOV.UK Prototype Components documentation](https://x-govuk.github.io/govuk-prototype-components/).
+Common and experimental components that are not yet part of the GOV.UK Design System.
+
+## Requirements
+
+Node.js v18 or later.
+
+## Installation
+
+```shell
+npm install @x-govuk/govuk-prototype-components
+```
+
+## Usage
+
+If you are using version 13 or later of the GOV.UK Prototype Kit, the components will be immediately available for use in Nunjucks templates.
+
+Learn more about how to [get started](https://x-govuk.github.io/govuk-prototype-components/get-started/).
+
+> ![NOTE]
+> Prior to v1.0.0, this project included a collection of decorated form components. These can now be found in the [`govuk-decorated-components`](https://github.com/x-govuk/govuk-decorated-components) package.
+
+## Contributing
+
+Bug reports and feature requests are welcome. Please raise an issue or submit a pull request.
+
+We use [StandardJS](https://standardjs.com) to ensure code follows [the GDS way](https://gds-way.cloudapps.digital/manuals/programming-languages/js.html). Use `npm run lint` to check your code before submitting a pull request.
+
+## Testing
+
+```shell
+npm test
+```
+
+## Releasing a new version
+
+`npm run release`
+
+This command will ask you what version you want to use. It will then publish a new version on NPM, create and push a new git tag and then generate release notes ready for posting on GitHub.
+
+> ![NOTE]
+> Releasing a new version requires permission to publish packages to the `@x-govuk` organisation.

docs/autocomplete.md

@@ -1,19 +1,20 @@
 ---
-title: Autocomplete
 layout: sub-navigation
-order: 1
+order: 2
+title: Autocomplete
+description: Help users find and select from a number of options.
 ---
 
-The autocomplete component implements the [Accessible autocomplete pattern](https://github.com/alphagov/accessible-autocomplete) to enhance a fixed list of options provided by a `<select>` element.
-
-This component may be useful if you want users to pick from a number of options. Unlike an autosuggest component, this component will only allow users to choose from a predetermined list of options.
-
 {% from "example/macro.njk" import appExample %}
 
 {{ appExample({
   component: "autocomplete"
 }) }}
 
+This component implements the [Accessible autocomplete pattern](https://github.com/alphagov/accessible-autocomplete) to enhance a fixed list of options provided by a `<select>` element.
+
+Unlike an autosuggest component, this component will only allow users to choose from a predetermined list of options.
+
 ## Component options
 
 Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

docs/data-attributes.md

@@ -0,0 +1,12 @@
+---
+layout: sub-navigation
+order: 7
+title: Data attributes
+description: Use data attributes to help guide users during user research.
+---
+
+{% for page in collections["data-attributes"] %}
+
+- [{{ page.data.title }}]({{ page.url | url }}) – {{ page.data.description }}
+
+{% endfor %}

docs/data-attributes/data-attributes.11tydata.js

@@ -0,0 +1,6 @@
+module.exports = {
+  tags: ['data-attributes'],
+  eleventyNavigation: {
+    parent: 'Data attributes'
+  }
+}

docs/edge.md → docs/data-attributes/edge.md

@@ -1,11 +1,12 @@
 ---
-title: Edge
 layout: sub-navigation
-order: 2
+order: 1
+title: Edge
+description: A data attribute to define the edges of your prototype for research.
+eleventyNavigation:
+  parent: Data attributes
 ---
 
-A javascript component to make it easy to define the edges of your prototype for research.
-
 Any link that points to `#` will give a customisable warning when clicked, ‘Sorry this has not been built yet’.
 
 Sometimes a prototype has:

docs/warn-on-unsaved-changes.md → docs/data-attributes/warn-on-unsaved-changes.md

@@ -1,11 +1,12 @@
 ---
-title: Warn on saved changes
 layout: sub-navigation
-order: 7
+order: 2
+title: Warn on saved changes
+description: A data attribute to warn users if they try to leave a page without saving changes to a form.
+eleventyNavigation:
+  parent: Data attributes
 ---
 
-A javascript component to warn users if they try to leave a page without saving their changes to a form.
-
 If a user makes a change then tries to close their tab, window, or click a link to navigate away, they will see a default browser message warning them about unsaved changes. This message is different on each browser and cannot be edited.
 
 The message will say something similar to:

docs/get-started.md

@@ -0,0 +1,96 @@
+---
+layout: sub-navigation
+order: 1
+title: Get started
+---
+
+## Requirements
+
+Node.js v18 or later.
+
+## Installation
+
+```shell
+npm install @x-govuk/govuk-prototype-components
+```
+
+## Usage with the GOV.UK Prototype Kit
+
+GOV.UK Prototype Components are designed to work with the GOV.UK Prototype Kit.
+
+If you are using v13 or later of the kit, the components will be immediately available once you have installed the package, and can be [managed alongside other plugins in your prototype](https://prototype-kit.service.gov.uk/docs/install-and-use-plugins).
+
+## Advanced usage
+
+If you are using an earlier version of the GOV.UK Prototype Kit, or only want to install selected components, you can do so by following the instructions below.
+
+### CSS
+
+To import all the Sass rules from GOV.UK Prototype Components, add the following to your Sass file:
+
+```scss
+@import "node_modules/@x-govuk/govuk-prototype-components/x-govuk/all";
+```
+
+You can also import Sass rules for an individual component. For example, to import styles for the masthead component, add the following to your Sass file:
+
+```scss
+@import "node_modules/@x-govuk/govuk-prototype-components/x-govuk/components/masthead/masthead";
+```
+
+### JavaScript
+
+To import the JavaScript for the GOV.UK Prototype Components, you can either:
+
+* add the GOV.UK Prototype Components JavaScript file to your HTML
+* import the JavaScript using a bundler like [Webpack](https://webpack.js.org/)
+
+#### Add the JavaScript file to your HTML
+
+If you decide to add the JavaScript to your HTML, first either:
+
+* set up your routing so that requests for the JavaScript file are served from `node_modules/@x-govuk/govuk-prototype-components/x-govuk/all.js`
+* copy the `node_modules/@x-govuk/govuk-prototype-components/x-govuk/all.js` file into your application
+
+Then import the JavaScript file before the closing `</body>` tag of your HTML page or page template, and run the `initAll` function to initialise all the components.
+
+```html
+<body>
+  ...
+  <script src="<YOUR-APP>/<YOUR-JS-FILE>.js"></script>
+  <script>
+    window.GOVUKPrototypeComponents.initAll()
+  </script>
+</body>
+```
+
+#### Import JavaScript using ES modules
+
+If you decide to import using a bundler, use `import` to import all GOV.UK Prototype Components, then run the `initAll` function to initialise them:
+
+```js
+import { initAll } from '@x-govuk/govuk-prototype-components'
+
+initAll()
+```
+
+You can also import the JavaScript for an individual component. For example, to import the autocomplete component, add the following to your JavaScript file:
+
+```js
+import { Autocomplete } from '@x-govuk/govuk-prototype-components'
+
+const myAutocomplete = document.querySelector('#my-autocomplete')
+new Autocomplete(myAutocomplete).init()
+```
+
+#### Import JavaScript using Common JS
+
+If you’re using a bundler that uses CommonJS (like [Browserify](http://browserify.org/)), use `require`:
+
+```js
+const GOVUKPrototypeComponents = require('@x-govuk/govuk-prototype-components')
+
+GOVUKPrototypeComponents.initAll()
+```
+
+It is not possible to import individual components using CommonJS.