Merge pull request #14 from LBHackney-IT/one-ring-to-rule-them-all

Use Docusaurus to build

Author: spikeheap

.editorconfig

@@ -0,0 +1,19 @@
+# EditorConfig ensures consistency: https://editorconfig.org
+# Plugins are available for all good editors (and even some
+# bad ones)
+#
+# VSCode plugin: https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig
+
+# This is the top-most editorconfig file for the repository
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+# Opinionated tab/space rules, matching the Docusaurus defaults.
+indent_style = space
+indent_size = 2

.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# The default owners for are the Hackney development team, and more specialised 
+# ownership can be added to directories/folders as needed.
+#
+# Note that order matters: more specific rules lower in this file will override 
+# the default, NOT add to it
+
+*       @LBHackney-IT/development-team

.github/workflows/deploy.yml

@@ -0,0 +1,71 @@
+name: Deploy to GitHub Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: [$default-branch]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+
+jobs:
+  build:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+        # with:
+          # Automatically inject pathPrefix in your Gatsby configuration file.
+          #
+          # You may remove this line if you want to manage the configuration yourself.
+          # static_site_generator: gatsby
+      # - name: Restore cache
+      #   uses: actions/cache@v4
+      #   with:
+      #     path: |
+      #       static
+      #       .cache
+      #     key: ${{ runner.os }}-docusaurus-build-${{ hashFiles('static') }}
+      #     restore-keys: |
+      #       ${{ runner.os }}-docusaurus-build-
+      - name: Install dependencies
+        run: npm ci
+      - name: Build with Docusaurus
+        run: npm run build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./build
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.github/workflows/test-build.yml

@@ -0,0 +1,24 @@
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm install
+      - name: Test build website
+        run: npm run build

.gitignore

@@ -1,18 +1,20 @@
-# See http://help.github.com/ignore-files/ for more about ignoring files.
-#
-# If you find yourself ignoring temporary files generated by your text editor
-# or operating system, you probably want to add a global ignore instead:
-# git config --global core.excludesfile ~/.gitignore_global
+# Dependencies
+/node_modules
 
-# Ignore bundler config
-/.bundle
-
-# Ignore the build directory
+# Production
 /build
 
-# Ignore cache
-/.sass-cache
-/.cache
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
 
-# Ignore .DS_store file
-.DS_Store
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# How to contribute to this site
+
+This website is built using [Docusaurus](https://docusaurus.io/) and is hosted on GitHub Pages using GitHub Actions to build and publish.
+
+
+## Getting set up
+
+### Prerequisites
+
+You'll need the following to run the site locally and make changes easily:
+
+1. Modern Node (check the `node-version` in [the deployment pipeline](./.github/workflows/deploy.yml) to see what we're targeting).
+2. [EditorConfig](https://editorconfig.org/) configured for your editor (optional). EditorConfig ensures your changes are consistent with the repository standards before you raise a pull request.
+
+> ℹ️ For VSCode there's an official [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) plugin.
+
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+## Local Development
+
+```bash
+npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+> ⚠️ The local development server doesn't build the search index. To test this locally, you'll need to build and serve the site (see below).
+
+## Build
+
+```bash
+npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service or using:
+
+```bash
+npm run serve
+```
+
+## Deployment
+
+Deployment is done automatically through GitHub Actions to GitHub Pages.
+
+### Break-glass deployment steps
+
+Using SSH:
+
+```bash
+USE_SSH=true npm run deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> npm run deploy
+```

LICENSE

@@ -0,0 +1,15 @@
+Copyright 2024 London Borough of Hackney
+
+## Source code
+
+Source code for the site (excluding the published content) is provided under the MIT License:
+
+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.
+
+## Published site content
+
+The written contents of the site, including code snippets held therein, are released under the [Open Government Licence](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

README.md

@@ -1,8 +1,35 @@
-# Hackney Development System Homepage
+# Hackney Development System
 
-This repo contains the homepage for the [Hackney Development System site](playbook.hackney.gov.uk)!
+The [Hackney Development System](https://playbook.hackney.gov.uk/) is the home of the Hackney development team's documentation, and details how we work as well as technical and architectural documentation.
+
+Project-specific documentation doesn't generally live here, and will be found alongside the code in the relevant repositories. There are exceptions, for example the API specifications section seeks to provide a central directory of Hackney's APIs.
+
+## Architecture
+
+This website is built using [Docusaurus](https://docusaurus.io/) and is hosted on GitHub Pages using GitHub Actions to build and publish.
+
+Before 2024 this site was built and deployed as a series of small static sites with independent repositories, build tooling, and styling.
+
+The site is now a single repository and build pipeline, which reduces the maintenance burden to upgrade dependencies and gives us more flexibility to alter and add to the structure.
+
+### Local search
+
+This site provides a search bar provided by an in-browser JavaScript library. This differs from the Docusaurus-supported default which relies on an Algolia account. We choose local-only search so we don't have to manage the Algolia account or rely on a third party service.
+
+### Google Analytics
+
+In order to measure the effectiveness of our documentation and identify stale or ineffective content we use Google Analytics, which records to a property in our Google Workspace.
+
+### Ownership
+
+Most of the content on this site belongs to Hackney's development community as a whole. Some sections, for example the Data Platform Playbook, belong to another group
+
+We use [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) to ensure the relevant owner approves a change before it can be merged.
+
+### Deployment
+
+The default branch of the repository is automatically built and deployed as a GitHub Pages site, using GitHub Actions. The deployment and test workflows are in [`.github/workflows/`](.github/workflows/).
 
 ## Contributing
-To make / preview changes, simply open the `index.html` file in your browser.
-Once your changes are complete, raise a PR. You must have at least one approval before you merge your PR.
-Upon merging, your changes will be deployed through our automated pipeline!
+
+Pull requeststs are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to run the site locally and make changes.

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};