fixed quickstart instruction and other small tweaks (#39)

Author: hrahim-moj

docs/setup/README.md

@@ -37,17 +37,19 @@ This creates the following structure in the directory:
 
 ## Update mkdocs.yml
 
-So that the template displays properly, in `mkdocs.yml` insert the relevant values for `site_name` and `repo_url`, and set the `theme` so that it uses our MkDocs tech docs template:
+So that the template displays properly, copy the following into `mkdocs.yml`:
 
 ```
-- site_name: <your-website-name>
-- repo_url: <your-website-url>
-- theme:
+repo_url: <your-website-url>
+repo_name: <your-repo-name>
+theme:
     name: tech_docs_template
 plugins:
     - material/search
 ```
 
+This sets the theme to use the MkDocs Tech Docs Template and enables the search bar plugin. After copying, insert the relevant values for `site_name`, `repo_url` and `repo_name`.
+
 ## Preview your documentation
 
 MkDocs includes a live preview server that automatically rebuilds when you save a file, so you can preview your changes as you write. To start the server, in your terminal run:
@@ -60,11 +62,11 @@ To stop the server, in your terminal press Ctrl+C. If the page stops loading, ch
 
 ## Build your documentation
 
-If you are using GitHub, you can use [GitHub Actions][gh_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 the [Material for MKDocs documentation][material_publishing] for more details and alternatives.
+If you are using GitHub, you can use [GitHub Actions][gh_actions] to automate the deployment of your documentation to [GitHub Pages](https://pages.github.com/) whenever someone pushes a commit to the master or main branch. See the [Material for MKDocs documentation][material_publishing] for more details and alternatives.
 
-## Customise your documentation
+## Configure page layout
 
-We have provided some customisation options in [customise](customise.md), but we encourage you to read the [Material for MkDocs documentation][material_docs] for more detailed information on customisation.
+This template is flexible. For examples of how you can structure navigation and table of contents, as well as other customisation options, see [Customise](customise.md).
 
 [gh_actions]: https://github.com/features/actions
 [gh_ssh]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh

docs/setup/customise.md

@@ -1,20 +1,23 @@
 # Customise your template
 
-This page explains the customisation used in the demo. You are encouraged to read the Material for MkDocs [guidance][material] for more detailed information on customisation.
+This page explains the different components we use to configure page layout for the demo site you are currently viewing. You can apply these to your template to make your site look similar. 
 
-When customising, be mindful of your users. Make sure you do not overcomplicate things for them or anyone else who might contribute to your documentation.
+When customising, keep your users in mind. The template is flexible, but try not to complicate things for readers, or anyone contributing to your documentation.
+
+For more information on customisation, see the [Material for MkDocs guidance][material].
 
 ## Page 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.
+The `nav` setting in your `mkdocs.yml` file defines which pages to include in your table of contents and their structure.
 
-If not provided, the navigation will be automatically created by discovering all the Markdown files in the documentation directory. See [Configure Pages and Navigation][pageNav] for more details.
+If you do not define `nav`, the template automatically search for Markdown files in the docs directory and creates a table of contents. For more information on how this works, see the [MkDocs documentation on configuring pages and navigation][pageNav].
 
 ### Nesting pages
 
-Parent items can either contain a single page or a nested list of child pages, but not both:
+Parent items can contain a single page or a nested list of child pages, but not both:
 
 ```
+nav:
 - Home: index.md
 - Parent:
     - 'Nested Page': 'somepage.md'
@@ -24,7 +27,7 @@ Parent items can either contain a single page or a nested list of child pages, b
 
 ### Top bar navigation
 
-Top bar navigation tabs are disabled by default. To enable them, update `mkdocs.yml` with the following:
+Top bar navigation tabs do not display by default. To display them, update `mkdocs.yml` with the following:
 ```
 theme:
     features:
@@ -35,21 +38,27 @@ theme:
 
 ### Right-hand navigation
 
-By default, this template displays page sections on the right-hand table of contents. To merge the sections into the left-hand table of comments, in `mkdocs.yml`, uncomment `toc.integrate`.
+By default, this template displays page sections on the right-hand table of contents. To merge the sections into the left-hand table of comments, add `toc.integrate` in `mkdocs.yml`:
+
+```
+theme:
+    features:
+        - toc.integrate
+```
 
-For more information on how you can customise navigation, see [setting up navigation][navSetup].
+For more information on how you can customise navigation, see the [Material for MkDocs documentation on setting up navigation][navSetup].
 
 ## Logos and Images
 
-To use your department's images you can use one of the provided [logos][logos] and [favicons][favicons] and specify the path in the `mkdocs.yml` for example:
+To use government images on your site you can use one of the provided [logos][logos] and [favicons][favicons] and specify the path in `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:
+Alternatively, you can add images to the `docs/assets` directory in your own repository and specify the path, for example:
 
 ```
 theme:
@@ -59,14 +68,11 @@ theme:
 
 ## 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 page][home]. Please refer to [admonitions][admonitions] for more details. Do consider adding the images to the template for sharing with colleagues!
+[Admonitions][admonitions] (also known as call-outs) are a way of including content without interrupting the flow of your content. They can also help to provide structure and coloured headings, such as those on the [homepage][home].
 
-## Footer
+## Social links
 
-### 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`
+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` using the following:
 with:
 
 ``` yaml
@@ -78,11 +84,25 @@ extra:
 
 Please refer to [social links][social] for more details.
 
-## Dark Mode
+## Dark Mode (experimental)
 
-Use the sun icon in the top bar to switch between light and dark mode.
+To enable Dark Mode, add the following in `mkdocs.yml`
+
+```
+palette: 
+    # Palette toggle for light mode
+    - scheme: default
+      toggle:
+        icon: material/brightness-7 
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+```
 
-See [Changing the colors](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/) for more details.
+Use the sun icon in the top bar to switch between light and dark mode.
 
 [material]: https://squidfunk.github.io/mkdocs-material/
 [pageNav]: https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation