}
Collaborative Book Authoring

Collaborative Book Authoring

Notes Icon When I used to use Atom, there was a great collaborative writing tool called Teletype. It allowed multiple people to be editing the same files at the same time. I’ve been working on a book lately and wanted to get another one in progress with a group of authors, so I tried to find something that would duplicate Teletype’s functionality iThonically.

There weren’t a lot of options. Both HackMD and StackEdit seemed decently put together, worked nicely in the browser, but I wanted a stand alone app that would load quickly so I could jot ideas on the train/bus as well as have longer sessions at home and on the go. I wanted to be able to collaboratively edit a bunch of Markdown documents and then build them into an ePub.

The only option was Apple Notes.

So, the Saturday morning before last, I sat around for a half an hour and patched a Pandoc build script together. This takes a folder of Notes and pulls it out of Apple Notes in plaintext, then makes a table of contents out of the Markdown chapters, then adds the front matter.

File and Directory Structure

You’ll need to use a folder structure something like:

mybook/
    templates/
        gfm.template
        epub.template
    css/
    fonts/
    chapters/
    publish.sh

I have modified Pandoc templates to control the Table of Contents Page, but you may or may not find that necessary. In case you do, here are the two templates I reference later in the publish script. Place them in the templates directory.

gfm.template

$if(titleblock)$
$titleblock$

$endif$
$for(header-includes)$
$header-includes$

$endfor$
$for(include-before)$
$include-before$

$endfor$
$if(toc)$
$if(toc-title)$
# $toc-title$
$endif$
$table-of-contents$

$endif$
$body$
$for(include-after)$

$include-after$
$endfor$

epub.template

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"$if(lang)$ xml:lang="$lang$"$endif$>
<head>
  <meta charset="utf-8" />
  <meta name="generator" content="pandoc" />
  <title>$pagetitle$</title>
$if(highlighting-css)$
  <style>
$highlighting-css$
  </style>
$endif$
$for(css)$
  <link rel="stylesheet" type="text/css" href="$css$" />
$endfor$
$for(header-includes)$
  $header-includes$
$endfor$
</head>
<body$if(coverpage)$ id="cover"$endif$$if(body-type)$ epub:type="$body-type$"$endif$>
$if(coverpage)$
<div id="cover-image">
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" height="100%" viewBox="0 0 $cover-image-width$ $cover-image-height$" preserveAspectRatio="xMidYMid meet">
<image border="5" width="$cover-image-width$" height="$cover-image-height$" xlink:href="../media/$cover-image$" />
</svg>
</div>
$else$
$for(include-before)$
$include-before$
$endfor$
$body$
$for(include-after)$
$include-after$
$endfor$
$endif$
</body>
</html>

publish.sh

I like to place this script in the root of my project directory for easy access.

#!/bin/bash

# change to working directory
cd ~/icloud/mybook/chapters

# sanitize the directory from any previous runs
rm *.md


# bring in a fresh copy of chapters/front matter from Notes
osascript <<EOF

# get a list of all the chapters

tell application "Notes"

	set myList to the name of every note of folder "mybook" of account "iCloud"

# Loop through the results

	repeat with a from 1 to length of myList
		set theCurrentListItem to item a of myList

# get title and content of each chapter

		tell folder "mybook" of account "iCloud"
				set myName to name of note theCurrentListItem
				set myText to plaintext of note theCurrentListItem
		end tell

# set textFile variable to the appropriate .md file

		set textFile to "~/icloud/mybook/chapters/" & myName & ".md"

# export title and content to build directory

# (the awk command removes the heading line)

		do shell script "echo  " & quoted form of myText & " | awk '{if(NR>1)print}'  >  " & quoted form of textFile

	end repeat

end tell

EOF


# stitch chapters and add TOC
/usr/local/bin/pandoc -s -t gfm --toc --toc-depth=2 -V toc-title:"Contents" --template=../templates/gfm.template ?hapter* > toc.chapters.md

# strip bullets from the table of contents (the $ in the sed
# command uses a string literal to pass the new line character)
# the rough syntax is:
# sed -e /start/,/end/$'s/find/replace'
sed -e /Contents/,/-----/$'s/  - \[/\\\n\[/' toc.chapters.md > debulleted.toc.chapters.md

# stitch title, front/back matters, and chapters
/usr/local/bin/pandoc -s --to=epub3 --template=../templates/epub.template --epub-embed-font='../fonts/*.otf' title.txt front-matter.md debulleted.toc.chapters.md > ../mybook.epub

# clean up the directory
rm *.md

With the build script in place, you’re ready to assemble the Markdown you’ve written in Apple Notes into an epub. I like to make a Shortcut to run the build script and leave it in my shortcuts widget so I can just tap on it from the home screen of my iPad.

All that’s left to do is share the Apple Notes with your collaborators, and you’re off to the races!

Happy writing.

will

About Will Puckett

A 20 year veteran of the San Francisco Bay Area, Will Puckett is an author, artist, and guide. He enjoys styling CSS ad infinitum, and helping friends move furniture. When not parked in front of his iPad, he rescues, restores and rides bikes. Will has been lucky enough to take long rides on both coasts of the United States, and encourages people to explore the world by bike. He tries to lay in his hammock as much as possible reading and planning his future container home, but does enjoy periodically escaping to skate. And of course ice cream.