README

Overview

README is a very simple HTML documentation generator whose goal is to be as pain-free as possible to put in place, maintain and navigate.

When relying on README, all you need to do is:

  1. To write your documentation files in the same Markdown format you're used to (the full ubiquitous CommonMark syntax is handled, with no added special syntax).

    Note that links, including those between Markdown files, are handled, as well as things like embedded image, video and audio resources.

  2. Put them in directories following a file tree architecture reflecting your wanted HTML documentation (categories in different directories, page groups as pages in the same subdirectory).

  3. Add .docConfig.json files in the resulting directories and sub-directories to set-up configuration and indicate the pages' ordering.

Then you can run README on it to generate static HTML files which can directly be served as your documentation. That's it!

Installation

README is installable through your favorite node package manager (npm / yarn / pnpm) by installing the @canalplus/readme.doc package:

# through npm
npm install @canalplus/readme.doc --save-dev

# or through yarn
yarn add @canalplus/readme.doc --dev

You should then be able to run it by referencing through its readme.doc name in a package.json script or through npx.

To ensure the readme.doc is accessible, you can try running it with the -v flag and see if the right version is outputed:

# Outputs README version
npx --no -- readme.doc -v

# Note: The `--no --` part in that npx command is there to ensure that README
# has been installed locally with success.
# If you see the expected version outputed, it is correctly installed and
# it is equivalent to just calling `npx readme.doc -v`.

Usage

Then producing your HTML documentation pages is straightforward.

Before going deep into all steps one by one, here is a brief description for each one of them:

  1. Documentation Files: Write documentation files in Markdown in a file tree architecture respecting the same structure you want in your HTML documentation (e.g. Getting Started pages in a given directory, API pages in another etc.).

  2. Configuration: Add a .docConfig.json file, setting the documentation's global configuration, in your documentation's root directory

  3. Page Listing: Add .docConfig.json files in each sub-directories to set the order of documentation pages as well as their name.

  4. Run: Run the readme.doc command.

  5. Serve: Serve the corresponding generated HTML pages.

README

Page List