DEV Community

Raphaël Pinson
Raphaël Pinson

Posted on

Git & Markdown to write a novel

#documentation #markdown #writing

This year, I started writing a historical novel about a branch of my family. I quickly realized I needed some tooling to organize my data: what I know about the characters, the places, a general timeline, etc.

Manuskript

I looked for software to do that and found that the reference is Scrivener. However interesting it looked, I'd rather use Open Source software whenever possible, so I started using Manuskript, an Open Source software for writers similar to Scrivener.

Manuskript on Ubuntu

I laid out some chapters, characters, plots… then I realized the saving format was binary. It's actually a Zip archive which contains all the information in flat files:

        1  2020-05-09 08:05   MANUSKRIPT
      137  2020-05-09 08:05   infos.txt
        0  2020-05-09 08:05   summary.txt
       46  2020-05-09 08:05   status.txt
      147  2020-05-09 08:05   labels.txt
      284  2020-05-09 08:05   characters/0-Samuel_L-on.txt
      281  2020-05-09 08:05   characters/1-L-on_Grunberg.txt
      261  2020-05-09 08:05   characters/2-Adolphe_Grunberg.txt
      309  2020-05-09 08:05   characters/3-Elisabeth_Rau.txt
      112  2020-05-09 08:05   characters/4-Victor_Grunberg.txt
      109  2020-05-09 08:05   characters/5-Maria_Schorr.txt
      224  2020-05-09 08:05   characters/6-Fred_Grunberg.txt
      125  2020-05-09 08:05   characters/7-Colonel_de_Villebois-Mareuil.txt
      107  2020-05-09 08:05   characters/8-Said_Pacha.txt
      109  2020-05-09 08:05   characters/9-Isaac_Aghion.txt
       92  2020-05-09 08:05   outline/00-Setup.md
      322  2020-05-09 08:05   outline/01-Les_joyaux_-gyptiens/folder.txt
     3753  2020-05-09 08:05   outline/01-Les_joyaux_-gyptiens/0-Une_rencontre_inattendue.md
     1706  2020-05-09 08:05   outline/01-Les_joyaux_-gyptiens/1-Office_de_chabbat.md
      715  2020-05-09 08:05   outline/01-Les_joyaux_-gyptiens/2-Un_d-ner_chez_Isaac.md
      482  2020-05-09 08:05   outline/01-Les_joyaux_-gyptiens/3-Proc-s_1.md
      166  2020-05-09 08:05   outline/01-Les_joyaux_-gyptiens/4-Sc-ne_5.md
       83  2020-05-09 08:05   outline/02-Paris/folder.txt
      102  2020-05-09 08:05   outline/02-Paris/0-Sc-ne_1.md
       97  2020-05-09 08:05   outline/03-Etudes_des_enfants/folder.txt
      103  2020-05-09 08:05   outline/03-Etudes_des_enfants/0-Sc-ne_1.md
      103  2020-05-09 08:05   outline/03-Etudes_des_enfants/1-Sc-ne_2.md
       95  2020-05-09 08:05   outline/04-Premiers_emplois/folder.txt
      103  2020-05-09 08:05   outline/04-Premiers_emplois/0-Sc-ne_1.md
       96  2020-05-09 08:05   outline/05-Vers_le_Transvaal/folder.txt
      103  2020-05-09 08:05   outline/05-Vers_le_Transvaal/0-Sc-ne_1.md
      334  2020-05-09 08:05   outline/21-Epilogue.md
    40074  2020-05-09 08:05   revisions.xml
      275  2020-05-09 08:05   world.opml
     1669  2020-05-09 08:05   plots.xml
     2499  2020-05-09 08:05   settings.txt
Enter fullscreen mode Exit fullscreen mode

This is rather good news, and there's ways to automate PDF creation from this within the software, good news again!

However, some things were problematic to me:

  • I like to tune my pandoc/LaTeX rendering, and the options in Manuskript were pretty limited for that
  • I'd rather not commit a single Zip file in Git, so I would have preferred to have all the files in the current directory
  • Manuskript cannot be automated to compile the PDF, you need to go through the GUI and click on buttons. That's a blocker for me.

Going the full-git way

So I decided I would do everything in Git + Markdown, without the help of a third-party application.

Chapters

I'm currently storing the chapters in their own directories, with numbered Markdown files:

