{"id":16183742,"url":"https://github.com/binokkio/markdownup","last_synced_at":"2026-01-20T04:32:34.145Z","repository":{"id":55618528,"uuid":"314675854","full_name":"binokkio/markdownup","owner":"binokkio","description":"Markdown server.","archived":false,"fork":false,"pushed_at":"2022-04-03T23:03:56.000Z","size":175,"stargazers_count":1,"open_issues_count":15,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-13T20:36:03.639Z","etag":null,"topics":["markdown","server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binokkio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-20T21:38:54.000Z","updated_at":"2022-04-03T23:03:59.000Z","dependencies_parsed_at":"2022-08-15T04:40:14.868Z","dependency_job_id":null,"html_url":"https://github.com/binokkio/markdownup","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binokkio%2Fmarkdownup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binokkio%2Fmarkdownup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binokkio%2Fmarkdownup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binokkio%2Fmarkdownup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binokkio","download_url":"https://codeload.github.com/binokkio/markdownup/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247713056,"owners_count":20983680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","server"],"created_at":"2024-10-10T07:06:31.401Z","updated_at":"2026-01-20T04:32:34.133Z","avatar_url":"https://github.com/binokkio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MarkdownUp\n\nMarkdownUp is a Markdown server that turns a set of Markdown documents into a website.\nThe main features are:\n\n- per directory group and/or role based authorization\n- integration with external authentication solutions through Keycloak\n- display of versioning information from Git\n- interactive tree view of the served directories and Markdown files\n- basic search functionality\n- themeable with [Mustache templates](https://mustache.github.io/)\n- support for [Markdown extensions](https://python-markdown.github.io/extensions/)\n\n\n## Installation\n\n`pip install markdownup`\n\n\n## Usage\n\n`python -m markdownup path/to/markdown/root`\n\nOr\n\n`python -m markdownup --start-config config.yml`\n\nAfter which the config.yml can be edited to suit your needs, and the MarkdownUp server launched with:\n\n`python -m markdownup config.yml`\n\n\n## Configuration\n\nThe configuration file created by the --start-config flag contains the default settings.\nThe configuration of features that are not configured by default is described here.\n\n\n### Access control\n\nMarkdownUp will look for a file with the name as configured at `access.filename` in each content directory.\nThis file should contain the roles and groups with access to the parent directory of the access file.\nThe structure of this file is simply 1 role or group per line.\nMarkdownUp will respond with a 404 Not Found for files which the authenticated user does not have access to.\nThe 404 is given instead of a 401/403 to prevent exposing that content exists for the given URL.\n\nAuthentication is not configured by default meaning that any directory with a non-empty access file will be inaccessible.\nThe following sections describe different authentication configurations. \n\n\n#### Authentication with HTTP basic auth\n\nThe `access` YAML structure can be extended as follows to get started with HTTP basic auth.\n\n```\naccess:\n  filename: .upaccess\n  auth:\n    type: basic-auth\n    realm: actual-realm-name\n    users:\n      actual-user-name:\n        password: plain-text-password\n        roles:\n        - actual-role-1\n        - actual-role-2\n```\n\n\n#### Authentication with Keycloak\n\nThe `access` YAML structure can be extended as follows to get started with Keycloak auth.\n\n```\naccess:\n  filename: .upaccess\n  auth:\n    type: keycloak\n    auth_url: \n    redirect_url: \n    realm: \n    client_id: \n    display_name: preferred_username\n    roles:\n    - realm_access.roles\n    cookie:\n      path: /\n      max_age: 2592000\n```\n\n|Configuration key         |Description                                                                                       |\n|--------------------------|--------------------------------------------------------------------------------------------------|\n|access.filename           |Name of file containing the groups and roles with access to the files parent directory            |\n|access.auth.type          |Type of auth provider, currently only \"keycloak\" is a valid option                                |\n|access.auth.auth_url      |The root URL of the Keycloak instance to use                                                      |\n|access.auth.redirect_url  |The root URL of the MarkdownUp instance to redirect back to from Keycloak                         |\n|access.auth.realm         |The Keycloak realm to use                                                                         |\n|access.auth.client_id     |The Keycloak client id to use                                                                     |\n|access.auth.display_name  |The key in the Keycloak access token from which to take the display name of the authenticated user|\n|access.auth.roles         |List of keys in the Keycloak access token from which to take the roles of the authenticated user  |\n|access.auth.cookie.path   |Value for the cookie Path attribute, defaults to '/'                                              |\n|access.auth.cookie.max_age|Value for the cookie Max-Age attribute, defaults to 2592000                                       |\n\n\n### Redis cache\n\nMarkdownUp can use Redis for caching and storing auth sessions, configuration is as follows:\n\n```\ncache:\n  type: redis\n  host: 127.0.0.1\n  port: 6379\n  db: 0\n```\n\n\n### Asset ETag\n\nMarkdownUp considers all non-Markdown files to be assets.\nAdd `etag_assets: true` in the `content` configuration section to enable asset etagging.\nAsset files inside Git repositories will be tagged with the commit hash in which they were last modified.\nAsset files outside of Git repositories will be tagged with a sha1 hash of their file last modified timestamp.\nThe etags are created during MarkdownUp start-up and file modifications are not monitored.\nSee the [MDN ETag documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) for more information on ETags.\n\n\n### Render config\n\nExtra data can be made available to the HTML templates by adding a `render` section in the config YAML. E.g.:\n\n```\nrender:\n  example: value\n  css:\n  - /extra.css\n```\n\nThe default theme will include css files configured this way.\n\n\n## Custom themes\n\nRun `python -m markdownup --start-theme theme-name` to get started with a new theme.\nAdd the path to the new theme in the config YAML at `theme`.\nModify the files in the theme directory to get the desired result.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinokkio%2Fmarkdownup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinokkio%2Fmarkdownup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinokkio%2Fmarkdownup/lists"}