django-markdown-view 0.0.6__py3-none-any.whl

django_markdown_view-0.0.6.dist-info/METADATA

@@ -0,0 +1,371 @@
+Metadata-Version: 2.4
+Name: django-markdown-view
+Version: 0.0.6
+Summary: Serve .md pages as Django views.
+Author-email: "Ryan J. Sullivan" <ryanj@ryanjsullivan.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, http://github.com/rgs258/django-markdown-view
+Keywords: django,markdown,markdown view,md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: django>=5.2
+Requires-Dist: markdown>=3.2
+Dynamic: license-file
+
+Django Markdown View
+====================
+
+.. image:: https://github.com/rgs258/django-markdown-view/actions/workflows/test.yml/badge.svg
+    :target: https://github.com/rgs258/django-markdown-view/actions/workflows/test.yml
+
+.. image:: https://coveralls.io/repos/github/rgs258/django-markdown-view/badge.svg?branch=master
+    :target: https://coveralls.io/github/rgs258/django-markdown-view?branch=master
+
+
+**Serve .md pages as Django views.**
+
+This package aims to make it easy to serve .md files on Django sites.
+
+
+.. contents:: Contents
+    :depth: 5
+
+Installation
+------------
+
+#. Install with ``pip install django-markdown-view``.
+
+#. Add ``'markdown_view'`` to your ``INSTALLED_APPS`` settings.
+
+    .. code-block:: python
+
+        INSTALLED_APPS = [
+            ...,
+            'markdown_view',
+            ...
+        ]
+
+#. (OPTIONAL) Add ``MARKDOWN_VIEW_BASE_DIR`` or ``BASE_DIR`` to settings
+    The dictionary of the application's base. See Settings_ below
+
+    For example, if settings are in config/settings/base.py, then:
+
+    .. code-block:: python
+
+        BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+
+
+Usage
+-----
+
+Views
+~~~~~
+
+Use one of ``MarkdownView``,  ``LoggedInMarkdownView``, or ``StaffMarkdownView``
+from ``markdown_view.views`` to serve a .md file
+
+.. code-block:: python
+
+    from markdown_view.views import StaffMarkdownView
+
+    path('readme/',
+        StaffMarkdownView.as_view(file_name='my_app/README.md'),
+        name="readme"),
+
+Settings
+~~~~~~~~
+
+All settings are optional. See `<markdown_view/constants.py>`_ for the defaults.
+
+* `MARKDOWN_VIEW_BASE_DIR` and `BASE_DIR`
+
+    When present, the value is taken as a location to append to the list of dirs that
+    Django's `django.template.utils.get_app_template_dirs` will return when passed
+    `dirname=""`. This is used to locate .md files in the root of the project, e.g.,
+    a README.md file. Looks for `BASE_DIR` if `MARKDOWN_VIEW_BASE_DIR` is not found.
+
+* `MARKDOWN_VIEW_LOADERS`
+
+    A list of loaders that locate .md files. The default list includes only
+    `markdown_view.loaders.MarkdownLoader` which will by default try to load .md files
+    from root directories in INSTALLED_APPS packages much the same as Django's
+    `django.template.loaders.app_directories.Loader` looks to load from "templates".
+
+* `MARKDOWN_VIEW_LOADER_TEMPLATES_DIR`
+
+    The name of the directories in INSTALLED_APPS packages in which to locate .md
+    files. Defaults to "" in order to locate .md filed in the root directories.
+
+* `MARKDOWN_VIEW_EXTENSIONS`
+
+    The extensions to enable. These extensions are enabled be default:
+
+    * `toc`:
+        generates a Table of Contents. If `toc` is removed from extensions, then
+        `MARKDOWN_VIEW_TEMPLATE_USE_TOC` must be set to False.
+
+    * `tables`:
+        enables tables.
+
+    * `fenced_code`:
+        enables code blocks. If `fenced_code` is removed from extensions, then
+        `MARKDOWN_VIEW_TEMPLATE_USE_HIGHLIGHT_JS`, which provides the highlighting for
+        code blocks, can be disabled.
+
+    * `markdown_view.markdown_extensions.ImageExtension`:
+        makes images responsive in bootstrap4.
+
+    See https://python-markdown.github.io/extensions/ and
+    https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions for more
+    extensions.
+
+    You can create your own extensions by following
+    https://github.com/Python-Markdown/markdown/wiki/Tutorial-1---Writing-Extensions-for-Python-Markdown
+
+* `MARKDOWN_VIEW_TEMPLATE`
+
+    The Django template that'll be used to render the HTML that is generated from the
+    Markdown. Set your own template to style your pages. Context includes:
+
+    * `markdown_content`:
+        The HTML produced from the Markdown.
+
+    * `use_highlight_js`:
+        If highlight.js is enabled.
+
+    * `use_toc`:
+        If the table of contents should be rendered.
+
+    * `markdown_toc`:
+        A table of contents from the headers of the Markdown. Not set when `use_toc`
+        is False.
+
+    * `page_title`:
+        A guess at a page title, for now it's the first row of the TOC. Not set when
+        `use_toc` is False, or when the Markdown has no headers for the TOC to be
+        built from.
+
+* `MARKDOWN_VIEW_TEMPLATE_USE_TOC`
+
+    Whether to render the TOC. If false, in the template context, `use_toc` is False
+    and `markdown_toc` and `page_title` are not present.
+
+* `MARKDOWN_VIEW_TEMPLATE_USE_HIGHLIGHT_JS`
+
+    Whether to load and activate the highlight.js library in the template.
+
+* `MARKDOWN_VIEW_REWRITE_INTERNAL_LINKS`
+
+    Defaults to `True`. Markdown source files commonly link to other `.md`
+    files using plain, filesystem-relative links (e.g.
+    ``[See also](../README-cron.md)``), exactly as they'd resolve on GitHub
+    or in a local editor. Since a rendered page is served at its *view's*
+    URL rather than at the source file's location on disk, such a link
+    would otherwise 404 in the browser.
+
+    When enabled, `MarkdownView` looks up whether any URL pattern in the
+    project serves the linked `.md` file via a `MarkdownView` (or
+    subclass), and if so, rewrites the link to that view's actual URL
+    instead of leaving the raw relative file path in place. See
+    `markdown_view/registry.py <markdown_view/registry.py>`_ for the
+    resolution logic. This is best-effort: links to files that aren't
+    routed anywhere, or whose route is behind a required URL argument, are
+    left exactly as Markdown would otherwise have rendered them -- nothing
+    breaks if a linked file simply isn't routed, unless
+    `MARKDOWN_VIEW_UNRESOLVED_LINK_ROOT` is also configured (see below).
+    Set to `False` to disable this rewriting entirely, including the
+    `MARKDOWN_VIEW_UNRESOLVED_LINK_ROOT` fallback.
+
+* `MARKDOWN_VIEW_UNRESOLVED_LINK_ROOT`
+
+    Defaults to `None` (disabled). Relative links that `MARKDOWN_VIEW_REWRITE_INTERNAL_LINKS`
+    can't resolve to a registered `MarkdownView` route -- including links to
+    files other than `.md`, such as repository-relative links to source
+    code (e.g. ``[`example.module.helper`](src/example/module.py)``) --
+    are left unchanged by default. Setting this to a root URL instead
+    resolves such links against it, e.g.:
+
+    .. code-block:: python
+
+        MARKDOWN_VIEW_UNRESOLVED_LINK_ROOT = (
+            "https://git.example.com/example/project/-/blob/main/"
+        )
+
+    With the setting above, ``[`example.module.helper`](src/example/module.py)``
+    would render as a link to
+    ``https://git.example.com/example/project/-/blob/main/src/example/module.py``.
+    Registered-route rewriting always takes precedence over this fallback;
+    it only applies once a link has already failed to resolve to a route.
+    `./` and `../` path segments, and any query string or `#fragment`, are
+    resolved/preserved correctly. Absolute URLs, root-relative URLs,
+    fragment-only links, and URLs with an explicit scheme are never
+    affected by this setting.
+
+* `MARKDOWN_VIEW_ESCAPE_UNSAFE_TEMPLATE_SYNTAX`
+
+    Defaults to `True`. `MarkdownView` re-parses the HTML converted from
+    Markdown as a Django template, so that the `{% static %}` tags
+    `ImageExtension` injects for image sources (and, when
+    `MARKDOWN_VIEW_USE_REQUEST_CONTEXT`/`MARKDOWN_VIEW_EXTRA_CONTEXT` are
+    used, any `{{ variable }}` reference to a real context key) actually
+    resolve. Markdown source files are prose, though, and prose about
+    Django itself routinely contains literal `{% ... %}`/`{{ ... }}` text
+    that was never meant to be executed as a template -- left unescaped,
+    an unrecognized `{% ... %}` block raises `TemplateSyntaxError` (a hard
+    500 for the whole page), and an unrecognized `{{ ... }}` variable is
+    silently rendered as an empty string (silent content loss, with no
+    error at all).
+
+    When enabled (the default), every `{% ... %}`/`{{ ... }}` span in the
+    converted HTML is escaped to inert literal text *except* the exact
+    `{% static '...' %}` tags `ImageExtension` injects, and bare
+    `{{ identifier }}` references to a name actually present in the
+    context the page renders with. See
+    `markdown_view/escaping.py <markdown_view/escaping.py>`_ for the exact
+    rules. Set to `False` to restore the previous, fully-permissive
+    behavior (the whole converted document is parsed as a real Django
+    template, with no escaping at all).
+
+Experimental Settings
+~~~~~~~~~~~~~~~~~~~~~
+
+* `MARKDOWN_VIEW_USE_REQUEST_CONTEXT`
+
+    If the request context should be used as a base when creating the context with
+    which to render the Markdown internally. This is because the Markdown is rendered
+    once first in order to prepend it with `{% load static %}`.
+    This is not well tested; YMMV. Note that a `{{ name }}` reference only
+    resolves against this context if `MARKDOWN_VIEW_ESCAPE_UNSAFE_TEMPLATE_SYNTAX`
+    (see above) recognizes `name` as a safe context key -- otherwise it's
+    escaped to literal text rather than looked up.
+
+* `MARKDOWN_VIEW_EXTRA_CONTEXT`
+
+    Any extra context to send to the internal render of the Markdown. Can be used
+    to expose context to template tags embedded in the Markdown.
+    This is not well tested; YMMV. As with `MARKDOWN_VIEW_USE_REQUEST_CONTEXT`
+    above, a `{{ name }}` reference to one of these keys is only left live
+    when `MARKDOWN_VIEW_ESCAPE_UNSAFE_TEMPLATE_SYNTAX` recognizes it as safe.
+
+
+Implementation
+--------------
+
+At a high level, `MarkdownView` will:
+
+#. Use a template loader to locate `.md` given as `file_name`
+
+#. Convert the Markdown to HTML
+
+#. If `MARKDOWN_VIEW_REWRITE_INTERNAL_LINKS` is enabled, rewrite any
+   relative links to other `.md` files that resolve to a file served by a
+   registered `MarkdownView` route, to that route's actual URL; any
+   relative link left unresolved by that step is instead resolved against
+   `MARKDOWN_VIEW_UNRESOLVED_LINK_ROOT`, if configured
+
+#. Render as a template, the resulting HTML prepended with
+   `{% load static %}`, into several context variables
+
+#. Serve the `MARKDOWN_VIEW_TEMPLATE` with the context variables
+
+Release Notes and Contributors
+------------------------------
+
+* `Release notes <https://github.com/rgs258/django-markdown-view/releases>`_
+* `Our wonderful contributors <https://github.com/rgs258/django-markdown-view/graphs/contributors>`_
+
+Releasing
+---------
+
+Versions are derived from git tags via `setuptools_scm`_, so there is no
+hardcoded ``version`` to bump.
+
+To publish a new release to PyPI:
+
+#. Merge the changes for the release into ``master``.
+
+#. `Create a GitHub Release`_ with a tag matching the desired version
+   (e.g. ``0.0.6``).
+
+#. Publishing the release triggers the `Publish to PyPI`_ GitHub Actions
+   workflow, which builds the sdist/wheel and uploads them to PyPI using
+   `PyPI Trusted Publishing`_ (no stored token required).
+
+Publishing beta / pre-releases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Beta and other pre-releases can be published to PyPI the same way as a
+regular release, and this is standard practice: PyPI understands
+`PEP 440`_ pre-release version identifiers and will not let a plain
+``pip install django-markdown-view`` pick them up by default, so betas are
+safe to publish without risking accidental adoption.
+
+#. Tag the release commit with an explicit PEP 440 pre-release suffix
+   instead of a plain version, e.g. ``0.0.6b1`` for a beta, or ``0.0.6rc1``
+   for a release candidate. ``setuptools_scm`` will pick up the tag as-is.
+
+#. `Create a GitHub Release`_ for that tag and check the **"Set as a
+   pre-release"** box. This only affects how the release is labeled on
+   GitHub; PyPI determines pre-release status purely from the version
+   string.
+
+#. Publishing the release triggers the same `Publish to PyPI`_ workflow,
+   which uploads the pre-release to PyPI. It will appear in the release
+   history but will not be installed by ``pip install
+   django-markdown-view``.
+
+#. Users who want to try it must opt in, e.g. ``pip install --pre
+   django-markdown-view`` or by pinning the exact version, such as
+   ``pip install django-markdown-view==0.0.6b1``.
+
+#. If further fixes are needed, bump the pre-release number (``0.0.6b2``,
+   ``0.0.6b3``, ...) rather than reusing one, since PyPI does not allow
+   re-uploading files for a version that has already been published.
+   Once the release is stable, tag and publish the final version without
+   a suffix (e.g. ``0.0.6``), which then becomes installable by default.
+
+.. _setuptools_scm: https://github.com/pypa/setuptools_scm
+.. _`Create a GitHub Release`: https://github.com/rgs258/django-markdown-view/releases/new
+.. _`Publish to PyPI`: https://github.com/rgs258/django-markdown-view/actions/workflows/publish.yml
+.. _`PyPI Trusted Publishing`: https://docs.pypi.org/trusted-publishers/
+.. _`PEP 440`: https://peps.python.org/pep-0440/#pre-releases
+
+Contributing
+------------
+
+All contributions are very welcomed. Propositions, problems, bugs, and
+enhancement are tracked with `GitHub issues`_ and patches are submitted
+via `pull requests`_.
+
+We use `GitHub Actions`_ coupled with `Coveralls`_ as continuous integration tools.
+
+.. _`GitHub issues`: https://github.com/rgs258/django-markdown-view/issues
+.. _`pull requests`: https://github.com/rgs258/django-markdown-view/pulls
+.. _`GitHub Actions`: https://github.com/rgs258/django-markdown-view/actions
+.. _Coveralls: https://coveralls.io/github/rgs258/django-markdown-view
+
+Requirements
+------------
+
+We aspire to support the currently supported versions of Django.
+
+**The Tested With section describes aspirational goals.**
+
+Tested with:
+
+* Python: 3.10, 3.11, 3.12, 3.13
+* Django: 5.2, 6.0

