0.1.0 - initial release

See CHANGES.md

GPL v3

• summary
• official site

1. python 3.9.7 or newer
2. pandoc 2.14.2 or newer

There are only a small number of dependencies to be installed.

On a command line, navigate to the folder and run:

pip3 install -r requirements.txt

And that will install all required dependencies, globally.

This is possible using venv.

However, this is currently not supported by the batch files included with pandoc-folder.

Run pandoc on all files with a given suffix in a folder and its subfolders, to create one output document.

For example, it will find all markdown files in a directory and its subdirectories, and use pandoc to create one output file from them.

This can be used to write an ebook in multiple markdown files, then generate a single EPUB or HTML document which includes the content from all of them.

python pandoc-folder.py ./path/to/book/.pandoc-folder/settings-file.yml

Or, with Windows batch file:

pandoc-folder.bat ./path/to/book/.pandoc-folder/settings-file.yml

Or, with bash script:

pandoc-folder.sh ./path/to/book/.pandoc-folder/settings-file.yml

If you add the Pandoc-Folder folder into your PATH, then you can run the batch/bash commands on the command-line, from any folder.

The first argument is the filename, including path, of a settings file.

By default, the suffix .pfy is used for the file. This is really just a YAML file, but using a custom (and unused) extension allows associating it with the pandoc-folder.bat file, in Windows.

.pfy is short for "Pandoc-Folder YAML".

Any settings file is required to be under a sub-folder named .pandoc-folder. This sub-folder can be used to store all settings files. See the example-book/.pandoc-folder folder for an example. This keeps the files organizes, so that the files related to pandoc aren't mixed with your source files.

Note that under Linux, the .pandoc-folder folder will not be shown by default. It will be considered a hidden folder, because it starts with a period (.). However, it is common to store settings in a folder starting with a period under Linux. Hopefully, this won't be a problem. If it is, you can change the folder name in the configuration. Or use the -a flag for the ls command, to see all folders, including hidden ones.

The expected folder and file structure is like this:

./book/
  .pandoc-folder/
    my-settings-file.pfy

See the example-book/.pandoc-folder folder for an example of how the files are laid out.

Here is an example of part of the output, when Debug is set to True in the config. This shows the pandoc command used when building the example ebook. You can see that the input files, ending in .md, are the last arguments. Also, they are found regardless of whether they are in subfolders under the example-book folder.

DEBUG - === pandoc_command:
('pandoc --css="example-book\\.pandoc-folder\\pandoc-epub.css" '
 '--metadata-file="example-book\\.pandoc-folder\\pandoc-meta.yml" '
 '--defaults="example-book\\.pandoc-folder\\pandoc-defaults-epub.yml" -o '
 '"out-pandoc\\example-book.epub" "example-book\\part-1.md" '
 '"example-book\\part 2\\00 section.md" "example-book\\part 2\\sub-part 1.md" '
 '"example-book\\part 2\\sub-part 2.md"')
DEBUG - ===

By default, the suffix .pfy is used for the settings file. This are really just YAML files, but using a custom (and unused) extension allows associating it with the pandoc-folder.bat file, in Windows.

To associate the file under Windows:

1. browse it in Windows Explorer (file manager).
2. Click on it to select it.
3. Then, hold down a shift key while right-clicking on the file.
4. In the right-click menu that comes up, you should see an Open With option. Click it.
5. In the dialog that appears, click "More Apps"
6. Scroll to the bottom of the list of apps
7. Click "Look for another App on this PC"
8. Browse to the pandoc-folder folder
9. Select pandoc-folder.bat
10. Click the Open button.

After doing this, whenever you double-click on a .pfy file in Windows Explorer, it will run the pandoc-folder.bat. This will run the pandoc-folder python program on that file, and then wait for you to press a key before it closes the terminal.

The settings files are expected to be in YAML format.

Optional: specify a defaults file for pandoc to use. This is a useful way to provide a number of default values for pandoc options, without needing to specific them on the command-line.

This file should be found in the same folder as the settings file.

Optional: specify a metadata file for pandoc to read. This can be used to specify the title, author, and other fields for the book/document.

This file should be found in the same folder as the settings file.

Optional: specify a CSS file for pandoc to use when formatting the output book. Useful for EPUB or HTML output, and possibly others.

This file should be found in the same folder as the settings file.

This suffix is used to find the source files. So, for a suffix of md, Pandoc-Folder will find all *.md files in the directory or subdirectories. These will all be passed to pandoc as input files.

The default suffix is md, for converting markdown files. However, you could change this to another suffix that pandoc recognizes, such as docx.

This is an array of the directory and subdirectories up to and including the output file.

If the output path doesn't exist, it will be created.

To build the example book:

• on Windows, run: .\build-example-book.bat
• on Linux, run: ./build-example-book.sh

To see how the command for building th example book works, open one of these files with a text editor (such as: Visual Studio Code, Vim, Nano, Notepad, etc.)

The configuration file is pandoc-folder-config.yml. It is in YAML format.

Configuration options:

The name of the pandoc command to run. Normally, just pandoc.

The name of the settings folder to require. If the

Whether to print debug output. Useful for debugging/testing the program, but prints too much for normal use.

Whether to open a file manager after the pandoc command is done. This can be useful to show the output file. However, it can be really annoying if you are running a batch which generates *multiple output files, because a file manager window will be opened *for each one!

Which command to run to open the file manager. The default, explorer, works under Windows. Under Linux, it will depend on which distro and/or Window Manager, etc you are using.