markdoc / README

Full commit

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

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



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]( -- 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/
    # ... 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/` for more
information on the roles of various subdirectories.