Make various documentation related updates.

.github/workflows/deploy.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip setuptools
-          python -m pip install -r doc-requirements.txt
+          python -m pip install .[docs]
       - name: Build
         run: |
           python -m mkdocs build --clean --verbose

.github/workflows/manual_deploy.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip setuptools
-          python -m pip install -r doc-requirements.txt
+          python -m pip install .[docs]
       - name: Build
         run: |
           python -m mkdocs build --clean --verbose

.spell-dict

@@ -22,6 +22,7 @@ CLI
 CodeHilite
 codehilite
 Cogumbreiro
+CommonMark
 convertFile
 CSS
 dedent

docs/contributing.md

@@ -56,9 +56,16 @@ library. Keeping new feature requests implemented as third party extensions
 allows us to keep the maintenance overhead of Python-Markdown to a minimum, so
 that the focus can be on continued stability, bug fixes, and documentation.
 
-Closing an issue does not necessarily mean the end of a discussion. If you
-believe your issue has been closed incorrectly, explain why and we'll consider
-if it needs to be reopened.
+If you intend to submit a fix for your bug or provide an implementation of your
+future request, it is not necessary to first open an issue. You can report a
+bug or make a feature request as part of a pull request. Of course, if you want
+to receive feedback on how to implement a bug-fix or feature before submitting
+a solution, then it would be appropriate to open an issue first and ask your
+questions there.
+
+Having your issue closed does not necessarily mean the end of a discussion. If
+you believe your issue has been closed incorrectly, explain why and we'll
+consider if it needs to be reopened.
 
 ## Pull Requests
 
@@ -99,6 +106,12 @@ GitHub interface to ensure that all tests are running as expected. If any checks
 fail, you may push additional commits to your branch. GitHub will add those
 commits to the pull request and rerun the checks.
 
+It is generally best not to squash multiple commits and force-push your changes
+to a pull request. Instead, the maintainers would like to be able to follow the
+series of commits along with the discussion about those changes as they
+progress over time. If your pull request is accepted, it will be squashed at
+that time if deemed appropriate.
+
 ## Style Guides
 
 In an effort to maintain consistency, Python-Markdown adheres to the following
@@ -224,6 +237,34 @@ Python-Markdown's [Admonition Extension]:
     This is the content of the note.
 ```
 
+#### Release Notes
+
+Any commit/pull request which changes the behavior of the Markdown library in
+any way must include an entry in the release notes. If a change only alters the
+documentation or tooling for the project, then an entry in the release notes is
+not necessary. The release notes can be found at `docs/change_log`.
+
+Each release must have an entry in `docs/change_log/index.md` which follows the
+format of the existing entries. A MAJOR release (`X.0.0`) and a MINOR release
+(`X.X.0`) should only include a single line in `docs/change_log/index.md` which
+links to a full document outlining all changes included in the release.
+However, a PATCH release (X.X.X) should include a list of single line entries
+summarizing each change directly in the file `docs/change_log/index.md` (see
+[Versions](#versions) for an explanation of MAJOR, MINOR, and PATCH releases).
+The description of each change should include a reference to the relevant
+GitHub issue in the format `#123` (where `123` is the issue number).
+
+Prior to a version being released, the text `*under development*` should be
+used as a placeholder for the release date. That text will be replaced with the
+release date as part of the [release process](#release-process).
+
+If a change is the first since the last release, then the appropriate entries
+and/or files may need to be created and included in a pull request. A pull
+request should not alter an entry for an existing version which has already
+been released, unless it is editing an error in the release notes for that
+version, or is otherwise expressly deemed appropriate by the project
+maintainers.
+
 ### Commit Message Style Guide
 
 Use the present tense ("Add feature" not "Added feature").

docs/index.md

@@ -21,13 +21,23 @@ The Python-Markdown project is developed with the following goals in mind:
 * Maintain a Python library (with an optional CLI wrapper) suited to use in web
   server environments (never raise an exception, never write to stdout, etc.) as
   an implementation of the markdown parser that follows the
-  [syntax rules](https://daringfireball.net/projects/markdown/syntax) and the
-  behavior of the original (markdown.pl) implementation as reasonably as
-  possible (see [differences](#differences) for a few exceptions).
+  [syntax rules][] and the behavior of the original (markdown.pl)
+  implementation as reasonably as possible (see [differences](#differences) for
+  a few exceptions).
 
 * Provide an [Extension API](extensions/api.md) which makes it possible
   to change and/or extend the behavior of the parser.
 
+!!! Note
+
+    *This is not a CommonMark implementation*; nor is it trying to be!
+    Python-Markdown was developed long before the CommonMark specification was
+    released and has always (mostly) followed the [syntax rules][] and behavior
+    of the original reference implementation. No accommodations have been made
+    to address the changes which CommonMark has suggested. It is recommended
+    that you look elsewhere if you want an implementation which follows the
+    CommonMark specification.
+
 Features
 --------
 
@@ -91,7 +101,7 @@ are summarized below:
     In the event that one would prefer different behavior,
     [tab_length](reference.md#tab_length) can be set to whatever length is
     desired. Be warned however, as this will affect indentation for all aspects
-    of the syntax (including root level code blocks). Alternatively, a 
+    of the syntax (including root level code blocks). Alternatively, a
     [third party extension] may offer a solution that meets your needs.
 
 * __Consecutive Lists__
@@ -109,4 +119,5 @@ Support
 You may report bugs, ask for help, and discuss various other issues on the [bug tracker][].
 
 [third party extension]: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions
+[syntax rules]: https://daringfireball.net/projects/markdown/syntax
 [bug tracker]: https://github.com/Python-Markdown/markdown/issues

mkdocs.yml

@@ -62,3 +62,6 @@ markdown_extensions:
   - codehilite
   - toc:
       permalink: true
+  - mdx_gh_links:
+      user: Python-Markdown
+      repo: markdown

pyproject.toml

@@ -52,6 +52,11 @@ testing = [
     'coverage',
     'pyyaml',
 ]
+docs = [
+    'mkdocs>=1.0',
+    'mkdocs-nature',
+    'mdx_gh_links>=0.2'
+]
 
 [project.urls]
 'Homepage' = 'https://Python-Markdown.github.io/'

tox.ini

@@ -26,10 +26,8 @@ commands = flake8 {toxinidir}/markdown {toxinidir}/tests
 skip_install = true
 
 [testenv:checkspelling]
-deps =
-    mkdocs
-    mkdocs_nature
-    pyspelling
+extras = docs
+deps = pyspelling
 commands =
     {envpython} -m mkdocs build --strict --config-file {toxinidir}/mkdocs.yml
     {envpython} -m pyspelling --config {toxinidir}/.pyspelling.yml