Skip to main content

A tool for quick and easy Markdown project documentation.

Project description


A tool for quick and easy Markdown project documentation.

DocServe renders an adapted Markdown to provide:

  • Images, Video, YouTube links, CSV tables.
  • Code highlighting.
  • File download blocks.
  • Lists and Tables.
  • Document defined template selection.
  • Document Meta-data.
  • Auto-generated index sidebar.

DocServe can be used as a server to:

  • Output documents as insecure HTML on a localhost.
  • Output documents as PDF files via the HTML server.

DocServe can also:

  • Create a static set of HTML files that contain the documentation and related resources.

Basic usage with the default template:

python -m pip install docserve
mkdir docs
vim docs/ # then add some documentation

Basic usage with a custom template:

python -m pip install docserve
docserve --new # copies sample style and docs into working directory
docserve # run the server


We are requesting pull-requests for the following features:

  • Clearer heading CSS. H1 and H2 are confusing.
  • Test cases and CI steps
  • Reload on new files.
  • Windows EXE bundle for non-developer use.
  • Responsive design in default template.
  • Generate a large PDF file made from multiple documents (including table of contents with page numbers).
  • Gravatar print CSS / absent internet in the default theme.
  • Examples of Python extensions and SCSS extensions.
  • New template themes.

Getting Started

If you are running from the script:

python                       # start a server on localhost:5000

python --html                # freeze the server into a static site as a set of HTML files
                                         # this will exit with -1 if there was a problem parsing any file

python --port                # specify a port for docserve to accept requests on

python --pdf                 # generate a set of pdf files for each .md file - won't pull through
                                         # static resource files like with the --html command

python --new                 # copy default templates and sample docs into the working directory
                                         # and update the config too, only if they don't already exist

python --new-force           # copy default templates and sample docs into the working directory
                                         # and update the config too, this will overwrite any existing docs or
                                         # configs.

python --dirs                # display all the different directories docserve will use to generate
                                         # the documentation

python --find-orphans        # display unreferenced media assets in the documentation
python --find-broken-links   # display external broken links in the documentation

Writing Documentation

Documents are managed using meta-data at the top of each document. Documents can select which template they present themselves with. Documents must end in lowercase .md. For example:

Environment variables

  • DS_FLASK_DEBUG flag for enabling or disabling flask debug. Defaults to TRUE.
  • DS_FLASK_CHANGERELOAD flag for reloading the server when a file changes. Defaults to TRUE. If set, this forces DS_FLASK_DEBUG to TRUE.
  • DS_WKHTMLTOPDF the path to the WkHTMLtoPDF binary. Defaults to wkhtmltopdf_0.12.5.exe.
  • DS_DOCS_DIR the path to the directory that contains the documents. Defaults to docs.
  • DS_STYLE_DIR the path to the directory that contains the style templates and resources. Defaults to style.
  • DS_PROJECT_LOGO the path to the project logo PNG file. Defaults to logo.png in the current working directory.


Virtual Environment

python -m virtualenv env
env/Scripts/activate.bat # or the bash equivalent
pip install -r requirements.txt
python # with options
pip install flake8
flake8 --max-line-length=120


To enable PDF output, WkHTMLtoPDF must be set in the config DS_WKHTMLTOPDF or wkhtmltopdf_0.12.5.exe placed in working directory.

This build uses version 0.12.5. Get it from here:


The default theme is built using SCSS.

The SASSC compiler can be found here: Usage: sassc style/static/default.scss style/static/default.css

If you want it to auto-watch, run as admin from this directory, and remember to disable your browser cache:

pip install watchdog
watchmedo shell-command --patterns="*.scss" --recursive --command='echo "${watch_src_path}" && sassc style/static/default.scss style/static/default.css' .


We use flake8 --max-line-length=110 to static check the code.

Rebuilding the Package

python -m pip install --user --upgrade setuptools wheel twine
python sdist bdist_wheel

python -m twine upload dist/*

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

docserve-0.9.7.tar.gz (10.6 MB view hashes)

Uploaded source

Built Distribution

docserve-0.9.7-py3-none-any.whl (10.6 MB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page