CCM-11207 Generate docs, overviews, placeholders, publish

.github/actions/build-docs/action.yml

@@ -14,7 +14,7 @@ runs:
         node-version: 18
     - name: Npm cli install
       working-directory: .
-      run: npm ci -w docs
+      run: npm ci
       shell: bash
     - name: Setup Ruby
       uses: ruby/setup-ruby@v1.180.1

.github/workflows/cicd-3-deploy.yaml

@@ -101,37 +101,15 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release download ${{steps.get-asset-version.outputs.release_version}} -p sdk-swagger-docs-*.tar --output artifact.tar
+          gh release download ${{steps.get-asset-version.outputs.release_version}} -p jekyll-docs-*.tar --output artifact.tar
 
       - uses: actions/upload-artifact@v4
         with:
-          name: sdk-swagger-docs-${{steps.get-asset-version.outputs.release_version}}
+          name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}
           path: artifact.tar
 
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
         with:
-          artifact_name: sdk-swagger-docs-${{steps.get-asset-version.outputs.release_version}}
-
-
-      ### BELOW WAS THE DEFAULT USING THE JEKYLL BUILD
-
-      # - name: "Get release version"
-      #   id: download-asset
-      #   shell: bash
-      #   env:
-      #     GH_TOKEN: ${{ github.token }}
-      #   run: |
-      #     gh release download ${{steps.get-asset-version.outputs.release_version}} -p jekyll-docs-*.tar --output artifact.tar
-
-      # - uses: actions/upload-artifact@v4
-      #   with:
-      #     name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}
-      #     path: artifact.tar
-
-      # - name: Deploy to GitHub Pages
-      #   id: deployment
-      #   uses: actions/deploy-pages@v4
-      #   with:
-      #     artifact_name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}
+          artifact_name: jekyll-docs-${{steps.get-asset-version.outputs.release_version}}

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to NHS Notify Supplier API
+
+## Feature Branches
+
+All changes to the repo must be created on a feature branch and submitted for peer review as a Pull Request (PR) via GitHub.
+
+Feature branch names should follow the format below:
+
+```text
+feature/${jira-ticket-number}_${precis-of-branch-purpose}
+```
+
+e.g.
+
+```text
+feature/CCM-11207_documentation
+```
+
+## Main Branch
+
+You are not permitted to push directly to the remote `main` branch in GitHub.
+
+Changes to `main` when require approval(s) recorded on your PR.
+Required approvers are controlled by the CODEOWNERS file but in summary:
+
+- Infrastructure changes should be reviewed by DevOps team members
+- Workflow/action changes should be reviewed by Maintainers of the repo
+- All other changes should be review by NHS API Development team members
+
+Merges should only take place:
+
+- They are intended for the next release cycle
+- All CI workflows have completed successfully
+
+## Coding Standards
+
+Your PR must follow all agreed coding standards for the project. Terraform and CI/CD standards are listed in sections below.
+
+### GitHooks
+
+GitHooks are available within this repo to help maintain standards and protect against e.g. secrets disclosure
+
+GitHooks **must** be configured and run on commits before pushing to remote. Refer to the developer documentation for more information if required.
+
+## Testing Your Branch
+
+You can test your branch in a dynamic environment prior to merging to `main`. These are created as part of the `cicd-1-pull-request.yaml` workflow, triggered when a PR is created or updated.

docs/.gitignore

@@ -7,3 +7,6 @@ vendor
 *Zone.Identifier
 node_modules
 _config.version.yml
