Move content across from alphagov/tdt-documentation

Author: Andrea Szöllössi

docs/.ruby-version

@@ -0,0 +1 @@
+2.5.3

docs/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+# For faster file watcher updates on Windows:
+gem 'wdm', '~> 0.1.0', platforms: [:mswin, :mingw]
+
+# Windows does not come with time zone data
+gem 'tzinfo-data', platforms: [:mswin, :mingw, :jruby]
+
+gem 'govuk_tech_docs', '~> 1.8.0'
+
+gem 'therubyracer'
+
+gem 'middleman-gh-pages'
+

docs/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Crown Copyright (Government Digital Service)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/README.md

@@ -0,0 +1,72 @@
+# Tech Docs Template Documentation
+
+[![Build Status](https://travis-ci.org/alphagov/tdt-documentation.svg?branch=master)](https://travis-ci.org/alphagov/tdt-documentation)
+
+This repository is used to generate the [documentation website for the Tech Docs Template][tdt-docs] and uses the template itself.
+
+The Tech Docs Template is a [middleman template][mmt] that
+you can use to build technical documentation websites using a GOV.UK style.
+
+## Before you start
+
+To use the Tech Docs Template you need:
+
+- [Ruby][install-ruby]
+- [Middleman][install-middleman]
+
+## Making changes
+
+To make changes to the documentation for the Tech Docs Template website, edit files in the `source` folder of this repository.
+
+You can add content by editing the `.html.md.erb` files. These files support content in:
+
+- Markdown
+- HTML
+- Ruby
+
+👉 You can use Markdown and HTML to [generate different content types][example-content] and [Ruby partials to manage content][partials].
+
+👉 Learn more about [producing more complex page structures][multipage] for your website.
+
+## Preview your changes locally
+
+To preview your new website locally, navigate to your project folder and run:
+
+```sh
+bundle exec middleman server
+```
+
+👉 See the generated website on `http://localhost:4567` in your browser. Any content changes you make to your website will be updated in real time.
+
+To shut down the Middleman instance running on your machine, use `ctrl+C`.
+
+If you make changes to the `config/tech-docs.yml` configuration file, you need to restart Middleman to see the changes.
+
+## Publishing changes
+
+Travis CI automatically publishes changes merged into the master branch of this repository.
+
+## Troubleshooting
+
+Run `bundle exec middleman build --verbose` to get detailed error messages to help with finding the problem.
+
+## Code of conduct
+
+Please refer to the `alphagov` [code of conduct](https://github.com/alphagov/code-of-conduct).
+
+## Licence
+
+Unless stated otherwise, the codebase is released under the [MIT License](LICENSE). This covers both the codebase and any sample code in the documentation.
+The documentation is [© Crown copyright](http://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/copyright-and-re-use/crown-copyright/) and available under the terms of the [Open Government 3.0 licence](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).
+
+[mmt]: https://middlemanapp.com/advanced/project_templates/
+[tdt-docs]: https://tdt-documentation.london.cloudapps.digital
+
+[config]: https://tdt-documentation.london.cloudapps.digital/configuration-options.html#configuration-options
+[frontmatter]: https://tdt-documentation.london.cloudapps.digital/frontmatter.html#frontmatter
+[multipage]: https://tdt-documentation.london.cloudapps.digital/multipage.html#build-a-multipage-site
+[example-content]: https://tdt-documentation.london.cloudapps.digital/content.html#content-examples
+[partials]: https://tdt-documentation.london.cloudapps.digital/single_page.html#add-partial-lines
+[contribute]: https://github.com/alphagov/tech-docs-gem/blob/master/CONTRIBUTING.md
+[install-ruby]: https://tdt-documentation.london.cloudapps.digital/install_macs.html#install-ruby
+[install-middleman]: https://tdt-documentation.london.cloudapps.digital/install_macs.html#install-middleman

docs/config.rb

@@ -0,0 +1,18 @@
+require 'govuk_tech_docs'
+
+GovukTechDocs.configure(self, livereload: { js_host: "localhost" })
+
+DOCS_LOCATION_IN_GEM = Bundler.rubygems.find_name('govuk_tech_docs').first.full_gem_path + "/docs"
+
+files.watch :source, path: DOCS_LOCATION_IN_GEM
+
+helpers do
+  def gem_docs(filename)
+    raw_markdown = File.read(DOCS_LOCATION_IN_GEM + "/#{filename}")
+
+    # Strip the h1 header from the original markdown file
+    markdown = raw_markdown.lines[1..-1].join
+
+    markdown
+  end
+end

docs/config/tech-docs.yml

@@ -0,0 +1,42 @@
+# Host to use for canonical URL generation (without trailing slash)
+host: https://tdt-documentation.london.cloudapps.digital/
+
+# Header-related options
+show_govuk_logo: true
+service_name: Tech docs template
+service_link:
+phase: Beta
+
+# Links to show on right-hand-side of header
+header_links:
+  About: https://sites.google.com/a/digital.cabinet-office.gov.uk/gds/communities-of-practice/content/technical-writing
+  Documentation: /
+  Support: /
+
+# Table of contents depth – how many levels to include in the table of contents.
+# If your ToC is too long, reduce this number and we'll only show higher-level
+# headings.
+max_toc_heading_level: 2
+
+# Tracking ID from Google Analytics (e.g. UA-XXXX-Y)
+ga_tracking_id: UA-86101042-3
+
+google_site_verification: "IJ5HOXpZrISM6la-YO_iX0rBUC5YFftpexygcKLsNs4"
+
+# Multi-page options
+multipage_nav: true
+collapsible_nav: true
+
+# Show links to contribute on GitHub
+show_contribution_banner: true
+github_repo: alphagov/tdt-documentation
+
+# Enable search
+enable_search: true
+
+# Ownership for page reviews
+default_owner_slack: '#docs-repos'
+owner_slack_workspace: gds
+
+# Enable GOV.UK crown logo
+show_govuk_logo: false

docs/manifest.yml

@@ -0,0 +1,8 @@
+---
+applications:
+- name: tdt-documentation
+  memory: 64M
+  instances: 2
+  buildpack: staticfile_buildpack
+  routes:
+    - route: 	tdt-documentation.london.cloudapps.digital

docs/source/api_ref.html.md.erb

@@ -0,0 +1,6 @@
+---
+title: "API reference"
+weight: 80
+---
+
+<%= partial 'functionality/api_reference' %>

docs/source/architecture/multipage.md

@@ -0,0 +1,194 @@
+# Build a multipage site
+
+You can create a technical documentation site that splits its content across multiple pages.
+
+This is suitable for documentation sites that have too much content for the single page format.
+
+You should use the search feature [link] with multipage documentation sites.
+
+## Basic multipage
+
+You can split the content into multiple individual pages. An example is the [GOV.UK PaaS technical documentation](https://docs.cloud.service.gov.uk/).
+
+### Amend the tech-docs.yml file
+
+Add this to your project’s `tech-docs.yml` file, or set it to true if it is already there:
+
+```
+# Enable multipage navigation in the sidebar
+multipage_nav: true
+```
+
+### Repo folder structure
+
+A typical single page documentation repo has this folder structure:
+
+<br/><br/>
+![](/diagrams/Single_page.svg)
+<br/><br/>
+
+A basic multipage documentation repo can have this structure:
+
+<br/><br/>
+![](/diagrams/Basic_multipage.svg)
+<br/><br/>
+
+You must amend the documentation repo folder structure to reflect this structure.
+
+### Create multiple .html.md.erb files
+
+Basic multipage requires multiple `.html.md.erb` files in the tech docs repo __source__ folder.
+
+Each `.html.md.erb` file relates to one separate page within the tech docs, and references the markdown files in the associated folder.
+
+Additionally, the tech doc repo must have at least one `.html.md.erb` file in the __source__ folder named `index.html.md.erb`.
+
+The .html.md.erb files must not have the same name as the folders that the .html.md.erb files use partials refer to.
+
+For example, you cannot have a support.html.md.erb file that contains the partial `<%= partial 'support/contact_us' %>`.
+
+### Amend the multiple .html.md.erb files
+
+1. Add a weight argument and value to the title of each .html.md.erb file. This builds the structure of the multipage documentation.
+
+    For example:
+
+    ```bash
+    ---
+    title: "Product Technical Documentation"
+    ---
+    ```
+
+    becomes
+
+    ```bash
+    ---
+    title: "Product Technical Documentation"
+    weight: 10
+    ---
+    ```
+
+    Higher weights mean that the content is lower down in the documentation hierarchy. An easy way to remember this is to think “heavier pages sink to the bottom”.
+
+    For example, a single `.html.md.erb` file becomes multiple `.html.md.erb` files:
+
+    <div style="height:1px;font-size:1px;">&nbsp;</div>
+
+    |Single page|Multipage|
+    |:---|:---|
+    |---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
+    ||---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
+    ||---<br>weight: 20<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/start' %>|
+    ||---<br>weight: 30<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/users' %>|
+
+    <div style="height:1px;font-size:1px;">&nbsp;</div>
+
+### Add H1 heading if required
+
+Add an H1 heading to either the `.html.md.erb` file or at the start of the first markdown file for each individual content page.
+
+If there is an H1 heading in both, you will see two H1s when the documentation site builds and renders in your internet browser.
+
+## Nested multipage
+
+You can split the content into multiple individual pages, and can have pages "nested" within one another. Two examples:
+
+- [GOV.UK PaaS technical documentation - Deploying services](https://docs.cloud.service.gov.uk/deploying_services/)
+- [GOV.UK Pay technical documentation - Switching to live](https://docs.payments.service.gov.uk/switching_to_live/#switching-to-live)
+
+### Amend the tech-docs.yml file
+
+Add this to your project’s `tech-docs.yml` file, or set it to true if it is already there:
+
+```
+# Enable multipage navigation in the sidebar
+multipage_nav: true
+```
+
+### Repo folder structure
+
+A typical single page documentation repo has this folder structure:
+
+<br/><br/>
+![](/diagrams/Single_page.svg)
+<br/><br/>
+
+A nested multipage documentation repo can have this structure:
+
+<br/><br/>
+![](/diagrams/Nested_multipage.svg)
+<br/><br/>
+
+You must amend the documentation repo folder structure to reflect this structure.
+
+### Create multiple .html.md.erb files
+
+Basic multipage requires multiple `.html.md.erb` files in the tech docs repo __source__ folder.
+
+Each `.html.md.erb` file relates to one separate page within the tech docs, and references the markdown files in the associated folder.
+
+Additionally, the tech doc repo must have at least one `.html.md.erb` file in the __source__ folder named `index.html.md.erb`.
+
+### Amend the multiple .html.md.erb files
+
+1. Add a weight argument and value to the title of each .html.md.erb file. This builds the structure of the multipage documentation.
+
+    For example:
+
+    ```bash
+    ---
+    title: "Product Technical Documentation"
+    ---
+    ```
+
+    becomes
+
+    ```bash
+    ---
+    title: "Product Technical Documentation"
+    weight: 10
+    ---
+    ```
+
+    Higher weights mean that the content is lower down in the documentation hierarchy. An easy way to remember this is to think “heavier pages sink to the bottom”.
+
+    For example, a single `.html.md.erb` file becomes multiple `.html.md.erb` files:
+
+    <div style="height:1px;font-size:1px;">&nbsp;</div>
+
+    |Single page|Multipage|
+    |:---|:---|
+    |---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
+    ||---<br>weight: 10<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/index' %>|
+    ||---<br>weight: 20<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/start' %>|
+    ||---<br>weight: 30<br>title: "Product Technical Documentation"<br>---<br><br><%= partial 'documentation/users' %>|
+
+    <div style="height:1px;font-size:1px;">&nbsp;</div>
+
+### Add H1 heading if required
+
+Add an H1 heading to either the `.html.md.erb` file or at the start of the first markdown file for each individual content page.
+
+If there is an H1 heading in both, you will see two H1s when the documentation site builds and renders in your internet browser.
+
+### Create folder for nested content .html.md.erb files
+
+Refer to the GOV.UK PaaS technical documentation repo [nested content folder](https://github.com/alphagov/paas-tech-docs/tree/master/source/deploying_services) as an example.
+
+1. Create a folder within the __source__ folder. This is where the `.html.md.erb` files for your nested content must live.
+
+1. Create an `index.html.md.erb` file within the nested content folder. This will be the "wrapper" for the nested content. It can refer to another content file through partials or have the content in itself.
+
+    Note that each `.html.md.erb` must have a weight value that preserves the overall hierarchy both within the nested content and compared to the other non-nested content.
+
+1. Create sub-folders for each nested page under the "wrapper".
+
+1. Create an `index.html.md.erb` file within each sub-folder. Each `.html.md.erb` file can refer to another content file through partials or have the content in itself.
+
+    Note that each `.html.md.erb` file must have a weight value that preserves the overall hierarchy both within the nested content and compared to the other non-nested content.
+
+### Add H1 heading if required
+
+Add an H1 heading to either the `.html.md.erb` file or at the start of the first markdown file for each individual content page.
+
+If there is an H1 heading in both, you will see two H1s when the documentation site builds and renders in your internet browser.