django_markdown_view-0.0.6.dist-info/RECORD

@@ -0,0 +1,42 @@
+django_markdown_view-0.0.6.dist-info/licenses/LICENSE,sha256=Xun9tu6GoUnr8qy5C3MBQeqJZeuzkw67SQiFzexknls,1542
+markdown_view/__init__.py,sha256=EXOCt-R6NOvU0yLhQcmwQT_U-DVK0TPZYpErkJ6tbko,61
+markdown_view/apps.py,sha256=QwgUCdY8AupkXpT7AOqqigSaPY45bpp7KHeAYvDlMds,332
+markdown_view/checks.py,sha256=z5YHRcwFF-_1vS6citYfLwQA4wFoXp_d7TQg8S_YtiI,1790
+markdown_view/constants.py,sha256=ao2aD9_rgQrCWJRn3sQ7VMHUHOcGcAktW60bmfZJY_k,689
+markdown_view/escaping.py,sha256=zofhvJzLc5qTII_9_IGh5731AWyQ3fCg8CbP-J8tTms,4097
+markdown_view/loaders.py,sha256=dtZ2X01MGfW5cnGMH78jSQ08SATqsv_amPmBM9jOA14,2221
+markdown_view/loading.py,sha256=I-H_d2pwHCmot5Ol9YZ9uDvcMm7qIx6R3yGd74wain0,2749
+markdown_view/markdown_extensions.py,sha256=T_9cRg99vnXyhBA-evqVRRE0kHITx1YitRGJV9IghX8,635
+markdown_view/models.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_view/registry.py,sha256=tHOKuCX3fYLauRShxK21hibLLleUVRotlFWUXgJCGqg,18244
+markdown_view/views.py,sha256=qNQlhihNz-bs46aicoApDkn8R6Uowy99WiOu8jMvKvQ,6197
+markdown_view/templates/markdown_view/markdown.html,sha256=QyddBcicEe0CnGQFN66BRCNcUr3SUVXBEqwzLm9NCWQ,1232
+markdown_view/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_view/tests/test_checks.py,sha256=dh4LYFj6kD_r7rEoPtsqfbqpJ5sOQmpnoQEi2-zkaq4,1584
+markdown_view/tests/test_escaping.py,sha256=JGYO6TG5_-GTSCwUlbqDB5DsmOFgiaq1XRkSCkOKzhU,3282
+markdown_view/tests/test_loaders.py,sha256=w1-WBFcRjTnYjZWFRFcJVWqbT5B8CYvU0oCwJiz7sZY,2583
+markdown_view/tests/test_loading.py,sha256=or4xpgWRo5NztC1GKk4Dgix2DTq5mlsEWFFZNoKDf4Q,1534
+markdown_view/tests/test_markdown_extensions.py,sha256=GHgcI3zeUFi-BisdrHJ8gx_NOXOv10q-vAKjuDuQ_kk,1271
+markdown_view/tests/test_registry.py,sha256=5eRczxgaOEzkkBEA7DDKNUGcSj6A7tp4up7lJVAlL4M,20015
+markdown_view/tests/test_settings_validation.py,sha256=dbelvQ2Z5j5Xu0GrOSQB3bsPI_fyVcpn8LyaNHRFM5w,3645
+markdown_view/tests/test_views.py,sha256=lMWQgwHKAO7U2Hqnv6FZacII_cyjdV-Yf_95xxbdPwg,12058
+markdown_view/tests/urls.py,sha256=Sgidy3YVxHGOsvfIjdB0lrRZBAmBVDgn-7m1TLaqcGA,4040
+markdown_view/tests/fixtures/loaders_a/readme.md,sha256=3ZLpASU8bfOp6GY2ExZPrzlnHfCb3LR8qGNpVC_9iLU,227
+markdown_view/tests/fixtures/loaders_b/readme.md,sha256=NwuNR4ZsdXlmp2wE5GvfVNrkYoRzXcHwtqdvU_t72sA,227
+markdown_view/tests/settings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_view/tests/settings/coveralls_settings.py,sha256=JG-heiLhtoiGwxKL0sb77yIFqPeZGMAKaM4FcDxMgTs,2263
+markdown_view/tests/testapp/CONTEXT_TEST.md,sha256=25kLvqZC8pHZ2DUuEUVABV28to3aMzUKsN-e5rDZPGY,72
+markdown_view/tests/testapp/ESCAPING_TEST.md,sha256=rH2gp79OE-7CTtH5eGr77Sjc_NbTAcyaYxaKhi74B9w,418
+markdown_view/tests/testapp/LOGGED_IN.md,sha256=_ycP4KN2-LCpdapSnskA-6VLs6f7nG3WTdmAGn3VDsw,73
+markdown_view/tests/testapp/NESTED.md,sha256=hXAcDFiEwtG0aZatjSKRzoDiZIOOH3voYMZqfFGBYjc,192
+markdown_view/tests/testapp/NO_HEADERS.md,sha256=YbL0KxChybEQauZ46zltWsQbzKRcvfGxTHzIZ174vkg,237
+markdown_view/tests/testapp/README.md,sha256=xk_cwqo8kS6qNHCMTmmFsgohoMvzrs_tgIpC8e010S4,896
+markdown_view/tests/testapp/STAFF.md,sha256=kJyaIF4JFSjc4QBcX_jAmlJ32_HHzpmWaygPbLeYqGw,68
+markdown_view/tests/testapp/UNROUTED.md,sha256=6xbM35PNQ2e1FJWmihJ8_aTXSN96vYG_6RUrQIibl0A,157
+markdown_view/tests/testapp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_view/tests/testapp/apps.py,sha256=my2snU00q5vjhr0BK_fs9tPVnDTLnk6PM8ezS3lV-ZY,173
+markdown_view/tests/testapp/docs/OTHER.md,sha256=xRf-5jaJCnJiaz_bQaVMI5OVpVcuhWlNVejSedyY57k,231
+django_markdown_view-0.0.6.dist-info/METADATA,sha256=5eaR6Bl6OcZEY6JprrDDRA6FS0lKJ7NDu8bYMDM9yYM,14716
+django_markdown_view-0.0.6.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+django_markdown_view-0.0.6.dist-info/top_level.txt,sha256=MqRRE0ldzEe17rDjvoESYz22dyeBcPAG9ELXUR5FD7w,14
+django_markdown_view-0.0.6.dist-info/RECORD,,

