Rippledoc
←prev | next→

Rippledoc

John Gabriele

2016-10

A particularly easy-to-use doc processing tool.

Rippledoc is a command-line program which generates easily-navigable html from a bunch of Markdown-formatted text files. That is, it turns:

doc/
    index.md
    changes.md
    tutorial.md
    mumble/
        frob.md

into something like:

doc/
    index.md
    index.html
    changes.md
    changes.html
    tutorial.md
    tutorial.html
    mumble/
        frob.md
        frob.html

Rippledoc requires nearly zero configuration. You just run it in a directory containing Markdown-formatted text files (see more info for the few rules you’ve got to follow) and it does the rest.

The main benefits of using Rippledoc rather than just having users view your docs directly on a site like GitLab or GitHub are:

  • the docs resulting from Rippledoc are ordered (you can customize the order in your (autogenerated) toc.conf files), and
  • they’re easily navigable. The side nav pane contains a full table of contents, and you can also click “next” and “prev” links to be taken you through every doc/chapter in your docs.
  • you can customize the styling if you like.

Under the hood, Rippledoc uses Pandoc to do the markdown ➞ html conversion.

You can find the source located at https://gitlab.com/uvtc/rippledoc.

OS Compatibility

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

Quick Usage

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

Of course, this site you’re reading now was generated using Rippledoc.

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

That will put the local doc directory into the remote your-proj directory.

License

Copyright 2014–2018 John Gabriele

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.