Repository files navigation

This repository contains aBookGen style which can effectively be used as a static site generator to create pages which are similar to those ofArchive of our Own from a Markdown, per-chapter source.

BookGen has a number of configuration options; this guide is targeted at the beginner and only covers the basics.You will need some command-line knowledge to follow this guide.

BookGen has a number of prerequisites; as ArchiveStyle only targets HTML output, you will only need the following installed on your computer:

• GNU Make, version 3.81 or later. You can see which version ofmake is installed on your computer usingmake -v. If you need, you can download a new version ofmake here:https://www.gnu.org/software/make/.

• Pandoc.Installation instructions can be found here:https://pandoc.org/installing.html.You only need to installpandoc-citeproc if you are creating a work with a bibliography.

• Python 3.You can usepython3 -V to see if you already have Python installed on your computer.

• Panflute.This is a Python library used to create the BookGen Pandoc filters.You can install it withpip3 install panflute.

• Zip.It is probably already installed on your computer (you can usezip -v to check), but if you need it, you can get it here:http://infozip.sourceforge.net/Zip.html.

• Git.You do nottechnically need Git installed on your computer; you can just download the repositories manually and place them in the proper locations.However, using Git makes it easier to keep things up-to-date, and handles submodule dependencies for you.You can check the version you have installed usinggit --version, and download the latest version athttps://www.git-scm.com/downloads.

Of the above, Pandoc and Panflute are the most likely things you will have to install yourself.

First, open a command line andcd into the parent directory within which you will place your source.You have two options for installation:

1. If you are going to be tracking this entire directory withgit (and not just using it to keep modules up to date), then make sure it is initialized (rungit init) and then you will usegit submodule add.

2. Otherwise, you will usegit clone.

In the commands below, replace$INSTALL withgit submodule add orgit clone as determined above.

To install BookGen itself:

$INSTALL https://github.com/marrus-sh/BookGen.git Modules/BookGen

To install ArchiveStyle:

$INSTALL https://github.com/marrus-sh/ArchiveStyle.git Modules/ArchiveStyle

Next, download the submodules required by BookGen with the following command:

git submodule update --recursive --init

Finally, create aMakefile (that is, a plain-text file literally namedMakefile) in your source directory with the following contents:

SHELL = /bin/shBOOKGEN :=  Modules/BookGenARCHIVESTYLE := Modules/ArchiveStyle# Uncomment these lines if you want to use multiple drafts (see below):# DRAFTS := Drafts# export DRAFTSdefault: htmlbookgen: ; @$(MAKE) -ef "$(BOOKGEN)/GNUmakefile"archivestyle: ; @$(MAKE) -f "$(ARCHIVESTYLE)/Makefile"Makefile: ;%: archivestyle; @$(MAKE) -ef "$(BOOKGEN)/GNUmakefile"$@clobberdistcleangone:@$(MAKE) -f"$(ARCHIVESTYLE)/Makefile" gone@$(MAKE) -ef"$(BOOKGEN)/GNUmakefile" gone.PHONY: default bookgen archivestyle clobber distclean gone

This looks complicated, but it is just setting things up to defer anymake commands you make to BookGen and/or ArchiveStyle as required.

Create a file titledinfo.yml in your source directory.This is aYAML file which will store all of your metadata for your work.Some values supported by ArchiveStyle are:

title:"Work title"series:"Work series"author:"Your name"publisher:"Your publisher/website"description:|  Work summary.homepage:"https://example.com/The-homepage-for-your-work"# A URLyear:"The copyright year(s) of your work"rights:"A short rights statement about your work"draft:"1"# The draft number of the work (this will be 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# You can use lists and HTML in the following properties:ArchiveStyle:metadata:rating:"The rating of your work (e.g., Mature)"warning:"Any content warnings for your work"category:"F/F, Other, etc."fandom:"Fandom name(s)"relationship:"Relationship pairings"character:"Characters in the fic"tagged:"Additional tags"clickthrough:|    If provided, this adds a clickthrough disclaimer for viewing the content.foreword:|    Leading work notesafterword:|    Trailing work notes

For more on the allowed properties of this file, seeBookGen's CONFIGURING.md (for general BookGen configuration) as well as theCONFIGURING.md in this directory (for ArchiveStyle specific configuration).

You needn't specify all (or any) of the above, but an emptyinfo.yml filewill be created if you do not make one.You can also set these values on a per-chapter basis using YAML frontmatter.

Your book can consist of any number of frontmatter chapters, main chapters, and appendices.These must all be placed in a folder titledMarkdown in your source directory, and must have an extension of.md.Do not use colons, semicolons, or spaces in filenames as Makefiles are not well-equipped to handle these characters and everything might break.

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 of two 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 in theDrafts directory, and the alphabetically last file in each will be automatically linked into theMarkdown directory for you.(For example, the file atDrafts/Chapter/01/Draft_02.md will be linked fromMarkdown/Chapter/01.md.)This allows you to store multiple drafts of a chapter alongside one another, with the last draft used as the final result.

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

To compile your book, simply runmake -s.This will create two new directories:HTML/Archive, which will contain the compiled HTML files (which you can then serve on your website) andZip, which will contain ZIPs of the compiled files and source.If you don't need the zips, runmake -s NOARCHIVE=1

make gone will delete all directories created by BookGen and all their contents.If you are in drafts mode,it will also delete theMarkdown directory, so be sure to store all your files as drafts if you plan on making use of this feature.

You can of course customize the stylesheet by editing the file atModules/ArchiveStyle/Archive.css.Or, you can make your own additional stylesheets in theModules/ArchiveStyle directory.If you make a new stylesheet, also copy and renameArchive.py to match its filename.Otherwise, the chapter metadata will not be inserted into your files.

To update, justcd theModules/BookGen and/orModules/ArchiveStyle directory andgit pull --recurse-submodules.