django_markdown_view-0.0.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_markdown_view-0.0.6.dist-info/licenses/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) Ryan J. Sullivan and individual contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Django nor the names of its contributors may be used
+       to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django_markdown_view-0.0.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+markdown_view

markdown_view/__init__.py

@@ -0,0 +1 @@
+default_app_config = "markdown_view.apps.MarkdownViewConfig"

markdown_view/apps.py

@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+from django.core.checks import register, Tags
+
+from markdown_view.checks import markdown_view_check
+
+
+class MarkdownViewConfig(AppConfig):
+    name = "markdown_view"
+    verbose_name = "Serve .md pages as Django templates"
+
+    def ready(self):
+        register(markdown_view_check, Tags.security)

markdown_view/checks.py

@@ -0,0 +1,46 @@
+from django.conf import settings
+from django.core import checks
+
+# Expected type for each optional markdown_view setting. Validated by
+# `markdown_view_check()` below (registered as a Django system check in
+# `apps.py`), rather than at import time, so `manage.py check` -- and
+# `override_settings` in tests -- can exercise this validation directly.
+SETTINGS_TYPES = {
+    "MARKDOWN_VIEW_LOADERS": list,
+    "MARKDOWN_VIEW_LOADER_TEMPLATES_DIR": str,
+    "MARKDOWN_VIEW_EXTENSIONS": list,
+    "MARKDOWN_VIEW_BASE_DIR": str,
+    "MARKDOWN_VIEW_TEMPLATE": str,
+    "MARKDOWN_VIEW_TEMPLATE_USE_TOC": bool,
+    "MARKDOWN_VIEW_TEMPLATE_USE_HIGHLIGHT_JS": bool,
+    "MARKDOWN_VIEW_USE_REQUEST_CONTEXT": bool,
+    "MARKDOWN_VIEW_EXTRA_CONTEXT": dict,
+    "MARKDOWN_VIEW_REWRITE_INTERNAL_LINKS": bool,
+    # `None` is an explicitly valid value here (meaning "no fallback root
+    # configured"), unlike every other setting in this dict.
+    "MARKDOWN_VIEW_UNRESOLVED_LINK_ROOT": (str, type(None)),
+    "MARKDOWN_VIEW_ESCAPE_UNSAFE_TEMPLATE_SYNTAX": bool,
+}
+
+
+def markdown_view_check(app_configs, **kwargs):
+    """
+    Validate that any of markdown_view's optional settings the project has
+    defined are of the expected type.
+    """
+    errors = []
+
+    for variable, instance_type in SETTINGS_TYPES.items():
+        if hasattr(settings, variable) and not isinstance(
+            getattr(settings, variable), instance_type
+        ):
+            errors.append(
+                checks.Error(
+                    "Setting %s is not of type %s" % (variable, instance_type),
+                    hint="Update %s in your settings module to be of type %s."
+                    % (variable, instance_type),
+                    id="markdown_view.E001",
+                )
+            )
+
+    return errors

