Note: Readme Auto-generated (2020-04-07 23:04 UTC). Do not edit this file.
A brief description of your project, what it is used for and how does life get awesome when someone starts to use it.
Verkilo™ Pandoc Book is my effort to create a Continuous Integration / Continuous Delivery (CI/CD) toolchain for book / document publication. I have a lifetime desire to write god-awful fiction, and a background in software development & project management.
- Use Cases
- Features
- Installing / Getting Started
- Pandoc Bots (Docker Containers)
- Configuration
- Contributing
- Links
- Acknowledgements
- Licensing
- Fiction Author. As an independent fiction author, you want to focus on writing, not formatting. Writing pays the bills. The typical author (See Alternatives) relies on a complex toolchain including Microsoft Word or Scrivener, Vellum, etc. that requires the author focus on non-revenue activities. Worse, they feel compelled to outsource this phase of production, which takes revenue away from the author. Pandoc Book (Verkilo™) provides professionally formatted, distribution-ready files in various formats.
- PhD Candidate. As an PhD candidate, you want to focus on writing, not formatting. You want to manage your bibliography in Zotero, and let the output take care of itself.
- Automated Book Formatting. Cycle your long-form narrative work product (um, book) faster and simplify your writing workflow that continuously delivers production-ready books.
- Git-Managed Content on Github. Enjoy the traceability, features and confidence provided by git & Github, along with 100 million other projects.
- Write in Markdown. Write in Markdown, a lightweight markup language, which lets you focus on your prose with minor styling. It is portable, platform-independent, future-proof, and used everywhere.
To use this template, clone the repository locally. Copy the contents of the my-book/ directory as the new book you want to write (changing the name as appropriate). Then create a git repository of the new book.
You will need to install Pandoc, and be familiar with Markdown.
Commands you can execute:
make clean- Deletes content ofbuild/make docx- Converts the Markdown intext/to Word DOCX format (output placed inbuild/directory).make html- Converts the Markdown intext/to HTML format (output placed inbuild/directory).make mobi- Converts the Markdown intext/to MOBI format (output placed inbuild/directory).make pdf- Converts the Markdown intext/to PDF format (output placed inbuild/directory).
Pandoc Novel uses the git tag for the version added in the metadata and the filename. This is useful to keep track of different versions of the same work (i.e., different drafts; releases to editors, beta readers, etc. )
git tag -a v1.4 -m "my version 1.4"
Pandoc Book Compile is a Docker container that auto-generates books using Pandoc and pushes them to an active release on Github. (docker://merovex/pandoc-book-compile:latest) Read more
Pandoc Book Readme is a Docker container that auto-generates a compound README from Markdown files within the repository. It looks for all content between two comment tags, then inserts them in a README based on a template. (docker://merovex/pandoc-book-readme:latest) Read more
At a minimum, you will want to review / edit the following attributes in the metadata.yml file:
title- The title of the booksubtitle- The subtitle of the bookauthor- The author(s) of the book (can be a string or array)website- The author's websiteother-titles- An array of other titles the author wants the reader to be aware ofrights- The work's copyright statementdisclaimer- The author's disclaimerreservation- The author's reservation of rightsisbn- An array of ISBNs associated with the underlying workidentifier- The ISBN associated with the EPUBcredits- An array of those who supported the books' publication (artists, authors)
The images/ directory is where you should place images used to support the published work. You will also want to replace the following images with your own:
cover.pngProvides the cover for the epub.logo.pngProvides the imprint logo (both the name and logo are registered trademarks).
The text/ directory is where Pandoc Novel looks for the Markdown content.
The PDF option includes multiple trim sizes, depending on your target form factor. The Word document has a fixed trim size (Letter). The ePUB and HTML lack trim sizes. Metric measures rounded to 2 digits in the table. All measures are in metric in the LaTeX macros. (US Customary Measures are defined by their Metric equivalent.) When calculating trim size, we compared commonly used sizes and those offered by KDP.
| Trimsize | Paper Size |
|---|---|
| Letter | 8-1/2" x 11" |
| LargeTrade | 8" x 10" |
| Textbook | 7" x 10" |
| Trade | 6" x 9" |
| Digest | 5-1/2" x 8-1/2" |
| SmallTrade | 5-1/4" x 8" |
| Novella | 5" x 8" |
| AFourSize | 21cm x 30cm |
| UKAFormat | 11cm x 18cm |
| UKBFormat | 13cm x 20cm |
- Top and Inner margins are 2cm (~3/4").
- Outer and bottom margins are 17mm (~5/8").
- When attribute
bleed: trueis set, then the paper size and margins are increased by 3mm wide and 6mm high. (I don't think we can bleed an image, though.) - Set attribute
crop: trueto see what a given size looks like scaled properly on a letter-sized printout.
Warning: Failure to use one of the listed trim sizes will cause the compilation to fail. Defaults to trimsize: Trade.
Read more
Verkilo configures three default fonts, but you may reconfigure them provided they are available when using the LaTeX font packages listed here. See Pandoc fonts for LaTeX for more information.
Fonts are configured in either the metadata.yml or the in-document Frontmatter.
The LaTeX packages used for font assignments are:
\usepackage{fontspec}
\usepackage{xunicode}
\usepackage{xltxtra}
| Family | Default | Attribute |
|---|---|---|
| Serif | Libre Baskerville | seriffont: Libre Baskerville |
| Sans-Serif | Libre Franklin | sansfont: Libre Franklin |
| Monospace | Inconsolata | monofont: Inconsolata |
Why default Baskerville, Franklin & Inconsolata? Both Libre Baskerville and Libre Franklin have been optimized for use on screen. Baskerville is nice and readable, so ideal for use as body text, while Franklin is better suited to headlines. Inconsolata pairs with Baskerville & Franklin as they all share similar traits (double-story g & a, etc.). See the Libre Baskerville / Franklin / Inconsolata pairing image.
Here is an example of customizing fonts based on the Source Pro series:
seriffont: "Source Serif Pro"
sansfont: "Source Sans Pro"
monofont: "Source Code Pro"
Fonts Available. The fonts available for use are listed below. Submit an issue if you would like other fonts added.
- Source Code Pro
- Source Serif Pro
- Inconsolata
- Oswald
- Libre Franklin
- Source Sans Pro
- Libre Baskerville Read more
If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome. See Contributions for more information.
Even though this information can be found inside the project on machine-readable format like in a .json file, it's good to include a summary of most useful links to humans using your project. You can include links like:
- Repository: https://github.com/Merovex/pandoc-book/
- Issue tracker: https://github.com/Merovex/pandoc-book/issues
- Related projects:
- Your other project: https://github.com/your/other-project/
- Someone else's project: https://github.com/someones/awesome-project/
My earlier forays into plaintext to Novel were in LaTeX, then a custom-modified Ruby approach. This toolchain is a pivot to an automated toolchain and its inspiration owes appreciation to:
- Scott Selisker, A Plain Text Workflow for Academic Writing with Atom & KDheepak, Writing Technical Papers with Markdown. Both articles encouraged me to re-build a toolchain.
- Dennis Tenen and Grant Wythoff, Sustainable Authorship in Plain Text using Pandoc and Markdown, for their article encouraging me to focus on Pandoc for the toolchain. Accessed 30 December 2019.
- Pascal Wagler, Eisvogel, for giving away that one can pull down the stock Pandoc LaTeX template and modify it.
- BP, Pandoc Google Group, for helping me understand how to change the Horizontal Rule into a Plain Fancy Break.
- Memoir class, for having code on Plain Fancy Break that I was able to copy over.
- Open Source.com How writers can get work done better with Git, Accessed 30 December 2019.
Copyright © 2019-2020 Ben Wilson. All rights reserved. The code in this project is licensed under a BSD-4 license.