As a prolific author, I am able to test and tweak my methods to come up with my own workflow and best practices more quickly than most.

I used Scrivener for drafting and formatting books for about seven years. That workflow involved generating a docx file which I then manually tweaked with drop caps and other formatting features I could not accomplish directly within Scrivener, then using that file to create the other sizes/bindings that I needed. Then, of course, save them as pdf files for upload to my distributors. If I had changes to make to a book, I had to change the three or more docx files individually, as well as the Scrivener file which I still used to generate the epub and mobi versions. It was quite intensive. I was also running into problems with files becoming corrupted, taking huge lengths of time to open/close, and not converting properly from version 2.0 to version 3.0.

I finally broke down and purchased Vellum in the summer of 2020, and at that point, began to rejig my workflow to eliminate Scrivener. (I have not completely eliminated it, as I still use it as a tool for formatting large print and my WordPress portfolio files, but I no longer write in it, I just import a Vellum rtf export file for that purpose.)

It took a few different attempts at using docx or odt files for my first draft before I landed on using Markdown files (one per chapter) for drafting, then compiling the Markdown files for my editor, and importing the finished file into Vellum for formatting and publishing. Now when I have changes to make, I only need to make them in Vellum, not in half a dozen different files, and I can produce my ebooks and print interiors with just a few clicks.

Initially, I was using Notebooks App to create the Markdown files and compile them, and have since made the shift to doing it all in Obsidian, using the Longform plugin. By my count, I have written 13 books in Markdown, so I have had 13 iterations to tweak and refine the process discussed in this article.

Note: if you are moving a project from Notebooks to the Longform plugin, you need to do one tweak first. Notebooks creates a plist file for each of your MD files, which contains various internal information about that file. Longform does not know to ignore plist files and does weird things with them. So before marking your folder as a Longform project, take a moment to either delete the plist files or to create another copy of your manuscript in another folder with only the MD files in it. If you can’t see the plist files, there is a setting in Notebooks to make them visible or invisible.

Why Markdown?

Markdown files are plain text, with a few added characters or symbols used to format it for conversation to HTML or other formats. Being plain text files, they are very small and not likely to become corrupted. Writing one scene or one chapter per file also keeps them very small and can be opened in an instant. Since they are written in plain text, they can be edited with any text processor or word processor on any platform and are future-proof. Plain text will never become obsolete.

What is outlined below is what works best for me at this time. That may change and be tweaked as other tools become available, but I intend to keep Markdown as the central file format for drafting. A different process or set of tools may work better for you, so take what you will and don’t worry about the rest.

Versioning and file backup

I use Dropbox to sync all of my data files across all of my devices, and the license that I pay for includes versioning, so I can roll any file back at any time if it becomes corrupted, overwritten, or something else disastrous happens, like a hard drive failure. I also use Mac OS Time Machine backups to four different hard drives so that I always have additional copies which can also be rolled back. And when I am actively drafting a new book, I also compile and save a backup every few days.

My file folder structure for a novel

• Writing
  • My books
    • Series folder (Obsidian vault)
      • Novel folder (Longform project folder)
        • archived (old drafts/versions of anything)
        • backup (compiled backups of book made every few days)
        • characters (character motivations/notes for this book, different than the general notes on the characters in the series wiki)
        • Drafts (Longform drafts folder)
          • draft 0 – preplanning – snowflake, outline, etc.
          • draft 1 … 2 … 3 …
          • editing notes (notes of things to look at later, formatting, things to bring to the attention of my editor)
        • graphics (covers, promotional graphics, ads, etc.)
        • published (Vellum output folder for this novel)
        • queries (saved search templates for Obsidian)
        • research and notes (background for this novel)
        • templates (character notes, snowflake template, word count tracking)
      • Series wiki (linked “series Bible”)

Writing in Markdown

Writing your manuscript in plain text is pretty simple and I assume if you are reading this article you have a basic understanding of Markdown. (ie. double-returns between paragraphs, no tab indent, use *asterisks* for italics.)

I am not going to give a tutorial in using Longform or any of the other plugins mentioned in this article. You can find that documentation elsewhere.

Best practices

These are my “best practices” for drafting a book using Markdown files for eventual use in Vellum. They may or may not work for you, but will maybe give you a starting point for your own system.

File names

