CONVERTINATOR

— concatenates & converts. A tool for writing ebooks in Markdown.

Specifically, Convertinator:

1. merges Markdown files across a number of (nested) directories
2. converts the resultant single Markdown file into nicely-formatted HTML and PDF versions.

Project structure

Take a look at the following content hierarchy:

├── 1-file.mdown
├── 2-file-hello-world.mdown
├── 3-dir
│   ├── 1-file.mdown
│   └── 4-dir
│       ├── 1-file.mdown
│       └── 2-file.mdown
├── 4-file.mdown
├── README.mdown
├── TODO.txt

As you can see, Convertinator uses number prefixes for files and directories in order to establish a content hierarchy:

1. x-filename.mdown signals "content" to Convertinator. These files will be merged and converted in the order of listing.
2. x-dirname signals a directory containing Markdown files, so will be traversed and merged based on the rule above.

Any other (non-prefixed) content will be ignored.

The Why

Convertinator is designed to bridge the gap between one's mental model of the content, and how that content evolves in the process of writing. It is inspired by the Zettelkasten method and its derivatives.

A non-trivial piece of content (an ebook, etc) appears linear and coherent in its final form. The workflow leading up to that finished product, however, can be very non-linear. Directories and files are moved around, renamed, deleted, added, branched, and merged.

Additionally, one likely also maintains a number of supporting files that aren't meant as part of the final product but are essential for one's workflow — research notes, references, etc.

In order to support this kind of workflow, Convertinator uses one universal convention for numbering files and folders, and is otherwise completely flexible as to how you choose to organize your content.

Installing

Convertinator uses Ruby and Web Standards.

1. Install Prince XML for PDF generation
2. Download Convertinator; navigate to the /build directory
3. Run $ ruby driver.rb at the command line to generate an ebook
4. Replace the test files in the top directory with your own content
5. Edit driver.rb to mirror your project structure.

Usage

Call these methods from your driver.rb.

Convert a specified file:

Convertinator::convert_file('3-dir/1-file.mdown')

Convert a specified directory:

Convertinator::convert_dir('3-dir/4-dir')

Convert the entire project, staring at root directory:

Convertinator::convert_project

MIT License

Copyright (c) 2021 Vahagn Hay

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.