Eliminate use of the include-markdown plugin for MkDocs (#1544)

* Eliminate use of the include-markdown plugin for MkDocs

Replace it's use with simply refactoring some of the documentaiton and also using the pymdown.snippets extension which is more reliably supported by MkDocs.

This is based in part on real-world problems encountered using the include-markdown problem with various other plugins and with migrating to Zensical.

* Removed extra base_path from pymdown.snippets extension

Author: tleonhardt

.github/CONTRIBUTING.md

@@ -93,20 +93,19 @@ for a list of dependencies needed for building `cmd2`.
 See the `dev` list under the `[dependency-groups]` heading in [pyproject.toml](../pyproject.toml)
 for a list of dependencies needed for building `cmd2`.
 
-| Prerequisite                                                                               | Minimum Version | Purpose                          |
-| ------------------------------------------------------------------------------------------ | --------------- | -------------------------------- |
-| [codecov](http://doc.pytest.org/en/latest/)                                                | `2.1.13`        | Cover coverage reporting         |
-| [invoke](https://www.pyinvoke.org/)                                                        | `2.2.0`         | Command automation               |
-| [mypy](https://mypy-lang.org/)                                                             | `1.13.0`        | Static type checker              |
-| [pytest](https://docs.pytest.org/en/stable/)                                               | `3.0.6`         | Unit and integration tests       |
-| [pytest-cov](http://doc.pytest.org/en/latest/)                                             | `6.0.0`         | Pytest code coverage             |
-| [pytest-mock](https://pypi.org/project/pytest-mock/)                                       | `3.14.0`        | Pytest mocker fixture            |
-| [mkdocs-include-markdown-plugin](https://pypi.org/project/mkdocs-include-markdown-plugin/) | `7.1.2`         | MkDocs Plugin include MkDn       |
-| [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/)                       | `1.3.7`         | MkDocs Plugin for macros         |
-| [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)                            | `9.5.49`        | Documentation                    |
-| [mkdocstrings[python]](https://mkdocstrings.github.io/)                                    | `0.27.0`        | MkDocs Plugin for Python AutoDoc |
-| [ruff](https://github.com/astral-sh/ruff)                                                  | `0.7.3`         | Fast linter and formatter        |
-| [uv](https://github.com/astral-sh/uv)                                                      | `0.5.1`         | Python package management        |
+| Prerequisite                                                         | Minimum Version | Purpose                          |
+| -------------------------------------------------------------------- | --------------- | -------------------------------- |
+| [codecov](http://doc.pytest.org/en/latest/)                          | `2.1.13`        | Cover coverage reporting         |
+| [invoke](https://www.pyinvoke.org/)                                  | `2.2.0`         | Command automation               |
+| [mypy](https://mypy-lang.org/)                                       | `1.13.0`        | Static type checker              |
+| [pytest](https://docs.pytest.org/en/stable/)                         | `3.0.6`         | Unit and integration tests       |
+| [pytest-cov](http://doc.pytest.org/en/latest/)                       | `6.0.0`         | Pytest code coverage             |
+| [pytest-mock](https://pypi.org/project/pytest-mock/)                 | `3.14.0`        | Pytest mocker fixture            |
+| [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) | `1.3.7`         | MkDocs Plugin for macros         |
+| [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)      | `9.5.49`        | Documentation                    |
+| [mkdocstrings[python]](https://mkdocstrings.github.io/)              | `0.27.0`        | MkDocs Plugin for Python AutoDoc |
+| [ruff](https://github.com/astral-sh/ruff)                            | `0.7.3`         | Fast linter and formatter        |
+| [uv](https://github.com/astral-sh/uv)                                | `0.5.1`         | Python package management        |
 
 If Python is already installed in your machine, run the following commands to validate the versions:
 

docs/examples/examples.md

@@ -1,5 +1,3 @@
 # List of cmd2 examples
 
-{%
-   include-markdown "../../examples/README.md"
-%}
+--8<-- "docs/../examples/README.md"

docs/index.md

@@ -25,46 +25,39 @@ app = App()
 app.cmdloop()
 ```
 
-<!-- Getting Started -->
+## Getting Started
 
-{%
-   include-markdown "./overview/index.md"
-%}
+See the [Getting Started](overview/index.md) section for info on how to get started building a
+`cmd2` application.
 
-<!-- Migrating from cmd -->
+## Migrating from cmd2
 
-{%
-   include-markdown "./migrating/index.md"
-%}
+See the [Migrating from cmd2](migrating/index.md) section for info on how to migrate a `cmd`
+application to `cmd2`.
 
 ## Features
 
-{%
-   include-markdown "./features/index.md"
-    start="<!--intro-start-->"
-    end="<!--intro-end-->"
-%}
+See the [Features](features/index.md) section for a detailed guide to the features available within
+`cmd2`.
 
 ## Examples
 
-{%
-   include-markdown "./examples/index.md"
-    start="<!--intro-start-->"
-    end="<!--intro-end-->"
-%}
+See the [Examples](examples/index.md) section for various examples of using `cmd2`.
 
 ## Mixins
 
-{%
-   include-markdown "./mixins/index.md"
-    start="<!--intro-start-->"
-    end="<!--intro-end-->"
-%}
+See the [Mixins](mixins/index.md) section for info on how to extend `cmd2` using mixins.
 
-## [Testing](testing.md)
+## Testing
 
-## [API Reference](api/index.md)
+See the [Testing](testing.md) section for special considerations when writing unit or integration
+tests for a `cmd2` application.
+
+## API Reference
+
+See the [API Reference](api/index.md) for detailed information on the public API of `cmd2`.
 
 ## Meta
 
-[Documentation Conventions](doc_conventions.md)
+See the [Documentation Conventions](doc_conventions.md) for info on conventions used in this
+documentation.

mkdocs.yml

@@ -60,10 +60,6 @@ theme:
 plugins:
   - search
   - git-revision-date-localized
-  - include-markdown:
-      preserve_includer_indent: true
-      dedent: true
-      comments: false
   - macros:
       render_by_default: false
       on_error_fail: true
@@ -121,6 +117,9 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.keys
   - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      base_path: [".", "docs"]
+      check_paths: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -137,7 +136,7 @@ validation:
     absolute_links: info
   links:
     not_found: warn
-    absolute_links: info
+    absolute_links: ignore
     unrecognized_links: info
 
 not_in_nav: |

pyproject.toml

@@ -45,7 +45,6 @@ dev = [
     "invoke>=2.2.1",
     "ipython>=8.23",
     "mkdocs-git-revision-date-localized-plugin>=1.5",
-    "mkdocs-include-markdown-plugin>=7",
     "mkdocs-macros-plugin>=1.2",
     "mkdocs-material>=9.7.1",
     "mkdocstrings[python]>=1",
@@ -60,7 +59,6 @@ dev = [
 docs = [
     "black>=25",
     "mkdocs-git-revision-date-localized-plugin>=1.5",
-    "mkdocs-include-markdown-plugin>=7",
     "mkdocs-macros-plugin>=1.2",
     "mkdocs-material>=9.7.1",
     "mkdocstrings[python]>=1",