Metadata-Version: 1.1
Name: django-markdown-view
Version: 0.0.5
Summary: Serve .md pages as Django views.
Home-page: http://github.com/rgs258/django-markdown-view
Author: Ryan J. Sullivan
Author-email: ryanj@ryanjsullivan.com
License: BSD
Description: 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
        
Keywords: django,markdown,markdown view,md
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django :: 2
Classifier: Framework :: Django :: 3
Classifier: Framework :: Django :: 4
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
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.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