markdown_view/constants.py

@@ -0,0 +1,13 @@
+from markdown_view.markdown_extensions import ImageExtension
+
+DEFAULT_MARKDOWN_VIEW_LOADERS = ["markdown_view.loaders.MarkdownLoader", ]
+DEFAULT_MARKDOWN_VIEW_LOADER_TEMPLATES_DIR = ""
+DEFAULT_MARKDOWN_VIEW_EXTENSIONS = ["tables", "fenced_code", "toc", ImageExtension(), ]
+DEFAULT_MARKDOWN_VIEW_TEMPLATE = "markdown_view/markdown.html"
+DEFAULT_MARKDOWN_VIEW_TEMPLATE_USE_TOC = True
+DEFAULT_MARKDOWN_VIEW_TEMPLATE_USE_HIGHLIGHT_JS = True
+DEFAULT_MARKDOWN_VIEW_USE_REQUEST_CONTEXT = False
+DEFAULT_MARKDOWN_VIEW_EXTRA_CONTEXT = {}
+DEFAULT_MARKDOWN_VIEW_REWRITE_INTERNAL_LINKS = True
+DEFAULT_MARKDOWN_VIEW_UNRESOLVED_LINK_ROOT = None
+DEFAULT_MARKDOWN_VIEW_ESCAPE_UNSAFE_TEMPLATE_SYNTAX = True

