markdoc /

Filename Size Date modified Message
doc
src
test
97 B
666 B
1.0 KB
114 B
2.3 KB
55 B
14.9 KB
107 B
2.3 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.

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


Quickstart
==========

Requirements
------------

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.

Installation
------------

    #!bash
    $ easy_install Markdoc

Making a Wiki
-------------

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

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/ref/layout.md` for more
information on the roles of various subdirectories.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.