From 42782018681941cd070fc080b82493981f5075e4 Mon Sep 17 00:00:00 2001 From: Ross Buggins Date: Thu, 30 May 2024 11:59:14 +0100 Subject: [PATCH 1/4] added dev container, docs and tasks to repo template. --- .devcontainer/devcontainer.json | 104 +++++++++++++ .github/workflows/jekyll-gh-pages.yml | 71 +++++++++ .tool-versions | 2 + .vscode/extensions.json | 36 ----- .vscode/settings.json | 7 - .vscode/tasks.json | 69 +++++++++ docs/.gitignore | 6 + docs/.vscode/launch.json | 11 ++ docs/.vscode/tasks.json | 13 ++ docs/404.html | 25 ++++ docs/Gemfile | 36 +++++ docs/Gemfile.lock | 107 ++++++++++++++ docs/Makefile | 17 +++ docs/README.md | 1 - .../nhs-notify-repository-template.md | 13 ++ docs/_config.dev.yml | 3 + docs/_config.yml | 100 +++++++++++++ docs/_includes/.gitkeep | 0 docs/_includes/notify-repo-list.html | 11 ++ docs/_includes/notify-repo-table.html | 18 +++ docs/_includes/page-info-header.html | 58 ++++++++ docs/_layouts/.gitkeep | 0 docs/_layouts/notify-repo.md | 29 ++++ docs/_layouts/page.html | 5 + .../2024-05-22-welcome-to-jekyll.markdown | 29 ++++ .../color_schemes/example-variables.scss | 137 ++++++++++++++++++ docs/_sass/color_schemes/nhs.scss | 18 +++ ...on_to_check_the_editorconfig_compliance.md | 42 +++--- ...2_Scan_repository_for_hardcoded_secrets.md | 34 +++-- ...GitHub_PAT_and_Apps_for_authN_and_authZ.md | 52 ++++--- docs/adr/index.md | 9 ++ docs/developer-guides/Bash_and_Make.md | 8 +- docs/developer-guides/Scripting_Docker.md | 8 +- docs/developer-guides/Scripting_Terraform.md | 30 ++-- docs/developer-guides/index.md | 6 + docs/index.md | 112 ++++++++++++++ docs/notify-repos/index.md | 8 + docs/package.json | 20 +++ docs/user-guides/Perform_static_analysis.md | 18 ++- docs/user-guides/Run_Git_hooks_on_commit.md | 14 +- docs/user-guides/Scan_dependencies.md | 8 +- docs/user-guides/Scan_secrets.md | 8 +- docs/user-guides/Sign_Git_commits.md | 8 +- .../Test_GitHub_Actions_locally.md | 18 ++- docs/user-guides/assets/test.drawio | 25 ++++ docs/user-guides/drawio.md | 19 +++ docs/user-guides/index.md | 6 + docs/user-guides/mermaid-diagrams.md | 17 +++ project.code-workspace | 8 - scripts/devcontainer/postcreatecommand.sh | 17 +++ scripts/devcontainer/poststartcommand.sh | 3 + 51 files changed, 1287 insertions(+), 137 deletions(-) create mode 100644 .devcontainer/devcontainer.json create mode 100644 .github/workflows/jekyll-gh-pages.yml delete mode 100644 .vscode/extensions.json delete mode 100644 .vscode/settings.json create mode 100644 .vscode/tasks.json create mode 100644 docs/.gitignore create mode 100644 docs/.vscode/launch.json create mode 100644 docs/.vscode/tasks.json create mode 100644 docs/404.html create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock create mode 100644 docs/Makefile delete mode 100644 docs/README.md create mode 100644 docs/_collections/_notify-repos/nhs-notify-repository-template.md create mode 100644 docs/_config.dev.yml create mode 100644 docs/_config.yml create mode 100644 docs/_includes/.gitkeep create mode 100644 docs/_includes/notify-repo-list.html create mode 100644 docs/_includes/notify-repo-table.html create mode 100644 docs/_includes/page-info-header.html create mode 100644 docs/_layouts/.gitkeep create mode 100644 docs/_layouts/notify-repo.md create mode 100644 docs/_layouts/page.html create mode 100644 docs/_posts/2024-05-22-welcome-to-jekyll.markdown create mode 100644 docs/_sass/color_schemes/example-variables.scss create mode 100644 docs/_sass/color_schemes/nhs.scss create mode 100644 docs/adr/index.md create mode 100644 docs/developer-guides/index.md create mode 100644 docs/index.md create mode 100644 docs/notify-repos/index.md create mode 100644 docs/package.json create mode 100644 docs/user-guides/assets/test.drawio create mode 100644 docs/user-guides/drawio.md create mode 100644 docs/user-guides/index.md create mode 100644 docs/user-guides/mermaid-diagrams.md delete mode 100644 project.code-workspace create mode 100755 scripts/devcontainer/postcreatecommand.sh create mode 100755 scripts/devcontainer/poststartcommand.sh diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..dd990735 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,104 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/jekyll +{ + "name": "Jekyll", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/jekyll:2-bullseye", + // Features to add to the dev container. More info: https://containers.dev/features. + // "features": {}, + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + // Uncomment the next line to run commands after the container is created. + "postCreateCommand": "zsh scripts/devcontainer/postcreatecommand.sh", + "postStartCommand": "zsh scripts/devcontainer/poststartcommand.sh", + "forwardPorts": [4000], + // Configure tool-specific properties. + "customizations": { + "codespaces": { + "openFiles": [ + "README.md", + ".github/SECURITY.md", + "docs/index.md" + ] + }, + "vscode": { + // Set *default* container specific settings.json values on container create. + "settings": { + "editor.formatOnSave": true, + "files.insertFinalNewline": true, + "[makefile]": { + "editor.insertSpaces": false, + "editor.detectIndentation": false + } + }, + // Add the IDs of extensions you want installed when the container is created. + "extensions": [ + "alefragnani.bookmarks", + "davidanson.vscode-markdownlint", + "dbaeumer.vscode-eslint", + "donjayamanne.githistory", + "eamodio.gitlens", + "editorconfig.editorconfig", + "esbenp.prettier-vscode", + "github.codespaces", + "github.github-vscode-theme", + "github.remotehub", + "github.vscode-github-actions", + "github.vscode-pull-request-github", + "hediet.vscode-drawio", + "johnpapa.vscode-peacock", + "mhutchie.git-graph", + "ms-azuretools.vscode-docker", + "ms-vscode-remote.remote-containers", + "ms-vscode-remote.remote-wsl", + "ms-vscode.hexeditor", + "ms-vscode.live-server", + "ms-vsliveshare.vsliveshare", + "redhat.vscode-xml", + "streetsidesoftware.code-spell-checker-british-english", + "tamasfe.even-better-toml", + "tomoki1207.pdf", + "vscode-icons-team.vscode-icons", + "vstirbu.vscode-mermaid-preview", + "wayou.vscode-todo-highlight", + "yzane.markdown-pdf", + "yzhang.dictionary-completion", + "yzhang.markdown-all-in-one" + ] + } + }, + "features": { + "ghcr.io/devcontainers/features/aws-cli:1": { + "version": "latest" + }, + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "moby": true, + "azureDnsAutoDetection": true, + "installDockerBuildx": true, + "installDockerComposeSwitch": true, + "version": "latest", + "dockerDashComposeVersion": "latest" + }, + "ghcr.io/devcontainers/features/node:1": { + "nodeGypDependencies": true, + "version": "lts", + "nvmVersion": "latest" + }, + "ghcr.io/devcontainers/features/github-cli:1": { + "installDirectlyFromGitHubRelease": true, + "version": "latest" + }, + "ghcr.io/devcontainers/features/common-utils:2": { + "installZsh": true, + "configureZshAsDefaultShell": true, + "installOhMyZsh": true, + "installOhMyZshConfig": true, + "upgradePackages": true, + "username": "automatic", + "userUid": "automatic", + "userGid": "automatic" + } + } + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" +} diff --git a/.github/workflows/jekyll-gh-pages.yml b/.github/workflows/jekyll-gh-pages.yml new file mode 100644 index 00000000..b3005c20 --- /dev/null +++ b/.github/workflows/jekyll-gh-pages.yml @@ -0,0 +1,71 @@ +# This workflow uses actions that are not certified by GitHub. +# They are provided by a third-party and are governed by +# separate terms of service, privacy policy, and support +# documentation. + +# Sample workflow for building and deploying a Jekyll site to GitHub Pages +name: Deploy Jekyll site to Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + + # 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 job + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docs + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Ruby + uses: ruby/setup-ruby@8575951200e472d5f2d95c625da0c7bec8217c42 # v1.161.0 + with: + ruby-version: '3.1' # Not needed with a .ruby-version file + bundler-cache: true # runs 'bundle install' and caches installed gems automatically + cache-version: 0 # Increment this number if you need to re-download cached gems + working-directory: './docs' + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + working-directory: ./docs + # Outputs to the './_site' directory by default + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + - name: Upload artifact + # Automatically uploads an artifact from the './_site' directory by default + uses: actions/upload-pages-artifact@v3 + with: + path: "docs/_site/" + + # 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 diff --git a/.tool-versions b/.tool-versions index 32db55a4..79f163d2 100644 --- a/.tool-versions +++ b/.tool-versions @@ -2,6 +2,8 @@ terraform 1.7.0 pre-commit 3.6.0 +nodejs 18.18.2 +gitleaks 8.15.3 # ============================================================================== # The section below is reserved for Docker image versions. diff --git a/.vscode/extensions.json b/.vscode/extensions.json deleted file mode 100644 index 957d73ff..00000000 --- a/.vscode/extensions.json +++ /dev/null @@ -1,36 +0,0 @@ -{ - "recommendations": [ - "alefragnani.bookmarks", - "davidanson.vscode-markdownlint", - "dbaeumer.vscode-eslint", - "donjayamanne.githistory", - "eamodio.gitlens", - "editorconfig.editorconfig", - "esbenp.prettier-vscode", - "github.codespaces", - "github.github-vscode-theme", - "github.remotehub", - "github.vscode-github-actions", - "github.vscode-pull-request-github", - "hediet.vscode-drawio", - "johnpapa.vscode-peacock", - "mhutchie.git-graph", - "ms-azuretools.vscode-docker", - "ms-vscode-remote.remote-containers", - "ms-vscode-remote.remote-wsl", - "ms-vscode.hexeditor", - "ms-vscode.live-server", - "ms-vsliveshare.vsliveshare", - "redhat.vscode-xml", - "streetsidesoftware.code-spell-checker-british-english", - "tamasfe.even-better-toml", - "tomoki1207.pdf", - "vscode-icons-team.vscode-icons", - "vstirbu.vscode-mermaid-preview", - "wayou.vscode-todo-highlight", - "yzane.markdown-pdf", - "yzhang.dictionary-completion", - "yzhang.markdown-all-in-one" - ], - "unwantedRecommendations": [] -} diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 423458c1..00000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "markdownlint.config": { - "MD013": false, - "MD024": { "siblings_only": true }, - "MD033": false - } -} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 00000000..eaac41b5 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,69 @@ + +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Start Make Config", + "type": "shell", + "command": "make config", + "group": "none", + "presentation": { + "reveal": "always", + "panel": "new" + }, + "runOptions": { + "runOn": "folderOpen", + } + } + ], + "settings": { + "workspace-terminals.switchTerminal": "always", + "workspace-terminals.auto": "always", + "markdownlint.config": { + "MD013": false, + "MD024": { "siblings_only": true }, + "MD033": false + }, + "cSpell.words": [ + "Codespaces", + "endfor" + ] + }, + "extensions": { + "recommendations": [ + "alefragnani.bookmarks", + "davidanson.vscode-markdownlint", + "dbaeumer.vscode-eslint", + "donjayamanne.githistory", + "eamodio.gitlens", + "editorconfig.editorconfig", + "esbenp.prettier-vscode", + "github.codespaces", + "github.github-vscode-theme", + "github.remotehub", + "github.vscode-github-actions", + "github.vscode-pull-request-github", + "hediet.vscode-drawio", + "johnpapa.vscode-peacock", + "mhutchie.git-graph", + "ms-azuretools.vscode-docker", + "ms-vscode-remote.remote-containers", + "ms-vscode-remote.remote-wsl", + "ms-vscode.hexeditor", + "ms-vscode.live-server", + "ms-vsliveshare.vsliveshare", + "redhat.vscode-xml", + "streetsidesoftware.code-spell-checker-british-english", + "tamasfe.even-better-toml", + "tomoki1207.pdf", + "vscode-icons-team.vscode-icons", + "vstirbu.vscode-mermaid-preview", + "wayou.vscode-todo-highlight", + "yzane.markdown-pdf", + "yzhang.dictionary-completion", + "yzhang.markdown-all-in-one", + "joshx.workspace-terminals" + ], + "unwantedRecommendations": [] + } +} diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..53d4e421 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,6 @@ +_site +.sass-cache +.jekyll-cache +.jekyll-metadata +vendor +#Gemfile.lock diff --git a/docs/.vscode/launch.json b/docs/.vscode/launch.json new file mode 100644 index 00000000..7a0ce952 --- /dev/null +++ b/docs/.vscode/launch.json @@ -0,0 +1,11 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "type": "node", + "request": "attach", + "name": "Attach", + "preLaunchTask": "jekyll" + } + ] +} diff --git a/docs/.vscode/tasks.json b/docs/.vscode/tasks.json new file mode 100644 index 00000000..ba151936 --- /dev/null +++ b/docs/.vscode/tasks.json @@ -0,0 +1,13 @@ +{ + "version": "2.0.0", + "tasks": [ + { + "label": "jekyll", + "options": { + "cwd": "${workspaceFolder}" + }, + "command": "make debug", + "type": "shell" + } + ] +} diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 00000000..086a5c9e --- /dev/null +++ b/docs/404.html @@ -0,0 +1,25 @@ +--- +permalink: /404.html +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 00000000..da46d858 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,36 @@ +source "https://rubygems.org" +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +gem "jekyll", "~> 4.3.3" +# This is the default theme for new Jekyll sites. You may change this to anything you like. +gem "minima", "~> 2.5" +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +# gem "github-pages", group: :jekyll_plugins +# If you have any plugins, put them here! +group :jekyll_plugins do + gem "jekyll-feed", "~> 0.12" + gem "jekyll-drawio" +end + +# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem +# and associated library. +platforms :mingw, :x64_mingw, :mswin, :jruby do + gem "tzinfo", ">= 1", "< 3" + gem "tzinfo-data" +end + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin] + +# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem +# do not have a Java counterpart. +gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby] + +gem "just-the-docs" diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 00000000..bb1714e5 --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,107 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.6) + public_suffix (>= 2.0.2, < 6.0) + cgi (0.4.1) + colorator (1.1.0) + concurrent-ruby (1.2.3) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + erb (4.0.4) + cgi (>= 0.3.3) + eventmachine (1.2.7) + ffi (1.16.3) + forwardable-extended (2.6.0) + google-protobuf (3.25.3-x86_64-linux) + http_parser.rb (0.8.0) + i18n (1.14.5) + concurrent-ruby (~> 1.0) + jekyll (4.3.3) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-drawio (1.1.1) + erb (>= 2.2, < 5.0) + jekyll (~> 4.3) + nokogiri (~> 1.12) + jekyll-feed (0.17.0) + jekyll (>= 3.7, < 5.0) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + just-the-docs (0.8.2) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + minima (2.5.1) + jekyll (>= 3.5, < 5.0) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + nokogiri (1.16.5-x86_64-linux) + racc (~> 1.4) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (5.0.5) + racc (1.8.0) + rake (13.2.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.2.8) + strscan (>= 3.0.9) + rouge (4.2.1) + safe_yaml (1.0.5) + sass-embedded (1.69.5) + google-protobuf (~> 3.23) + rake (>= 13.0.0) + strscan (3.1.0) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.5.0) + webrick (1.8.1) + +PLATFORMS + x86_64-linux + +DEPENDENCIES + http_parser.rb (~> 0.6.0) + jekyll (~> 4.3.3) + jekyll-drawio + jekyll-feed (~> 0.12) + just-the-docs + minima (~> 2.5) + tzinfo (>= 1, < 3) + tzinfo-data + wdm (~> 0.1.1) + +BUNDLED WITH + 2.5.10 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..b4d072ae --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,17 @@ +default: install + +h help: + @egrep '^\S|^$$' Makefile + +install: + bundle config set --local path vendor/bundle + bundle install + +s serve: + bundle exec jekyll serve --trace --livereload + +build: + JEKYLL_ENV=production bundle exec jekyll build --trace + +debug: + npm run debug diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 6968736e..00000000 --- a/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -# Documentation Home Page diff --git a/docs/_collections/_notify-repos/nhs-notify-repository-template.md b/docs/_collections/_notify-repos/nhs-notify-repository-template.md new file mode 100644 index 00000000..0e4b053b --- /dev/null +++ b/docs/_collections/_notify-repos/nhs-notify-repository-template.md @@ -0,0 +1,13 @@ +--- +repo-name: nhs-notify-repository-template +owners: ["rossbugginsnhs"] +name: Notify Template Management +description: Notify Template Management +layout: notify-repo +author: "Ross Buggins" +order: 1 +--- + +# Something + +Core repos. diff --git a/docs/_config.dev.yml b/docs/_config.dev.yml new file mode 100644 index 00000000..53d08cd1 --- /dev/null +++ b/docs/_config.dev.yml @@ -0,0 +1,3 @@ + +baseurl: "" # the subpath of your site, e.g. /blog +url: "" diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..d061fc80 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,100 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. +# +# If you need help with YAML syntax, here are some quick references for you: +# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml +# https://learnxinyminutes.com/docs/yaml/ +# +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. + +title: NHS Notify Repository Template Docs +# email: your-email@example.com +description: >- # this means to ignore newlines until "baseurl:" + Repository Template documentation for the NHS Notify Platform. +baseurl: "" # the subpath of your site, e.g. /blog +url: "https://nhsdigital.github.io" # the base hostname & protocol for your site, e.g. http://example.com + +collections_dir: _collections + +collections: + notify-repos: + output: true + sort_by: order + +# Build settings +theme: just-the-docs +plugins: + - jekyll-feed + +color_scheme: nhs +mermaid: + # Version of mermaid library + # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ + version: "10.9.1" + +aux_links: + "NHS Notify Repo Template on GitHub": + - "//github.com/NHSDigital/nhs-notify-repository-template" + +aux_links_new_tab: false + +# Footer "Edit this page on GitHub" link text +gh_edit_link: true # show or hide edit this page link +gh_edit_link_text: "Edit this page on GitHub." +gh_edit_repository: "https://github.com/NHSDigital/nhs-notify-repository-template" # the github URL for your repo +gh_edit_branch: "main" # the branch that your docs is served from +# gh_edit_source: docs # the source that your files originate from +gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately + +nav_external_links: + - title: Notify Service Catalogue + url: https://digital.nhs.uk/services/nhs-notify + hide_icon: false # set to true to hide the external link icon - defaults to false + opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false + + - title: Notify Tech Docs + url: https://nhsdigital.github.io/nhs-notify/ + hide_icon: false # set to true to hide the external link icon - defaults to false + opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false + + - title: NHS SEQF + url: https://github.com/NHSDigital/software-engineering-quality-framework + hide_icon: false # set to true to hide the external link icon - defaults to false + opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false + + +callouts: + warning: + title: Warning + color: red + +# Exclude from processing. +# The following items will not be processed, by default. +# Any item listed under the `exclude:` key here will be automatically added to +# the internal "default list". +# +# Excluded items can be processed by explicitly listing the directories or +# their entries' file path in the `include:` list. +# +# exclude: +# - .sass-cache/ +# - .jekyll-cache/ +# - gemfiles/ +# - Gemfile +# - Gemfile.lock +# - node_modules/ +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/docs/_includes/.gitkeep b/docs/_includes/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/_includes/notify-repo-list.html b/docs/_includes/notify-repo-list.html new file mode 100644 index 00000000..c2f8218d --- /dev/null +++ b/docs/_includes/notify-repo-list.html @@ -0,0 +1,11 @@ +