markdown_view/escaping.py

@@ -0,0 +1,82 @@
+"""
+Escaping for literal Django template syntax found inside rendered Markdown.
+
+`MarkdownView` re-parses the HTML produced from a `.md` file as a Django
+template, so that the `{% static %}` tags `ImageExtension` injects for
+image sources (and, when a project opts in via
+`MARKDOWN_VIEW_EXTRA_CONTEXT`/`MARKDOWN_VIEW_USE_REQUEST_CONTEXT`, any
+`{{ variable }}` references to those context values) actually resolve.
+
+Markdown source files are prose, though, and prose about Django itself
+routinely contains literal `{% ... %}`/`{{ ... }}` text that was never
+meant to be executed as a template -- e.g. a paragraph explaining how a
+template tag works. Left unescaped, that literal text is a genuine
+production hazard: an unrecognized `{% ... %}` block raises
+`TemplateSyntaxError` (a hard 500 for the whole page), and an unrecognized
+`{{ ... }}` variable is silently rendered as an empty string by Django's
+default `Context` behavior (silent content loss, with no error at all).
+
+`escape_unsafe_template_syntax()` walks the converted HTML and leaves only
+the two genuinely-intended constructs alone -- the exact `{% static '...'
+%}` tags `ImageExtension` injects, and `{{ identifier }}` references to a
+name actually present in the context the page will render with -- while
+converting every other `{% ... %}`/`{{ ... }}` span into inert literal
+text, so a documentation author can safely write about template syntax
+without needing to know anything about this rendering pipeline.
+"""
+import re
+
+# The exact shape `ImageExtension.InlineImageProcessor` emits: always
+# single-quoted, no filters, no whitespace variation beyond a single space
+# after `static`.
+_STATIC_TAG_RE = re.compile(r"^\{%\s*static\s+'[^']*'\s*%\}$")
+
+# A bare `{{ identifier }}` reference -- no dotted lookups, no filters. This
+# intentionally covers only the simple case `MarkdownView`'s own context-
+# variable support is documented/tested against; anything more elaborate
+# appearing in a `.md` file is far more likely to be prose describing
+# template syntax than a real, intended lookup.
+_SIMPLE_VARIABLE_RE = re.compile(r"^\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}$")
+
+# Matches one `{% ... %}` or `{{ ... }}` span at a time, restricted to a
+# single line (`.` does not match `\n`) since genuine template tags and
+# variable references are not expected to span multiple lines, and
+# allowing them to would risk one stray, unmatched delimiter swallowing an
+# entire unrelated section of a document into a single "match".
+_TEMPLATE_SYNTAX_RE = re.compile(r"(\{%.*?%\})|(\{\{.*?\}\})")
+
+
+def _escape_braces(text):
+    """Render literal ``{``/``}`` characters inert to Django's template lexer."""
+    return text.replace("{", "{").replace("}", "}")
+
+
+def escape_unsafe_template_syntax(html, safe_context_keys=()):
+    """
+    Escape any ``{% ... %}``/``{{ ... }}`` span in `html` that is not one
+    of the two constructs `MarkdownView` genuinely intends to execute,
+    rendering it as inert literal text instead.
+
+    :param html: Rendered HTML markup, already converted from Markdown.
+    :param safe_context_keys: Top-level variable names that will actually
+        be present in the context `html` renders with (e.g. from
+        `MARKDOWN_VIEW_EXTRA_CONTEXT` or, when
+        `MARKDOWN_VIEW_USE_REQUEST_CONTEXT` is enabled, the view's own
+        context). A `{{ name }}` reference to one of these is left alone;
+        anything else is treated as literal text.
+    :return: `html` with every unsafe template-syntax-shaped span escaped.
+    """
+    safe_context_keys = set(safe_context_keys)
+
+    def _replace(match):
+        block_tag, variable_tag = match.group(1), match.group(2)
+        if block_tag is not None:
+            if _STATIC_TAG_RE.match(block_tag):
+                return block_tag
+            return _escape_braces(block_tag)
+        variable_match = _SIMPLE_VARIABLE_RE.match(variable_tag)
+        if variable_match and variable_match.group(1) in safe_context_keys:
+            return variable_tag
+        return _escape_braces(variable_tag)
+
+    return _TEMPLATE_SYNTAX_RE.sub(_replace, html)

