% More Info % John Gabriele 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](http://johnmacfarlane.net/pandoc/README.html#pandocs-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](http://johnmacfarlane.net/pandoc/README.html#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) # 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](http://johnmacfarlane.net/pandoc/README.html#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](quick-markdown-example.html). Once you've got some docs written, you might rsync/ftp/scp your docs dir to the web to publish them.