Table of Contents

• What is Fiction Publisher
• Features
• Building your Books
• Metadata Options
• Fiction Publisher Structure
• Your Book Structure
• Requirements

What is Fiction Publisher

Fiction Publisher is a fork of Open Publisher, redesigned to work with Manuskript-structured projects. It is a PowerShell script that wraps Pandoc and LaTeX and uses a set of custom Pandoc templates (created with a focus on fiction).

Write your manuscript in markdown, configure a Pandoc metadata file, run a build script, and receive some beautifully formatted ePub (including an Amazon KDP-ready ePub) and print-ready PDF books.

Refer here for the recommended file structure for your book.

Features

PowerShell build script which creates

• PDF (print)
• ePub
• Amazon KDP ePub (with Amazon-specific series page)
• Word (using a Draft template)

Input formats

• Supports Markdown files within Manuskript folder structure

Configurable components for output (PDF and ePub)

• Copyright page templates
  • creative-commons
  • commercial
• Impression lines
• Chapter heading templates (PDF only)
  • default
  • romance-calligraphy
  • romance-cursive
  • scifi
  • oldwest
  • blockletter
  • classic
  • minimal
  • fantasy
  • Or you can select styles from the fncychap LaTeX package
• Drop cap styles (PDF only, ePub uses a simple default format)
  • default (same font as the body text)
  • romance
  • blockletter
  • scifi
  • oldwest
  • none
• Half-title page template (PDF only)
• Series page template
• Colophon page template (PDF only, details typesetting information)
• Author biography page template
• Customizable fonts for the main text, author name, and title

Adds formatting to output (PDF and ePub)

• Adds header to start of chapters if missing (based on parent folder name)
• Formats start of chapter with drop cap and small caps
• Can convert *** separators between scene breaks/POV changes with custom code (e.g., fleurons)
• Unindents starting paragraph of new scenes/POV changes
• Supports CriticMarkup syntax

Validation features

Every occurrence of an issue is reported, along with its file and line number.

