Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A lightweight Markdown-based wiki system.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
doc
src/markdoc
test
.hgignore
.hgtags
LICENSE
MANIFEST.in
README
REQUIREMENTS
distribute_setup.py
nose.cfg
setup.py

README

<!--*-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.
Something went wrong with that request. Please try again.