Overview

Tanagra is a documentation pipeline tool for building a template for a markdown-based book, generating a directory and file structure based on an outline, and then converting markdown files into HTML, PDF, and EPUB books using Pandoc.

Markdown Book Pipelines Workflow

1. Decide on a topic for your book. Tangara cannot help you with this step. :)
2. Create a book template using Tanagra. This will generate a book content directory, an outline.md file,
3. Populate your book’s outline.md file. Using markdown, populate the outline.md file generated in step 1 above. See the outline structure below.
4. Convert your book’s outline.md file into a book directory hierarchy and markdown files. This step will create a hierarchy of directories (per part and chapter) and markdown files (per chapter) with sections and subsections stubbed out in the markdown files. Each part will also have its own directory to store media (images, etc.) for local reference. These will be included in the final compilation later.
5. Write your book in the markdown files. Using the chapter markdown files, populate your book within the files and headings populated in the previous step. Also, you can add images or other media files to each book part’s media directory.
6. Generate the final output file(s) for your book. Once you have completed writing your book in the markdown files, you can generate a PDF, EPUB, or HTML version of your book.
7. Publish your book. Tanagra cannot help you with this step either. Upload, email, or do whatever you need to do with your generated book to deliver it to your audience.

FAQ

Why should I write my book in markdown?

By writing in Markdown files, you can easily use version control for your files and you can still use text markup (headings, bold, italic, code, etc.).

Why would I want to write the outline first?

For non-fiction and technical books, having a thorough outline can help keep your writing focused on your topic and ensure that you cover the necessary subtopics.

Why would I want to use separate directories and files for my chapters?

Breaking up your book into small chunks can help keep you focused on chunks that you can tackle without being overwhelmed.

Who asked for this project? It seems like a duplicate of {some_project}.

No one asked for this and it might be similar to something else out there, but it seemed like a fun idea at the time. :)

Why use Python for the scripts?

Python is a cool language and the founder of the Tanagra project was interested in using Python on a project at the time of inception.

---