markdown_view/loaders.py

@@ -0,0 +1,61 @@
+from django.conf import settings
+from django.core.exceptions import SuspiciousFileOperation
+from django.template import Origin
+from django.template.loaders.filesystem import Loader as FilesystemLoader
+from django.template.utils import get_app_template_dirs
+from django.utils._os import safe_join
+
+from markdown_view.constants import DEFAULT_MARKDOWN_VIEW_LOADER_TEMPLATES_DIR
+
+
+class MarkdownLoader(FilesystemLoader):
+    """
+    A loader that will find a .md file in the context of any installed app or
+    application root.
+    """
+
+    def get_dirs(self):
+        base_dir = getattr(
+            settings,
+            "MARKDOWN_VIEW_BASE_DIR",
+            getattr(
+                settings,
+                "BASE_DIR",
+                None)
+        )
+        dirs = [*get_app_template_dirs(
+            getattr(
+                settings,
+                "MARKDOWN_VIEW_LOADER_TEMPLATES_DIR",
+                DEFAULT_MARKDOWN_VIEW_LOADER_TEMPLATES_DIR
+            )
+        )]
+        if base_dir:
+            dirs.extend([base_dir])
+        return dirs
+
+    def get_template_sources(self, template_name):
+        """
+        Return an Origin object pointing to an absolute path in each directory
+        in template_dirs. For security reasons, if a path doesn't lie inside
+        one of the template_dirs it is excluded from the result set.
+        """
+        if template_name.endswith('.md'):
+            template_split = template_name.split("/")
+            template_split.reverse()
+            template_app_dir = template_split.pop()
+            template_split.reverse()
+            for template_dir in self.get_dirs():
+                if str(template_dir).endswith(template_app_dir):
+                    try:
+                        name = safe_join(template_dir, *template_split)
+                    except SuspiciousFileOperation:
+                        # The joined path was located outside of this template_dir
+                        # (it might be inside another one, so this isn't fatal).
+                        continue
+
+                    yield Origin(
+                        name=name,
+                        template_name=template_name,
+                        loader=self,
+                    )