  
  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.

  -t TEMPLATE, --template TEMPLATE
                  Use given TEMPLATE for conversion. TEMPLATE should be
                  defined in pandocomatic's configuration hierarchy. TEMPLATE
                  will override any internal template. More so pandocomatic 
                  configuration in YAML block will be ignored.

                  Only allowed when converting files; option not allowed when
                  converting directories.

                  You can use this option multiple times. For each given 
                  TEMPLATE a separate conversion is run. Duplicate TEMPLATEs
                  are ignored.

  -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—2025 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/>.
