update admonitions and site navigation

ministryofjustice · Feb 18, 2023 · 64f9aa9 · 64f9aa9
1 parent f537831
commit 64f9aa9
Show file tree

Hide file tree

Showing 12 changed files with 205 additions and 142 deletions.
diff --git a/README.md b/README.md
@@ -0,0 +1,5 @@
+# README
+
+A python-based alternative to the ruby-based [Tech Docs Template](https://github.com/alphagov/tech-docs-template).
+
+Visit the [documentation website](https://ministryofjustice.github.io/mkdocs-tech-docs-template/) for more details.
diff --git a/docs/README.md b/docs/README.md
@@ -1,41 +1,34 @@
-# MkDocs Tech Docs Template
-
-!!! danger ""
-
-    This template is under construction and should only be used for prototyping
-
-The MkDocs Tech Docs Template is an [MkDocs theme](https://www.mkdocs.org/) that you can use to build technical documentation with a [GOV.UK style](https://design-system.service.gov.uk/). For a demo visit [mkdocs-tech-docs-template](https://ministryofjustice.github.io/mkdocs-tech-docs-template/).
+---
+hide:
+  - navigation
+  - toc
+---
 
-The MkDocs Tech Docs Template is a python-based alternative to the ruby-based Middleman [Tech Docs Template](https://github.com/alphagov/tech-docs-template) with the following benefits:
-
-- simple to setup, use and customise
-- exploits the [MkDocs Materials theme](https://squidfunk.github.io/mkdocs-material/) and all it's associated features
-- compatible with the vast ecosystem of [MkDocs Plugins](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins), see [plugins](plugins/) for some examples
-- unified tech stack for python-based teams and projects
-- easy to upgrade as new versions of the theme are released
-
-You’re welcome to use the MkDocs Tech Docs Template even if your service isn’t considered part of GOV.UK, but your site or service must not:
+# MkDocs Tech Docs Template
 
-- identify itself as being part of GOV.UK
-- use the crown or GOV.UK logotype in the header
-- use the GDS Transport typeface
-- suggest that it’s an official UK government website if it’s not
+!!! banner "Build technical documentation with a [GOV.UK style](https://design-system.service.gov.uk/)"
 
-## Usage
+    ![Services](homepage-illustration.svg){ align=right width=300px height=300px}
 
-Please refer to [Usage](./Usage.md) for more details.
+    A python-based alternative to the ruby-based [Tech Docs Template](https://github.com/alphagov/tech-docs-template) with the following benefits:
 
-## Questions
+    - simple to [setup](./setup/), [customise](./setup/customise.md) and [enhance](./setup/CONTRIBUTE.md)
+    - exploits the [MkDocs Materials theme](https://squidfunk.github.io/mkdocs-material/) and all it's associated features
+    - compatible with the vast ecosystem of MkDocs [plugins](plugins/)
+    - unified tech stack for python-based teams and projects
 
-Please raise on [Discussions](https://github.com/ministryofjustice/mkdocs-tech-docs-template/discussions).
 
-## Contribute
+!!! warning inline end "Prototype"
 
-👉 Find out how to [contribute](CONTRIBUTE.md).
+    This template is under construction and should only be used for prototyping
+
+!!! quote "Restrictions"
 
-## Licence
+    You’re welcome to use the MkDocs Tech Docs Template even if your service isn’t considered part of GOV.UK, but your site or service must not:
 
-Unless stated otherwise, the codebase is released under [the MIT License](LICENSE).
-This covers both the codebase and any sample code in the documentation.
+    - identify itself as being part of GOV.UK
+    - use the crown or GOV.UK logotype in the header
+    - use the GDS Transport typeface
+    - suggest that it’s an official UK government website if it’s not
 
-The documentation is [© Crown copyright](http://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 3.0](http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) licence.
+<br>
diff --git a/docs/Usage.md b/docs/Usage.md
diff --git a/docs/homepage-illustration.svg b/docs/homepage-illustration.svg
diff --git a/docs/CONTRIBUTE.md → docs/setup/CONTRIBUTE.md b/docs/CONTRIBUTE.md → docs/setup/CONTRIBUTE.md
diff --git a/docs/setup/README.md b/docs/setup/README.md
@@ -0,0 +1,51 @@
+# Minimal Setup
+
+This page contains the minimal steps to use the MKDocs Tech Docs Template. Some additional customisation is provided in [customise](customise.md). You are encouraged to read the Material for MkDocs [guidance](https://squidfunk.github.io/mkdocs-material/) for more detailed information on setting up and customisation.
+
+## Installation
+
+MkDocs Tech Docs template is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install with:
+
+```
+pip install mkdocs-tech-docs-template
+```
+
+Bootstrap your project documentation:
+
+```
+mkdocs new .
+```
+
+This creates the following structure:
+
+```
+.
+├─ docs/
+│  └─ index.md
+└─ mkdocs.yml
+```
+
+## Configuration
+
+Update/add the following variables to `mkdocs.yml`:
+
+```
+- site_name: <website-name>
+- repo_url: <url>
+- theme:
+    name: tech_docs_template
+```
+
+## Preview
+
+MkDocs includes a live preview server, so you can preview your changes as you write your documentation. The server will automatically rebuild the site upon saving. Start it with:
+
+``` sh
+mkdocs serve
+```
+
+## Publish
+
+You can use [GitHub Actions](https://github.com/features/actions) to automate the deployment of your documentation to [GitHub Pages](https://pages.github.com/) when a commit is pushed to either the master or main branches. 
+
+See [publishing your site](https://squidfunk.github.io/mkdocs-material/publishing-your-site/) for more details and alternatives.
diff --git a/docs/setup/customise.md b/docs/setup/customise.md
@@ -0,0 +1,78 @@
+# Customise
+
+This page explains the customisation used in the demo. You are encouraged to read the Material for MkDocs [guidance](https://squidfunk.github.io/mkdocs-material/) for more detailed information on customisation.
+
+## Documentation Layout
+
+The `nav` configuration setting in your `mkdocs.yml` file defines which pages are included in the global site navigation menu as well as the structure of that menu.
+
+If not provided, the navigation will be automatically created by discovering all the Markdown files in the documentation directory. See [Configure Pages and Navigation](https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation) for more details.
+
+## Navigation Formatting
+
+Tabs are disabled by default:
+
+![No tabs](no_tabs.png)
+
+To enable tabs and use the same navigation structure as displayed in the demo update the `mkdocs.yml` as follows:
+```
+theme:
+    features:
+        - navigation.tabs
+        - navigation.tabs.sticky
+        - navigation.indexes
+```
+
+You can hide the navigation and contents page on individual pages using the front matter:
+
+```
+---
+hide:
+  - navigation
+  - toc
+---
+
+# MkDocs Tech Docs Template
+
+```
+
+Please refer to [setting up navigation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/) for more details.
+
+## Logos and Images
+
+To use your department's images you can use one of the provided [logos](../tech_docs_template/logos/) and [favicons](../tech_docs_template/favicons/) and specify the path in the `mkdocs.yml` for example:
+
+```
+theme:
+    logo: logos/moj.png
+    favicon: favicons/moj.ico             
+```
+
+Alternatively you can add the images to the `docs/assets` directory in your own repository and specify the path for example:
+
+```
+theme:
+    logo: assets/ho_logo.png
+    favicon: assets/ho_icon.ico             
+```
+
+Do consider adding the images to the template for sharing with colleagues!
+
+## Social links
+
+Social links are rendered above the copyright notice as part of the 
+footer of your project documentation. Add a list of social links in `mkdocs.yml` 
+with:
+
+``` yaml
+extra:
+  social:
+    - icon: fontawesome/brands/mastodon
+      link: https://fosstodon.org/@squidfunk
+```
+
+Please refer to [social links](https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/?h=social#navigation) for more details.
+
+## Admonitions
+
+Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. They can also be used to provide structure and coloured headings as in used on the [home](README.md) page. Please refer to [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#admonition-icons) for more details.
diff --git a/docs/no_tabs.png → docs/setup/no_tabs.png b/docs/no_tabs.png → docs/setup/no_tabs.png
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -20,17 +20,6 @@ theme:
     code: Roboto Mono
   icon:
     admonition:
-      note: octicons/tag-16
-      abstract: octicons/checklist-16
-      info: octicons/info-16
-      tip: octicons/squirrel-16
-      success: octicons/check-16
-      question: octicons/question-16
-      warning: octicons/alert-16
-      failure: octicons/x-circle-16
-      danger: octicons/zap-16
-      bug: octicons/bug-16
-      example: octicons/beaker-16
       quote: octicons/quote-16
 
 edit_uri: edit/main/docs/
@@ -41,17 +30,30 @@ plugins:
   - git-revision-date-localized:
       enable_creation_date: true
       fallback_to_build_date: true
+      exclude:
+          - README.md
 markdown_extensions:
   - admonition
   - pymdownx.details
   - pymdownx.superfences
   - tables
+  - attr_list
+extra:
+  social:
+    - icon: fontawesome/brands/slack
+      link: https://mojdt.slack.com/archives/CBVUV2613
+    - icon: fontawesome/solid/paper-plane 
+      link: mailto:soumaya.mauthoor@digital.justice.gov.uk
+    - icon: fontawesome/brands/github
+      link: https://github.com/ministryofjustice/mkdocs-tech-docs-template/discussions
 
 nav:
-  - About:
+  - Home:
       - README.md
-      - Usage: Usage.md
-      - Contribute: CONTRIBUTE.md
+  - Setup: 
+      - setup/README.md
+      - Customise: setup/customise.md
+      - Contribute: setup/CONTRIBUTE.md
   - Plugins:
       - plugins/README.md
       - Demo Table: plugins/demo_table.md

diff --git a/tech_docs_template/__init__.py b/tech_docs_template/__init__.py
@@ -1 +1 @@
-__version__ = "0.0.18"
+__version__ = "0.0.19"
diff --git a/tech_docs_template/assets/stylesheets/extra.css b/tech_docs_template/assets/stylesheets/extra.css
@@ -45,6 +45,8 @@
 }
 
 .md-footer{
+  padding-top: 40px;
+  padding-bottom: 25px;
   border-top: 1px solid;
   border-color: #b1b4b6;
 }
@@ -118,19 +120,34 @@
   border-bottom-color:   #1d70b8;
 }
 
-/* Configure the warning and info panels */
+/* Configure the adminitions */
 .md-typeset .admonition,
 .md-typeset details {
-  font-size: 16px;
+  font-size: 0.85rem;
   border: 3px solid;
+  box-shadow: none; 
+  /* border-width: 0;  */
+  /* border-left-width: 4px; */
 }
 
 /* Configure the main panel */
 .md-main__inner {
   margin-top:10px;
 }
 
-/* Configure the jupyter notebook code panels
-.highlight {
-  background-color:#e0f7fa;
-} */
+/* Create a new banner admonition */
+.md-typeset .admonition.banner,
+.md-typeset details.banner {
+  border-color: #1d70b8;
+}
+.md-typeset .banner > .admonition-title,
+.md-typeset .banner > .admonition-title a,
+.md-typeset .banner > summary {
+  font-size: 30px;
+  background-color: #1d70b8;
+  color: white;
+}
+.md-typeset .banner > .admonition-title::before,
+.md-typeset .banner > summary::before {
+  background-color: white;
+}