Rippledoc

[toc]

A static doc site generator with near-zero setup/config required. Default output looks ok (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.

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.

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

Copyright (c) 2024 John Gabriele

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.