The purpose of this little project is to make the process of producing a novel targeting different formats easier and more streamlined.
You just write the book in markdown, a very basic and easy to use markup language. You don’t need a word processor for this, every editor will do. Then you just edit the metadata.yaml file with the options you want to use and execute the script. Voila: You have produced your book as an eBook and a pdf, ready to be printed! The main advantage of this method is, that you don’t have to maintain different files for different formats.
This project is a wrapper around pandoc. It automates many steps that would be needed to convert the files manually and provides an example metadata.yaml file for easy configuration. In addition it provides many filters for pandoc to style some special elements.
Before you can use this template, you need some programs installed on your computer:
Python 3.6 or higher: You can get python here.
Pandoc: You can download pandoc here.
A latex distribution: If you want a pdf in addition to an epub, you need to install a latex engine. Depending on your operating system, this are some popular choices:
Windows: MiKTeX. I recommend the full webinstall. It is very big and takes quite some time, but you don’t need to install any packages yourself this way.
MacOS: MacTeX
Linux: TeXLive via the package manager
Additional packages for latex: If you didn’t choose a complete latex distribution, you may have to install some additional packages in them. All of these distributions have a package manager you can use to download the needed packages. This template needs these three packages:
Pandoc needs some packages too. You can find the list in pandocs documentation (depending on the distribution, most or all could be installed already).
Kindlegen: If you want to convert your book for amazons kindle, you need this little tool from amazon. You can get it here.
Now you need to install this script itself. Open the console and enter:
pip3 install panovel
How to open the command prompt on windows: There are many ways to open the console on windows. Instead of the command prompt, you can use Powershell, if you like. The ways to access Powershell are mostly the same. Here are a few examples:
cmd in the adressbarOpen command window herefile menu item and select Open command prompt. You can even add this command to the menu toolbar
with the right click option menu for more convinient use.Panovel can create a project folder for you, which includes anything you need to get started with your new project. Open the console in the folder you want to create your new project folder in. Then enter the following into the console:
panovel your_project_name
Per default, this creates a basic metadata.yaml file. If you need all available options, you can instead enter:
panovel your_project_name -c
Of course you can always create the full metadata file later, by opening the console in the project folder and entering:
panovel -c
All markdown files in the folder are used to create the book. You can therefor either have your book in just one file or in different files. All files are joined alphabetically or you can specify the exact sequence in the metadata file. In addition you can specify the files containing the front- and backmatter.
The image folder holds all images used, for example the cover for the epub/mobi file.
Panovel has a small list of additional options available for more advanced uses. Enter
panovel -h
in the console, to see all options available.
Markdown is used to format the book. You can use all functionality provided by pandocs markdown. But while markdown excels at light markup, sometimes you need special formatting. Poems, epigraphs etc. are good examples. To make formatting these elements easy, this template comes with an easy to use syntax for many such elements. Each of this styles comes with one or more filters, which formats these elements according to the output format.
The syntax is very easy:
~~~{.type .option key=value}
The content that should be styled.
~~~
Types and simple options are preceded by a dot, attributes consist of a name and a value. These options are separated by a simple space. If the value of an attribute contains spaces, you need to surround it with quotation marks.
For example, this is how you would implement a poem:
~~~{.poem author="William Shakespeare" title="Sonnet 18"}
Shall I compare thee to a summer's day?
Thou art more lovely and more temperate:
Rough winds do shake the darling buds of May,
And summer's lease hath all too short a date:
Sometime too hot the eye of heaven shines,
And often is his gold complexion dimmed,
And every fair from fair sometime declines,
By chance, or nature's changing course untrimmed:
But thy eternal summer shall not fade,
Nor lose possession of that fair thou ow'st,
Nor shall death brag thou wand'rest in his shade,
When in eternal lines to time thou grow'st,
| So long as men can breathe or eyes can see,
| So long lives this, and this gives life to thee.
~~~
You can find a description of all the provided styles at the end of this documentation.
You can use html style comments in your source files. But not inside other style elements. Such a comment looks like this:
<!-- This is a comment. -->
You can add a curly bracket with “.unnumbered” or “-” inside it at the end of a heading, to exclude it from the automatic numbering, if you chose to use that.
# Example Heading{.unnumbered}
# Example Heading{-}
You configure how your novel is build through the “metadata.yaml” file. It consists of fields you enter your data into. Each field starts with its name and a colon. Your data comes behind the colon. Many fields have example values - just overwrite them.
Some fields are lists and can take multiple values. List items begin in the next line, indented and preceded by a dash. Just orientate yourself on the examples.
Lines beginning with a ‘#’ are comments. They mostly explain what the field controls. Sometimes the actual field is commented out, which means it is ignored. That is an easy way to enable a feature. Just remove the ‘#’.
The metadata file should be rather self explanatory. There are only a couple of things you have to add to make it work:
If you have frontmatter and/or backmatter in seperate files, remember to add the filenames to the corresponding field.
On windows you can simply use the provided bat file. Just double click it and your book is build. Otherwise the script is invoked from the command line. Just enter:
panovel
panovel accepts command line arguments. These overwrite the corresponding settings in the metadata.yaml. Just invoke it with the -h argument to see the options available.
Below you find a description of each type provided with the template and which filter is used to render it. If no filter is given, it is named like the style. Some styles have options how they should look in the rendered book. You can change these in the metadata.yaml file.
Needs a second qualifier, one of ‘.center’, ‘.right’ or ‘.left’.
Text gets aligned accordingly inside the block.
You need your copyrights surrounded by this style to be recognized properly.
You need your dedication surrounded by this style to be recognized properly.
Adds an epigraph.
Attributes:
This style is an exception to all others. To make a new scene, just
enter three ‘*’ on one line surrounded by blank lines. Please note,
that this overrides one default markdown command for a horizontal line.
Just use --- for horizontal lines.
Example:
The last paragraph in the old scene.
* * *
The first paragraph in the new scene.
Render Options:
* * *The paragraph is not indented.
Styles the content as a poem. There are three render options for this style, each just formatting the poem slightly different.
Render Options:
Options:
Attributes:
Styles the content as a quote. Of course markdown has its own syntax for quotes. You only need this style, if you want to include an author and/or a title.
There are three render options for this style, each just formating the quote slightly different.
Render Options:
Options:
Attributes:
Here are some additional filters, not used for styling elements.
This filter is used for a technical issue. Just keep it active.
Adds an image beneath each heading. You need to provide an image in the options.
You can use html comments to annotate your text. This filter removes this comments from the output.
Removes all images from the output.
FAQs
A script to make a novel out of markdown files with the help of pandoc
We found that panovel demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.