From 7aca3345bccd53ccf653f5a00e21c184b0564179 Mon Sep 17 00:00:00 2001
From: silviana amethyst <1388063+ofloveandhate@users.noreply.github.com>
Date: Wed, 24 Jul 2024 11:53:17 -0500
Subject: [PATCH] tutorial on markdown extensions

also, adding references to other content, to touched `conf.py`
---
 docs/conf.py                                  |  6 +-
 docs/tutorials/markdown_python_extensions.rst | 74 +++++++++++++++++++
 2 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 docs/tutorials/markdown_python_extensions.rst

diff --git a/docs/conf.py b/docs/conf.py
index 9646fc0..14eb543 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -14,7 +14,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc','sphinx.ext.autosectionlabel'
 ]
 
 templates_path = ['_templates']
@@ -41,3 +41,7 @@
 # test the path; not strictly needed
 import markdown2canvas
 
+
+rst_prolog = """
+.. |markdowndefaults| replace:: :attr:`markdown2canvas.translation_functions.default_markdown_extensions`
+"""
diff --git a/docs/tutorials/markdown_python_extensions.rst b/docs/tutorials/markdown_python_extensions.rst
new file mode 100644
index 0000000..4ee56cb
--- /dev/null
+++ b/docs/tutorials/markdown_python_extensions.rst
@@ -0,0 +1,74 @@
+
+
+Customize translation from Markdown to HTML via extensions to `markdown`
+============================================================================
+
+
+This library, `markdown2canvas`, essentially acts as a wrapper around a translation function `markdown2canvas.translation_functions.markdown2html`, or just `markdown2html` for short.  The `markdown2html` function uses the Python library `markdown` (`link to library <https://python-markdown.github.io/>`_) to translate.  You can customize the behaviour of this translation using "extensions" to the `markdown` library.
+
+
+Background
+------------
+
+Before I tell you how to use your own custom set of extensions to `markdown`, here's a brief rundown of how `markdown2canvas` works when you publish a page or assignment to Canvas:
+
+#. :doc:`The style is applied <styling_content>`.
+
+    #. The markdown header and footer from the used style are assembled around your `source.md`.
+    #. The html header and footer from the used style are assembled around that.
+
+#. :doc:`Replacements are done <text_replacements>`.
+#. Emoji shortcodes are emojified
+#. The markdown is translated to HTML.  THIS IS THE STEP YOU CAN CUSTOMIZE. 
+#. :doc:`Links to existing content are implemented <../making_links_to_existing_content>`, further modifying the HTML.
+#. Local files and images which are linked-to in the source are uploaded (if necessary), and the HTML is adjusted to use the Canvas links to that content.
+#. Content properties are set from `meta.json`.
+#. The content is placed in modules as described in `meta.json`.
+
+This tutorial is about customizing the first translation to HTML, by using `markdown` extensions.
+
+
+Provided default `markdown` extensions
+--------------------------------------------
+
+This library provides a decent set of default extensions, chosen for 
+
+* Syntax highlighting of code
+* Translating markdown tables
+* Trying to make sure that markdown inside of HTML is translated, too
+
+The specific default list is |markdowndefaults|.  
+
+
+
+Specifying your own list of extensions
+-----------------------------------------
+
+You may wish to use your own set of extensions.  Easy!  Just specify the list in your `defaults.json` file.
+
+#. Edit `_course_metadata/defaults.json`.
+#. Add a key-value pair.  
+    
+    * Key: `markdown_extensions`
+    * Value: A list of strings which are names of extensions.  
+
+
+
+
+Where to find more extensions
+----------------------------------
+
+I have found `the official `markdown` Extensions documentation <https://python-markdown.github.io/extensions/>` to be very helpful.
+
+Cruise the list, find one that you need, and try it out by:
+
+* Add it to the list of extensions you are using
+* Publish the content to a test or sandbox course on Canvas
+* Check it out!  Did it do what you needed?
+
+
+Limitations
+---------------
+
+ℹ️ Known limitation: This system is missing methods for you writing your own extensions to `markdown`.  I do not know what happens if your list of extensions includes references to your own, but I suspect errors because they'll be strings, not Python modules, classes, or functions.
+