BookGen is a Makefile‐based system for turning Markdown files into oneor more different formats which can then be uploaded online, printed,distributed, et cetera.It serves a similar purpose for chaptered media as static sitegenerators do for websites.

To reiterate,BookGen is not an application, program, library, orframework.It is a series of configurable instructions which tell your computer(viaGNU Make) to use some number ofexisting programsand libraries (which also must be installed on your computer) inorder to generate a desired result.Consequently, the setup for BookGen is a bit more complicated than manyother workflows, and using it requires a willingness to live “in theoperating system” of your computer rather than isolated to one oranother application or platform.

If you can get on board with those premises, BookGen is a powerful andconfigurable workflow for cross-format book authorship, and one whichcan be easily extended and built upon to meet your precise needs.

Because BookGen is a Makefile‐based system, it suffers the same flawsthat Makefiles have generally.It does not play well with filenames which contain spaces or unusualascii punctuation.Its “A·P·I” consists of the filesystem and a few environment variables.It cannot operate in directories which do not conform to itsexpectations.

In my experience, working around these limitations is usually an easiertask than building a software which does not have them.

In order to use BookGen, you will need a basic understanding of thefollowing concepts :—

• The file system
• Text files & editors
• Makefiles
• The UNIX command line
• Yaml
• Markdown

The following advanced topics may also prove useful, but shouldn’t benecessary to get started :—

• Git
• The Bourne shell
• Python
• Pandoc
• LaTeX
• HTML
• CSS

A typical BookGen workflow consists of the following components :—

• The BookGen source repository, available athttps://github.com/BookGen/BookGen.

• One or more BookGen style repositories.

• A collection of chaptered Markdown files, comprising the source foryour book.

• A Makefile you wrote (see below) which ties these elementstogether.

BookGen requires you to have all of the following installed on yourcomputer :—

• GNU Make, version 3.81 or later.BookGen willnot work properly with earlier versions of GNU Make,or with Make versions which are not GNU.You can test which version of Make you have by runningmake -v.

• Pandoc, version 2.8 or later.You can test which version of Pandoc you have by runningpandoc -v.

• Python 3, as well as thePanflute package,which can be installed by runningpip3 install panflute.You can test whether Python is installed on your computer byrunningpython3 -V.

There are additional dependencies depending on what file types you arehoping to generate.For PDF generation :—

• A TeX distribution, including LaTeX and XeTeX.I useTeXLive, or more properlyMacTeX.Usexelatex -v to see if you already have it installed.

• The following TeX packages (as well as all their dependencies) :—

  • background
  • biblatex, includingbiber (for works with bibliographies)
  • everypage
  • hyperref
  • ifetex
  • logreq
  • mfirstuc
  • ncctools
  • newunicodechar
  • memoir
  • ulem
  • url
  • xcolor

  These will likely come packaged with your TeX distribution unlessyou purposefully installed a limited distribution like BasicTeX.

For PNG generation :—

• Everything required for PDF generation, as PNGs are built fromPDFs.

• GhostScript.If you are on macOS, MacTeX offers their own GhostScript package athttp://www.tug.org/mactex/morepackages.html, if you didn’tinstall it as part of MacTeX.You can usegs -v to see if you already have it installed.

• ImageMagick.Usemagick -version to see if you already have it installed.

• TheXpdf command line tools, namelypdftotext.Usepdftotext -v to see if you already have it installed.

• Zip.This comes preinstalled on many platforms.Usezip -v to see if you already have it installed.

It is entirely up to you how you choose to install these dependencies,but my recommendation is to follow the official instructions forinstalling your TeX distribution, and to use a package manager (likeHomebrew) for everything else.

After you have downloaded the BookGen source, installed alldependencies, and chosen and downloaded a style repository, the nextstep is to create aMakefile in your working directory which tieseverything together.A simple example follows :—

SHELL = /bin/shBOOKGEN := ~/BookGen# replace this with the path to the BookGen sourceMYSTYLE := ~/MyStyle# replace this with the path to your chosen style# Uncomment these lines if you want to use multiple drafts (see below):# DRAFTS := Drafts# export DRAFTS# The first command is what will be run if you just run a simple#   `make`.# Change this if you only want to generate certain kinds of files (for#   example, `html`.)default: all# Runs BookGen.bookgen: ; @$(MAKE) -ef "$(BOOKGEN)/GNUmakefile"# Runs the `make` script for your chosen style.mystyle: ; @$(MAKE) -f "$(MYSTYLE)/Makefile"# Any unhandled targets will be passed through to the BookGen script.# Explicitly do nothing for `make Makefile`.Makefile: ;# Pass through all remaining targets to BookGen.## Note that `mystyle` is a dependency here.%: mystyle; @$(MAKE) -ef "$(BOOKGEN)/GNUmakefile"$@# Remove generated files.clobberdistcleangone:@$(MAKE) -f"$(ARCHIVESTYLE)/Makefile" gone@$(MAKE) -ef"$(BOOKGEN)/GNUmakefile" gone# Identify phony targets..PHONY: default bookgen archivestyle clobber distclean gone

