id       = "pandoc"
name     = "Pandoc"
since    = "3.0"
version_from = { command = ["pandoc", "--version"] }
homepage = "https://pandoc.org"
description = "Pandoc is a Haskell library for converting from one markup format to another, and a command-line tool that uses this library."
icon     = "SimpleIcons:pandoc"
executables   = ["pandoc"]

[dotfiles]

# pandoc(1), --data-dir: the user data directory is "$HOME/.local/share",
# overridable by setting the XDG_DATA_HOME environment variable. "If that
# directory does not exist and $HOME/.pandoc exists, it will be used (for
# backwards compatibility). On Windows the default user data directory is
# %APPDATA%\pandoc." `pandoc --version` prints the one in force, and on macOS
# it prints ~/.local/share/pandoc — so the Unix directory is [xdgData], the
# name that follows $XDG_DATA_HOME, and not [dataHome], which would be
# ~/Library/Application Support. ~/.pandoc is the backwards-compatible home
# dotfile and %APPDATA%\pandoc the Windows spelling, neither of which any base
# directory covers. Files placed there — reference.odt, reference.docx,
# epub.css, templates, filters and defaults files — override pandoc's built-in
# versions.
paths = [
  "[xdgData]/pandoc/",
  "~/.pandoc/",
  "%APPDATA%/pandoc/",
]

# Nothing in the data directory is cache: pandoc only reads it.

secret = []

# Re-read on every run — pandoc is a one-shot process with no resident state.
side_effect = false

# No machine_lines: templates, filters, styles and defaults files are the
# user's own document tooling. A defaults file can name an absolute
# --resource-path, but there is no key that is machine-local by definition, so
# no rule is invented for it.

[commands]
format = 1
features = ["standard_streams", "optional_values"]
label = "Convert document"
description = "Convert documents from files, pasted text or native standard input to a file or terminal output. Multiple inputs are combined into one output. PDF, filters, Lua, templates, citeproc and batch execution are outside this form."
quality = "curated"
base = "fig:pandoc"
required_capabilities = ["pandoc.list-formats"]
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.source]]
id = "pandoc-manual"
kind = "curated"
url = "https://pandoc.org/MANUAL.html"
revision = "2026-10-26"
evidence = "Pandoc User Guide: --from, --to, --output, --standalone, --toc, --reference-doc, input files and --list-input-formats/--list-output-formats. Only these declared fields are editable."

[[commands.field]]
id = "from"
label = "Input format"
description = "Leave unset to infer the format from the input filenames; otherwise use a Pandoc reader name."
type = "string"
option = ["--from", "-f", "--read", "-r"]
provider = "builtin:pandoc.input-formats"
suggestions = [{ value = "markdown", label = "Markdown" }, { value = "docx", label = "Word (DOCX)" }, { value = "html", label = "HTML" }]
observed_default = "inferred from input extensions"
sources = ["pandoc-manual"]

[[commands.field]]
id = "to"
label = "Output format"
description = "Leave unset to infer the format from the output filename. Candidates are suggestions; manual input remains available."
type = "string"
option = ["--to", "-t", "--write", "-w"]
provider = "builtin:pandoc.output-formats"
suggestions = [{ value = "docx", label = "Word (DOCX)" }, { value = "html5", label = "HTML" }, { value = "gfm", label = "GitHub-flavored Markdown" }, { value = "markdown", label = "Markdown" }]
observed_default = "inferred from output extension"
sources = ["pandoc-manual"]

[[commands.field]]
id = "output"
label = "Output file"
description = "Choose one output file, or leave unset / use - for terminal standard output. Multiple inputs are combined, not converted in a batch."
type = "path"
option = ["--output", "-o"]
path = { kind = "file", role = "output", must_exist = false, standard_stream = true }
effect = "overwrite"
sources = ["pandoc-manual"]

[[commands.field]]
id = "standalone"
label = "Standalone document"
description = "Include the header and footer appropriate to a complete document."
type = "boolean"
option = ["--standalone", "-s"]
arity = 1
value_optional = true
value_style = "equals"
choices = [{ value = true, label = "True" }, { value = false, label = "False" }]
sources = ["pandoc-manual"]

[[commands.field]]
id = "toc"
label = "Table of contents"
type = "boolean"
option = ["--toc", "--table-of-contents"]
arity = 1
value_optional = true
value_style = "equals"
choices = [{ value = true, label = "True" }, { value = false, label = "False" }]
sources = ["pandoc-manual"]

[[commands.field]]
id = "reference_doc"
label = "Reference DOCX"
description = "Use the styles from an existing DOCX document. Enabled for DOCX output."
type = "path"
option = ["--reference-doc"]
path = { kind = "file", role = "input", must_exist = true }
enabled_when = { any = [{ field = "to", op = "equals", value = "docx" }, { all = [{ not = { field = "to", op = "is_set" } }, { field = "output", op = "extension_in", values = ["docx"] }] }] }
sources = ["pandoc-manual"]

[[commands.field]]
id = "inputs"
label = "Input files"
description = "Files are read in this order and combined into one output. Leave unset or use - for native standard input; a real file named - must use ./- or an absolute path."
type = "path"
position = 0
multiple = true
path = { kind = "file", role = "input", must_exist = true, standard_stream = true, transforms = ["dot_slash_if_dash"] }
sources = ["pandoc-manual"]

[[commands.task]]
id = "to-docx"
label = "Markdown → Word"
set = { from = ["markdown"], to = ["docx"] }
lock = ["to"]
fields = ["inputs", "output", "from", "reference_doc", "standalone", "toc"]
required = []

[[commands.task]]
id = "to-html"
label = "Markdown → HTML"
set = { from = ["markdown"], to = ["html5"], standalone = [true] }
lock = ["to"]
fields = ["inputs", "output", "from", "standalone", "toc"]
required = []

[[commands.task]]
id = "to-markdown"
label = "Word → Markdown"
set = { from = ["docx"], to = ["gfm"] }
lock = ["from", "to"]
fields = ["inputs", "output", "standalone", "toc"]
required = []

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["inputs", "output", "from", "to", "standalone", "toc"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["reference_doc"]