Package: markdownup
MarkdownUpMarkdownUp 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 authorizationintegration with external authentication solutions through Keycloakdisplay of versioning information from Gitinteractive tree view of the served directories and Markdown filesbasic search functionalitythemeable withMustache templatessupport forMarkdown extensionsInstallationpip install markdownupUsagepython -m markdownup path/to/markdown/rootOrpython -m markdownup --start-config config.ymlAfter which the config.yml can be edited to suit your needs, and the MarkdownUp server launched with:python -m markdownup config.ymlConfigurationThe 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 controlMarkdownUp will look for a file with the name as configured ataccess.filenamein 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 authTheaccessYAML 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-2Authentication with KeycloakTheaccessYAML 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
    cookie:
      path: /
      max_age: 2592000Configuration keyDescriptionaccess.filenameName of file containing the groups and roles with access to the files parent directoryaccess.auth.typeType of auth provider, currently only "keycloak" is a valid optionaccess.auth.auth_urlThe root URL of the Keycloak instance to useaccess.auth.redirect_urlThe root URL of the MarkdownUp instance to redirect back to from Keycloakaccess.auth.realmThe Keycloak realm to useaccess.auth.client_idThe Keycloak client id to useaccess.auth.display_nameThe key in the Keycloak access token from which to take the display name of the authenticated useraccess.auth.rolesList of keys in the Keycloak access token from which to take the roles of the authenticated useraccess.auth.cookie.pathValue for the cookie Path attribute, defaults to '/'access.auth.cookie.max_ageValue for the cookie Max-Age attribute, defaults to 2592000Redis cacheMarkdownUp can use Redis for caching and storing auth sessions, configuration is as follows:cache:
  type: redis
  host: 127.0.0.1
  port: 6379
  db: 0Asset ETagMarkdownUp considers all non-Markdown files to be assets.
Addetag_assets: truein thecontentconfiguration section to enable asset etagging.
Asset files inside Git repositories will be tagged with the commit hash in which they were last modified.
Asset files outside of Git repositories will be tagged with a sha1 hash of their file last modified timestamp.
The etags are created during MarkdownUp start-up and file modifications are not monitored.
See theMDN ETag documentationfor more information on ETags.Render configExtra data can be made available to the HTML templates by adding arendersection in the config YAML. E.g.:render:
  example: value
  css:
  - /extra.cssThe default theme will include css files configured this way.Custom themesRunpython -m markdownup --start-theme theme-nameto get started with a new theme.
Add the path to the new theme in the config YAML attheme.
Modify the files in the theme directory to get the desired result.