modoc
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.