<!--*-markdown-*--> # Markdoc README Markdoc is a lightweight Markdown-based wiki system. It’s geared towards managing technical documentation, but can be used for a range of purposes. It has a few notable selling points: * Wikis are made up completely of plaintext files, so you can easily put them under version control. * Wikis compile into standalone HTML directories, which can be distributed as tarballs or served by a HTTP server. * Set up Google Analytics tracking in one line of configuration. * Create barebones wikis that just look like folders containing Markdown-formatted text files. * You can optionally include static media which will be compiled into the HTML directory alongside all your rendered pages. * Markdoc comes with a fully-functional pure-Python WSGI application and HTTP server for serving up compiled wikis. * You can render your wiki with a variety of Markdown extensions, such as Pygments-based code highlighting, extended syntax for definition lists, TOC generation, et cetera. * You can completely customize how your wiki is rendered by editing the Jinja2 templates used to convert rendered Markdown into full HTML documents. Quickstart ========== Requirements ------------ The minimum requirements to run the Markdoc utility are: * Python 2.4 or later (2.5+ highly recommended) * A UNIX (or at least POSIX-compliant) operating system * [rsync](http://www.samba.org/rsync/) -- installed out of the box with most modern OSes, including Mac OS X and Ubuntu. In the future Markdoc may include a pure-Python implementation. Installation ------------ #!bash $ easy_install Markdoc Making a Wiki ------------- #!bash $ markdoc init my-wiki $ cd my-wiki/ $ vim wiki/somefile.md # ... write some documentation ... $ markdoc build $ markdoc serve # .. open http://localhost:8008/ in a browser ... Layout ====== Markdoc wikis have the following default layout: WIKI_ROOT/ |-- .html/ |-- .templates/ |-- .tmp/ |-- static/ |-- wiki/ `-- markdoc.yaml The `.html/` and `.tmp/` directories should be excluded from any VCS, since they contain temporary files. Consult the layout documentation in `doc/wiki/ref/layout.md` for more information on the roles of various subdirectories.