WIP: Standardize Headings In Docs

documentation/docs/configuration/blocks.md

@@ -12,7 +12,7 @@ Let's say you want to add a banner above each page's markdown content.  You stil
 [Tile Grid]: ../tile-grid/index.md
 
 
-## 1. Add Overrides Folder
+### 1. Add Overrides Folder
 Create the following directory structure and add your banner snippet to `banner.html`:
 
 ```directory
@@ -29,7 +29,7 @@ Create the following directory structure and add your banner snippet to `banner.
 ```
 
 
-## 2. Add Theme Custom Directory
+### 2. Add Theme Custom Directory
 Configure MkDocs to look at the new `./overrides` folder:
 
 **file name**: mkdocs.yml  
@@ -41,7 +41,7 @@ theme:
 ```
 
 
-## 3. Add Extended Partial 
+### 3. Add Extended Partial 
 You can add a custom banner above each page's content by adding the following theme extension:
 
 **file name**: page.html  
@@ -74,7 +74,7 @@ If you wanted to override higher level blocks[^block-levels] you would add them
 Calling `super()` will include any Terminal for MkDocs features which are inside the original block definition.
 <hr>
 
-# Overridable Blocks
+## Overridable Blocks
 
 `analytics`
 
@@ -133,7 +133,7 @@ Calling `super()` will include any Terminal for MkDocs features which are inside
 [Git Revision Plugin]: ../plugins/git-revision
 
 
-# Override Locations
+## Override Locations
 
 | Block Name              | Add to `./overrides/` | Extend From `mkdocs-terminal` |
 | ----------------------- | --------------------- | ----------------------------- |

documentation/docs/configuration/extensions/index.md

@@ -36,11 +36,11 @@ The following extensions have been confirmed to work with Terminal for MkDocs an
   [Tables]: python-markdown.md#tables
 
 
-# Configuration
+## Configuration
 
 Extensions are enabled in the MkDocs configuration file.  See below for two example configurations to bootstrap your documentation project.
 
-## Minimal Config
+### Minimal Config
 
 The minimal configuration is a good starting point for when you're using MkDocs for the first time.  You can explore the suggested extensions and gradually add extensions as needed:
 
@@ -54,7 +54,7 @@ markdown_extensions:
       permalink: "#"
 ```
 
-## Recommended Config
+### Recommended Config
 
 The recommended configuration enables all Markdown-related features of Terminal for MkDocs
 and is great for experienced users bootstrapping a new documentation project:
@@ -80,5 +80,5 @@ markdown_extensions:
         - docs
 ```
 
-# Credit
+## Credit
 This documentation page is based on squidfunk's [Material for MkDocs Extensions](https://squidfunk.github.io/mkdocs-material/setup/extensions/) documentation.

documentation/docs/configuration/extensions/pymdown-extensions.md

