Writing a novel in Markdown

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.

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 novelWritingMy booksSeries 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”)Best practices for drafting a book using Markdown files for eventual use in VellumFile names

I like to use descriptive file name for the chapter or scene. Numbered so that they can be sorted sequentially in any file viewer or editor. I eliminate the description in Vellum and just use numbered chapters. If you use named chapters in your final copy, then use them 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.

Commenting outYAML--- metadata ---

Three hyphens as 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

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 to make it ignore the metadata.

Metadata I Use

I use metadata in the front matter of the document to tag each chapter or scene with information that I want to filter on or track later. My metadata may include something like this.

%%Character:: !KiaraCharacter:: !MalachiCharacter:: !NurseSetting:: ~DoctorPOV:: KiaraDay:: 1Note:: Draft:: 2Grammarly:: √%%

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 breaks, italics, etc. You can check the file and paste the results back into your Markdown file, and everything will still be properly formatted, unlike trying to copy and paste other formats into/out of Grammarly.

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

Special formatting

If you are going to draft one scene or chapter per file, then you are going to need (a) a tool to combine those chapters into one long file and (b) a tool to convert that 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.

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.

Why H1 headers?

H1 headers are automatically recognized by Vellum as chapter titles.

Marking scene breaks

If you are importing into Vellum, then you want all of your scene breaks to be properly marked. 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 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.

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 used the Obsidian Longform Plugin to create your compiled MD file, then install the Pandoc Plugin in Obsidian. (If you are using another Markdown editor, you will need to see what the options are there, learn Pandoc command line prompts, or use an online tool such as StackEdit to convert the file from MD to HTML.)

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

Other formats

You can use Pandoc to create pdf files, epub files, etc. 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.

Writing in Obsidian Longform plugin

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:

---cssclass: wordcountTable---%%## Configuration**Folder containing Notes**folderPath:: ZG 11/Drafts/Draft 1**set to 0 to ignore**charTarget:: 0wordTarget:: 80000includeFootnotes:: truecharactersIncludeSpaces:: trueexcludeComments:: true**Notes to exclude**Leave empty to disable.Notes with the yaml-key "status" and value "exclude" for that key are also excluded excludeTag:: #exclude **Bibliography estimate for Pandoc Citations**includeBibliographyEstimate:: falsewordsPerCitation:: 22charsPerCitation:: 155**purely visual**thousandSeperator:: ,naChar:: —%%

And this is what the query results look like:

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