Repository List

+ + diff --git a/docs/_includes/notify-repo-table.html b/docs/_includes/notify-repo-table.html new file mode 100644 index 00000000..aaa0efab --- /dev/null +++ b/docs/_includes/notify-repo-table.html @@ -0,0 +1,18 @@ +

Repository List

+ + + + + + + {% for repo in site.notify-repos %} + + + + + {% endfor %} +
Repository NameMore Info
{{repo.repo-name}} + + {{ repo.name }} - {{ repo.description }} + +
diff --git a/docs/_includes/page-info-header.html b/docs/_includes/page-info-header.html new file mode 100644 index 00000000..a83edfa2 --- /dev/null +++ b/docs/_includes/page-info-header.html @@ -0,0 +1,58 @@ +{% if page.is_not_draft %}{% else %} {% assign is_draft = true %} {% endif %} {% +assign wordWarning = 200 %} {% assign wordCount = content | number_of_words%} {% +assign readTime = wordCount | divided_by: 100.0 | ceil %} {% if page.sub_title +%} +

{{ page.title }}

+

{{ page.summary }}

+{% else %} +

{{ page.title }}

+{% endif %} + +
+

+ {% if page.last_modified_date %} {{ page.last_modified_date | date: + "%Y-%m-%d"}} | {% else %} 2022-07-01 | {% endif %} 📑 {{ wordCount }} words + | ⏱ {{readTime}} mins {% if site.gh_edit_link and site.gh_edit_link_text and + site.gh_edit_repository and site.gh_edit_branch and site.gh_edit_view_mode + %} | + 🧾 History + + {% endif %} | {% if page.author %} ✍ {{page.author}} {% else %} ✍ Ross + Buggins {% endif %} | {% if page.owner %} 🔑 {{page.owner}} {% else %} 🔑 + Ross Buggins {% endif %} +