I write one chapter per Markdown file. It may consist of 1-3 scenes. I like to use descriptive file name for the chapter so that I can quickly find what I am looking for and jump from one scene to another. They are numbered so that they can be sorted sequentially in any file viewer or editor. Some apps will let you manually arrange the chapters in the order you want them in, so you can drag them around until it suits you. I would suggest that once you are pretty sure of the order, you number them. I generally write in sequence, but I’ll write three or four chapters without a number, just in case I decide I want to add or move around a scene, and then number them once the sequence is solidified. Of course, you can always move things around and renumber again later. I would like to see the Longform app add auto-numbering at some point.

When I import into Vellum, I eliminate the description and just use let Vellum autonumber the chapters. If you use named chapters in your final copy, then use your chapter names as your file names.

Front matter

I put searchable metadata in the front matter of each MD file. There are a number of different ways to do this, depending on which editor you want to use as your main Markdown editor. This metadata is “commented out” so that it will not appear in the final file, but can be used during the drafting stages to quickly find scenes or necessary information. Four methods of commenting out follow.

Commenting out

YAML

--- 
metadata 
---

Three hyphens are the first characters in the markdown file, followed by the metadata, followed by three more hyphens. YAML is a standard format for front matter, but is not recognized by all apps (like Notebooks). It is recognized by Obsidian.

The information normally included in a YAML header is things like title, author, and date (examples). Some apps or plugins (such as Obsidian Dataview) may make use of other variables to be included in the YAML header. You can put other Dataview fields anywhere in your file, so they can be inserted between any of the other pairings below as well.

If you are using the Obsidian Longform plugin to compile your scenes into one document, you can’t put a YAML header in each scene, only the first will actually convert to a header. Choose the Percents or HTML comments format below instead.

Percents

%% 
metadata 
%%

Recognized in some apps but not in others. Does not work for Notebooks App. Can be used anywhere in the document.

If you are using the Obsidian Word Count Dashboard to track your word count, use this method to comment out your metadata so that they will not be counted with your novel’s words.

Slashes

// 
metadata 
//

Recognized in some apps but not in others. Does not work for Obsidian. Can be used anywhere in the document.

HTML comments

<!-- 
metadata 
-->

Works in the majority of apps. (I won’t say all, because, who knows, but this one has worked pretty universally for me.) Can be used anywhere in the document.

This is the only method I could find that works for both Notebooks App and Obsidian. It is not recognized by the Obsidian Word Count Dashboard, but you can nest %% inside of the html comment bookends to make the counter ignore the metadata. Word Count Dashboard has been updated to recognize this format for comments.

Metadata I Use

You can use the metadata section to add whatever tags or information you want to track, search, or filter. My metadata may look something like this.

%%
Character:: !Kiara
Character:: !Malachi
Character:: !Nurse
Setting:: ~Doctor
POV:: Kiara
Day:: 1
Note::  
Draft:: 2
Grammarly:: √
%%

I precede character names with ! and setting names with ~ so that I can also search/filter them quickly from any file explorer. Why would I not just search Malachi instead of !Malachi? Because I don’t want to bring up every scene that Malachi is mentioned in, only the ones where he is a main character in the scene.

I only use POV in books that have multiple points of view. If there is only one POV in the book, I don’t need to track it. Similarly, if every scene in the book uses Joe Blow’s POV, then I don’t include !Joe in the list of characters, because he would be listed for every single scene, there’s never any need to filter on him.

Day helps me to keep track of day of the week or month, length of time between scenes, etc.

Note is anything that I need to remember for later.

Draft is the draft number

Grammarly indicates whether I have run the scene through Grammarly. Yes—you can copy and paste Markdown text into Grammarly and it will not screw up the paragraph spacing, italics, etc. like many formats do. You can check the file and paste the results back into your Markdown file, and everything will still be properly formatted.

As well as letting me search or filter by these variables in any file browser, I can also use the Obsidian Dataview plugin to produce a tabulated summary, like this:

Dataview query

Produces these results

• 

• 

• 

Other special formatting considerations

H1 Headers for chapters

H1 headers are automatically recognized by Vellum as chapter titles. If you use H1 headers, you will never fail in your chapters dividing in the correct place and retaining their names.

Notebooks has the option to make the first line of a file an H1 header (and by default synchronizes the first line of the file and the file name.) The Obsidian Longform plugin lets you add your Scene name as an H1 header in the compiling process.

