Rippledoc

[toc]

A static doc site generator with near-zero setup/config required. Default output looks very plain (you’re looking at it).

Rippledoc is a python script that uses Pandoc to generate easily-navigable HTML from a bunch of Markdown-formatted text files (it ripples down into subdirectories looking for .md files, generating corresponding html files from them).

The examples here show it being used to document a software project, but you could use it for any documentation or general writing project.

At a glance

Rippledoc turns this:

my-doc-proj/
    010-getting-started.md
    020-tutorial.md
    030-changes.md
    _copyright
    examples/
        010-ex-1.md
        020-ex-2.md
    index.md

into:

my-doc-proj/
    010-getting-started.md
    getting-started.html  # generated
    020-tutorial.md
    tutorial.html   # generated
    030-changes.md
    changes.md      # generated
    _copyright
    examples/
        010-ex-1.md
        ex-1.html   # generated
        020-ex-2.md
        ex-2.html   # generated
    index.md
    index.html      # generated
    styles.css      # generated
    toc.txt         # generated
    toc.html        # generated

Download

Download here. Save the file into your ~/bin and make it executable: chmod +x rippledoc.py.

You’ll need Pandoc and Python installed for this script to run.

Docs

To see the docs, run rippledoc.py -h.

Goals

Goals of this script:

• make it as easy as possible to create, write, and manage nice-looking, ordered, easily-navigable html docs
• low barrier as possible for others to contribute to your docs
• support mathematical notation in your docs (Pandoc lets you add LaTeX math)
• not tie you to any one particular doc processing tool (including this one). Your docs are just a pile of .md files.

OS Compatibility

The author has not given even a passing thought to running this program on any OS other than GNU/Linux.

Quick Usage

cd path/to/my-doc-project
touch index.md _copyright 010-getting-started.md
touch 020-tutorial.md 030-cheatsheet.md # whatev
# edit edit edit
rippledoc.py

then point your browser to file:///path/to/my-doc-project/index.html to see the results.

Renumbering Filenames

If your filename numbers get too bunched up, you can use a script like this one to renumber your filenames.

Customize the Styling

Edit the autogenerated styles.css file. You can always rm it and rippledoc will generate a fresh one for you.

Upload Your Site

To upload your docs to a server, you might use rsync:

rsync -urv --delete /path/to/your-doc-proj you@remote:public_html/your-doc-proj

That will put everything from inside the local your-doc-proj directory into the remote public_html/your-doc-project directory.

More Info

For more info, see the table of contents.

License

MIT