<!--*-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. * 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 ========== Installation ------------ #!/bin/bash hg clone ssh://firstname.lastname@example.org/zacharyvoase/markdoc cd markdoc/ pip install -r REQUIREMENTS python setup.py install Making a Wiki ------------- #!/bin/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 ... Requirements ============ The minimum requirements to run the Markdoc utility are: * Python 2.4 or later * A UNIX (or at least UNIX-like) operating system * [pip](http://pip.openplans.org/) (you can get it via `easy_install -U pip`) * [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. `pip` is used to install all of the Python dependencies, which are individually listed in the `REQUIREMENTS` file alongside this README. If you don't want to use `pip`, you can manually go through this list and run `easy_install <package>` on each package name. 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/layout.md` for more information on the roles of various subdirectories.