If you are using other tools, create an H1 header by typing # followed by a space and your header.

# Header

Marking scene breaks

If you are importing into Vellum, then you want all of your scene breaks to be properly marked. Trust me, you don’t want to have to input all of your scene breaks after the file has been imported!

If you use *** or --- to mark your scene breaks, then they will be converted to a horizontal line <hr> when you convert to HTML. And horizontal lines are not recognized by Vellum as scene breaks.

If you use +++ to mark your scene breaks (you don’t need to center it), it will not be converted to a horizontal line when you convert to HTML. It will stay as a +++. And +++ is recognized as as scene break by Vellum.

My Obsidian Longform plugin formatting

You can format your editing and preview screens in Obsidian using CSS formatting that only applies to Longform project files.

My edit screen:

My preview screen:

My sample CSS

/* Font for the markdown source panel */
.Longform-leaf .cm-s-Obsidian
{
    font-family: Arial;
    font-size: 1.1em;
    line-height: 2em;
}

.Longform-leaf .cm-comment
{
    font-family: monospace;
    font-size: .8em;
    line-height: 1em;
}

.Longform-leaf .cm-header-1
{
  font-family: Garamond;
  font-size: 1.5em;
  line-height: 2em;
}


/* Font for the markdown preview panel */
.Longform-leaf .markdown-preview-view {
    font-family: Garamond;
    font-size: 1.2em;
        text-indent: 1em;
    text-align: justify;
}

.Longform-leaf h1 {
  font-family: Garamond;
  font-size: 2em;
  text-indent: 0em;
  margin-top: 1em;
}

.Longform-leaf p {
  margin-bottom: -15px;
  line-height: 1.3em;
}

.Longform-leaf {
  --background-primary: antiquewhite;
  --background-primary-alt: white;
  --background-secondary: white;
  --background-secondary-alt: white;
  --text-selection: #aaa;
  --text-normal: black;
    --text-faint: blue;
  color: black;
}

.Longform-leaf .suggestion-item.is-selected {
  background-color: var(--text-accent);
}

.Longform-leaf .markdown-preview-view blockquote {
    border-color: darkgrey;
    font-size: 95%;
    text-align: left;
    hyphens: auto;
    word-break: keep-all;
    color: black; # you need to define
    font-color: #aacdbe;
    line-height: 1.3;
    padding: 10px 2% 10px 2%;
    margin-top: 15pt;
    margin-bottom: 15pt;
}

Using Word Count Dashboard in Obsidian

I use the Word Count Dashboard to keep track of the word count in my Longform Project Draft folder. It is a little complex to set up and took a bit of playing around to get right.

This is what the top portion of my query template looks like (updated code Dec 18 – Word Count Dashboard has been updated):

---
cssclass: wordcountTable
---

%%
## Configuration

__Notes to display__
*Gets either notes in a folder or notes with a certain tag. Leave one of them empty.*
sourceFolder:: ZG 11/Drafts/Draft 1
sourceTag::

__Notes to exclude__
*Leave empty to disable.* 
excludeTag:: #exclude
*(Notes with the yaml-key "status" and value "exclude" for that key are also excluded.)*

__Counting Settings__
*set to zero to ignore*
charTarget:: 0
wordTarget:: 80000
wordsPerPage:: 0

includeFootnotes:: false
charactersIncludeSpaces:: true
excludeComments:: true

**Bibliography estimate for Pandoc Citations**
includeBibliographyEstimate:: false
wordsPerCitation:: 22
charsPerCitation:: 155

__Longform Plugin__
*Leave empty to sort alphabethically. Enter the path to the index file of a longform project to sections by their order in the longform plugin. (The sourceFolder further above has to be a Longform Drafts folder.)*
pathToIndexFile:: ZG 11/Index

*begin a filename with this character and it will be treated as subsection*
subsectionStartChar:: _

__Purely visual__
useThousandSeperator:: true
thousandSeperator:: ,
naChar:: —

%%

And this is what the query results look like:

I have also added a link at the bottom of the template to an Excel spreadsheet where I paste my daily total so that I can track my targets/completed words.

Other settings/plugins that I find helpful drafting novels in Obsidian

As well as the Longform and Pandoc plugins, I also find these to be useful when drafting novels.

Dataview Plugin

Needed to produce the data summaries you see above with my metadata and word count.