+
+# Generated or copied from other repo resources
+_includes/components/generated/*

docs/Makefile

@@ -19,10 +19,10 @@ define baseurlparam =
 $(if $(BASE_URL),-- --baseurl $(BASE_URL),-- --baseurl "")
 endef
 
-build: version
+build: version .generate-includes
 	npm run build $(baseurlparam)
 
-debug: version
+debug: version .generate-includes
 	npm run debug
 
 version:
@@ -38,3 +38,6 @@ version:
 	fi
 
 	echo "{ \"schemaVersion\": 1, \"label\": \"version\", \"message\": \"$$(head -n 1 .version 2> /dev/null || echo unknown)\", \"color\": \"orange\" }" > version.json
+
+.generate-includes:
+	npm run generate-includes

docs/_config.yml

@@ -28,9 +28,62 @@ url: "https://nhsdigital.github.io" # the base hostname & protocol for your site
 collections_dir: collections
 
 collections:
-  notify-repos:
+  repos:
     output: true
     sort_by: order
+  consumers:
+    output: true
+    sort_by: order
+  developers:
+    output: true
+    sort_by: order
+
+just_the_docs:
+  collections:
+    consumers:
+      name: API Consumers
+    developers:
+      name: API Developers
+    repos:
+      name: Notify Repositories
+      # Exclude the collection from the navigation
+      # Supports true or false (default)
+      nav_exclude: false
+      # Fold the collection in the navigation
+      # Supports true or false (default)
+      nav_fold: false # note: this option is new in v0.4
+      # Exclude the collection from the search
+      # Supports true or false (default)
+      search_exclude: false
+
+defaults:
+  - scope:
+      path: "repositories"
+      type: "repos"
+    values:
+      layout: "notify-repo"
+      is_not_draft: false
+      owner: NHS Notify
+      author: NHS Notify
+      last_modified_date: 2025-10-08
+  - scope:
+      path: "api-consumers"
+      type: "consumers"
+    values:
+      layout: "page"
+      is_not_draft: false
+      owner: NHS Notify
+      author: NHS Notify
+      last_modified_date: 2025-10-08
+  - scope:
+      path: "api-developers"
+      type: "developers"
+    values:
+      layout: "page"
+      is_not_draft: false
+      owner: NHS Notify
+      author: NHS Notify
+      last_modified_date: 2025-10-08
 
 # Build settings
 theme: just-the-docs
@@ -45,15 +98,15 @@ mermaid:
   version: "10.9.1"
 
 aux_links:
-  "NHS Notify Repo Template on GitHub":
-    - "//github.com/NHSDigital/nhs-notify-repository-template"
+  "NHS Notify Supplier API Template on GitHub":
+    - "//github.com/NHSDigital/nhs-notify-supplier-api"
 
 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_repository: "https://github.com/NHSDigital/nhs-notify-supplier-api" # 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

docs/_includes/notify-repo-list.html

@@ -0,0 +1,11 @@
+<h2>Repository List</h2>
+
+<ul>
+  {% for repo in site.repos %} {% if repo.order > 0 %}
+  <li>
+    <a href="{{site.baseurl}}/repos/{{repo.repo-name}}.html">
+      {{ repo.repo-name }} - {{ repo.name }}
+    </a>
+  </li>
+  {% endif %} {% endfor %}
+</ul>

docs/_includes/notify-repo-table.html

@@ -0,0 +1,18 @@
+<h2>Repository List</h2>
+
+<table>
+  <tr>
+    <th>Repository Name</th>
+    <th>More Info</th>
+  </tr>
+  {% for repo in site.repos %} {% if repo.order > 0 %}
+  <tr>
+    <td>{{repo.repo-name}}</td>
+    <td>
+      <a href="{{site.baseurl}}/repos/{{repo.repo-name}}.html">
+        {{ repo.name }} - {{ repo.description }}
+      </a>
+    </td>
+  </tr>
+  {% endif %} {% endfor %}
+</table>

docs/_layouts/home.html

@@ -0,0 +1,5 @@
+---
+layout: default
+---
+
+{{ content }}

docs/_layouts/notify-repo.md

@@ -0,0 +1,21 @@
+---
+layout: page
+---
+
+<!-- markdownlint-disable MD041 -->
+
+<dl>
+  <dt>Repository</dt>
+  <dd><a href="https://github.com/NHSDigital/{{page.repo-name}}">https://github.com/NHSDigital/{{page.repo-name}}</a></dd>
+
+<dt>Owners</dt>
+{% for owner in page.owners %}
+    <dd> <a href="http://github.com/{{owner}}">{{owner}}</a> </dd>
+{% endfor %}
+</dl>
+
+{{ content }}
+
+{% include notify-repo-list.html %}
+
+<!-- markdownlint-enable MD041 -->