---@meta

quarto.doc = {}

---@type string Full path to input file for the current render
quarto.doc.input_file = ""

---@type string Full path to output file for the current render
quarto.doc.output_file = ""

--[[
Add an HTML dependency (additional resources and content) to a document. 

HTML Dependencies can bundle together JavaScript, CSS, and even arbitrary content
to inject into the `<head>` of the document. These dependencies have a `name` and
a `version`, which is used to ensure that the same dependency isn’t bundled into 
the document more than once.

See the documentation on [HTML Dependencies](https://quarto.org/docs/extensions/lua.html#html-dependencies) in Quarto Extensions for additional details.
]]
---@param dependency table Dependency object (see [HTML Dependency](https://quarto.org/docs/extensions/lua.html#html-dependencies))
function quarto.doc.add_html_dependency(dependency) end

--[[
Include a file within the output directory for an HTML dependency
]]
---@param name string HTML dependency name
---@param file string|{ path: string, name: string } File path relative to Lua filter or table with `path` and `name` for renaming the file as its copied.
function quarto.doc.attach_to_dependency(name, file) end

--[[
Adds a `\usepackage` statement to the LaTeX output

If appropriate, include package options using the `options` parameter.
]]
---@param package string LaTeX package name
---@param options? string (Optional) LaTeX package options
function quarto.doc.use_latex_package(package, options) end

--[[
Add a format resource to the document. The path to the file should relative to the Lua script calling this function.

Format resources will be copied into the directory next 
to the rendered file. This is useful, for example, if your format references a bst or cls file 
which must be copied into the LaTeX output directory.
]]
---@param file string Format resource file (relative path from Lua script)
function quarto.doc.add_format_resource(file) end

--[[
Add a resource file to the document. The file will be copied to the same
relative location in the output directory.

The path should be relative to the Lua script calling this function.
]]
---@param path string Resource file path (relative to Lua script)
function quarto.doc.add_resource(path) end

--[[
Add a supporting file to the document. Supporting files are moved to the
output directory and may be cleaned up after rendering.

The path should be relative to the Lua script calling this function.
]]
---@param path string Supporting file path (relative to Lua script)
function quarto.doc.add_supporting(path) end

--[[
Include text at the specified location (`in-header`, `before-body`, or `after-body`).
]]
---@param location 'in-header'|'before-body'|'after-body' Location for include
---@param text string Text to include
function quarto.doc.include_text(location, text) end

--[[
Include file at the specified location (`in-header`, `before-body`, or `after-body`). 

The path to the file should relative to the Lua script calling this function.
]]
---@param location 'in-header'|'before-body'|'after-body' Location for include
---@param file string File to include (relative path from Lua script)
function quarto.doc.include_file(location, file) end


--[[
Detect if the current format matches `name`

The name parameter can match an exact Pandoc format name (e.g. `docx`, `latex`, etc. or can match
based on an alias that groups commonly targeted formats together. Aliases include:

- **latex**: `latex`, `pdf`
- **pdf**: `latex`, `pdf`
- **epub**: `epub*`
- **html**: `html*`, `epub*`, `revealjs`
- **html:js**: `html*`, `revealjs`
- **markdown**: `markdown*`, `commonmark*`, `gfm`, `markua`

Note that the `html:js` alias indicates that the target format is capable of executing JavaScript (this maps to all HTML formats save for ePub).
]]
---@param name string Format name or alias
---@return boolean 
function quarto.doc.is_format(name) end

--[[
Cite method (`citeproc`, `natbib`, or `biblatex`) for the current render
]]
---@return 'citeproc'|'natbib'|'biblatex'
function quarto.doc.cite_method() end

--[[
PDF engine (e.g. `pdflatex`) for the current render
]]
---@return string
function quarto.doc.pdf_engine() end

--[[
Does the current output format include Bootstrap themed HTML
]]
---@return boolean
function quarto.doc.has_bootstrap() end

--[[
Check whether a specific internal Quarto filter is currently active.
]]
---@param filter string Filter name to check
---@return boolean
function quarto.doc.is_filter_active(filter) end

--[[
Provides the project relative path to the current input
if this render is in the context of a project (otherwise `nil`)
]]
---@return string|nil
function quarto.doc.project_output_file() end

--[[
Returns the current file metadata state for book projects.

This provides access to book-specific information like the current file's
role in the book structure. The returned table contains:
- `file`: Table with `bookItemType` ("chapter", "part", "appendix"),
  `bookItemNumber`, `bookItemDepth`, and `appendix` (boolean)
- `appendix`: Boolean indicating if currently in appendix section
- `include_directory`: Directory for includes

Note: This function requires `quarto.utils.file_metadata_filter()` to be
combined with your filter using `quarto.utils.combineFilters()` for the
metadata to be properly populated during traversal.
]]
---@return table|nil File metadata state or nil if not in a book context
function quarto.doc.file_metadata() end

--[[
Language settings for the current document.

Provides access to localized strings for document elements like section titles.
For example, `quarto.doc.language["section-title-appendices"]` returns the
localized title for the appendices section (e.g., "Appendices" in English).

Returns `nil` if no language settings are available.
]]
---@type table|nil
quarto.doc.language = nil

--[[
Cross-reference category definitions.

Provides access to all crossref categories including built-in types (figures,
tables, equations) and custom types defined by the document. Each category
includes properties like `ref_type`, `kind` ("float" or "Block"), and `name`.

Use `quarto.doc.crossref.categories.all` to iterate over all categories.

This is useful for extensions that need to generate counter resets or
other category-specific code dynamically.
]]
---@type table
quarto.doc.crossref = {}

---@type table[]
quarto.doc.crossref.categories = {}