• Checks for paragraphs not separated by blank lines (this is recommended over ending lines with double spaces because it makes the intention clearer and avoids possible errors)
• Checks for straight quotes (smart quotes should be included in source markdown to avoid ambiguity)
• Checks for a hyphen surrounded by spaces (e.g., "word - word"), which was probably intended to be an em dash
• Checks for correct ordering of closing quotation marks and commas/periods
• Checks for Unicode ellipsis (should be three periods, "...")
• Checks for repeated punctuation (e.g., "..", ".....", ",,", "!!", or "??")
• Checks for en dash (– or --) at the end of a quote (should be an em dash)
• Checks for en dash (– or --) between words (probably intended to be a hyphen or an em dash)
• Checks for hyphen between numbers (should be an en dash)
• Checks for extra spaces
• Checks for spaces before punctuation (e.g., "Hello , world" or "Really ?")
• Checks for missing spaces after punctuation (e.g., "wait,then" or "the door.She")
• Checks for indenting spaces (these should not be hardcoded in source markdown files)
• Checks for tabs
• Checks for invisible characters (e.g., zero-width spaces, soft hyphens, and non-breaking spaces) that are often pasted in from word processors or web pages
• Checks for a line that ends with space(s), followed by single newline (indicates ambiguous intention as to whether this should be a new paragraph [a full blank line is recommended here] or the same paragraph [the newline should be removed])
• Checks for items that should be italicized (items are user-defined in metadata)
• Checks for possessive suffixes being italicized
• Checks for unbalanced italics/bold markers (* or ** that isn't closed within the same paragraph)
• Checks for stray periods or commas around '?' or '!'
• Checks for dialogue that probably should end with a '?'
• Checks for dialogue that probably should end with a ','
• Checks for dialogue followed by a speech tag that is missing punctuation before the closing quote (e.g., “Hello” she said)
• Checks for dialogue tags that start with a capitalized pronoun (e.g., “Hello,” She said)
• Checks for unbalanced quotes (quotes that continue into the next paragraph are allowed)
• Checks for lines that look like scene separators (e.g., * * *, #, ~~~, or ---), but won't be converted because they aren't ***

Building your Books

Set Up a Book Project

• Keep your project wherever you like. Refer here for a description of how your book project should be organized.

• Run "Config.ps1" on your book's folder:

  pwsh -File Config.ps1 -BookFolder /path/to/your/book
  

  This adds a skeleton "config.yml" (if the book doesn't already have one) and a ".vscode/tasks.json" for building the book from VS Codium / VS Code. The "tasks.json" is replaced each time "Config.ps1" is run, so don't customize it. If the book already has its own "tasks.json", it is left as is.

• Copy any custom fonts that you wish to use into the "Pandoc/fonts" folder.

Update Your MetaData

Each book project contains a "config.yml", which is used to define metadata about your book. Refer to the Metadata Documentation for more information.

Build Your Book

Use the "Build.ps1" script to build your book, passing it your book's folder:

pwsh -File Build.ps1 -BookFolder /path/to/your/book

The finished files are written to a "Fiction-Publisher-Output" folder inside your book's folder, and are named after the book's folder.

Note: Each build deletes and recreates the "Fiction-Publisher-Output" folder, so don't keep anything else in it. (If a folder with that name already exists but wasn't created by a build, the build stops rather than deleting it.) If a build fails, its "build" subfolder is kept for troubleshooting. It contains the generated LaTeX pages and the processed markdown.

Any formatting issues found in your source files are saved to Fiction-Publisher-Output/<book> Format Warnings.log.

Any errors or warnings from Pandoc (including LaTeX errors and characters missing from a font) are saved to Fiction-Publisher-Output/<book> Build Errors.log.

Before building, the script checks that:

• Pandoc and XeLaTeX are available
• LaTeX packages needed for the print PDF are installed
• Book project is valid

Try the Example

The "Example" folder is a short sample book with deliberate formatting mistakes. Configure it first (this adds its VS Codium/VS Code build tasks), then build it to see the warnings that the script reports:

pwsh -File Config.ps1 -BookFolder Example
pwsh -File Build.ps1 -BookFolder Example

Using VS Codium / VS Code

• Run "Config.ps1" on your book's folder like normal.
• Open your book's folder in VS Codium/VS Code.
• Run the Build Book task (Ctrl+Shift+B, or Cmd+Shift+B on macOS): this will build the output and display any errors or formatting warnings. Formatting warnings for your source files are also listed in the Problems panel (with file and line number). Clicking a warning opens the file at that line.
• Run the Open Format Warnings Log task to open the book's "Format Warnings.log".

These tasks refer to "Build.ps1" by its full path, so if you move or update the "Fiction-Publisher" folder, run "Config.ps1" on the book again to update them.

Opening the "Fiction-Publisher" folder itself provides the same tasks (plus Configure Book, which runs "Config.ps1"), which ask for the book's folder each time.

The optional PowerShell extension (search for "PowerShell" in the Extensions view) adds syntax highlighting and debugging for the scripts.

Metadata Options

The following can be specified in a book project's "config.yml" file (which should be in the root of the book project's folder)

Title & Author

• title: Title of your book
• title-latex: LaTeX-formatted title (will override "title" value on the title and half-title pages of PDF output)
  • A raggedrighttitle environment is available for multi-line titles to make them ragged right. It takes a parameter specifying the width of the left and right margins.
• title-page-top-margin: How much space should be above the title on the title page (default is 4cm). This is useful if you need to add illustrator information to the title page and need a smaller top margin to make it all fit on one page
• main-font: The main body font for PDF output (can be a TTF/OTF filename in the "Pandoc/fonts" folder or font name). Default is Cochineal
• main-font-bold, main-font-italic, main-font-bold-italic: The bold, italic, and bold italic variants of main-font (TTF/OTF filenames in the "Pandoc/fonts" folder or font names). These are needed when main-font is a font file; an installed font name will find its variants automatically
• title-font: The font for the book title on the title and half-title pages (can be a TTF/OTF filename in the "Pandoc/fonts" folder or font name)
• title-font-pointsize: Font size of title in PDF output (default is 50)
• subtitle: Optional subtitle
• subtitle-latex: LaTeX-formatted subtitle (will override "subtitle" value on the title page of PDF output)
• author: Author name
• author-font: The font for the author's name on the title page (can be a TTF/OTF filename in the "Pandoc/fonts" folder or font name)
• author-by-header: The "By" label that appears above the author on the title page (default is blank)
• email: Author e-mail
• website: Author website

Book Info

• type: Genre of your book

• lang: A string value in BCP 47 format: http://tools.ietf.org/html/bcp47 (e.g., en-US). For languages other than English, install that language's TeX Live packages (e.g., tlmgr install babel-french hyphen-french)

• date: YYYY-MM-DD

• year: YYYY

• identifier:

  • scheme: UUID
  • text: A unique UUID for your ebook ("Config.ps1" generates one for you)

Cover

• cover-image: The path to the ePub cover image, relative to the book's folder (e.g., images/cover.jpg for "MyBook/images/cover.jpg")

Copyright Page

• copyright-page: Which copyright page template to use. Templates to select from are available in the "Pandoc/templates/copyright" folder (e.g., creative-commons and commercial)

• contributors:

  • designer: Who designed your book/cover
  • cover-artist: Who created the art of your book cover
  • editor: Who edited your book
  • illustrator: Who did the interior illustrations (will appear on the title page)

• publisher: Publisher of your book

• publisher-address-latex: LaTeX-formatted publisher address (used on PDF copyright page)

• publisher-address-html: HTML-formatted publisher address (used on ePub copyright page)

• rights: A single sentence regarding the licensing of your book

• paperback-isbn-13: Optional 13 digit ISBN of your paperback book

• hardcover-isbn-13: Optional 13 digit ISBN of your hardcover book

• epub-isbn-13: Optional 13 digit ISBN of your ePub book

• paperback-isbn-10: Optional 10 digit ISBN of your paperback book

• hardcover-isbn-10: Optional 10 digit ISBN of your hardcover book

• epub-isbn-10: Optional 10 digit ISBN of your ePub book

• first-paperback-date: Publication date of first paperback edition

• lcc-info-latex: LaTeX-formatted Library of Congress Cataloging-in-Publication Data (used on PDF copyright page)

• lcc-info-html: HTML-formatted Library of Congress Cataloging-in-Publication Data (used on ePub copyright page)

• impression-line-years: The year part of the impression number/printer line (years run right-to-left, and are usually 2-digit)

• impression-line-printings: The print-run part of the impression number/printer line (number run left-to-right)

Dedication Page

• dedication: Optional dedication

Table of Contents

• toc: Whether to include a table of contents in the print output (true or false)
• toc-title: The header text for the Table of Contents
• toc-depth: How many heading levels the Table of Contents in the print output shows (0 for chapters only, 1 to also show sections [headings marked with ##], and so on)

Series Page

• series-book1:
  • title: Optional books to include on the series page
  • title-latex: LaTeX-formatted title for PDF output (will override title)
  • subtitle: Subtitle of book
  • subtitle-latex: LaTeX-formatted subtitle of book (will override subtitle)
  • link: Store link for the book (used in the Amazon ePub)
• series-book2:
  • title: Add a second book
• series-book3:
  • title: Third book
• series-book4:
  • title: Fourth book
• series-book5:
  • title: Fifth book
• series-header: Header that should appear on the series title page (default is "Also Available")

Colophon

• colophon: Whether to include a colophon page (detailing typesetting information) in the print output

Author Bio

• author-bio: Author biography

Page Formatting

• paper-height: The height of the paper for print output (the default papersize is 6x9 inches)

• paper-width: The width of the paper for print output

• top-margin: The top margin in the print output (headers will be inside of the text body)

• bottom-margin: The bottom margin in the print output

• inner-margin: The inner/gutter margin in the print output

• outer-margin: The outer margin in the print output

• fancy-chapter: Chapter heading style from the fncychap library (PDF output only). Styles include Sonny, Lenny, Glenn, Conny, Rejne, Bjarne, and Bjornstrup

• chapter-heading: The name of the custom chapter heading theme to use (default, romance-calligraphy, romance-cursive, scifi, oldwest, blockletter, classic, minimal, fantasy). Note that using fancy-chapter will override this

• chapter-name: The word used for "Chapter" (default is Chapter), for example Kapitel or Part. PDF output uses it in chapter headings and running headers. ePub output uses it for chapters with no title. Spelled-out numbers follow lang.

• unnumbered-chapters: Semicolon-separated list of chapter folder names (without the number prefix) that are unnumbered chapters, such as a prologue (default is Prologue; Epilogue). Names are case-insensitive, and underscores in folder names match spaces. Setting this replaces the defaults, so include Prologue and Epilogue if you still want them (e.g., Prologue; Interlude; Epilogue).

• Chapter with no title: A chapter whose heading should show only "Chapter N" (no separate title) can be created by:

  • naming its folder with only a number (e.g., 02)
  • naming with a trailing hyphen (e.g., 02-)
  • or by writing an empty top-level heading (# ) in its first scene The print PDF shows "Chapter N" via the chapter label, and the ePub shows "Chapter N" as the heading and in the table of contents.

• drop-cap-style: The drop cap style to use for first letter at the start of each chapter (default, romance, blockletter, scifi, oldwest, none)

• scene-separator-latex: LaTeX code to replace *** sequences between scenes (used for PDF output)

• scene-separator-html: HTML code to replace *** sequences between scenes (used for ePub output)

• no-hyphenate-list: Space-separated list of words that explicitly show how words should be hyphenated when split across lines; useful for listing (non-hyphenated) names of characters whose names should not be split between lines

Extra

• header-includes: Raw content to embed in the template file's header (e.g., LaTeX commands)

Validation & Testing

• emphasis-check: Semicolon-separated list of phrases that should be italicized. If they are not, a warning will be logged
• copyedit: Set as true to draw an outline around the various sections in the print output and show marginal notes in the print output (useful if using CriticMarkup)

Build Options

• build-draft: false to not build a draft copy (true by default)
• build-epub: false to not build an ePub file (true by default)
• build-amazon-epub: false to not build the Amazon KDP ePub, <book>-amazon.epub (true by default)
• build-print: false to not build a PDF file (true by default)

Fiction Publisher Structure

The following folders in "Fiction-Publisher" hold the resources that the build uses:

Pandoc

This directory holds the stylesheet, templates, and fonts used by Pandoc.

Pandoc/css

This is the stylesheet used when creating ePub and Amazon ePub files.

Pandoc/templates

This folder contains the custom templates Fiction-Publisher uses when converting files with Pandoc. The main templates are "custom-print.tex" (print PDF), "custom-epub.html" (ePub), and "draft.docx" (the reference document for the Word draft).

Pandoc/templates/biography

This folder contains the author biography page templates, which display the author-bio field from your config.yml file.

Pandoc/templates/chapter-heading

This folder contains the custom chapter heading templates (PDF only). You can select which template to use using the chapter-heading field in your config.yml file.

Pandoc/templates/colophon

This folder contains the colophon page template (PDF only), which is included when the colophon field in your config.yml file is true.

Pandoc/templates/copyright

This folder contains the custom copyright templates. You can select which template to use using the copyright-page field in your config.yml file.

Pandoc/templates/half-titlepage

This folder contains the half-title page template (PDF only).

Pandoc/templates/seriespage

This folder contains the series page templates (including the Amazon KDP version), which list the series-book entries from your config.yml file.

Pandoc/fonts

This folder contains any font files (TTF, OTF) you would like to use in your PDF output.

The following fonts are included, licensed under the SIL Open Font License (see the *-OFL.txt files):

• Cochineal: the default main font
• Orbitron: used by the scifi drop cap and chapter heading styles
• Chunk Five: used by the oldwest drop cap and chapter heading styles
• Miama Nueva: used by the romance-cursive chapter heading style

The following font is included, licensed under the GUST Font License:

• TeX Gyre Chorus: used by the romance drop cap style and fantasy chapter heading style

Your Book Structure

The following is the folder structure that your book projects should be in (i.e., Manuskript format):

A book folder should have the following:

• A "config.yml" file with build settings.
• A subfolder named "outline" which contains the chapters.
  • In the "outline" folder, there should be a subfolder for each chapter, prefixed with a 2-digit number and hyphen. (This will inform the build script about how to order the chapters.) A folder whose name is only a number (e.g., 02) or a number and hyphen (e.g., 02-) creates a chapter with no title (see Chapter with no title above).
    • A chapter folder named "Prologue" or "Epilogue" (e.g., "00-Prologue") is an unnumbered chapter. Its title appears as is (with no "Chapter N" label) and in the TOC, and it isn't counted in the chapter numbering. Other names (e.g., "Interlude" or names in another language) can be set with unnumbered-chapters in "config.yml". Any other chapter can be made unnumbered by adding {-} to the end of its heading (e.g., # Interlude {-}).
    • In each chapter folder, there should be a separate Markdown file for each scene. (A numeric prefix on these files will inform the build script of their order.) It is recommended to add a *** at the end of each Markdown file (except for the last one) in a chapter if you wish to have scene separators added.

Fiction-Publisher-Output

This folder holds your finished book in each format you've built, along with any "Format Warnings" and "Build Errors" logs (refer to Build Your Book for details).

Requirements

Fiction Publisher needs the following tools to be installed in order to work:

Pandoc

Pandoc - converts from many file formats to many other file formats. For our purposes, it converts our markdown files to ePub, PDF, and Word.

LaTeX / TexLive / MiKTeX

LaTeX - typesetting software that can output PDF files.

The print templates use a number of LaTeX packages that a minimal install (e.g., TinyTeX) may not include. Before building PDF, the script checks that the packages your book needs are installed. With TeX Live (including MacTeX and TinyTeX), it stops and shows the tlmgr install command for any that are missing. With MiKTeX, it shows a warning instead, since MiKTeX can install missing packages during the build.

PowerShell 7

PowerShell 7 (pwsh) - runs the build scripts. On macOS use brew install --cask powershell. On Linux install it with your package manager (refer to the install docs). Verify with pwsh --version.

EPUBCheck (optional)

EPUBCheck - if installed (epubcheck on the PATH), the build will validate the generated ePub files and report any problems. If it isn't installed, this check is skipped.

Ghostscript (optional)

Ghostscript - if installed (gs on Linux/macOS, gswin64c on Windows), the build will check the print PDF for an odd page count and fonts that are not embedded. If it isn't installed, these checks are skipped.

Fiction Publisher

Git clone the Fiction Publisher repo.

git clone https://github.com/Blake-Madden/Fiction-Publisher