Pandocomatic. Automate the use of pandoc to convert files or directories.

USAGE

pandocomatic options [INPUT]

DESCRIPTION

Automate the use of pandoc. Either converts a single file or a directory
tree. Configure the conversion process through configuration files.  Each
input file that is converted by pandocomatic is processed as follows:

  setup(0) ... setup(K)
  input_file -> 
    preprocessor(0) -> ... -> preprocessor(N) ->
      pandoc -> 
        postprocessor(0) -> ... -> postprocessor(M) -> 
          output_file
  cleanup(0) ... cleanup(L)

The setup and cleanup scripts are run before and after the conversion
process, respectively. The preprocessors and postprocessors used in the
conversion process are configured in pandocomatic templates. Besides
processors, you can also specify pandoc options to use to convert the input
file. These templates are specified in a configuration file. Templates can
be used over and over, thus automating the use of pandoc.

OPTIONS

Required:

-i PATH, --input PATH
                Convert PATH. If this option is not given, INPUT is
                converted. INPUT and --input cannot be used together.
                You can use this option multiple times, denoting to 
                concatenate each input file in the order they
                are specified on the command-line. Pandocomatic treats 
                the concatenated files as a single input file.

Optional:

-o PATH, --output PATH
                Create converted files and directories in PATH. Cannot be
                used together with the `--stdout` option.

-s, --stdout
                Write the converted files to STDOUT. Cannot be used when
                converting directories, nor in combination with the
                `--output` option.

-d PATH, --data-dir PATH
                Configure pandocomatic to use PATH as its data directory.
                Default is PANDOC's data dir. (See `pandoc --version` to
                find PANDOC's data dir.)

-c PATH, --config PATH
                Configure pandocomatic to use PATH as its configuration file
                to use during the conversion process. Default is
                DATA_DIR/pandocomatic.yaml.

                Configuration files are YAML files and can contain the
                following properties:

                - data-dir: PATH (see --data-dir option)

                - settings:
                  - skip: [GLOB PATTERNS] files to not convert. By default
                    hidden files (starting with a ".") and
                    "pandocomatic.yaml" are skipped.
                  - recursive: BOOLEAN convert this directory recursively.
                    Default is TRUE
                  - follow_links: BOOLEAN follow symbolic links. Default is
                    TRUE

                - templates:
                  - cleanup: [SCRIPTS] paths to scripts to run after a
                    conversion is finished, i.e. after the last
                    postprocessor is run.
                  - glob: [GLOB PATTERNS] files to convert using this
                    template.
                  - setup: [SCRIPTS] paths to scripts to run before a
                    conversion is started, i.e. before any preprocessor is
                    run.
                  - metadata: [YAML properties] metadata properties
                  - preprocessors: [SCRIPTS] paths to scripts to run before
                    converting with pandoc.
                  - postprocessors: [SCRIPTS] paths to scripts to run after
                    converting with pandoc.
                  - pandoc: PANDOC OPTIONS to use when converting with
                    pandoc.

                Each file and directory that is converted can contain a
                configuration YAML metadata block or YAML configuration file
                respectively. In a file, the property 'use-template' tells
                pandocomatic which template to use.

-m, --modified-only

                Only convert files that have been modified. Only source files
                that have been updated later than the corresponding
                destination files will be converted, copied, or linked.
                Default is FALSE.

-V, --verbose   Run pandocomatic verbosely. Default is FALSE. Pandocomatic
                runs quietly unless the verbose, or dry-run options are given.

-y, --dry-run   Configure pandocomatic to run the conversion process, but do
                not actually run it. Default is FALSE. When using this
                dry-run option, pandocomatic runs verbosely.

-r PATH, --root-path PATH  
                Set the root path to use with paths that are specified as
                relative to that root path. It is used mostly with the 
                --css pandoc option. It defaults to the directory of the
                specified output.

-e FEATURE, --enable FEATURE
                Enable FEATURE in pandocomatic. Pandocomatic supports the
                following feature toggles:

                - "pandoc-verbose" to enable using pandoc's verbose option.
                  By default pandocomatic removes that verbose option
                  because it can interfere with running pandoc filters or
                  pandocomatic processors.

Logging:

-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.

Common:

-v, --version   Show the version. If this option is used, all other options
                are ignored.

-h, --help      Show this help. If this options is used, all other options
                but --version are ignored.

EXAMPLE:

Convert `hello.md` to `hello.html` according to the configuration in
`pandocomatic.yaml`:

  pandocomatic --config pandocomatic.yaml -o hello.html -i hello.md

Generate a static site using data directory `assets`:

  pandocomatic --data-dir assets/ -o website/ -i source/

SEE ALSO

- Pandocomatic's manual
  https://heerdebeer.org/Software/markdown/pandocomatic/

- Pandoc's user guide
  https://pandoc.org/MANUAL.html

- YAML website
  https://yaml.org/

AUTHOR

Huub de Beer <huub@heerdebeer.org>

LICENSE

Copyright 2014—2024 Huub de Beer <huub@heerdebeer.org>

Pandocomatic is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

Pandocomatic is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License along
with pandocomatic.  If not, see <http://www.gnu.org/licenses/>.