Add mkdocs GDS theme

Add PDF generation support and styling for mkdocs documentation, resolves #11

Author: milkshakeuk

.github/workflows/publish-guidelines.yml

@@ -40,23 +40,42 @@ jobs:
     - uses: actions/cache@v4
       with:
         key: mkdocs-material-${{ env.cache_id }}
-        path: .cache
+        path: ~/.cache
         restore-keys: |
           mkdocs-material-
 
-    - run: |
+    - name: install mkdocs and plugins
+      run: |
         pip install mkdocs-material
         pip install markdown-callouts
         pip install mkdocs-git-revision-date-localized-plugin
         pip install mkdocs-git-committers-plugin-2
-        pip install mkdocs-exporter
+        pip install pytest-playwright
+        pip install mkdocs-print-site-plugin
+        pip install mkdocs-tech-docs-template
         pip install mkdocs-redirects
         pip install mkdocs-awesome-pages-plugin
 
-    - run: |
+    - name: install playwright
+      run: |
         playwright install --with-deps
         playwright install chrome --with-deps
 
+    - name: generate site pdf 
+      run: |
+        mkdocs serve --no-livereload -c -q &
+        echo "waiting for mkdocs dev server to start..."
+        until curl --output /dev/null --silent --head --fail http://localhost:8000; do
+          printf '.'
+          sleep 1
+        done
+        playwright pdf --wait-for-selector=#print-site-page localhost:8000/print_page/ docs/ukhsa-api-guidelines.pdf
+        killall -9 mkdocs
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        MKDOCS_GIT_PROVENANCE_ENABLED: true
+        MKDOCS_EXPORTER_PDF_ENABLED: true
+
     - name: Publish docs
       run: mkdocs build
       env:

docs/assets/images/favicon-new.svg

@@ -0,0 +1,39 @@
+/* print styles for mkdocs material theme 
+https://github.com/squidfunk/mkdocs-material */
+
+/* Table of Contents styling */
+#print-site-page ul.toc-section-line-border { 
+    border-left: 5px solid var(--md-default-fg-color--lightest);
+}
+
+
+/* Box shadows don't do well in PDFs */
+#print-site-page table {
+    border: 1px solid hsla(200, 18%, 26%, 1); /* #EFEFEF */
+    box-shadow: none !important;
+}
+
+@media print {
+    #print-site-page td {
+        word-wrap: break-word;
+    }
+
+}
+
+@page {
+
+    size: A4 portrait;
+    margin: 4em 1.5em 4em 1.5em;
+    padding: 0em 0em 0em 0em;
+    counter-increment: page;
+
+    @bottom-center {
+        content: string(chapter);
+    }
+    @bottom-right {
+        font-size: 0.65rem;
+        padding-right: 1.0rem;
+        content: "Page " counter(page) " of " counter(pages);
+    }
+
+}

docs/assets/images/logo-ukhsa-landscape-new.svg

@@ -1,5 +1,5 @@
 site_name: API Guidelines
-site_description: 'Home of UKHSA API Guidelines'
+site_description: 'UKHSA API Guidelines'
 site_author: 'UKSHA'
 docs_dir: docs/
 repo_name: 'UKHSA-Internal/api-guidelines'
@@ -19,8 +19,6 @@ nav:
     - api-design-guidelines/pagination-filtering-sorting.md
     - api-design-guidelines/testing.md
     - Performance, Reliability & Monitoring:
-    #- api-design-guidelines/performance-reliability-monitoring.md
-    #- api-design-guidelines/performance-reliability-monitoring-new.md
       - api-design-guidelines/caching.md
     - api-design-guidelines/governance.md
     - api-design-guidelines/data-standards.md
@@ -36,13 +34,15 @@ nav:
       - ... | flat | spectral-rules/should/*.md
 
 theme:
-  name: material
-  logo: assets/images/logo-ukhsa-landscape.svg
-  favicon: assets/images/favicon.svg
+  name: tech_docs_template
+  custom_dir: overrides
+  logo: assets/images/logo-ukhsa-landscape-new.svg
+  favicon: assets/images/favicon-new.svg
   palette:
-    - primary: white
+    # - primary: black
+    #   accent: teal
+    - scheme: default
       accent: teal
-      scheme: default
 
   features:
     - navigation.instant
@@ -58,9 +58,11 @@ theme:
     - content.code.select
     - content.action.edit
     - content.action.view
+    #- toc.integrate
 
 extra_css:
   - stylesheets/extra.css
+  - stylesheets/pdf.css
 
 markdown_extensions:
   - github-callouts
@@ -79,7 +81,8 @@ markdown_extensions:
           case: lower
 
 plugins:
-  - search
+  - material/search
+  #- search
   - awesome-pages
   - redirects:
       redirect_maps:
@@ -93,26 +96,9 @@ plugins:
       repository: UKHSA-Internal/api-guidelines
       token: !ENV [GITHUB_TOKEN]
       branch: main
-  - exporter:
-      buttons:
-        - title: View as PDF
-          icon: material-file-move-outline
-          enabled: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.enabled
-          attributes:
-            target: _blank
-            href: /ukhsa-api-guidelines.pdf
-        - title: Download as PDF
-          icon: material-file-download-outline
-          enabled: !!python/name:mkdocs_exporter.formats.pdf.buttons.download.enabled
-          attributes: 
-            download: ukhsa-api-guidelines.pdf
-            href: /ukhsa-api-guidelines.pdf
-      formats:
-        pdf:
-          enabled: !ENV [MKDOCS_EXPORTER_PDF_ENABLED, false]
-          stylesheets:
-            - docs/stylesheets/pdf.scss
-          aggregator:
-            enabled: true
-            output: ukhsa-api-guidelines.pdf
-            covers: none
+  - print-site:
+      add_to_navigation: false
+      add_cover_page: true
+      include_css: true
+      path_to_pdf: "ukhsa-api-guidelines.pdf"
+      enabled: !ENV [MKDOCS_EXPORTER_PDF_ENABLED, false]