chapitres/
├── 01_les_joyaux_egyptiens
│   ├── 00_titre.md
│   ├── 01_une_rencontre_innatendue.md
│   ├── 02_office_de_chabbat.md
│   ├── 03_brody.md
│   ├── 04_chabbat_2.md
│   ├── 05_diner_chez_isaac.md
│   └── 06_audience.md
├── 02_les_enfants_grunberg
│   ├── 00_titre.md
│   ├── 01_leon.md
│   ├── 02_retour.md
│   ├── 03_coffre.md
│   ├── 04_burtaux.md
│   ├── 05_article.md
│   └── 06_article2.md
├── 03_annees_noires
│   └── 00_titre.md
├── 04_etudes
│   └── 00_titre.md
├── 05_premier_travail
│   └── 00_titre.md
├── 06_le_creusot
│   └── 00_titre.md
└── 21_epilogue.md
Enter fullscreen mode Exit fullscreen mode

Characters & Places

The characters documentation is stored in Markdown files as well, and links can be made between them when necessary:

personnages/
├── Adolphe_Grunberg.md
├── Charlotte_Grunberg.md
├── Elisabeth_Rau.md
├── Emilie_Grunberg.md
├── Felix_Zottier.md
├── Frederic_Grunberg.md
├── Isaac_Aghion.md
├── Jacques_Grunberg.md
├── Leon_Grunberg.md
├── Lucie_Leon.md
├── Marc_Leon.md
├── Mirel_Schorr.md
├── Paul_Grunberg.md
└── Samuel_Leon.md
Enter fullscreen mode Exit fullscreen mode

Same goes for places:

lieux/
├── Alexandrie.md
├── Brody.md
├── Dubno.md
├── Grunberg_Boulogne.md
├── Paris.md
├── Petite_Jonchere.md
└── Vienne.md
Enter fullscreen mode Exit fullscreen mode

Links can easily be made between these documentation files:

# Mirel Schorr


## État civil

* Prénoms : Mirel, dite Maria
* Nom : Grünberg
* Nom de naissance : Schorr


## Portrait

Inconnu


## Description physique

Inconnu



## Evénements


* ca 1800 : ° à [Dubno](../lieux/Dubno.md) (Russie)
* Enfance à [Brody](../lieux/Brody.md) (Autriche)
  avec ses parents [Schachne](Schachne_Schorr.md)
  et [Sarah](Sarah_Bick.md)
  et ses frères [Naphtali](Naphtali_Mendel_Schorr.md)
  et [Osias](Osias_Heschel_Schorr.md)

* 1821: Mariage à [Brody](../lieux/Brody.md)

* 1870 : habite à [Vienne](../lieux/Vienne.md) (testament [Adolphe](Adolphe_Grunberg.md))

* 1877 : habite à [Paris](../lieux/Paris.md) (+)
* 1877 : + à [Vienne](../lieux/Vienne.md)


## Habillement

Voir sa garde-robe en 1853 dans l'inventaire de [Victor](Victor_Grunberg.md)
Enter fullscreen mode Exit fullscreen mode

Section stats

Manuskript provides stats about the number of words in a section. I've added a Make target for that:

stats:
    find chapitres/ -name "*.md" -not -name '00_titre.md' -print0 | sort -z | xargs -0 wc -w
Enter fullscreen mode Exit fullscreen mode

Caveat: it also lists the words in the comments…

Building the project

I'm using Pandoc to build the project with my own LaTeX template.

%.md:
    cat meta.md > $@
    find chapitres/ -name "*.md"  -print0 | sort -z | xargs -0 cat >> $@

%.tex: %.md
    pandoc --pdf-engine lualatex  --template extended.tex \
           --variable numbersections --toc --variable toc-depth=2 \
           --variable documentclass=memoir --variable fontsize=12pt \
           --filter pandoc-citeproc \
           --verbose \
           $< -o $@

%.pdf: %.tex
    OSFONTDIR=$(FONTSDIR) lualatex $<
    makeindex $*.idx
    OSFONTDIR=$(FONTSDIR) lualatex $<
Enter fullscreen mode Exit fullscreen mode

The novel project can be found in this GitHub repository:

GitHub logo raphink / genearoman

📖 Long Tom, un roman généalogique


View on GitHub


Top comments (0)

Read next

r0mymendez profile image

Diagram-as-Code: Creating Dynamic and Interactive Documentation for Visual Content

Romina Mendez -

koladev profile image

How Senior Software Engineers Document Their Project

Mangabo Kolawole -

robertobutti profile image

Building a website using Markdown content with Next.js App Router and Fusionable

Roberto B. -

itlackey profile image

Cassi: An AI-Powered CSS Style Guide Generator

IT Lackey -