I've added two new features: logging and feature toggles. Because the log is more detailed than the already existing debug information printed when you used pandocomatic's --debug command-line option, I've removed that command-line option. However, as that's a breaking change, I've created a new major version of pandocomatic: 2.0.0.
Logging
Pandocomatic 2.0.0 adds logging to pandocomatic. Use the log to investigate and understand your conversion process in detail. Use new command-line options --log [FILE] and --log-level [LEVEL] to control pandocomatic's logging. Use them as follows:
-
-l [FILE], --log [FILE]Let pandocomatic log what it is doing to FILE. If FILE is not given, pandocomatic uses 'pandocomatic.log'. Control detail of logging with option '--log-level'.
-
--log-level [LEVEL]Let pandocomatic log with detail LEVEL. LEVEL should be one of 'fatal', 'error', 'warn', 'info', or 'debug'. By default, pandocomatic logs at detail level info. Choose level 'debug' to see all steps pandocomatic takes to convert every directory and file.
When using the "debug" detail level, pandocomatic will log the full conversion process in a structured way. Using this log, you can see exactly what steps pandocomatic took when converting a file or directory. It'll allow you to perform the same steps manually and investigate the conversion process.
For example, part of the log when running a test looks like:
2024-10-09 07:49:15 INFO : (1) - convert index.md -> index.html
2024-10-09 07:49:15 DEBUG: # Using template 'wiki-page'.
2024-10-09 07:49:15 DEBUG: # Selected template mixed with internal template and pandocomatic metadata gives final template:
extends: []
glob:
- "*.md"
setup:
- scripts/create_temp_file.sh
preprocessors:
- preprocessors/now.rb
metadata: {}
pandoc:
from: markdown
to: html5
standalone: true
template: templates/wiki.html
postprocessors:
- postprocessors/branding.rb
cleanup: []
2024-10-09 07:49:15 DEBUG: # Running setup:
2024-10-09 07:49:15 DEBUG: | /home/pandocomatic-user/example/data-dir/scripts/create_temp_file.sh
2024-10-09 07:49:15 DEBUG: → Reading source file: '/home/pandocomatic-user/example/src/setup-cleanup-wiki/index.md'
2024-10-09 07:49:15 DEBUG: | FileInfoPreprocessor. Adding file information to metadata:
pandocomatic-fileinfo:
from: markdown
to: html5
template: templates/wiki.html
path: '/home/pandocomatic-user/example/src/setup-cleanup-wiki/index.md'
src_path: '/home/pandocomatic-user/example/src/setup-cleanup-wiki'
created: 2024-05-22
modified: 2024-05-04
2024-10-09 07:49:15 DEBUG: # Running preprocessors:
2024-10-09 07:49:15 DEBUG: | /home/pandocomatic-user/example/data-dir/preprocessors/now.rb
2024-10-09 07:49:15 DEBUG: # Changing directory to '/home/pandocomatic-user/example/src/setup-cleanup-wiki'
2024-10-09 07:49:15 DEBUG: # Running pandoc
2024-10-09 07:49:15 DEBUG: | pandoc --from=markdown \
--to=html5 \
--standalone \
--template=/home/pandocomatic-user/example/data-dir/templates/wiki.html
2024-10-09 07:49:15 DEBUG: # Running postprocessors:
2024-10-09 07:49:15 DEBUG: | /home/pandocomatic-user/example/data-dir/postprocessors/branding.rb
2024-10-09 07:49:15 DEBUG: ← Writing output to '/tmp/setup_cleanup20241009-42-uqczz2/setup-cleanup-wiki/index.html'.
Feature toggles
From pandocomatic 2.0.0 on, pandocomatic also supports feature toggles. Use command-line option --enable FEATURE to enable a feature.
At the moment, pandocomatic only support feature toggle "pandoc-verbose". By default, pandocomatic does not forward pandoc's "--verbose" option to pandoc when you set it in a template because the output of pandoc's verbose mode might interfere with the working of pandocomatic processors and pandoc's filters. However, if you want, you can force pandocomatic to adhere to the template and pass on the "--verbose" option to pandoc by using command-line option --enable pandoc-verbose.