django-markdown-view 0.0.5
Serve .md pages as Django views.
License: BSD
Keywords: django,markdown,markdown view,md

Django Markdown View
====================

.. image:: https://travis-ci.org/rgs258/django-markdown-view.svg?branch=master
    :target: https://travis-ci.org/rgs258/django-markdown-view

.. 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

.. note::
    * This package needs tests, and to have Travis and Coveralls properly configured.

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.

* `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.

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.

* `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.


Implementation
--------------

At a high level, `MarkdownView` will:

#. Use a template loader to locate `.md` given as `file_name`

#. Render as a template, the contents of the `.md` file 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>`_

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 `Travis`_ coupled with `Coveralls`_ as continious integration tools.

.. _`GitHub issues`: https://github.com/rgs258/django-markdown-view/issues
.. _`pull requests`: https://github.com/rgs258/django-markdown-view/pulls
.. _Travis: https://travis-ci.org/github/rgs258/django-markdown-view
.. _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.6, 3.7, 3.8, 3.9, 3.10
* Django: 2.2, 3.2, 4.0