I thoroughly enjoy writing and generally when I write, I do so using Markdown for formatting. Markdown is great because it can be easily exported to HTML, a PDF, Word Documents, etc. There’s great tooling around Markdown, abd it’s a well supported markup language.

My only problem is when I’m writing larger documents, such as if you were to write book, you quickly end up with a massive, unwieldly document. A few problems that come to mind:

1. If you want to go back and reorganize sections or chapters of your document it’s usually pretty difficult as you have to recreate your headings as the heading levels won’t match up.
2. How do you go about managing a table of contents? You could manually manage it, but updating the links and text, and maintaining order and depth of each heading is a pain.

What I wanted was a small, lightweight framework that can be used to organize a larger document into smaller, more manageable chunks, but still output to a single Markdown file complete with table of contents. That’s where modoc comes in.

With modoc you simply create a directory structure where each directory has a TITLE and README.md file, and modoc does all the rest. Here’s what the directory structure for the README document of the opensource modoc repository looks like:

$ tree examples/readme/
examples/readme/
├── 1-features
│   ├── README.md
│   └── TITLE
├── 2-usage
│   ├── 1-install
│   │   ├── README.md
│   │   └── TITLE
│   ├── 2-command-line
│   │   ├── 1-init
│   │   │   ├── README.md
│   │   │   └── TITLE
│   │   ├── 2-compile
│   │   │   ├── README.md
│   │   │   └── TITLE
│   │   ├── README.md
│   │   └── TITLE
│   ├── 3-project-structure
│   │   ├── README.md
│   │   └── TITLE
│   ├── 4-examples
│   │   ├── README.md
│   │   └── TITLE
│   └── TITLE
├── 3-authors
│   ├── 1-contributing
│   │   ├── README.md
│   │   └── TITLE
│   ├── README.md
│   └── TITLE
├── 4-license
│   ├── README.md
│   └── TITLE
├── README.md
└── TITLE

11 directories, 23 files

Directories are loaded into modoc recursively and in alphabetical order, and the titles, sections, and table of contents are created from there. In the example above, you end up with a document that looks like so:

# Features
...
# Usage
...
## Install
...
## Command-Line
...
### init
...
### compile
...

(Take a look at the full document at github.com/KyleBanks/modoc.)

modoc also generates the table of contents at the top of the document, complete with links to each section, so you don’t have to worry about it:

## Table of Contents

- [Features](#features)
- [Usage](#usage)
   - [Install](#install)
   - [Command Line](#command-line)
      - [init](#init)
      - [compile](#compile)
   - [Project Structure](#project-structure)
   - [Examples](#examples)
- [Authors](#authors)
   - [Contributing](#contributing)
- [License](#license)

This makes it really easy to structure and organize larger writing projects without having a full-blown framework to get in your way. Check it out on GitHub at github.com/KyleBanks/modoc and try it for yourself. If you have any ideas or run into trouble, don’t hesitate to create an issue!