Source

markdoc /

Filename Size Date modified Message
doc
src/markdoc
test
97 B
140 B
1.0 KB
65 B
2.5 KB
55 B
14.9 KB
107 B
2.2 KB

<!---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://hg@bitbucket.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.