Rippledoc
← prev | next →     Top-level ToC     /more-info.html     (printable version)

1 What it expects

Rippledoc has a few rules:

  • All doc files which you’d like rippledoc to process must be Markdown-formatted (see Pandoc’s Markdown) and their filenames must end in “.md”. Rippledoc only cares about filenames ending in “.md”.

  • You must have at least an index.md file plus one other .md file.

  • Your doc files must begin with a header block supplying a title:

    % Title for this Doc

    You can also add additional lines to that block for author and date (see Title Block).

  • It requires that you have a _copyright file in your doc dir; this is how Rippledoc knows it’s at the top-level of your docs (in case you were to accidentally run it in a subdirectory therein). Rippledoc will place the html content of _copyright as-is into the footer of every html file it generates. The _copyright file will usually contain something like: Your Name, 2016.

Further, Rippledoc:

  • is happy to process nested subdirectories of .md files

  • gleefully ignores directories containing no .md files (for example, you might have just a subdirectory of images)

2 What it does

Rippledoc generates cross-linked html files from your markdown-formatted doc files. It also generates:

  • easily-printable html versions
  • top-level styles.css and styles-printable.css files (which you can feel free to customize)
  • toc.conf files in the top-level and any subdirs. Likewise with toc.md files.

A given generated html file resides in the same directory as its source .md file.

To rearrange the order in which docs are listed in a given directory’s ToC, edit that dir’s autogenerated toc.conf file and re-run rippledoc.sh.

The index.md file is special, and it’s required. It serves as the “front page” of your documentation. Also, its title (in its “title block”) should be the name of your project — it will be shown in the header of every generated page.

As a simple template, you might start each of your docs looking something like this:

% Title Goes Here
% Author Name
% 2016-10

Some text.

An H1 Heading
=============

Some text.

An H2 Heading
-------------

etc.

The title after the first “%” is what will appear in the ToC (except for index.md, the title of which will be used as the name of your documentation project as a whole).

For more help writing Pandoc’s Markdown, see the Quick Markdown Example.

Once you’ve got some docs written, you might rsync/ftp/scp your docs dir to the web to publish them.