Mara Markdown Documentation

Display markdown documentation in mara UI

This package displays configured documentation in markdown format in the UI:

• Convert markdown to html via markdown-it
• Supports a folder structure (single level) in the menu
• Supports mermaid diagrams
• Serves referenced images (.png, .jpg, .gif) in markdown and .txt files (for example config, etc) if these are in the same folder as the markdown file

 

Screenshot

 

Installation

To use the library directly, use pip:

python3 -m pip install mara-markdown-docs

# or directly from git
python3 -m pip install git+https://github.com/mara/mara-markdown-docs.git

 

Configuration

Assuming you configure via app/local_setup.py:

"""Configures the docs functionality"""

import pathlib
from mara_app.monkey_patch import patch

import mara_markdown_docs.config

@patch(mara_markdown_docs.config.documentation)
def documentation() -> dict:
    """Dict with name -> path to markdown file.

    If name contains a single '/' it will be shown in a submenu. Multiple '/' are not allowed.
    The insertion order is mostly preserved (folders are grouped in the menu)."""

    repo_root_dir = pathlib.Path(__file__).parent.parent

    # Cases matter in path!
    docs = {
        'Pipeline/Marketing': repo_root_dir / 'app/pipelines/marketing/README.md',
        'Developer/Setup': repo_root_dir / 'README.md',
        'Developer/Code Conventions': repo_root_dir / 'code_conventions.md',
    }

    return docs