Tag: MkDocs

Write The Docs EU — Tom Christie — Designing MkDocs

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

MkDocs is used to create project documentation with Markdown.

Background:

  • Needs documentation for open source projects, such as the Django REST framework.
  • Documentation is the design for the product.
  • Built a custom–script to redo the Django REST framework — which was hard–wired to that specific project — and MkDocs was born!

(As an aside, Tom is a fan of the simple aesthetic of the Mou editor, which allows him to visualize the document rather than using a regular editor.

Requires Python and pip, install took about thirty seconds. Has a single configuration file (YAML). Will automatically reload the content after editing any of the source, configuration, or theme files.

  • Use relative links.
  • Documentation will be hyperlinked in the editor.
  • Use references to target a page or title anywhere in the documentation.
  • Name the linked title explicitly (if needed).

Some configuration options:

  • site_name (required)
  • site_url
  • site_description
  • repo_url (like GitHub)
  • copyright
  • google_analytics

Custom themes are available (see the Bootswatch project.)

mkdocs build builds the site to the “site” directory for static site deployment, such as GitHub pages or Amazon S3. (MkDocs already includes GitHub page support.)

Focus of MkDocs:

  • No programmatic API.
  • No embedded documentation.
  • Not a semantic markup tool.
  • Markdown only.

Lastly, the 1.0 release is in progress, and he needs help, so contact him if you’re interested. Very slick! 🙂