Skip to content

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

Notifications You must be signed in to change notification settings

sielay/roadmarks

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Roadmarks

Join the chat at https://gitter.im/sielay/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?

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:

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  -->
<!-- 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

About

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

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published