@@ -8,9 +8,9 @@ The [PyMdown Extensions] package is an excellent collection of extensions suited
 
   [PyMdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
 
-# Suggested PyMdown Extensions
+## Suggested PyMdown Extensions
 
-## Caret, Mark & Tilde
+### Caret, Mark & Tilde
 
 The [Caret], [Mark], and [Tilde] extensions add the ability to highlight text
 and define subscript and superscript using a simple syntax. Enable them together
@@ -42,7 +42,7 @@ See reference for usage:
   [Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
 
 
-## Snippets
+### Snippets
 
 The [Snippets] extension adds the ability to embed content from arbitrary files into a document, including other documents or source files, by using a simple syntax. Enable it via `mkdocs.yml`:
 
@@ -64,6 +64,6 @@ See reference for usage:
   [Adding Snippets]: ./snippets.md
 
 
-# Credit
+## Credit
 
 This documentation page is based on squidfunk's [Material for MkDocs Pymdown Extension](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/) documentation.

documentation/docs/configuration/extensions/python-markdown.md

@@ -8,9 +8,9 @@ Terminal for MkDocs is compatible with some of the [Python Markdown] extensions.
 
   [Python Markdown]: https://python-markdown.github.io/extensions/
 
-# Suggested Python Markdown Extensions
+## Suggested Python Markdown Extensions
 
-## Attribute Lists
+### Attribute Lists
 
 The [Attribute Lists] extension helps to add HTML attributes and CSS classes to Markdown inline and block-level elements. Enable it via `mkdocs.yml`:
 
@@ -30,7 +30,7 @@ No configuration options are available. See reference for usage:
   [Adding tooltips]: ../../elements/tooltips.md#example
   [Adding link target]: ../../elements/links.md#enhanced-example
 
-## Definition Lists
+### Definition Lists
 
 The [Definition Lists] extension adds a Markdown syntax for definition lists (more commonly known as [description lists]). Enable it via `mkdocs.yml`:
 
@@ -47,7 +47,7 @@ No configuration options are available. See reference for usage:
   [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
   [Using definition lists]: ../../elements/definitions.md#example
 
-## Footnotes
+### Footnotes
 
 The [Footnotes] extension enables inline footnotes which are then rendered below all of a document's Markdown content.  Enable it via `mkdocs.yml`:
 
@@ -65,7 +65,7 @@ See reference for usage:
   [Adding footnote markers]: ../../elements/footnotes.md#example-footnote-marker
   [Adding footnote content]: ../../elements/footnotes.md#example-footnote-content
 
-## Markdown in HTML
+### Markdown in HTML
 
 The [Markdown in HTML] extension allows for writing Markdown inside of HTML, which is useful for wrapping Markdown content with custom elements. Enable it
 via `mkdocs.yml`:
@@ -89,7 +89,7 @@ No configuration options are available. See reference for usage:
   [Adding Figures]: ../../elements/figure.md#example
 
 
-## Table of Contents
+### Table of Contents
 
 The [Table of Contents] extension automatically generates a table of contents from a document which Terminal for MkDocs will render as part of the resulting page. It can be configured via `mkdocs.yml`:
 
@@ -130,7 +130,7 @@ See reference for usage:
   [Table of Contents Example]: ../../navigation/toc.md
 
 
-## Tables
+### Tables
 
 The [Tables] extension adds a Markdown syntax for data tables.  It is enabled by default but you can specify it explicitly in `mkdocs.yml`:
 
@@ -148,7 +148,7 @@ No configuration options are available. See reference for usage:
   [Adding tables]: ../../elements/table.md#example
 
 
-# Credit
+## Credit
 
 This documentation page is based on squidfunk's [Material for MkDocs Python Markdown](https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/) documentation.
 

documentation/docs/configuration/features.md

@@ -1,4 +1,5 @@
-# Theme Features
+# Features
+## Theme Features
 
 ```yaml
 theme:
@@ -15,49 +16,49 @@ theme:
     - revision.history
     - style.links.underline.hide
 ```
-## footer.prev_next
+### footer.prev_next
 Adds "Previous" and "Next" links to the bottom of each site page.
 
-## navigation.side.hide  
+### navigation.side.hide  
 Hides the side navigation menu and page table of contents on all site pages.
 
-## navigation.side.indexes  
+### navigation.side.indexes  
 Enables section links in the side navigation menu.  
 Ignored if `navigation.side.hide` is set.  
 See [Section Indexes](../navigation/section-indexes.md) for details.  
 
-## navigation.side.toc.hide  
+### navigation.side.toc.hide  
 Hides page table of contents on all site pages.  
 Ignored if `navigation.side.hide` is set.  
 See [Page Table of Contents](../configuration/index.md#page-table-of-contents) for more info. 
 
-## navigation.top.hide  
+### navigation.top.hide  
 Hides top navigation menu on all site pages.  
 See [Top Navigation Menu](../configuration/index.md#top-navigation-menu) for more info.  
 
-## navigation.top.cursor_animation.hide  
+### navigation.top.cursor_animation.hide  
 Hides the blinking cursor animation in the top navigation menu.  
 Ignored if `navigation.top.hide` is set.  
 
-## navigation.top.search_button.hide
+### navigation.top.search_button.hide
 Hides the search button in the top navigation menu.  
 Ignored if `navigation.top.hide` is set.  
 
-## revision.date
+### revision.date
 Enables the "Page last updated..." text at the bottom of each site page.  Requires [git-revision-date plugin setup].
 
-## revision.history
+### revision.history
 Enables the "See revision history..." text at the bottom of each site page.  Requires [git-revision-date plugin setup] and additional [git-revision-date configuration].
 
-## style.links.underline.hide
+### style.links.underline.hide
 Hides the underline styling on links.  The underline text decoration on links is added to make links identifiable without color vision.  If you choose to hide this styling you should consider adding an alternate [non-color link indicator].    
 
 [git-revision-date plugin setup]: ../plugins/git-revision/
 [git-revision-date configuration]: ../plugins/git-revision/#advanced-configuration
 [non-color link indicator]: https://www.w3.org/WAI/WCAG21/Techniques/general/G182.html
 <hr>
 
-# Page Features
+## Page Features
 
 To hide certain Terminal for MkDocs components on a per-page basis, add a [YAML Style Meta-Data] section to the very top of your Markdown page. Inside this metadata section, add the attribute `hide` which is a list of page-specific feature names.
 
@@ -75,18 +76,18 @@ hide:
 
 [YAML Style Meta-Data]: https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data
 
-## hide: revision_date
+### hide: revision_date
 Hides the "Page last updated" text at the bottom of the page.  
 Ignored if `revision.date` Theme Feature is not enabled.  
 Ignored if `git-revision-date` plugin is not enabled.  
 
-## hide: revision_history
+### hide: revision_history
 Hides the "See revision history..." text at the bottom of the page.  
 Ignored if `revision.history` Theme Feature is not enabled.  
 Ignored if `git-revision-date` plugin is not enabled.  
 
-## hide: side_toc
+### hide: side_toc
 Hides the table of contents in the side panel on the page.
 
-## hide: top_nav
+### hide: top_nav
 Hides the top navigation menu on the page.  

documentation/docs/configuration/plugins/git-revision.md

@@ -5,7 +5,7 @@ The third-party [git-revision-date plugin] automatically adds the last revision
 [MkDocs Page Metadata]: https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data
 [^mkdocs-page-meta]: see [MkDocs Page Metadata] for more info
 
-# Built-in Support
+## Built-in Support
 When the `git-revision-date` plugin is installed and enabled and the `revision.date` theme feature is enabled, Terminal for MkDocs will display the date of the most recent change to a page's source file on the rendered site page.  This component is added at the bottom of each page unless [page-specific hiding] is enabled.
 
 <section markdown>
@@ -19,9 +19,9 @@ When the `git-revision-date` plugin is installed and enabled and the `revision.d
 [page-specific hiding]: ../../features#page-features
 
 
-# Quick Setup
+## Quick Setup
 
-## 1. Install Plugin
+### 1. Install Plugin
 Add the package to your `requirements.txt` file:
 
 ```text
@@ -32,7 +32,7 @@ mkdocs-git-revision-date-plugin
 Then run:  `pip install -r ./requirements.txt`
 
 
-## 2. Enable Plugin
+### 2. Enable Plugin
 
 Enable the Git Revision Date Plugin by adding `git-revision-date` to the `plugins` list in `mkdocs.yml`:
 ```yaml
@@ -41,7 +41,7 @@ plugins:
   - git-revision-date
 ```
 
-## 3. Enable Theme Feature  
+### 3. Enable Theme Feature  
 Enable the "Page last updated" theme component by adding `revision.date` to the theme's `features` list in `mkdocs.yml`:
 ```yaml
 theme:
@@ -51,7 +51,7 @@ theme:
 ```
 <br>
 
-# Advanced Configuration
+## Advanced Configuration
 There are two revision-related theme features that can be individually enabled.  The example above only discusses `revision.date` as it is easier to configure without error.  
 
 The second revision-related theme feature is `revision.history`.  Enabling this theme feature will add a "See revision history..." note to the bottom of the page.  The link included in this note relies on MkDocs' [repo_url], [repo_name], and [edit_uri]/[edit_uri_template] settings.  
@@ -74,9 +74,9 @@ Currently the `revision.history` theme feature supports two repository hosts, [G
 [GitHub]: git-revision.md#github
 [Bitbucket]: git-revision.md#bitbucket
 
-## GitHub
+### GitHub
 
-### MkDocs project in root directory
+#### MkDocs project in root directory
 ```yaml
 repo_url: https://github.com/ntno/ntno.net  
 edit_uri: edit/main/docs/
@@ -91,7 +91,7 @@ theme:
     - revision.history  
 ```
 
-### MkDocs project in child 'documentation' directory
+#### MkDocs project in child 'documentation' directory
 ```yaml
 repo_url: https://github.com/ntno/mkdocs-terminal
 edit_uri_template: https://github.com/ntno/mkdocs-terminal/edit/main/documentation/docs/{path}
@@ -106,8 +106,8 @@ theme:
     - revision.history  
 ```
 
-## Bitbucket
-### MkDocs project in root directory
+### Bitbucket
+#### MkDocs project in root directory
 ```yaml
 repo_url: https://bitbucket.org/norganick/demo
 edit_uri_template: src/main/docs/{path}?mode=edit
@@ -124,7 +124,7 @@ theme:
 
 
 
-## Adding Repository Hosts
+### Adding Repository Hosts
 If your repository is not stored on GitHub or Bitbucket and you would like to use this feature please [submit a feature request] on GitHub.  
 
 You can further customize what revision information is included on the page by implementing your own `revision` template block.  See [Blocks] for more information.

documentation/docs/configuration/plugins/macros.md

@@ -7,9 +7,9 @@ You can write and publish your own functions to use in your markdown pages.  The
 [mkdocs-macros plugin]: https://mkdocs-macros-plugin.readthedocs.io/en/latest/
 [jinja2]: https://jinja.palletsprojects.com/en/3.1.x/intro/
 
-# Quick Setup
+## Quick Setup
 
-## 1. Install Plugin
+### 1. Install Plugin
 Add the `mkdocs-macros-plugin` package to your `requirements.txt` file:
 
 ```text
@@ -20,7 +20,7 @@ mkdocs-macros-plugin
 Then run:  `pip install -r ./requirements.txt`
 
 
-## 2. Enable Plugin
+### 2. Enable Plugin
 
 Enable the MkDocs Macros Plugin by adding `macros` to the `plugins` list in `mkdocs.yml`:
 ```yaml
@@ -30,7 +30,7 @@ plugins:
 ```
 
 
-## 3. Verify Setup
+### 3. Verify Setup
 
 Test that the plugin is working correctly by calling the built-in info macro from one of your documentation pages:  
 
@@ -48,7 +48,7 @@ A table with entries describing the MkDocs configuration for your site should be
 </section>
 
 
-## 4. Configuration
+### 4. Configuration
 
 See the plugin's [configuration documentation] for additional options.