1. Adam Lindsay
  2. markdoc


markdoc / README


# Markdoc README

Markdoc is a lightweight Markdown-based wiki system. Its 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.



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.


    $ easy_install Markdoc

Making a Wiki

    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 ...


Markdoc wikis have the following default layout:

    |-- .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.