Metadata-Version: 2.1
Name: markdownup
Version: 0.0.42
Summary: Markdown server
Home-page: https://github.com/binokkio/markdownup
Author: Binokkio
Author-email: binokkio@b.nana.technology
License: LGPLv3+
Description: # MarkdownUp
        
        MarkdownUp is a Markdown server that turns a set of Markdown documents into a website.
        The main features are:
        
        - per directory group and/or role based authorization
        - integration with external authentication solutions through Keycloak
        - display of versioning information from Git
        - interactive tree view of the served directories and Markdown files
        - basic search functionality
        - themeable with [Mustache templates](https://mustache.github.io/)
        - support for [Markdown extensions](https://python-markdown.github.io/extensions/)
        
        
        ## Installation
        
        `pip install markdownup`
        
        
        ## Usage
        
        `python -m markdownup path/to/markdown/root`
        
        Or
        
        `python -m markdownup --start-config config.yml`
        
        After which the config.yml can be edited to suit your needs and the MarkdownUp server launched with:
        
        `python -m markdownup config.yml`
        
        
        ## Configuration
        
        The configuration file created by the --start-config flag contains the default settings.
        The configuration of features that are not configured by default is described here.
        
        
        ### Access control
        
        MarkdownUp will look for a file with the name as configured at `access.filename` in each content directory.
        This file should contain the roles and groups with access to the parent directory of the access file.
        The structure of this file is simply 1 role or group per line.
        MarkdownUp will respond with a 404 Not Found for files which the authenticated user does not have access to.
        The 404 is given instead of a 401/403 to prevent exposing that content exists for the given URL.
        
        Authentication is not configured by default meaning that any directory with a non-empty access file will be inaccessible.
        The following sections describe different authentication configurations. 
        
        
        #### Authentication with HTTP basic auth
        
        The `access` YAML structure can be extended as follows to get started with HTTP basic auth.
        
        ```
        access:
          filename: .upaccess
          auth:
            type: basic-auth
            realm: actual-realm-name
            users:
              actual-user-name:
                password: plain-text-password
                roles:
                - actual-role-1
                - actual-role-2
        ```
        
        
        #### Authentication with Keycloak
        
        The `access` YAML structure can be extended as follows to get started with Keycloak auth.
        
        ```
        access:
          filename: .upaccess
          auth:
            type: keycloak
            auth_url: 
            redirect_url: 
            realm: 
            client_id: 
            display_name: preferred_username
            roles:
            - realm_access.roles
        ```
        
        |Configuration key       |Description                                                                                       |
        |------------------------|--------------------------------------------------------------------------------------------------|
        |access.filename         |Name of file containing the groups and roles with access to the files parent directory            |
        |access.auth.type        |Type of auth provider, currently only "keycloak" is a valid option                                |
        |access.auth.auth_url    |The root URL of the Keycloak instance to use                                                      |
        |access.auth.redirect_url|The root URL of the MarkdownUp instance to redirect back to from Keycloak                         |
        |access.auth.realm       |The Keycloak realm to use                                                                         |
        |access.auth.client_id   |The Keycloak client id to use                                                                     |
        |access.auth.display_name|The key in the Keycloak access token from which to take the display name of the authenticated user|
        |access.auth.roles       |List of keys in the Keycloak access token from which to take the roles of the authenticated user  |
        
        
        ## Custom themes
        
        Run `python -m markdownup --start-theme theme-name` to get started with a new theme.
        Add the path to the new theme in the config YAML at `theme`.
        Modify the files in the theme directory to get the desired result.
        
Keywords: markdown,server
Platform: UNKNOWN
Description-Content-Type: text/markdown
