2 How to format your project with book and research notes in separate root level folders

bertput edited this page 2021-12-17 20:24:05 -06:00

Table of Contents

• Acknowledgements
• Introduction
• The Problem
• The Solution

Acknowledgements

Before I get started, I want to thank Alan Dunaway and everyone else in the GITHUB forums and ticket system.

Thank you to:

• Alan who provided a possible solution that involved calibre that helped me quite a bit!
• Olivier for starting and sharing the manuskript project
• All the mainteners for keeping it alive!

Introduction

As delivered, the documentation for manuskript would have you creating the chapters for your book at the root level of the project. In fact, that works very well, if all you want to do is have manuskript hold only your book.

This HOWTO describes how to configure manuskript to let you record research notes in the same project, and still be able to manage your manuscript just as if all the chapter folders were at root level.

The Problem

If you put all your folders at the root level, any document you compile will generate a chapter for each folder. I think this is the intended method of operation, and based on the screenshots, that is the preferred method. It works if you're a "pantser" because you can just build enough to establish the structure of the book, and then just start writing.

Since some of us "plotters" like to do research before getting into the writing part, we need an area to store our research notes. For some, that might mean using a separate app (like Obsidian, One Note, Roam Research, Evernote) to do your research, and then using Manuskript to actually write the book.

Wouldn't it be nice to be able to do it all inside a manuskript project? It would be cool to be able to flesh out your research notes and still be able to take advantage of the world building, plots and character sheets while you are doing your research? This HOWTO shows you how to do just that: Have your manuscript contained in one root-level folder, and have your research notes in a different folder. The advantages are:

1. You get a word count of your entire book, right there on the outline screen.
2. You can still generate your EPUB, PDF, or HTML document with chapters at the correct level, just as if you had all your folders at the root level.
3. You have all the linking functionality from your research notes to characters, locations, etc.
4. You can jump from "research" to "writing" at will and do so seamlessly.

The Solution

To implement this solution, you need:

1. Manuskript (you likely already have this) :-)
2. pandoc (If you are currently generating EPUB or PDF from within manuskript, then you already have this).

The necessary steps are:

1. Format your manuskript project to have a top-level folder for your manuscript and another one for your research notes.

   • See this project for an example of the required structure.

2. Specify to compile only your manuscript, not the research notes, typically using the compile check boxes.

   • For convenience, you might want to place your compiled output into an export folder at your project root level.
   • If you choose to use a YAML file, it must be at the root of the document (i.e., at root level, not inside a folder).

3. When you are ready to compile, there is nothing special to do; just compile to MD format.

   • The output file will have one # line for the title of the book.
   • Then there will be multiple ## lines, one for each chapter. Yes, it looks strange to have section markers for chapters but we fix that in the next step.

4. Now you navigate to the directory that you placed the compiled markdown output file, and run this command:

   pandoc --shift-heading-level-by=-1 --top-level-division=chapter --toc -o manuscript.epub manuscript.md

   • The --shift-level-heading-by=-1 argument converts the sections to chapters.
   • The --top-level-division=chapter argument sets the top levels to chapters, not sections (which would be the defaullt).
   • You are not restricted to generating .epub - you can generate anything pandoc will let you: PDF, HTML, plain text... pretty much whatever you want.