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!🙂

Published by

Bryan Villarin

Bryan is a Community Guardian at Automattic. He's also a photographer, card magician, and cat whisperer. (Thanks to my friend and colleague Steve Blythe for the sweet photo!)

Talk to me, Goose

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s