How to update

This documentation is a static HTML site generated from the street-manager-docs repository

Requires:

See here for guides to GitHub.

Notes for updating the documentation:

  • The documentation uses markdown augmented with gov.uk design system styles
  • See here for guide on adding CSS styles to markdown HTML
  • Code sections should be wrapped in <code>...</code> tags
  • All paragraphs need to be followed with {: .govuk-body}
  • All heading must be followed by {: .govuk-heading-l}, {: .govuk-heading-m} etc.
  • Some HTML elements must use explicit HTML in markdown to render correctly, such as lists/tables, e.g. <ol class="govuk-list govuk-list--bullet"><li>item</li></ol> NOT * item

To edit the documentation you can do it different ways

Editing articles with Rich Text controls

If you are an authorised GitHub user you can edit documentation articles via the CMS site URL on the /admin page. See How to add an article for details and ask your admin for the CMS URL.

Editing on GitHub directly

You can use the GitHub website to edit raw files directly. This allows quick changes for small updates, but does not allow you to preview how the final rendered site will look.

Forking the repo

You can preview your changes in your own generated Github pages site before committing them by forking the repository. Do this by clicking the "Fork" button in the top right of the GitHub street-manager-docs page.

This will create a copy of the repo under your own GitHub user. You can then edit the setting of your repo to enable GitHub pages to generate the GitHub pages site each time you commit changes to your repo, under Settings->Options->GitHub pages (Source: Master branch /docs folder). You can find the generated site URL in the "environment" link on your GitHub repo page.

When you are finished making changes make a pull request to bring them back into the main street-manager-docs repo (see here for details).

Locally

You can clone the repository to your own machine, make changes there and preview them before pushing them back up for review and merging.

Local development environment

Requires:

        cd docs
        bundle install
        bundle exec jekyll serve # runs on http://localhost:4000/street-manager-docs/

Local development container

Requires:

      1. Open folder in Visual Studio Code
      2. Click bottom left corner and select "Remote-Containers: Open Folder in Container" (requires extension)
      3. Wait for container to be built
      4. Run task to launch Jekyll via `Terminal -> Run Task -> Jeykll`
      5. Browse to http://localhost:4000