From 7b474ee1e7067c8b1813cb0da1c7395dbde273f3 Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Mon, 11 Aug 2025 19:12:08 -0500
Subject: [PATCH 1/3] add advanced_markdown page

---
 docs/advanced_markdown.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 docs/advanced_markdown.md

diff --git a/docs/advanced_markdown.md b/docs/advanced_markdown.md
new file mode 100644
index 0000000..e69de29

From 1c576a12ec6a84b56e82021ce755f5bcf9506645 Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Mon, 11 Aug 2025 20:10:47 -0500
Subject: [PATCH 2/3] add some advanced features

---
 docs/advanced_markdown.md | 88 +++++++++++++++++++++++++++++++++++++++
 mkdocs.yml                |  9 ++--
 2 files changed, 94 insertions(+), 3 deletions(-)

diff --git a/docs/advanced_markdown.md b/docs/advanced_markdown.md
index e69de29..4416e92 100644
--- a/docs/advanced_markdown.md
+++ b/docs/advanced_markdown.md
@@ -0,0 +1,88 @@
+# Making your docs shine :star: :rainbow:
+
+This is a [great reference guide](https://squidfunk.github.io/mkdocs-material/reference/) to many advanced features of Mkdocs, but doesn't necessarily explain things well.
+
+## Code blocks :computer:
+
+Code blocks can be rendered with a few mkdocs extensions. Add to your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - pymdownx.superfences
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+```
+
+Then you can use code blocks in your markdown like this:
+
+````raw
+```python
+def hello_world():
+    print("Hello, world!")
+```
+````
+
+Displays as
+
+```python
+def hello_world():
+    print("Hello, world!")
+```
+
+## Emojis :cat:
+
+Emojis can bcan be added with the mkdocs markdown extension `pymdownx.emoji`. To use it, add the following to your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+```
+
+Then you can use emojis in your markdown like `:cat:` or `:rainbow:`.
+
+## Admonitions :exclamation: :exclamation: :exclamation:
+
+Admonitions are a general part of doc making libraries. To use [mkdocs style admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/), add the following to your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - admonition
+```
+
+Then you can use admonitions in your markdown like this:
+
+````raw
+!!! note "Note Title"
+    This is a note admonition. It can contain **bold text**, *italic text*, and even [links](https://www.example.com).
+````
+
+Displays as
+!!! note "Note Title"
+    This is a note admonition. It can contain **bold text**, *italic text*, and even [links](https://www.example.com).
+
+## Cross-references :link:
+
+[Versioning](Versioning)
+
+## Math :heavy_plus_sign:
+
+Math can be added with the mkdocs markdown extension `pymdownx.arithmatex`. **But** you also need to have javascript at runtime. To use it, add the following to your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - pymdownx.arithmatex
+
+extra_javascript:
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+```
+
+`$E = mc^2$` inline math
+
+$E = mc^2$
+
+`$$\int_0^\infty e^{-x} dx = 1$$` block form
+
+$$\int_0^\infty e^{-x} dx = 1$$
+
diff --git a/mkdocs.yml b/mkdocs.yml
index a524e74..700f3de 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -5,11 +5,11 @@ theme:
 
 markdown_extensions:
   - admonition
-
   - toc:
       permalink: true
-
   # Python Markdown Extensions
+  - pymdownx.arithmatex:
+      generic: true
   - pymdownx.highlight
   - pymdownx.superfences
   - pymdownx.inlinehilite
@@ -20,4 +20,7 @@ markdown_extensions:
       alternate_style: true
 
 plugins:
-  - mkdocs-jupyter:
\ No newline at end of file
+  - mkdocs-jupyter:
+
+extra_javascript:
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
\ No newline at end of file

From 0a2248c5d9a062c42dc6c931b834d54961ef0f09 Mon Sep 17 00:00:00 2001
From: Tim Monko <timmonko@gmail.com>
Date: Wed, 13 Aug 2025 03:29:33 -0500
Subject: [PATCH 3/3] add cross-referencing

---
 docs/advanced_markdown.md | 4 +++-
 mkdocs.yml                | 1 +
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/advanced_markdown.md b/docs/advanced_markdown.md
index 4416e92..628597f 100644
--- a/docs/advanced_markdown.md
+++ b/docs/advanced_markdown.md
@@ -64,7 +64,9 @@ Displays as
 
 ## Cross-references :link:
 
-[Versioning](Versioning)
+`[Versioning](versioning.md)` will link as [Versioning](versioning.md).
+
+`[Versioning Sub Header](versioning.md#versioning-frameworks)` will link to a sub-header as [Versioning Sub Header](versioning.md#versioning-frameworks) and link directly to the section!
 
 ## Math :heavy_plus_sign:
 
diff --git a/mkdocs.yml b/mkdocs.yml
index d4395f4..eafdced 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -9,6 +9,7 @@ nav:
   - Repository Documentation: repo_setup.md
   - GitHub Repo Settings: gh_repo_settings.md
   - Documenting Code: docstrings.md
+  - Making Your Docs Shine: advanced_markdown.md
   - Notebooks: notebooks.ipynb
   - Versioning: versioning.md