Next, create a file titledinfo.yml in your source directory.This is aYaml file which will store all of themetadata for your work.Some values supported by BookGen are :—

title:Work titleseries:Work seriesauthor:Your namepublisher:Your publisher/websitedescription:|  Work summary.homepage:https://example.com/The-homepage-for-your-work# A URLyear:The copyright year(s) of your workrights:A short rights statement about your workdraft:1# The draft number of the work (added automatically if you are in drafts mode)lang:en# Work language as an IETF (i·e HTML) langauge tagfinal:true# If this is a final, published draft; adds copyright declaration

For more on the allowed properties of this file, seeBookGen’sCONFIGURING.md as well as the documentation foryour chosen style.You can also set these values on a per‐chapter basis using Yamlfrontmatter.

Your book can consist of any number of frontmatter chapters, mainchapters, and appendices.These must all be placed in a folder titledMarkdown in your sourcedirectory, and must have an extension of.md.Do not use colons, semicolons, or spaces in filenames as Makefilesare not well‐equipped to handle these characters and everything mightbreak.

The type of a chapter is determined by its location :—

• All files directly in theMarkdown directory are frontmatter,ordered alphabetically.You can use leading digits to manually determine their order.

• All files in theMarkdown/Chapters directory with a filename oftwo digits are chapters.The chapter number is given by the filename.

• All files in theMarkdown/Chapters directory with a filename ofA, followed by two digits (for example,A01) are appendices.The appendix number is given by the filename.

Alternatively, if you setDRAFTS := Drafts in your Makefile above,you may instead give your chapters asfolders of Markdown files intheDrafts directory, and the alphabetically last file in each willbe automatically linked into theMarkdown directory for you.(For example, the file atDrafts/Chapter/01/Draft_02.md will belinked fromMarkdown/Chapter/01.md.)This allows you to store multiple drafts of a chapter alongside oneanother, with the last draft used as the final result.

If you are using drafts mode, it is best not to ever touch theMarkdown folder directly, and work entirely inDrafts (even forchapters with only one draft).

BookGen uses Pandoc under the hood, so the Markdown syntax isPandocMarkdown.

There are a few added features you can take advantage of in yourMarkdown for special formatting and display :—

• A Div with a class ofchapterprecis can be used at the beginningof a chapter to insert a chapter precis :—

  #My Chapter::: chapterprecis :::| A very good chapter,| Yes, very good indeed.:::::::::::::::::::::

• A Div with a class ofverse can be used for verse.

  If you also set the classalternating, then every other line willbe indented :—

  ::: {.verse .alternating}| A couplet writ in very little time,| With indentation on this second line.:::

  Alternatively, you can use an empty Span with a class ofindentto manually indent verse lines :—

  ::: verse :::| There once was a limerick, quite good,| And people assumed that it would|[]{.indent}End with some joke|[]{.indent}About some poor bloke,| But I don't see whyfor it should.:::::::::::::

• A Div with arole ofnote can be used for notes :—

  ::: {role=note}This is a note.:::

• A Div with a class ofcontinuation can be used to create aparagraph which continues from the previous, useful if ablockquote or line of verse comes between them :—

  To quote Light Yagami from <cite>Death Note</cite>,>This useless Pride, I suppose I'll have to… Get Rid of It!::: continuation :::(as translated by the English dub).::::::::::::::::::::

• A Div with a class ofplain, which contains only one paragraph,can be used to "unwrap" the paragraph (so that no<p> tag isused) :—

  ::: plain :::This will not use a`<p>` tag.:::::::::::::

• A Div or Span withdata-from-metadata set will have its contentsreplaced by the corresponding metadata value, if set.This is especially useful for localization :—

  See[Chapter]{data-from-metadata="localization-type-chapter"} 02.

• A Span with a class oflettrine can be used for leading text.An initial span will produce a drop cap :—

  [[T]{}his is the beginning]{.lettrine} of a section of text.

• A Span with adata-colour (ordata-color) attribute can be usedto set the text colour.This can be either a 6-digit HTML hex value or an SVG colour name.In the latter case, the name must be properly capitalized :—

  Some[red]{data-colour=#FF0000} and[blue]{data-colour=MidnightBlue} text.

• A Span with adata-font attribute may be used to manually set thetext font.Which values are supported depends on your current style.

  This is[fantastic]{data-font=fantasyfont}.

• An empty Span with a class ofat can be used to generate a\@for sentence-spacing adjustment in LaTeX.This is only necessary if you are generating PDFs with a stylewhich does not use\frenchspacing:

  Reading Rainbow, Mr.[]{.at} Rogers, etc.[]{.at} are all fond  memories for I[]{.at}.

• A raw HTML block of the form<hr/> represents aplain (unfancy) break.

Although these are standard BookGen features, full support may dependon your selected style.Furthermore, your style may have additional features besides these.

For a comprehensive account of all of the features and customizationoptions of BookGen, seethe Bookgen README.

Repositories