Skip to content
modoc is the Master Of Document Organization and Compilation
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd
examples
pkg
vendor/github.com
.gitignore
.travis.yml
Gopkg.lock
Gopkg.toml
LICENSE
Makefile
README.md
main.go

README.md

modoc

GoDoc  Build Status  Go Report Card  Coverage Status

modoc is the Master Of Document Organization and Compilation (and definitely not just a play on the name MODOK).

What does that mean? It means modoc allows you to compile a large Markdown project from an organized folder structure. In fact, this documentation you're currently reading was compiled by modoc from the examples/readme/ directory:

.
├── 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

Table of Contents

Features

  • organize your projects into smaller, digestable sections
  • nest sections and subsections as deep as you like
  • generate a table of contents for your document

Usage

Install

To install modoc from source you'll need a working Go environment:

$ go get -u github.com/KyleBanks/modoc

Command Line

First up, definitely check modoc usage like so:

$ modoc --help

init

If you're starting a new project, try the init command:

$ modoc init [--path ./optional/path]

This will generate a sample project in the current directory (or you can provide an optional --path) to help you get started right away. You can also reference the examples directory if you want to create your own project manually.

compile

With a project initialized, you can compile it into a single Markdown file:

$ modoc compile [--source ./optional/path] [--output ./OPTIONAL.md]

This will compile the current directory (or optional --source) into a single file called COMPILED.md - of course, you can name it whatever you like using the --output flag.

By default the file will contain:

  • Header: the root TITLE followed by the root README.md
  • ToC: the table of contents
  • Body: the titles and contents of each section, subsection, etc.

You can disable generating any of these components using the following flags:

$ modoc compile --header false --toc false --body false

Project Structure

Each directory represents a section or chapter of the document, with child directories being subsections, and so on.

  • TITLE (plaintext, required): contains the section title
  • README.md (markdown, optional): contains the section content

modoc traverses your section hierarchy in alphabetical order, so it's recommended that you prefix your folders with an incrementing counter at each level to preserve ordering, like so:

examples/basic/
├── 1-introduction
│   ├── 1-subsection-a
│   ├── 2-subsection-b
│   ├── 3-subsection-c
├── 2-chapter-one
│   ├── 1-subsection-a
│   ├── 2-subsection-b
│   ├── 3-subsection-c
├── 3-chapter-two
│   ├── 1-subsection-a
│   ├── 2-subsection-b
│   ├── 3-subsection-c

Examples

You can generate this README like so:

$ modoc compile --source ./examples/readme --output ./README.md

Compiling the basic example will produce the following:

$ modoc compile --source ./examples/basic --output ./examples/BASIC.md
$ cat ./examples/BASIC.md
# A Modoc Tale

This is the introduction to the document, found below the title and before the Table of Contents.

## Table of Contents

- [Introduction](#introduction)
   - [Subsection A](#subsection-a)
   - [Subsection B](#subsection-b)
   - [Subsection C](#subsection-c)
- [Chapter One](#chapter-one)
   - [Subsection A](#subsection-a)
   - [Subsection B](#subsection-b)
   - [Subsection C](#subsection-c)
- [Chapter Two](#chapter-two)
   - [Subsection A](#subsection-a)
   - [Subsection B](#subsection-b)
   - [Subsection C](#subsection-c)

## Introduction

This is the contents of the Introduction chapter.

### Subsection A

This is Introduction, Subsection A.

### Subsection B

This is Introduction, Subsection B.

### Subsection C

This is Introduction, Subsection C.

## Chapter One

This is the contents of Chapter One.

### Subsection A

This is Chapter 1, Subsection A.

### Subsection B

This is Chapter 1, Subsection B.

### Subsection C

This is Chapter 1, Subsection C.

## Chapter Two

This is the contents of Chapter Two.

### Subsection A

This is Chapter 2, Subsection A.

### Subsection B

This is Chapter 2, Subsection B.

### Subsection C

This is Chapter 2, Subsection C.

Authors

modoc was developed by:

Contributing

If you'd like to contribute to modoc then take a look at the issues list. If you have an idea/suggestion/bug/question/etc. then feel free to create an issue to discuss it - you can also submit a pull request but it's probably better to chat before you spend time making big changes.

Also, feel free to add your name and twitter to the authors list above if you'd like a little recognition for your effort!

License

modoc is made available under the MIT License.

You can’t perform that action at this time.