Roadmarks

Extensive tool to create and maintain Markdown documentation tables of contents and navigation

This project was originally called tocmd, but because large use of that name I decided to rename it.

This documentation (including nested sits in built with Roadmarks)

Table of contents

Got to parent | Got to top

• Why?
• Features
• Installation
• Usage
  • Markup
  • Rules
• Credits
• Licence

---

• doc
  • Instalation
  • README.md
    • content
    • Ignore
    • media
    • paging
    • snippets
    • Tree
  • Roadmarks

Why?

Markdown is already standard in the industry. There are number of various tools (mostly commercial) to give extra powers to MD. This simple liblary is meant to allow you add maintainless, hasslefree tables of contents and other indexing widgets to your project. Idea is that you can connect this lib to your build or versioning process to keep documentation navigation always up to date.

There are similar projects (listed below), but so far none of them address file tree:

• https://www.npmjs.com/package/marked-toc
• https://www.npmjs.com/package/md2toc
• https://www.npmjs.com/package/markdown-toc
• https://www.npmjs.com/package/md-toc

If you find features that would make this package better, or you know better open package, please let me know.

Features

• 100% Markdown and HTML compatible
• List structure of the Markdown file
• List structure of folders
• Ignores folders containing .git and .hg
• Appreciate .gitignore
• Gulp and Grunt integration
• Config files
• Source inlinking and quoting

Installation

sudo npm install roadmarks -g

Usage

Start in current dir

roadmarks 

Start in other dir

roadmarks -d /path/to/my/project

Process one file

roadmarks -f /path/to/my/file.MD

Markup

By default comment block load

<!-- RM -->
<!-- /RM -->
<!-- RM(max-depth:3)-->
<!-- /RM -->
<!-- RM(tree:/) -->
<!-- /RM -->

You can use ignore blocks

<!-- RM-IGNORE -->
<!-- /RM-IGNORE -->

Now you can create indexes

<!-- RM(images,tree:*,nocontent,noparent,notop) -->
<!-- /RM  -->

• doc
  • Instalation
  • README.md
    • content
    • Ignore
    • media
      • Image: Cookies
    • paging
    • snippets
    • Tree
  • Roadmarks

<!-- RM(definitions,images,tree:*,nocontent,noparent,notop,table) -->
<!-- /RM  -->

Name	Page
indexable	paging, Tree
indexed	paging

<!-- RM(images,tree:*,nocontent,noparent,notop,table) -->
<!-- /RM -->

Name	Page
Ignore	ignore.mD
Instalation	installation.md
README.md	markup
Roadmarks	INDEX.MD
Tree	tree.MD
content	content.MD
doc	doc
media	media.md
paging	paging.md
snippets	snippets.md

Rules

I tried to put rules as close to Markdown specifciation and way how GitHub works with Markdown.

• File is described in lists by level one heading. If absent, file name is used.
• Files are listed in alphabetical order (of file, not heading).
• Tables of content combining internal headers and files, list internal headers first
• README.md is being used as index file of directory (INDEX seems to be natural, but is not used by GitHub).
• README.md is alias to folder - so all sibling files in the same directory are understood as it's children.
• Multiple level one headings are being ignored.

Credits

Author Lukasz Sielski. Hugely improved thanks to comments from Patrick Polloni. Uses parser from amazing Marked project.

Licence

MIT of course