Obsidian Tabs Plugin

I prefer to have multiple documents open in tabs rather than panes. I’ll have my current scene open, my tabular summaries, my outline, and research documents, and they all show up as tabs that I can switch between. You cannot vertically or horizontally split with this plugin turned on.

Smart Typography Plugin

I want curly quotes and apostrophes. I want my ellipses converted. Other than that, I turn the rest off.

I recommend that if you use Smart Typography, you turn off “auto pair brackets” in your editor preferences. Otherwise things can get a little wonky.

Templates Plugin (Core)

I use templates for my character notes and my snowflake planning. I could also use them to automatically insert my metadata template. Alternatively, you could use TextExpander or another utility for this.

Starred Plugin (Core)

I like to star certain reference documents, such as my outline, word count dashboard, etc.

Wikilinks (Preferences)

I use Wikilinks to set up my series wiki (series Bible).

Compiling and Converting to final format

If you are drafting one scene or chapter per file, as you do with the Longform plugin, then you are going to need tools that (a) combine those chapters into one long file and (b) convert that compiled file into docx format for your editor and/or for import into Vellum and/or to convert into epub and pdf for publication. I am going to focus on getting from Markdown to Vellum here, you will need to experiment and adapt for other formats.

Compiling tools

The two compiling tools that I have used are:

Notebooks App

You can compile all files in a folder to one HTML file by clicking the three dots at the top of the panel and selecting compile. By default, the first line of the file becomes an H1 header. By default, the first line of the file is the file name, and changing one changes the other. This prevents you from using a YAML header in Notebooks App, since the three dashes need to be the first three characters in the file.

Obsidian Longform Plugin

You can compile all files in the draft folder of a Longform project by going to the Longform panel compile tab and clicking compile. Select the checkbox to make the Scene titles become H1 headers.

Converting to your final file format

In order to import cleanly into Vellum, you want to convert to HTML first. Converting to HTML first will retain chapter names as H1 headers, which Vellum will recognize as chapter names. Converting directly to docx will not retain the H1 headers.

Notebooks App

You can compile directly to HTML as mentioned above.

Pandoc

The Obsidian Longform Plugin will compile all of the Scenes into one long MD (markdown) file.

To convert from MD to HTML, you will want to use Pandoc. Pandoc is a command line file converter that lets you convert from one file format to another in Terminal. But don’t panic. If you are using Obsidian, install the Pandoc Plugin. (If you are using another Markdown editor, you will need to see what the options are available, learn Pandoc command line prompts, or use an online tool such as StackEdit to convert the file from MD to HTML.)

To convert using Pandoc plugin in Obsidian: navigate to the compiled MD file and click on it. Pull up the command palette (cmd-p) and type HTML. You should see “Pandoc Plugin: Export as HTML (without Pandoc)” Select this option to convert your MD file to an HTML file.

HTML to docx

Here is the magical step to convert your HTML file to a docx file for import into Vellum, retaining those H1 headers so that Vellum splits the chapters on the H1 header, using the H1 header as the chapter name.

Find the HTML file in your File Finder. Right click and select “Open With” and click either Word or your word processor. I have only tested this with Word and LibreOffice. I can confirm that it works with both of these apps. Then you can “save as” a docx file.

This new docx file can be imported into Vellum and all Chapter and Scene breaks will be properly converted. (Of course, you may want to send it to your editor first, and the import the finalized file into Vellum.) If you don’t want your chapters to have names, you can select all of your chapters on the left navigation panel and clear the titles. Then they will just show up as Chapter 1, Chapter 2, etc.

Vellum does not retain formatting such as block quotes, so if you have sections that will need to be converted to alignment blocks or other special formatting, I suggest that you use a symbol combination to mark each of those sections while working in Markdown, and then search for that combination in the Vellum file and format it accordingly.

eg. use “999 alignment block” and search for 999 in the text in Vellum after importing.

Vellum also does not import graphics embedded in your docx file. You will need to insert them manually.

Other formats

You can use Pandoc to create pdf files, epub files, etc. directly and not use Vellum or another formatting program. I have not experimented with this for novels. I have used Pandoc to create very nice formatted pdf files for printed newsletters (for people who want print copies rather than emails), but that is a topic for a separate article. It would take a little bit of work to get exactly the format you want for a book, but it would certainly be possible. Pandoc even has codes for running headers and footers.