diff --git a/docs/extensions/lua-api.qmd b/docs/extensions/lua-api.qmd index 83267e378..51ad4a8d9 100644 --- a/docs/extensions/lua-api.qmd +++ b/docs/extensions/lua-api.qmd @@ -20,14 +20,14 @@ To get started with programming in Lua and learn about some recommended tools an The Lua standard library provides core functions for low-level string, math, table, and file operations. Here we provide links to a few of the more useful standard libaries (complete documentation can be found in the [Lua Reference Manual](https://www.lua.org/manual/5.3/)). -| Library | Description | +| Library | Description | |---------------------------------|---------------------------------------| -| [string](https://www.lua.org/manual/5.3/manual.html#6.4) | This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. | -| [utf8](https://www.lua.org/manual/5.3/manual.html#6.5) | This library provides basic support for UTF-8 encoding. | -| [table](https://www.lua.org/manual/5.3/manual.html#6.6) | This library provides generic functions for table manipulation. | -| [math](https://www.lua.org/manual/5.3/manual.html#6.7) | This library provides basic mathematical functions. | +| [string](https://www.lua.org/manual/5.3/manual.html#6.4) | This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. | +| [utf8](https://www.lua.org/manual/5.3/manual.html#6.5) | This library provides basic support for UTF-8 encoding. | +| [table](https://www.lua.org/manual/5.3/manual.html#6.6) | This library provides generic functions for table manipulation. | +| [math](https://www.lua.org/manual/5.3/manual.html#6.7) | This library provides basic mathematical functions. | | [io](https://www.lua.org/manual/5.3/manual.html#6.8), [file](https://www.lua.org/manual/5.3/manual.html#6.8) | The I/O library provides two different styles for file manipulation: one uses implicit file handles and the other explicit handles. | -| [os](https://www.lua.org/manual/5.3/manual.html#6.9) | Date/time, locales, environment variables, etc. | +| [os](https://www.lua.org/manual/5.3/manual.html#6.9) | Date/time, locales, environment variables, etc. | : {tbl-colwidths="\[30,70\]"} @@ -35,18 +35,18 @@ The Lua standard library provides core functions for low-level string, math, tab Complete documentation for the Pandoc Lua API can be found in the [Lua Filters](https://pandoc.org/lua-filters.html) article available on the Pandoc website. Here are the various components of the API along with links to their reference documentation: -| Lua Module | Description | +| Lua Module | Description | |--------------------------|----------------------------------------------| -| [pandoc](https://pandoc.org/lua-filters.html#module-pandoc) (ast) | Constructors for document tree elements (e.g. `pandoc.Div()`, `pandoc.Strong()`, etc.) as well as core components (e.g. `pandoc.Attr()`) | -| [pandoc](https://pandoc.org/lua-filters.html#helper-functions) (functions) | Functions to parse text in a given format, filter and modify a sub-tree, and run child processes. | -| [pandoc.text](https://pandoc.org/lua-filters.html#module-text) | UTF-8 aware text manipulation functions (e.g. `upper()`, `lower()`, etc.) | -| [pandoc.List](https://pandoc.org/lua-filters.html#module-pandoc.list) | This module defines pandoc's list type. It comes with useful methods and convenience function (e.g `find_if()`, `includes()`, `filter()`, `map()`, etc.) | -| [pandoc.utils](https://pandoc.org/lua-filters.html#module-pandoc.utils) | Internal pandoc functions and utility functions (e.g. `blocks_to_inlines()`, `stringify()`, `citeproc()`, etc.) | -| [pandoc.path](https://pandoc.org/lua-filters.html#module-pandoc.path) | Module for file path manipulations (e.g. `is_absolute()`, `is_relative()`, `join()`, etc. | -| [pandoc.system](https://pandoc.org/lua-filters.html#module-pandoc.system) | Access to system information and functionality (e.g. `get_working_directory()`, `list_directory()`, etc. | +| [pandoc](https://pandoc.org/lua-filters.html#module-pandoc) (ast) | Constructors for document tree elements (e.g. `pandoc.Div()`, `pandoc.Strong()`, etc.) as well as core components (e.g. `pandoc.Attr()`) | +| [pandoc](https://pandoc.org/lua-filters.html#helper-functions) (functions) | Functions to parse text in a given format, filter and modify a sub-tree, and run child processes. | +| [pandoc.text](https://pandoc.org/lua-filters.html#module-text) | UTF-8 aware text manipulation functions (e.g. `upper()`, `lower()`, etc.) | +| [pandoc.List](https://pandoc.org/lua-filters.html#module-pandoc.list) | This module defines pandoc's list type. It comes with useful methods and convenience function (e.g `find_if()`, `includes()`, `filter()`, `map()`, etc.) | +| [pandoc.utils](https://pandoc.org/lua-filters.html#module-pandoc.utils) | Internal pandoc functions and utility functions (e.g. `blocks_to_inlines()`, `stringify()`, `citeproc()`, etc.) | +| [pandoc.path](https://pandoc.org/lua-filters.html#module-pandoc.path) | Module for file path manipulations (e.g. `is_absolute()`, `is_relative()`, `join()`, etc. | +| [pandoc.system](https://pandoc.org/lua-filters.html#module-pandoc.system) | Access to system information and functionality (e.g. `get_working_directory()`, `list_directory()`, etc. | | [pandoc.mediabag](https://pandoc.org/lua-filters.html#module-pandoc.mediabag) | Access to pandoc's media storage. The "media bag" is used when pandoc is called with the `--extract-media` or (for HTML only) `--embed-resources` option. | -| [pandoc.template](https://pandoc.org/lua-filters.html#module-pandoc.template) | Compile and access defualt pandoc templates (e.g. `compile()`) | -| [pandoc.types](https://pandoc.org/lua-filters.html#module-pandoc.types) | Constructors for types which are not part of the pandoc AST (e.g. `Version()`) | +| [pandoc.template](https://pandoc.org/lua-filters.html#module-pandoc.template) | Compile and access defualt pandoc templates (e.g. `compile()`) | +| [pandoc.types](https://pandoc.org/lua-filters.html#module-pandoc.types) | Constructors for types which are not part of the pandoc AST (e.g. `Version()`) | : {tbl-colwidths="\[30,70\]"} @@ -56,10 +56,10 @@ Complete documentation for the Pandoc Lua API can be found in the [Lua Filters]( Various utility functions are provided: -| Function | Description | -|-------------------|-----------------------------------------------------| -| `quarto.version` | Return the current Quarto version as a `pandoc.Version` object. | -| `quarto.log.output(obj)` | Dump a text representation of the passed object to stdout. | +| Function | Description | +|--------------------|----------------------------------------------------| +| `quarto.version` | Return the current Quarto version as a `pandoc.Version` object. | +| `quarto.log.output(obj)` | Dump a text representation of the passed object to stdout. | | `quarto.utils.resolve_path(path)` | Compute the full path to a file that is installed alongside your extension's Lua script. This is useful for *internal* resources that your filter needs but should not be visible to the user. | Quarto includes the [pandoc-lua-logging](https://github.com/wlupton/pandoc-lua-logging) library, which should be used in preference to the dump function. For example, you can examine an element passed to a filter function as follows: @@ -74,9 +74,9 @@ end Extensions will often need to detect the current format to create custom content depending on the target output medium. The `quarto.doc.is_format()` function -| Function | Description | -|-------------------|-----------------------------------------------------| -| `quarto.doc.is_format(name)` | Detect if the current format matches `name`. | +| Function | Description | +|--------------------|----------------------------------------------------| +| `quarto.doc.is_format(name)` | Detect if the current format matches `name`. | | `quarto.doc.has_bootstrap()` | Query whether [Bootstrap CSS](https://getbootstrap.com/) is available within the current document (it is by default for standard `html` documents but this may have been overridden by e.g. `theme: none`). | 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. The following values format aliases are handled specially by `quarto.doc.is_format()`: @@ -97,26 +97,26 @@ end For LaTeX output, you may need to additionally detect which citation utility and pdf engine are being used for the current render. You can use these functions to do that detection: -| Function | Description | -|--------------------|----------------------------------------------------| -| `quarto.doc.cite_method()` | Returns a string (`citeproc`, `natbib`, or `biblatex)` indicating the cite method in use. | -| `quarto.doc.pdf_engine()` | Returns a string (`pdflatex`, `xelatex`, `lualatex`, or `tectonic`) indicating the PDF engine being used to render the document. | +| Function | Description | +|---------------------|---------------------------------------------------| +| `quarto.doc.cite_method()` | Returns a string (`citeproc`, `natbib`, or `biblatex)` indicating the cite method in use. | +| `quarto.doc.pdf_engine()` | Returns a string (`pdflatex`, `xelatex`, `lualatex`, or `tectonic`) indicating the PDF engine being used to render the document. | ### Includes Sometimes extensions need to inject content into the target document. There are three locations that content can be included (pass one of these locations as the first argument of the include functions): -| Location | Description | -|--------------------|----------------------------------------------------| -| `in-header` | In the header of the document (HTML `` tag or LaTeX preamble) | -| `before-body` | Before the document body | -| `after-body` | After the document body | +| Location | Description | +|---------------------|---------------------------------------------------| +| `in-header` | In the header of the document (HTML `` tag or LaTeX preamble) | +| `before-body` | Before the document body | +| `after-body` | After the document body | Note that the included content should use the *raw target format* (e.g. HTML or LaTeX) rather than markdown. You can use these functions to include text or the contents of a file: -| Function | Description | -|--------------------|----------------------------------------------------| -| `quarto.doc.include_text(location, text)` | Include text at the specified location (`in-header`, `before-body`, or `after-body`) | +| Function | Description | +|---------------------|---------------------------------------------------| +| `quarto.doc.include_text(location, text)` | Include text at the specified location (`in-header`, `before-body`, or `after-body`) | | `quarto.doc.include_file(location, file)` | 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. | For example the following code includes an HTML file after the body in the rendered document: @@ -129,12 +129,12 @@ quarto.doc.include_file("after-body", "comments.html") Extensions will sometimes want to add external dependencies (for example, a JavaScript library and related CSS, or the usage of a LaTeX package). This can be accomplished with the following functions: -| Function | Description | -|-------------------|-----------------------------------------------------| -| `quarto.doc.add_html_dependency(dep)` | Add an HTML dependency (additional resources and content) to a document. See docs on the [HTML Dependencies](#html-dependencies) below for additional details. | -| `quarto.doc.attach_to_dependency(name, attach)` | Attach a file to an existing dependency. `attach` is a file path relative to the Lua filter or table with \`path\` and \`name\` for renaming the file as its copied. | -| `quarto.doc.use_latex_package(pkg, opt)` | Adds a `\usepackage` statement to the LaTeX output (along an options string specified in `opt`) | -| `quarto.doc.add_format_resource(path)` | Add a format resource to the document. Format resources will be copied into the directory next to the rendered output. This is useful, for example, if your format references a `bst` or `cls` file which must be copied into the LaTeX output directory. | +| Function | Description | +|--------------------|----------------------------------------------------| +| `quarto.doc.add_html_dependency(dep)` | Add an HTML dependency (additional resources and content) to a document. See docs on the [HTML Dependencies](#html-dependencies) below for additional details. | +| `quarto.doc.attach_to_dependency(name, attach)` | Attach a file to an existing dependency. `attach` is a file path relative to the Lua filter or table with \`path\` and \`name\` for renaming the file as its copied. | +| `quarto.doc.use_latex_package(pkg, opt)` | Adds a `\usepackage` statement to the LaTeX output (along an options string specified in `opt`) | +| `quarto.doc.add_format_resource(path)` | Add a format resource to the document. Format resources will be copied into the directory next to the rendered output. This is useful, for example, if your format references a `bst` or `cls` file which must be copied into the LaTeX output directory. | For example, here we add a LaTeX package dependency: @@ -148,17 +148,17 @@ HTML Dependencies can bundle together JavaScript, CSS, and even arbitrary conten The `dep` object passed to `quarto.doc.add_html_dependency()` has the following fields: -| Field | Description | -|-------------------|-----------------------------------------------------| -| `name` | Unique name. Required. | -| `version` | Version number (as a string). Required. | -| `scripts` | List of scripts to include (paths can be absolute or relative to the Lua file calling the function). Scripts can be either a simple path or a [script object](#script-object). | -| `stylesheets` | List of CSS style-sheets to include (paths can be absolute or relative to the Lua file calling the function). Stylesheets can either be a simple path or a [stylesheet object](#stylesheet-object) | -| `links` | List of link tags to add to the document. Each tag should be a table with `rel` and `ref` (required) and optionally `type` | -| `resources` | Additional files to copy to the input directory (each resource is an object with `name` (target file name in input directory) and `path` (source file name relative to Lua script). | -| `serviceworkers` | JavaScript serviceworker files that should be copied to the root output directory (can be a simple string file name or table with \`path\` and \`name\` for renaming the file as its copied). | -| `meta` | Table of optional `key = value` meta tags to insert into the document `` | -| `head` | Arbitrary string to include in document `` | +| Field | Description | +|--------------------|----------------------------------------------------| +| `name` | Unique name. Required. | +| `version` | Version number (as a string). Required. | +| `scripts` | List of scripts to include (paths can be absolute or relative to the Lua file calling the function). Scripts can be either a simple path or a [script object](#script-object). | +| `stylesheets` | List of CSS style-sheets to include (paths can be absolute or relative to the Lua file calling the function). Stylesheets can either be a simple path or a [stylesheet object](#stylesheet-object) | +| `links` | List of link tags to add to the document. Each tag should be a table with `rel` and `ref` (required) and optionally `type` | +| `resources` | Additional files to copy to the input directory (each resource is an object with `name` (target file name in input directory) and `path` (source file name relative to Lua script). | +| `serviceworkers` | JavaScript serviceworker files that should be copied to the root output directory (can be a simple string file name or table with \`path\` and \`name\` for renaming the file as its copied). | +| `meta` | Table of optional `key = value` meta tags to insert into the document `` | +| `head` | Arbitrary string to include in document `` | For example, here we add a dependency to a JavaScript library: @@ -175,10 +175,10 @@ quarto.doc.add_html_dependency({ The easiest way to specify `scripts` is with simple paths. However, in some cases you may need to add attributes to the `