+ +

+ {% for tag in page.tags %}{{tag}},{% endfor %} +

+ + {% if wordCount < wordWarning %} +

+ 🚧 This page has less that {{wordWarning}} words. So it looks like this page + is still under construction. +

+ {% endif %} {% if page.description %} +

{{page.description}}

+ {% endif %} {% if page.todo or is_draft %} +

Known Issues / Todo

+ + + {% endif %} +
+ +
diff --git a/docs/_layouts/.gitkeep b/docs/_layouts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/_layouts/notify-repo.md b/docs/_layouts/notify-repo.md new file mode 100644 index 00000000..1b9cf0c6 --- /dev/null +++ b/docs/_layouts/notify-repo.md @@ -0,0 +1,29 @@ +--- +layout: default +--- + +

{{page.name}} Repository

+ +

+{{page.description}} +

+ +

+https://github.com/NHSDigital/{{page.repo-name}} +

+ +

Authors

+ + + +

{{ page.date }} - Written by {{ page.author }}

+ +

Content

+ +{{ content }} + +{% include notify-repo-list.html %} diff --git a/docs/_layouts/page.html b/docs/_layouts/page.html new file mode 100644 index 00000000..76206ebb --- /dev/null +++ b/docs/_layouts/page.html @@ -0,0 +1,5 @@ +--- +layout: default +--- + +{% include page-info-header.html %} diff --git a/docs/_posts/2024-05-22-welcome-to-jekyll.markdown b/docs/_posts/2024-05-22-welcome-to-jekyll.markdown new file mode 100644 index 00000000..0397aa74 --- /dev/null +++ b/docs/_posts/2024-05-22-welcome-to-jekyll.markdown @@ -0,0 +1,29 @@ +--- +layout: post +title: "Welcome to Jekyll!" +date: 2024-05-22 11:56:11 +0100 +categories: jekyll update +--- +You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated. + +Jekyll requires blog post files to be named according to the following format: + +`YEAR-MONTH-DAY-title.MARKUP` + +Where `YEAR` is a four-digit number, `MONTH` and `DAY` are both two-digit numbers, and `MARKUP` is the file extension representing the format used in the file. After that, include the necessary front matter. Take a look at the source for this post to get an idea about how it works. + +Jekyll also offers powerful support for code snippets: + +{% highlight ruby %} +def print_hi(name) + puts "Hi, #{name}" +end +print_hi('Tom') +#=> prints 'Hi, Tom' to STDOUT. +{% endhighlight %} + +Check out the [Jekyll docs][jekyll-docs] for more info on how to get the most out of Jekyll. File all bugs/feature requests at [Jekyll’s GitHub repo][jekyll-gh]. If you have questions, you can ask them on [Jekyll Talk][jekyll-talk]. + +[jekyll-docs]: https://jekyllrb.com/docs/home +[jekyll-gh]: https://github.com/jekyll/jekyll +[jekyll-talk]: https://talk.jekyllrb.com/ diff --git a/docs/_sass/color_schemes/example-variables.scss b/docs/_sass/color_schemes/example-variables.scss new file mode 100644 index 00000000..dd871781 --- /dev/null +++ b/docs/_sass/color_schemes/example-variables.scss @@ -0,0 +1,137 @@ +//Reference Links + +$color-scheme: dark; +$body-background-color: $grey-dk-300; +$body-heading-color: $grey-lt-000; +$body-text-color: $grey-lt-300; +$link-color: $blue-000; +$nav-child-link-color: $grey-dk-000; +$sidebar-color: $grey-dk-300; +$base-button-color: $grey-dk-250; +$btn-primary-color: $blue-200; +$code-background-color: #31343f; // OneDarkJekyll default for syntax-one-dark-vivid +$code-linenumber-color: #dee2f7; // OneDarkJekyll .nf for syntax-one-dark-vivid +$feedback-color: darken($sidebar-color, 3%); +$table-background-color: $grey-dk-250; +$search-background-color: $grey-dk-250; +$search-result-preview-color: $grey-dk-000; +$border-color: $grey-dk-200; + + +// To be set in colour scheme + +// prettier-ignore +$body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI", + roboto, "Helvetica Neue", arial, sans-serif, "Segoe UI Emoji" !default; +$mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default; +$root-font-size: 16px !default; // DEPRECATED: previously base font-size for rems +$body-line-height: 1.4 !default; +$content-line-height: 1.6 !default; +$body-heading-line-height: 1.25 !default; + +// Font size +// `-sm` suffix is the size at the small (and above) media query + +$font-size-1: 0.5625rem !default; +$font-size-1-sm: 0.625rem !default; +$font-size-2: 0.6875rem !default; // h4 - uppercased!, h6 not uppercased, text-small +$font-size-3: 0.75rem !default; // h5 +$font-size-4: 0.875rem !default; +$font-size-5: 1rem !default; // h3 +$font-size-6: 1.125rem !default; // h2 +$font-size-7: 1.5rem !default; +$font-size-8: 2rem !default; // h1 +$font-size-9: 2.25rem !default; +$font-size-10: 2.625rem !default; +$font-size-10-sm: 3rem !default; + +// Colors + +$white: #fff !default; +$grey-dk-000: #959396 !default; +$grey-dk-100: #5c5962 !default; +$grey-dk-200: #44434d !default; +$grey-dk-250: #302d36 !default; +$grey-dk-300: #27262b !default; +$grey-lt-000: #f5f6fa !default; +$grey-lt-100: #eeebee !default; +$grey-lt-200: #ecebed !default; +$grey-lt-300: #e6e1e8 !default; +$purple-000: #7253ed !default; +$purple-100: #5e41d0 !default; +$purple-200: #4e26af !default; +$purple-300: #381885 !default; +$blue-000: #2c84fa !default; +$blue-100: #2869e6 !default; +$blue-200: #264caf !default; +$blue-300: #183385 !default; +$green-000: #41d693 !default; +$green-100: #11b584 !default; +$green-200: #009c7b !default; +$green-300: #026e57 !default; +$yellow-000: #ffeb82 !default; +$yellow-100: #fadf50 !default; +$yellow-200: #f7d12e !default; +$yellow-300: #e7af06 !default; +$red-000: #f77e7e !default; +$red-100: #f96e65 !default; +$red-200: #e94c4c !default; +$red-300: #dd2e2e !default; + +// Spacing + +$spacing-unit: 1rem; // 1rem == 16px + +$spacers: ( + sp-0: 0, + sp-1: $spacing-unit * 0.25, + sp-2: $spacing-unit * 0.5, + sp-3: $spacing-unit * 0.75, + sp-4: $spacing-unit, + sp-5: $spacing-unit * 1.5, + sp-6: $spacing-unit * 2, + sp-7: $spacing-unit * 2.5, + sp-8: $spacing-unit * 3, + sp-9: $spacing-unit * 3.5, + sp-10: $spacing-unit * 4, +) !default; +$sp-1: map-get($spacers, sp-1) !default; // 0.25 rem == 4px +$sp-2: map-get($spacers, sp-2) !default; // 0.5 rem == 8px +$sp-3: map-get($spacers, sp-3) !default; // 0.75 rem == 12px +$sp-4: map-get($spacers, sp-4) !default; // 1 rem == 16px +$sp-5: map-get($spacers, sp-5) !default; // 1.5 rem == 24px +$sp-6: map-get($spacers, sp-6) !default; // 2 rem == 32px +$sp-7: map-get($spacers, sp-7) !default; // 2.5 rem == 40px +$sp-8: map-get($spacers, sp-8) !default; // 3 rem == 48px +$sp-9: map-get($spacers, sp-9) !default; // 3.5 rem == 56px +$sp-10: map-get($spacers, sp-10) !default; // 4 rem == 64px + +// Borders + +$border: 1px solid !default; +$border-radius: 4px !default; +$border-color: $grey-lt-100 !default; + +// Grid system + +$gutter-spacing: $sp-6 !default; +$gutter-spacing-sm: $sp-4 !default; +$nav-width: 16.5rem !default; +$nav-width-md: 15.5rem !default; +$nav-list-item-height: $sp-6 !default; +$nav-list-item-height-sm: $sp-8 !default; +$nav-list-expander-right: true; +$content-width: 50rem !default; +$header-height: 3.75rem !default; +$search-results-width: $content-width - $nav-width !default; +$transition-duration: 400ms; + +// Media queries in pixels + +$media-queries: ( + xs: 20rem, + sm: 31.25rem, + md: $content-width, + lg: $content-width + $nav-width, + xl: 87.5rem, +) !default; diff --git a/docs/_sass/color_schemes/nhs.scss b/docs/_sass/color_schemes/nhs.scss new file mode 100644 index 00000000..5b45b8f1 --- /dev/null +++ b/docs/_sass/color_schemes/nhs.scss @@ -0,0 +1,18 @@ +@import "./color_schemes/light"; + +// Typography + +// prettier-ignore +$body-font-family: "Frutiger W01", Arial, Sans-serif; +$mono-font-family: "Frutiger W01", Arial, Sans-serif; + + + +$blue-000: #005eb8; +$grey-dk-000: #d8dde0; +$grey-dk-100: #f0f4f5; +$sidebar-color: $grey-dk-000; +$body-background-color: $grey-dk-100; +$link-color: $blue-000; + +$font-size-7: 1.25rem; diff --git a/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md b/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md index 0ddc032b..a3020cd4 100644 --- a/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md +++ b/docs/adr/ADR-001_Use_git_hook_and_GitHub_action_to_check_the_editorconfig_compliance.md @@ -1,4 +1,12 @@ -# ADR-001: Use git hook and GitHub Action to check the `.editorconfig` compliance +--- +layout: default +title: ADR-001 +parent: ADRs +description: Use git hook and GitHub Action to check the .editorconfig compliance +summary: Use git hook and GitHub Action to check the .editorconfig compliance +--- + +## ADR-001: Use git hook and GitHub Action to check the `.editorconfig` compliance >| | | >| ------------ | ---------------------------------------------------- | @@ -11,22 +19,22 @@ --- - [ADR-001: Use git hook and GitHub Action to check the `.editorconfig` compliance](#adr-001-use-git-hook-and-github-action-to-check-the-editorconfig-compliance) - - [Context](#context) - - [Decision](#decision) - - [Assumptions](#assumptions) - - [Drivers](#drivers) - - [Options](#options) - - [Options 1: The pre-commit project](#options-1-the-pre-commit-project) - - [Options 2a: Custom shell script](#options-2a-custom-shell-script) - - [Options 2b: Docker-based custom shell script](#options-2b-docker-based-custom-shell-script) - - [Option 3: A GitHub Action from the Marketplace](#option-3-a-github-action-from-the-marketplace) - - [Outcome](#outcome) - - [Rationale](#rationale) - - [Consequences](#consequences) - - [Compliance](#compliance) - - [Notes](#notes) - - [Actions](#actions) - - [Tags](#tags) +- [Context](#context) +- [Decision](#decision) + - [Assumptions](#assumptions) + - [Drivers](#drivers) + - [Options](#options) + - [Options 1: The pre-commit project](#options-1-the-pre-commit-project) + - [Options 2a: Custom shell script](#options-2a-custom-shell-script) + - [Options 2b: Docker-based custom shell script](#options-2b-docker-based-custom-shell-script) + - [Option 3: A GitHub Action from the Marketplace](#option-3-a-github-action-from-the-marketplace) + - [Outcome](#outcome) + - [Rationale](#rationale) +- [Consequences](#consequences) +- [Compliance](#compliance) +- [Notes](#notes) +- [Actions](#actions) +- [Tags](#tags) ## Context diff --git a/docs/adr/ADR-002_Scan_repository_for_hardcoded_secrets.md b/docs/adr/ADR-002_Scan_repository_for_hardcoded_secrets.md index 0cf78d43..a18dc620 100644 --- a/docs/adr/ADR-002_Scan_repository_for_hardcoded_secrets.md +++ b/docs/adr/ADR-002_Scan_repository_for_hardcoded_secrets.md @@ -1,4 +1,12 @@ -# ADR-002: Scan repository for hard-coded secrets +--- +layout: default +title: ADR-002 +parent: ADRs +description: Scan repository for hard-coded secrets +summary: Scan repository for hard-coded secrets +--- + +## ADR-002: Scan repository for hard-coded secrets >| | | >| ------------ | ------------------------------------------------------------- | @@ -11,18 +19,18 @@ --- - [ADR-002: Scan repository for hard-coded secrets](#adr-002-scan-repository-for-hard-coded-secrets) - - [Context](#context) - - [Decision](#decision) - - [Assumptions](#assumptions) - - [Drivers](#drivers) - - [Options](#options) - - [Outcome](#outcome) - - [Rationale](#rationale) - - [Consequences](#consequences) - - [Compliance](#compliance) - - [Notes](#notes) - - [Actions](#actions) - - [Tags](#tags) +- [Context](#context) +- [Decision](#decision) + - [Assumptions](#assumptions) + - [Drivers](#drivers) + - [Options](#options) + - [Outcome](#outcome) + - [Rationale](#rationale) +- [Consequences](#consequences) +- [Compliance](#compliance) +- [Notes](#notes) +- [Actions](#actions) +- [Tags](#tags) ## Context diff --git a/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md b/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md index cd82a32c..be0a9aff 100644 --- a/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md +++ b/docs/adr/ADR-003_Acceptable_use_of_GitHub_PAT_and_Apps_for_authN_and_authZ.md @@ -1,4 +1,12 @@ -# ADR-003: Acceptable use of GitHub authentication and authorisation mechanisms +--- +layout: default +title: ADR-003 +parent: ADRs +description: Acceptable use of GitHub authentication and authorisation mechanisms +summary: Acceptable use of GitHub authentication and authorisation mechanisms +--- + +## ADR-003: Acceptable use of GitHub authentication and authorisation mechanisms >| | | >| ------------ | --- | @@ -11,27 +19,27 @@ --- - [ADR-003: Acceptable use of GitHub authentication and authorisation mechanisms](#adr-003-acceptable-use-of-github-authentication-and-authorisation-mechanisms) - - [Context](#context) - - [Decision](#decision) - - [Assumptions](#assumptions) - - [Drivers](#drivers) - - [Options](#options) - - [Outcome](#outcome) - - [Built-in authentication using `GITHUB_TOKEN` secret](#built-in-authentication-using-github_token-secret) - - [GitHub PAT (fine-grained Personal Access Token)](#github-pat-fine-grained-personal-access-token) - - [GitHub App](#github-app) - - [Rationale](#rationale) - - [Notes](#notes) - - [GitHub App setup](#github-app-setup) - - [Recommendation for GitHub Admins](#recommendation-for-github-admins) - - [Diagram](#diagram) - - [Context diagram showing the GitHub App setup](#context-diagram-showing-the-github-app-setup) - - [Authentication flow diagram](#authentication-flow-diagram) - - [Limitations](#limitations) - - [Examples of acquiring access token](#examples-of-acquiring-access-token) - - [Actions](#actions) - - [Tags](#tags) - - [Footnotes](#footnotes) +- [Context](#context) +- [Decision](#decision) + - [Assumptions](#assumptions) + - [Drivers](#drivers) + - [Options](#options) + - [Outcome](#outcome) + - [Built-in authentication using `GITHUB_TOKEN` secret](#built-in-authentication-using-github_token-secret) + - [GitHub PAT (fine-grained Personal Access Token)](#github-pat-fine-grained-personal-access-token) + - [GitHub App](#github-app) + - [Rationale](#rationale) +- [Notes](#notes) + - [GitHub App setup](#github-app-setup) + - [Recommendation for GitHub Admins](#recommendation-for-github-admins) + - [Diagram](#diagram) + - [Context diagram showing the GitHub App setup](#context-diagram-showing-the-github-app-setup) + - [Authentication flow diagram](#authentication-flow-diagram) + - [Limitations](#limitations) + - [Examples of acquiring access token](#examples-of-acquiring-access-token) +- [Actions](#actions) +- [Tags](#tags) +- [Footnotes](#footnotes) ## Context diff --git a/docs/adr/index.md b/docs/adr/index.md new file mode 100644 index 00000000..09dc82dd --- /dev/null +++ b/docs/adr/index.md @@ -0,0 +1,9 @@ +--- +layout: default +title: ADRs +nav_order: 2 +has_children: true +child_nav_order: reversed +--- + +## NHS Notify Architecture Decision Records (ADR) diff --git a/docs/developer-guides/Bash_and_Make.md b/docs/developer-guides/Bash_and_Make.md index d4379910..a2f74049 100644 --- a/docs/developer-guides/Bash_and_Make.md +++ b/docs/developer-guides/Bash_and_Make.md @@ -1,4 +1,10 @@ -# Developer Guide: Bash and Make +--- +layout: default +title: Bash and Make +parent: Developer Guides +--- + +## Developer Guide: Bash and Make - [Developer Guide: Bash and Make](#developer-guide-bash-and-make) - [Using Make](#using-make) diff --git a/docs/developer-guides/Scripting_Docker.md b/docs/developer-guides/Scripting_Docker.md index fa12093c..74741171 100644 --- a/docs/developer-guides/Scripting_Docker.md +++ b/docs/developer-guides/Scripting_Docker.md @@ -1,4 +1,10 @@ -# Developer Guide: Scripting Docker +--- +layout: default +title: Scripting Docker +parent: Developer Guides +--- + +## Developer Guide: Scripting Docker - [Developer Guide: Scripting Docker](#developer-guide-scripting-docker) - [Overview](#overview) diff --git a/docs/developer-guides/Scripting_Terraform.md b/docs/developer-guides/Scripting_Terraform.md index 14b80ca1..8a0dc788 100644 --- a/docs/developer-guides/Scripting_Terraform.md +++ b/docs/developer-guides/Scripting_Terraform.md @@ -1,17 +1,23 @@ -# Developer Guide: Scripting Terraform +--- +layout: default +title: Scripting Terraform +parent: Developer Guides +--- + +## Developer Guide: Scripting Terraform - [Developer Guide: Scripting Terraform](#developer-guide-scripting-terraform) - - [Overview](#overview) - - [Features](#features) - - [Key files](#key-files) - - [Usage](#usage) - - [Quick start](#quick-start) - - [Your stack implementation](#your-stack-implementation) - - [Conventions](#conventions) - - [Secrets](#secrets) - - [Variables](#variables) - - [IaC directory](#iac-directory) - - [FAQ](#faq) +- [Overview](#overview) +- [Features](#features) +- [Key files](#key-files) +- [Usage](#usage) + - [Quick start](#quick-start) + - [Your stack implementation](#your-stack-implementation) +- [Conventions](#conventions) + - [Secrets](#secrets) + - [Variables](#variables) + - [IaC directory](#iac-directory) +- [FAQ](#faq) ## Overview diff --git a/docs/developer-guides/index.md b/docs/developer-guides/index.md new file mode 100644 index 00000000..58d58346 --- /dev/null +++ b/docs/developer-guides/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: Developer Guides +nav_order: 3 +has_children: true +--- diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..c77dafc6 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,112 @@ +--- +# Feel free to add content and custom Front Matter to this file. +# To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults + +layout: home +title: Home +nav_order: 1 +--- + +[![CI/CD Pull Request](https://github.com/NHSDigital/nhs-notify/actions/workflows/jekyll-gh-pages.yml/badge.svg)](https://github.com/NHSDigital/nhs-notify/actions/workflows/jekyll-gh-pages.yml) + +## NHS Notify Technical Developer Documentation + +> Please visit the [NHS Service Catalogue](https://digital.nhs.uk/services/nhs-notify) for: +> +> - NHS Notify web site. +> - Onboarding guidance. +> - Customer support. +> - Supplier support. +> +> ### Who/what is this repository is for? +> +> - NHS Developers working on NHS Notify +> - Those who are interested in NHS Notify architecture and how it is actively developed +> +> ### Who/what is this repository **not** for? +> +> - Customer Support +> - Supplier Support +> +> ### What this repo contains +> +> - High level developer documentation for source code location, and build process. +> - Acts as the "root" for all separate public NHS Notify repositories. +> +> ### What this repo does **not** contain +> +> - Any configuration of details of the Deployment phases or infrastructure of the NHS Notify Platform. +> - Information about the NHS England hosted NHS Notify platform +> + +## Table of Contents + +- [NHS Notify Technical Developer Documentation](#nhs-notify-technical-developer-documentation) +- [Table of Contents](#table-of-contents) +- [Related Repos](#related-repos) +- [Documentation](#documentation) +- [Setup](#setup) + - [Prerequisites](#prerequisites) + - [Configuration](#configuration) +- [Contributing](#contributing) +- [Licence](#licence) + +## Related Repos + +- [nhs-notify](https://nhsdigital.github.io/nhs-notify) +- [nhs-notify-dns](https://nhsdigital.github.io/nhs-notify-dns) + +## Documentation + +- [Built](https://nhsdigital.github.io/nhs-notify/) +- [Source](/docs/README.md) + +## Setup + +Clone the repository + +```shell +git clone https://github.com/NHSDigital/nhs-notify.git +cd nhs-notify +code project.code-workspace +``` + +### Prerequisites + +The following software packages, or their equivalents, are expected to be installed and configured: + +- [Docker](https://www.docker.com/) container runtime or a compatible tool, e.g. [Podman](https://podman.io/), +- [asdf](https://asdf-vm.com/) version manager, +- [GNU make](https://www.gnu.org/software/make/) 3.82 or later, +- [GNU coreutils](https://www.gnu.org/software/coreutils/) and [GNU binutils](https://www.gnu.org/software/binutils/) may be required to build dependencies like Python, which may need to be compiled during installation. For macOS users, this has been scripted and automated by the `dotfiles` project; please see this [script](https://github.com/nhs-england-tools/dotfiles/blob/main/assets/20-install-base-packages.macos.sh) for details, +- [Python](https://www.python.org/) required to run Git hooks, +- [`jq`](https://jqlang.github.io/jq/) a lightweight and flexible command-line JSON processor. + +> [!NOTE]
+> The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain `make` tasks will fail. On macOS, you will need [Homebrew](https://brew.sh/) installed, then to install `make`, like so: +> +> ```shell +> brew install make +> ``` +> +> You will then see instructions to fix your `$PATH` variable to make the newly installed version available. If you are using [dotfiles](https://github.com/nhs-england-tools/dotfiles), this is all done for you. + +### Configuration + +Installation and configuration of the toolchain dependencies (including pre-git hooks). + +```shell +make config +``` + +## Contributing + +Describe or link templates on how to raise an issue, feature request or make a contribution to the codebase. Reference the other documentation files, like + +- Environment setup for contribution, i.e. `CONTRIBUTING.md` + +## Licence + +Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. + +Any HTML or Markdown documentation is [© Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). diff --git a/docs/notify-repos/index.md b/docs/notify-repos/index.md new file mode 100644 index 00000000..1914d9c8 --- /dev/null +++ b/docs/notify-repos/index.md @@ -0,0 +1,8 @@ +--- +layout: default +title: Repositories +nav_order: 6 +has_children: false +--- + +{% include notify-repo-table.html %} diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 00000000..785304f3 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,20 @@ +{ + "name": "nhs-notify", + "version": "1.0.0", + "description": "", + "private": true, + "engines": { + }, + + "scripts": { + "debug": "JEKYLL_ENV=development BUNDLE_GEMFILE=Gemfile bundle exec jekyll serve --config _config.yml,_config.dev.yml --limit_posts 100 --trace --livereload" + + }, + "keywords": [], + "author": "", + "license": "ISC", + "devDependencies": { + }, + "dependencies": { + } +} diff --git a/docs/user-guides/Perform_static_analysis.md b/docs/user-guides/Perform_static_analysis.md index a1f70118..7f9ef01a 100644 --- a/docs/user-guides/Perform_static_analysis.md +++ b/docs/user-guides/Perform_static_analysis.md @@ -1,11 +1,17 @@ -# Guide: Perform static analysis +--- +layout: default +title: Perform static analysis +parent: User Guides +--- + +## Guide: Perform static analysis - [Guide: Perform static analysis](#guide-perform-static-analysis) - - [Overview](#overview) - - [Key files](#key-files) - - [Setup](#setup) - - [Testing](#testing) - - [Configuration checklist](#configuration-checklist) +- [Overview](#overview) +- [Key files](#key-files) +- [Setup](#setup) +- [Testing](#testing) +- [Configuration checklist](#configuration-checklist) ## Overview diff --git a/docs/user-guides/Run_Git_hooks_on_commit.md b/docs/user-guides/Run_Git_hooks_on_commit.md index 5dd191f5..07c9569b 100644 --- a/docs/user-guides/Run_Git_hooks_on_commit.md +++ b/docs/user-guides/Run_Git_hooks_on_commit.md @@ -1,9 +1,15 @@ -# Guide: Run Git hooks on commit +--- +layout: default +title: Run Git hooks on commit +parent: User Guides +--- + +## Guide: Run Git hooks on commit - [Guide: Run Git hooks on commit](#guide-run-git-hooks-on-commit) - - [Overview](#overview) - - [Key files](#key-files) - - [Testing](#testing) +- [Overview](#overview) +- [Key files](#key-files) +- [Testing](#testing) ## Overview diff --git a/docs/user-guides/Scan_dependencies.md b/docs/user-guides/Scan_dependencies.md index 4145897e..303fd82d 100644 --- a/docs/user-guides/Scan_dependencies.md +++ b/docs/user-guides/Scan_dependencies.md @@ -1,4 +1,10 @@ -# Guide: Scan dependencies +--- +layout: default +title: Scan dependencies +parent: User Guides +--- + +## Guide: Scan dependencies - [Guide: Scan dependencies](#guide-scan-dependencies) - [Overview](#overview) diff --git a/docs/user-guides/Scan_secrets.md b/docs/user-guides/Scan_secrets.md index 1e3e1e10..03c36590 100644 --- a/docs/user-guides/Scan_secrets.md +++ b/docs/user-guides/Scan_secrets.md @@ -1,4 +1,10 @@ -# Guide: Scan secrets +--- +layout: default +title: Scan secrets +parent: User Guides +--- + +## Guide: Scan secrets - [Guide: Scan secrets](#guide-scan-secrets) - [Overview](#overview) diff --git a/docs/user-guides/Sign_Git_commits.md b/docs/user-guides/Sign_Git_commits.md index 0ad07281..a6273746 100644 --- a/docs/user-guides/Sign_Git_commits.md +++ b/docs/user-guides/Sign_Git_commits.md @@ -1,4 +1,10 @@ -# Guide: Sign Git commits +--- +layout: default +title: Sign Git commits +parent: User Guides +--- + +## Guide: Sign Git commits - [Guide: Sign Git commits](#guide-sign-git-commits) - [Overview](#overview) diff --git a/docs/user-guides/Test_GitHub_Actions_locally.md b/docs/user-guides/Test_GitHub_Actions_locally.md index 2da643b2..7bed68fe 100644 --- a/docs/user-guides/Test_GitHub_Actions_locally.md +++ b/docs/user-guides/Test_GitHub_Actions_locally.md @@ -1,11 +1,17 @@ -# Guide: Test GitHub Actions locally +--- +layout: default +title: Test GitHub Actions locally +parent: User Guides +--- + +## Guide: Test GitHub Actions locally - [Guide: Test GitHub Actions locally](#guide-test-github-actions-locally) - - [Overview](#overview) - - [Key files](#key-files) - - [Prerequisites](#prerequisites) - - [Testing](#testing) - - [FAQ](#faq) +- [Overview](#overview) +- [Key files](#key-files) +- [Prerequisites](#prerequisites) +- [Testing](#testing) +- [FAQ](#faq) ## Overview diff --git a/docs/user-guides/assets/test.drawio b/docs/user-guides/assets/test.drawio new file mode 100644 index 00000000..4a8fd61a --- /dev/null +++ b/docs/user-guides/assets/test.drawio @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user-guides/drawio.md b/docs/user-guides/drawio.md new file mode 100644 index 00000000..4f806e02 --- /dev/null +++ b/docs/user-guides/drawio.md @@ -0,0 +1,19 @@ +--- +layout: default +title: Draw IO +parent: User Guides + +--- +## Using Draw io + +Reference a drawio file by: + +{% raw %} + +```text +{% drawio path="./user-guides/assets/test.drawio" page_number=0 height=400 %} +``` + +{% endraw %} + +{% drawio path="./user-guides/assets/test.drawio" page_number=0 height=400 %} diff --git a/docs/user-guides/index.md b/docs/user-guides/index.md new file mode 100644 index 00000000..5a77b064 --- /dev/null +++ b/docs/user-guides/index.md @@ -0,0 +1,6 @@ +--- +layout: default +title: User Guides +nav_order: 4 +has_children: true +--- diff --git a/docs/user-guides/mermaid-diagrams.md b/docs/user-guides/mermaid-diagrams.md new file mode 100644 index 00000000..5058b378 --- /dev/null +++ b/docs/user-guides/mermaid-diagrams.md @@ -0,0 +1,17 @@ +--- +layout: default +title: Mermaid Diagrams +parent: User Guides +--- + +## Guide: Perform static analysis + +- [Guide: Perform static analysis](#guide-perform-static-analysis) +- [Overview](#overview) + +## Overview + +```mermaid +flowchart TB + A & B--> C & D +``` diff --git a/project.code-workspace b/project.code-workspace deleted file mode 100644 index ff841431..00000000 --- a/project.code-workspace +++ /dev/null @@ -1,8 +0,0 @@ -{ - "folders": [ - { - "name": "NHS Notify Repo Template", - "path": "." - } - ] -} diff --git a/scripts/devcontainer/postcreatecommand.sh b/scripts/devcontainer/postcreatecommand.sh new file mode 100755 index 00000000..aefabaf3 --- /dev/null +++ b/scripts/devcontainer/postcreatecommand.sh @@ -0,0 +1,17 @@ +#!/bin/bash + +rm -Rf ~/.asdf +git clone https://github.com/asdf-vm/asdf.git ~/.asdf; +chmod +x ~/.asdf/asdf.sh; +echo '. $HOME/.asdf/asdf.sh' >> ~/.zshrc +echo '. $HOME/.asdf/completions/asdf.bash' >> ~/.zshrc + +source ~/.zshrc + +echo 'asdf setup complete' + +make config + +jekyll --version && cd docs && bundle install + +echo 'jekyll setup complete' diff --git a/scripts/devcontainer/poststartcommand.sh b/scripts/devcontainer/poststartcommand.sh new file mode 100755 index 00000000..31a110d1 --- /dev/null +++ b/scripts/devcontainer/poststartcommand.sh @@ -0,0 +1,3 @@ +#!/bin/bash +source ~/.zshrc +make config From 6bea3135c9d76a06af77265f13906b2d57dab270 Mon Sep 17 00:00:00 2001 From: Ross Buggins Date: Thu, 30 May 2024 12:04:19 +0100 Subject: [PATCH 2/4] spelling --- docs/user-guides/drawio.md | 4 ++-- scripts/config/vale/styles/Vocab/words/accept.txt | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/user-guides/drawio.md b/docs/user-guides/drawio.md index 4f806e02..07a571e1 100644 --- a/docs/user-guides/drawio.md +++ b/docs/user-guides/drawio.md @@ -4,9 +4,9 @@ title: Draw IO parent: User Guides --- -## Using Draw io +## Using draw.io -Reference a drawio file by: +Reference a draw.io file by: {% raw %} diff --git a/scripts/config/vale/styles/Vocab/words/accept.txt b/scripts/config/vale/styles/Vocab/words/accept.txt index dccae85c..034010b5 100644 --- a/scripts/config/vale/styles/Vocab/words/accept.txt +++ b/scripts/config/vale/styles/Vocab/words/accept.txt @@ -15,4 +15,6 @@ idempotence onboarding toolchain [A-Z]+s -Github +GitHub +endraw +draw.io From c0566fc509894469c92b9d8c024ba2bb839d3d26 Mon Sep 17 00:00:00 2001 From: Ross Buggins Date: Thu, 30 May 2024 12:10:35 +0100 Subject: [PATCH 3/4] docs home page --- docs/index.md | 104 +------------------------------------------------- 1 file changed, 2 insertions(+), 102 deletions(-) diff --git a/docs/index.md b/docs/index.md index c77dafc6..6c205011 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,106 +7,6 @@ title: Home nav_order: 1 --- -[![CI/CD Pull Request](https://github.com/NHSDigital/nhs-notify/actions/workflows/jekyll-gh-pages.yml/badge.svg)](https://github.com/NHSDigital/nhs-notify/actions/workflows/jekyll-gh-pages.yml) +[![CI/CD Pull Request](https://github.com/NHSDigital/nhs-notify-repository-template/actions/workflows/cicd-1-pull-request.yaml/badge.svg)](https://github.com/NHSDigital/nhs-notify-repository-template/actions/workflows/cicd-1-pull-request.yaml) -## NHS Notify Technical Developer Documentation - -> Please visit the [NHS Service Catalogue](https://digital.nhs.uk/services/nhs-notify) for: -> -> - NHS Notify web site. -> - Onboarding guidance. -> - Customer support. -> - Supplier support. -> -> ### Who/what is this repository is for? -> -> - NHS Developers working on NHS Notify -> - Those who are interested in NHS Notify architecture and how it is actively developed -> -> ### Who/what is this repository **not** for? -> -> - Customer Support -> - Supplier Support -> -> ### What this repo contains -> -> - High level developer documentation for source code location, and build process. -> - Acts as the "root" for all separate public NHS Notify repositories. -> -> ### What this repo does **not** contain -> -> - Any configuration of details of the Deployment phases or infrastructure of the NHS Notify Platform. -> - Information about the NHS England hosted NHS Notify platform -> - -## Table of Contents - -- [NHS Notify Technical Developer Documentation](#nhs-notify-technical-developer-documentation) -- [Table of Contents](#table-of-contents) -- [Related Repos](#related-repos) -- [Documentation](#documentation) -- [Setup](#setup) - - [Prerequisites](#prerequisites) - - [Configuration](#configuration) -- [Contributing](#contributing) -- [Licence](#licence) - -## Related Repos - -- [nhs-notify](https://nhsdigital.github.io/nhs-notify) -- [nhs-notify-dns](https://nhsdigital.github.io/nhs-notify-dns) - -## Documentation - -- [Built](https://nhsdigital.github.io/nhs-notify/) -- [Source](/docs/README.md) - -## Setup - -Clone the repository - -```shell -git clone https://github.com/NHSDigital/nhs-notify.git -cd nhs-notify -code project.code-workspace -``` - -### Prerequisites - -The following software packages, or their equivalents, are expected to be installed and configured: - -- [Docker](https://www.docker.com/) container runtime or a compatible tool, e.g. [Podman](https://podman.io/), -- [asdf](https://asdf-vm.com/) version manager, -- [GNU make](https://www.gnu.org/software/make/) 3.82 or later, -- [GNU coreutils](https://www.gnu.org/software/coreutils/) and [GNU binutils](https://www.gnu.org/software/binutils/) may be required to build dependencies like Python, which may need to be compiled during installation. For macOS users, this has been scripted and automated by the `dotfiles` project; please see this [script](https://github.com/nhs-england-tools/dotfiles/blob/main/assets/20-install-base-packages.macos.sh) for details, -- [Python](https://www.python.org/) required to run Git hooks, -- [`jq`](https://jqlang.github.io/jq/) a lightweight and flexible command-line JSON processor. - -> [!NOTE]
-> The version of GNU make available by default on macOS is earlier than 3.82. You will need to upgrade it or certain `make` tasks will fail. On macOS, you will need [Homebrew](https://brew.sh/) installed, then to install `make`, like so: -> -> ```shell -> brew install make -> ``` -> -> You will then see instructions to fix your `$PATH` variable to make the newly installed version available. If you are using [dotfiles](https://github.com/nhs-england-tools/dotfiles), this is all done for you. - -### Configuration - -Installation and configuration of the toolchain dependencies (including pre-git hooks). - -```shell -make config -``` - -## Contributing - -Describe or link templates on how to raise an issue, feature request or make a contribution to the codebase. Reference the other documentation files, like - -- Environment setup for contribution, i.e. `CONTRIBUTING.md` - -## Licence - -Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. - -Any HTML or Markdown documentation is [© Crown Copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/crown-copyright/) and available under the terms of the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). +## NHS Notify Template Repository Documentation Home Page From 24142681aaba65408714c859643b40e9cd40138d Mon Sep 17 00:00:00 2001 From: Ross Buggins Date: Thu, 30 May 2024 12:12:54 +0100 Subject: [PATCH 4/4] spelling --- scripts/config/vale/styles/Vocab/words/accept.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/config/vale/styles/Vocab/words/accept.txt b/scripts/config/vale/styles/Vocab/words/accept.txt index 034010b5..4a2b7179 100644 --- a/scripts/config/vale/styles/Vocab/words/accept.txt +++ b/scripts/config/vale/styles/Vocab/words/accept.txt @@ -18,3 +18,5 @@ toolchain GitHub endraw draw.io +endfor +drawio