diff --git a/_freeze/docs/authoring/cross-references/execute-results/html.json b/_freeze/docs/authoring/cross-references/execute-results/html.json index 4b62cfe54f..4063c013b6 100644 --- a/_freeze/docs/authoring/cross-references/execute-results/html.json +++ b/_freeze/docs/authoring/cross-references/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "ffcf92035b7827f0a64c166c735bb4d6", + "hash": "678be4a109d6af4187026ed14445bc84", "result": { "engine": "jupyter", - "markdown": "---\ntitle: \"Cross References\"\nformat: html\n---\n\n## Overview\n\nCross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables. Every cross-referenceable entity requires a label (unique identifier prefixed with type e.g. `#fig-element`) and caption (description). For example, this is a cross-referenceable figure:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n```\n\nThe presence of the caption (`Elephant`) and label (`#fig-elephant`) make this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document:\n\n``` markdown\nSee @fig-elephant for an illustration.\n```\n\nHere is what this would look like rendered to HTML:\n\n![](images/crossref-figure.png){.border fig-alt=\"A line drawing of an elephant. The caption 'Figure 1: Elephant' is centered beneath it.\" width=\"100%\"}\n\nQuarto enables you to create cross-references to figures, tables, equations, sections, code listings, theorems, proofs, and more. Cross references can also be applied to dynamic output from Knitr and Jupyter.\n\nNote that cross reference identifiers must start with their type (e.g. `fig-` or `tbl-`). So the identifier `#fig-elephant` is valid for a cross-reference but the identifiers `#elephant` and `#elephant-fig` are not.\n\nThere are options available that control the text used for titles and references. For example, you could change \"Figure 1\" to read \"Fig 1\" or \"fig. 1\". See the [options documentation](#options) for details on how to customize the text used for cross-references.\n\n::: {.callout-note style=\"padding-bottom: 16px\"}\nQuarto's syntax for cross-references is based on [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) (which is in turn based on this discussion: ). There are however several differences (mostly related to handling computational output) to note:\n\n1. Quarto uses the prefix `#fig-` rather than `#fig:` (which is more compatible with Jupyter notebook [cell ids](https://jupyter.org/enhancement-proposals/62-cell-id/cell-id.html)).\n2. Quarto is able to reference raw HTML and LaTeX figures and tables (which are often produced by executable code blocks).\n3. Quarto has support for referencing theorems and proofs (and related types).\n:::\n\n## Figures\n\nAs described above, this is the markdown used to create a cross-referenceable figure and then refer to it:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n\nSee @fig-elephant for an illustration.\n```\n\nNote again that cross-reference identifiers must start with their type (e.g. `#fig-`) and that cross-reference identifiers must be all lower case.\n\n### Subfigures\n\nYou may want to create a figure composed of multiple subfigures. To do this, enclose the figures in a div (with its own label and caption) and give each subfigure its own label and (optionally) caption. You can then refer to either the entire figure in a reference or a single subfigure:\n\n``` markdown\n::: {#fig-elephants layout-ncol=2}\n\n![Surus](surus.png){#fig-surus}\n\n![Hanno](hanno.png){#fig-hanno}\n\nFamous Elephants\n:::\n\nSee @fig-elephants for examples. In particular, @fig-hanno.\n```\n\nHere is what this looks like when rendered as HTML:\n\n![](images/crossref-subfigures.png){.preview-image .border fig-alt=\"An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption '(a) Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption '(b) Hanno.' The words 'Figure 1: Famous elephants' are centered beneath both pictures. The text 'See fig. 1 for examples. In particular, fig. 1(b).' is underneath this text and is aligned to the left.\" width=\"100%\"}\n\nNote that we also used the `layout-ncol` attribute to specify a two-column layout. See the article on [Figures](figures.qmd) for more details on laying out panels of figures.\n\n### Computations\n\nFigures produced by Jupyter and Knitr can also be cross-referenced. To do this, add a `label` and `fig-cap` option at the top of the code block. For example:\n\n::: panel-tabset\n#### Jupyter\n\n ```{{python}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-jupyter.png){fig-alt=\"A line plot with the label 'Figure 1: Plot' centered underneath it. The text 'For example, see fig. 1' is underneath this label and aligned to the left.\"}\n\n#### Knitr\n\n ```{{r}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n plot(cars)\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-r.png){fig-alt=\"A scatter plot of speed versus distance for the `cars` dataset. The label 'Figure 1: Plot' is centered beneath it. The text 'For example, see fig. 1' is aligned to the left underneath that.\"}\n:::\n\nYou can also create multiple figures within a code cell and reference them as subfigures. To do this use `fig-cap` for the main caption, and `fig-subcap` to provide an array of subcaptions. For example:\n\n ```{{python}}\n #| label: fig-plots\n #| fig-cap: \"Plots\" \n #| fig-subcap:\n #| - \"Plot 1\"\n #| - \"Plot 2\" \n #| layout-ncol: 2\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n\n plt.plot([8,65,23,90])\n plt.show()\n ```\n\n See @fig-plots for examples. In particular, @fig-plots-2.\n\n![](images/crossref-subfigures-jupyter.png){fig-alt=\"Two line plots side-by-side. The plot on the left has the caption '(a) Plot 1' centered underneath it. The plot on the right has the caption '(b) Plot 2' centered underneath it. The text 'Figure 1: Plots' is centered underneath both of these plots. The text 'See fig. 1 for examples. In particular, fig. 1(b)' is aligned to the left underneath that.\"}\n\nNote that subfigure reference labels are created automatically based on the main chunk label (e.g. `@fig-plots-1`, `@fig-plots-2`, etc.).\n\nIf you'd like subfigure captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `fig-subcap: true` rather than providing explicit subcaption text:\n\n```{{python}}\n#| label: fig-plots\n#| fig-cap: \"Plots\" \n#| fig-subcap: true\n#| layout-ncol: 2\n```\n\n## Tables\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable. For example:\n\n::: {#tbl-planets .cell tbl-cap='Planets' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Planets\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",696000,1989100000],\n [\"Earth\",6371,5973.6],\n [\"Moon\",1737,73.5],\n [\"Mars\",3390,641.85]]\nMarkdown(tabulate(\n table, \n headers=[\"Planet\",\"R (km)\", \"mass (x 10^29 kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nPlanet R (km) mass (x 10^29 kg)\n-------- -------- -------------------\nSun 696000 1.9891e+09\nEarth 6371 5973.6\nMoon 1737 73.5\nMars 3390 641.85\n:::\n:::\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\n\n\nFor markdown tables, add a caption below the table, then include a `#tbl-` label in braces at the end of the caption. For example:\n\n``` markdown\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: My Caption {#tbl-letters}\n\nSee @tbl-letters.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](images/crossref-table.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\n\n\n### Subtables\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n### Computations\n\nYou can also cross-reference tables created from code executed via computations. To do this, add the `label` and `tbl-cap` cell options. For example:\n\n```{{r}}\n#| label: tbl-iris\n#| tbl-cap: \"Iris Data\"\n\nlibrary(knitr)\nkable(head(iris))\n```\n\n![](/docs/authoring/images/crossref-table-knitr.png){fig-alt=\"Example table output.\" fig-align=\"center\" width=\"80%\"}\n\nYou can also create multiple tables within a code cell and reference them as subtables. To do this, add a `tbl-subcap` option with an array of subcaptions. For example:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap:\n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-knitr.png){fig-alt=\"Two tables side-by-side. Each table has 2 columns and 8 rows. The table on the left is titled '(a) Cars'. The table on the right is titled '(b) Pressure'. Centered underneath both tables is the text 'Table 1: Tables.'\" fig-align=\"center\" width=\"80%\"}\n\nIf you'd like subtable captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `tbl-subcap: true` rather than providing explicit subcaption text:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap: true\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-nocaption-knitr.png){fig-align=\"center\" width=\"80%\"}\n\n## Equations\n\nProvide an `#eq-` label immediately after an equation to make it referenceable. For example:\n\n``` markdown\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm C^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n```\n\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm S^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n\nNote that the equation number is included (via `\\qquad`) in the right margin of the equation.\n\n## Sections\n\nTo reference a section, add a `#sec-` identifier to any heading. For example:\n\n``` markdown\n## Introduction {#sec-introduction}\n\nSee @sec-introduction for additional context.\n```\n\nNote that when using section cross-references, you will also need to enable the `number-sections` option (so that section numbering is visible to readers). For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nnumber-sections: true\n---\n```\n\n## Code Listings\n\nTo create a reference-able code block, add a `#lst-` identifier along with a `lst-cap` attribute. For example:\n\n```` markdown\n```{#lst-customers .sql lst-cap=\"Customers Query\"}\nSELECT * FROM Customers\n```\n\nThen we query the customers database (@lst-customers).\n````\n\n::: {.callout-note}\n\nNote that code listings currently only work with _display code blocks_ (as opposed to executable code blocks). If you wish to both execute and reference a code block, use a combination of a display block and a code block with `echo: false` in the cell YAML.\n\n:::\n\n\n\n## Theorems and Proofs\n\nTheorems are commonly used in articles and books in mathematics. To include a reference-able theorem, create a div with a `#thm-` label (or one of other theorem-type labels described below). You also need to specify a theorem name either via the first heading in the block. You can include any content you like within the div. For example:\n\n``` markdown\n::: {#thm-line}\n\n## Line\n\nThe equation of any straight line, called a linear equation, can be written as:\n\n$$\ny = mx + b\n$$\n:::\n\nSee @thm-line.\n```\n\n![](images/crossref-theorem.png){fig-alt=\"A snippet of a LaTeX document. The first line reads: 'Thereom 1 (Line) The equation of any straight line, called a linear equation, can be written as:' Cenetered on a separate line is the equation 'y = mx + b'. The text 'See thm. 1' is aligned to the left underneath that.\"}\n\nFor LaTeX output, the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used for typesetting theorems. For other formats an appropriate treatment is used (the above is an example of HTML output).\n\nThere are a number of theorem variations supported, each with their own label prefix:\n\n| **Label Prefix** | **Printed Name** | **LaTeX Environment** |\n|------------------|------------------|-----------------------|\n| `#thm-` | Theorem | theorem |\n| `#lem-` | Lemma | lemma |\n| `#cor-` | Corollary | corollary |\n| `#prp-` | Proposition | proposition |\n| `#cnj-` | Conjecture | conjecture |\n| `#def-` | Definition | definition |\n| `#exm-` | Example | example |\n| `#exr-` | Exercise | exercise |\n\nThe `proof`, `remark`, and `solution` environments generally receive similar typesetting as theorems, however they are not numbered (and therefore cannot be cross-referenced). To create these environments just use them as the class name of a div:\n\n``` markdown\n::: {.solution}\nThe solution.\n:::\n```\n\nAs with theorems you can optionally include a heading as the first element of the div (or a `name` attribute) to give the environment a caption for typesetting (this typically appears in parentheses after the environment title).\n\nFor LaTeX output the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used to typeset these environments. For other formats a similar treatment is used, but you can further customizing this using CSS.\n\n## References\n\nThe examples above have all used the default syntax for inline references (e.g. `@fig-elephant`), which results in the reference text \"Figure 1\", \"Table 1\", etc.\n\nYou can customize the appearance of inline references by either changing the syntax of the inline reference or by setting options. Here are the various ways to compose a cross-reference and their resulting output:\n\n| Type | Syntax | Output |\n|---------------|-----------------------|----------|\n| Default | `@fig-elephant` | Figure 1 |\n| Capitalized | `@Fig-elephant` | Figure 1 |\n| Custom Prefix | `[Fig @fig-elephant]` | Fig 1 |\n| No Prefix | `[-@fig-elephant]` | 1 |\n\nNote that the capitalized syntax makes no difference for the default output, but would indeed capitalize the first letter if the default had been change via an option to use lower case (e.g. \"fig.\").\n\nYou can also group cross-references using the following syntax:\n\n``` markdown\nAs illustrated in [@fig-elephant; @fig-panther; @fig-rabbit].\n```\n\nThere are a number of options that can be used to further customize the treatment of cross-references. See the section below on [References Options](#references-1) for additional details.\n\n## Chapter Numbering\n\nYou can use the `crossref: chapters` option to indicate that top-level headings (H1) in your document correspond to chapters, and that cross-references should be sub-numbered by chapter. For example:\n\n``` markdown\n---\ntitle: \"My Document\"\nauthor: \"Jane Doe\"\nnumber-sections: true\ncrossref:\n chapters: true\n---\n\n# Introduction\n\n![Elephant](elephant.png){#fig-elephant}\n\nSee @fig-elephant for an illustration.\n```\n\n![](images/crossref-chapters.png){fig-alt=\"A line drawing of an elephant. Above it is the text '1 Introduction' in large, bold font. The label 'Figure 1.1: Elephant' is centered underneath it. The text 'See fig. 1.1 for an illustration' is aligned to the left underneath that.\"}\n\n## Lists\n\nFor LaTeX / PDF output, you can use the raw LaTeX commands `\\listoffigures`, `\\listoftables` and `\\listoflistings` to produce listings of all figures, tables, etc. within a document. You can use the `lof-title`, `lot-title`, and `lol-title` crossref options to customize the title of the listing.\n\nFor example:\n\n``` markdown\n---\ntitle: \"My Document\"\ncrossref:\n lof-title: \"List of Figures\"\nformat: pdf\n---\n\n\\listoffigures\n```\n\nNote that the default titles for the lists use the form displayed above (i.e. \"List of \\\").\n\n## Options {#options}\n\nThere are a wide variety of options available for customizing caption labels and references. These options are all specified within the `crossref` key of document metadata.\n\n::: {.callout-note appearance=\"simple\"}\nNote that since LaTeX does its own formatting and layout of figures and tables, not all of these options will apply when rendering to PDF. Specifically, delimiter options like `title-delim` and numbering options like `labels` don't work for PDF output. Additionally, formatting directives are not applied (e.g. italicizing the figure title) for LaTeX titles.\n:::\n\n### Titles\n\nYou can specify the title prefix used for captions using `*-title` options. You can also specify the delimiter used between the prefix and the caption using the `title-delim` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-title: Fig # (default is \"Figure\")\n tbl-title: Tbl # (default is \"Table\")\n title-delim: \"—\" # (default is \":\")\n---\n```\n\n### References {#references-1}\n\nYou can specify the prefix used for inline reference type using `*-prefix` options. You can also specify whether references should be hyper-linked using the `ref-hyperlink` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-prefix: figure # (default is \"Figure\")\n tbl-prefix: table # (default is \"Table\")\n ref-hyperlink: false # (default is true)\n---\n```\n\n### Numbering\n\nThere are a variety of numbering schemes available for cross-references, including:\n\n- `arabic` (1, 2, 3)\n\n- `roman` (I, II, III, IV)\n\n- `roman i` (i, ii, iii, iv)\n\n- `alpha x` (start from letter 'x')\n\n- `alpha X` (start from letter 'X')\n\nYou can specify the number scheme used for all types (other than sub-references) using the `labels` option. For sub-references (e.g. subfigures), you can specify the number scheme using the `subref-labels` option. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n labels: alpha a # (default is arabic)\n subref-labels: roman i # (default is alpha a)\n---\n```\n\nIf you would like, you can specify the number scheme for a specific type using the `*-labels` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\ncrossref:\n fig-labels: alpha a # (default is arabic)\n tbl-labels: alpha a # (default is arabic)\n subref-labels: roman i # (default is alpha a)\n---\n```\n\nIf both `labels` and a type specific label option is provided, the type specific option will override the `labels` option.\n\n", + "markdown": "---\ntitle: \"Cross References\"\nformat: html\ntoc-expand: 2\ntoc-depth: 4\naliases: \n - /docs/authoring/cross-references-listings.html\n - /docs/authoring/cross-references-callouts.html\n---\n\n## Overview\n\nCross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables. Every cross-referenceable entity requires a label---a unique identifier prefixed with a cross-reference type e.g. `#fig-element`. For example, this is a cross-referenceable figure:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n```\n\nThe presence of the label (`#fig-elephant`) makes this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document:\n\n``` markdown\nSee @fig-elephant for an illustration.\n```\n\nHere is what this would look like rendered to HTML:\n\n![](images/crossref-figure.png){.border fig-alt=\"A line drawing of an elephant. The caption 'Figure 1: Elephant' is centered beneath it.\" width=\"100%\"}\n\nNote that cross reference identifiers must start with their type (e.g. `fig-` or `tbl-`). So the identifier `#fig-elephant` is valid for a cross-reference but the identifiers `#elephant` and `#elephant-fig` are not.\n\nQuarto enables you to create cross-references to figures, tables, equations, sections, code listings, theorems, proofs, and more. Cross references can also be applied to dynamic output from Knitr and Jupyter. \n\nOn this page you'll learn:\n\n* Different ways to use the `@` syntax to create [References](#references).\n* How to add [Lists](#lists) of references in LaTeX / PDF output.\n\nThen, we enumerate the syntax for the different types of elements you might want to reference:\n\n* [Floats](#floats): [Figures](#figures), [Tables](#tables) and [Code Listings](#code-listings)\n* Blocks: [Callouts](#callouts), [Theorems and Proofs](#theorems-and-proofs) and [Equations](#equations) \n* [Sections](#sections)\n\nThere are options available that control the text used for titles and references. For example, you could change \"Figure 1\" to read \"Fig 1\" or \"fig. 1\". See the [options documentation](cross-reference-options.qmd) for details on how to customize the text used for cross-references.\n\n## References\n\nThe examples on this page all use the default syntax for inline references (e.g. `@fig-elephant`), which results in the reference text \"Figure 1\", \"Table 1\", etc.\n\nYou can customize the appearance of inline references by either changing the syntax of the inline reference or by setting options. Here are the various ways to compose a cross-reference and their resulting output:\n\n| Type | Syntax | Output |\n|---------------|-----------------------|----------|\n| Default | `@fig-elephant` | Figure 1 |\n| Capitalized | `@Fig-elephant` | Figure 1 |\n| Custom Prefix | `[Fig @fig-elephant]` | Fig 1 |\n| No Prefix | `[-@fig-elephant]` | 1 |\n\nNote that the capitalized syntax makes no difference for the default output, but would indeed capitalize the first letter if the default prefix had been changed via an [option](cross-reference-options.qmd#references) to use lower case (e.g. \"fig.\").\n\nThese syntax variations work not only for Figures, but for all cross-referenceable elements in Quarto such as Tables, Equations, Theorems, and so on.\n\nYou can also group cross-references using the following syntax:\n\n``` markdown\nAs illustrated in [@fig-elephant; @fig-panther; @fig-rabbit].\n```\n\nThere are a number of options that can be used to further customize the treatment of cross-references. See the guide on [Cross Reference Options](cross-reference-options.qmd#references) for additional details.\n\n## Lists\n\nFor LaTeX / PDF output, you can use the raw LaTeX commands `\\listoffigures`, `\\listoftables` and `\\listoflistings` to produce listings of all figures, tables, etc. within a document. You can use the `lof-title`, `lot-title`, and `lol-title` crossref options to customize the title of the listing.\n\nFor example:\n\n``` markdown\n---\ntitle: \"My Document\"\ncrossref:\n lof-title: \"List of Figures\"\nformat: pdf\n---\n\n\\listoffigures\n```\n\nNote that the default titles for the lists use the form displayed above (i.e. \"List of \\\").\n\n## Floats\n\n[Figures](#figures), [tables](#tables) and [code listings](#code-listings) are known as \"float\" cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions. \n\nIn addition to the compact syntax for the most common uses of float cross-references, you can also define float cross-references with a div syntax. Use the div syntax when you need more flexibility in the content of your cross-reference, for example, to have a [video](cross-references-divs.qmd#videos) be referenced as a figure. Basic examples of the div syntax are included in the sections below, but you can find more complicated examples in [Cross-Reference Div Syntax](cross-references-divs.qmd). \n\nYou can also define custom types of float cross-reference to reference elements beyond figures, tables and code listings. Read more at [Custom Float Cross-References](cross-references-custom.qmd).\n\n\n### Figures\n\nAs described on the Overview above, this is the markdown used to create a cross-referenceable figure and then refer to it:\n\n``` markdown\n![Elephant](elephant.png){#fig-elephant}\n\nSee @fig-elephant for an illustration.\n```\n\nNote again that cross-reference identifiers must start with their type (e.g. `#fig-`) and that cross-reference identifiers must be all lower case.\n\nTo create a cross-reference to a figure using div syntax, create a fenced div with an id starting with `fig-`, include the image followed by the caption inside the div:\n\n````markdown\n::: {#fig-elephant}\n\n![](elephant.png)\n\nAn Elephant\n:::\n````\n\n\n\nYou can read about using div syntax with figures at [Cross-Reference Div Syntax](cross-references-divs.qmd#figures).\n\n#### Subfigures\n\nYou may want to create a figure composed of multiple subfigures. To do this, enclose the figures in a div (with its own label and caption) and give each subfigure its own label and (optionally) caption. You can then refer to either the entire figure in a reference or a single subfigure:\n\n``` markdown\n::: {#fig-elephants layout-ncol=2}\n\n![Surus](surus.png){#fig-surus}\n\n![Hanno](hanno.png){#fig-hanno}\n\nFamous Elephants\n:::\n\nSee @fig-elephants for examples. In particular, @fig-hanno.\n```\n\nHere is what this looks like when rendered as HTML:\n\n![](images/crossref-subfigures.png){.preview-image .border fig-alt=\"An artistic rendition of Surus, Hannibal's last war elephant, is on the left. Underneath this picture is the caption '(a) Surus.' On the right is a line drawing of Hanno, a famous elephant. Underneath this picture is the caption '(b) Hanno.' The words 'Figure 1: Famous elephants' are centered beneath both pictures. The text 'See fig. 1 for examples. In particular, fig. 1(b).' is underneath this text and is aligned to the left.\" width=\"100%\"}\n\nNote that we also used the `layout-ncol` attribute to specify a two-column layout. See the article on [Figures](figures.qmd) for more details on laying out panels of figures.\n\n#### Computations\n\nFigures produced by Jupyter and Knitr can also be cross-referenced. To do this, add a `label` and `fig-cap` option at the top of the code block. For example:\n\n::: panel-tabset\n##### Jupyter\n\n ```{{python}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-jupyter.png){fig-alt=\"A line plot with the label 'Figure 1: Plot' centered underneath it. The text 'For example, see fig. 1' is underneath this label and aligned to the left.\"}\n\n##### Knitr\n\n ```{{r}}\n #| label: fig-plot\n #| fig-cap: \"Plot\"\n\n plot(cars)\n ```\n\n For example, see @fig-plot.\n\n![](images/crossref-figure-r.png){fig-alt=\"A scatter plot of speed versus distance for the `cars` dataset. The label 'Figure 1: Plot' is centered beneath it. The text 'For example, see fig. 1' is aligned to the left underneath that.\"}\n:::\n\nYou can also create multiple figures within a code cell and reference them as subfigures. To do this use `fig-cap` for the main caption, and `fig-subcap` to provide an array of subcaptions. For example:\n\n ```{{python}}\n #| label: fig-plots\n #| fig-cap: \"Plots\" \n #| fig-subcap:\n #| - \"Plot 1\"\n #| - \"Plot 2\" \n #| layout-ncol: 2\n\n import matplotlib.pyplot as plt\n plt.plot([1,23,2,4])\n plt.show()\n\n plt.plot([8,65,23,90])\n plt.show()\n ```\n\n See @fig-plots for examples. In particular, @fig-plots-2.\n\n![](images/crossref-subfigures-jupyter.png){fig-alt=\"Two line plots side-by-side. The plot on the left has the caption '(a) Plot 1' centered underneath it. The plot on the right has the caption '(b) Plot 2' centered underneath it. The text 'Figure 1: Plots' is centered underneath both of these plots. The text 'See fig. 1 for examples. In particular, fig. 1(b)' is aligned to the left underneath that.\"}\n\nNote that subfigure reference labels are created automatically based on the main chunk label (e.g. `@fig-plots-1`, `@fig-plots-2`, etc.).\n\nIf you'd like subfigure captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `fig-subcap: true` rather than providing explicit subcaption text:\n\n```{{python}}\n#| label: fig-plots\n#| fig-cap: \"Plots\" \n#| fig-subcap: true\n#| layout-ncol: 2\n```\n\n### Tables\n\n\n\nFor markdown tables, add a caption below the table, then include a `#tbl-` label in braces at the end of the caption. For example:\n\n``` markdown\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: My Caption {#tbl-letters}\n\nSee @tbl-letters.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](images/crossref-table.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\n\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\nTo create a cross-reference to a table using div syntax, create a fenced div with an id starting with `tbl-`, include the table followed by the caption inside the div:\n\n````markdown\n::: {#tbl-letters}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\nMy Caption\n\n::: \n````\n\n\n\nYou can read more about using div syntax with tables at [Cross-Reference Div Syntax](cross-references-divs.qmd#tables).\n\n#### Subtables\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n#### Computations\n\nYou can also cross-reference tables created from code executed via computations. To do this, add the `label` and `tbl-cap` cell options. For example:\n\n```{{r}}\n#| label: tbl-iris\n#| tbl-cap: \"Iris Data\"\n\nlibrary(knitr)\nkable(head(iris))\n```\n\n![](/docs/authoring/images/crossref-table-knitr.png){fig-alt=\"Example table output.\" fig-align=\"center\" width=\"80%\"}\n\nYou can also create multiple tables within a code cell and reference them as subtables. To do this, add a `tbl-subcap` option with an array of subcaptions. For example:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap:\n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-knitr.png){fig-alt=\"Two tables side-by-side. Each table has 2 columns and 8 rows. The table on the left is titled '(a) Cars'. The table on the right is titled '(b) Pressure'. Centered underneath both tables is the text 'Table 1: Tables.'\" fig-align=\"center\" width=\"80%\"}\n\nIf you'd like subtable captions that include only an identifier, e.g. \"(a)\", and not a text caption, then specify `tbl-subcap: true` rather than providing explicit subcaption text:\n\n```{{r}}\n#| label: tbl-tables\n#| tbl-cap: \"Tables\"\n#| tbl-subcap: true\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n\n![](/docs/authoring/images/crossref-subtable-nocaption-knitr.png){fig-align=\"center\" width=\"80%\"}\n\n\n### Code Listings\n\nTo create a reference-able code block, add a `#lst-` identifier along with a `lst-cap` attribute. For example:\n\n```` markdown\n```{#lst-customers .sql lst-cap=\"Customers Query\"}\nSELECT * FROM Customers\n```\n\nThen we query the customers database (@lst-customers).\n````\n\nTo create a cross-reference to a code listing using div syntax, create a fenced div with an id starting with `lst-`, include the code cell followed by the caption inside the div: \n\n````markdown\n::: {#lst-customers}\n\n```{.sql}\nSELECT * FROM Customers\n```\n\nCustomers Query\n\n:::\n````\n\n\n\nYou can read more about using div syntax for code listings in [Cross-Reference Div Syntax](cross-references-divs.qmd).\n\nTo cross-reference code from an executable code block, add the code cell options `lst-label` and `lst-cap`. The option `lst-label` provides the cross reference identifier and must begin with the prefix `lst-` to be treated as a code listing. The value of `lst-cap` provides the caption for the code listing. For example:\n\n````{.markdown}\n```{{python}}\n#| lst-label: lst-import\n#| lst-cap: Import pyplot\n\nimport matplotlib.pyplot as plt\n```\n\n@lst-import...\n````\n\nWhen rendered, this results in the following:\n\n::: {.border .p-3}\n\n::: {#ac1ae5a3 .cell execution_count=1}\n``` {#lst-import .python .cell-code lst-cap=\"Import pyplot\"}\nimport matplotlib.pyplot as plt\n```\n:::\n\n\n@lst-import...\n\n:::\n\nIf the code cell produces a figure or table, you can combine the `lst-` options with `label` and `fig-cap`/`tbl-cap` to create cross references to both the code and output:\n\n````{.markdown}\n```{{python}}\n#| label: fig-plot\n#| fig-cap: Figure caption\n#| lst-label: lst-plot\n#| lst-cap: Listing caption\n\nplt.plot([1,23,2,4])\nplt.show()\n```\n\nThe code in @lst-plot produces the figure in @fig-plot.\n````\n\nWhen rendered, this produces the following output:\n\n:::{.border .p-3}\n\n::: {#cell-fig-plot .cell execution_count=2}\n``` {#lst-plot .python .cell-code lst-cap=\"Listing caption\"}\nplt.plot([1,23,2,4])\nplt.show()\n```\n\n::: {.cell-output .cell-output-display}\n![Figure caption](cross-references_files/figure-html/fig-plot-output-1.png){#fig-plot width=566 height=411}\n:::\n:::\n\n\nThe code in @lst-plot produces the plot in @fig-plot.\n:::\n\n\n\n## Callouts\n\nTo cross-reference a callout, add an ID attribute that starts with the appropriate callout prefix (see @tbl-callout-prefixes). You can then reference the callout using the usual `@` syntax. For example, here we add the ID `#tip-example` to the callout, and then refer back to it:\n\n``` markdown\n::: {#tip-example .callout-tip}\n## Cross-Referencing a Tip\n\nAdd an ID starting with `#tip-` to reference a tip.\n:::\n\nSee @tip-example...\n```\n\nThis renders as follows:\n\n::: {.border .p-3}\n::: {#tip-example .callout-tip}\n## Cross-Referencing a Tip\n\nAdd an ID starting with `#tip-` to reference a tip.\n:::\n\nSee @tip-example...\n:::\n\nThe prefixes for each type of callout are:\n\n| Callout Type | Prefix |\n|--------------|---------|\n| `note` | `#nte-` |\n| `tip` | `#tip-` |\n| `warning` | `#wrn-` |\n| `important` | `#imp-` |\n| `caution` | `#cau-` |\n\n: Prefixes for callout cross-references {#tbl-callout-prefixes}\n\n\n\n## Theorems and Proofs\n\nTheorems are commonly used in articles and books in mathematics. To include a reference-able theorem, create a div with a `#thm-` label (or one of other theorem-type labels described below). You also need to specify a theorem name either via the first heading in the block. You can include any content you like within the div. For example:\n\n``` markdown\n::: {#thm-line}\n\n## Line\n\nThe equation of any straight line, called a linear equation, can be written as:\n\n$$\ny = mx + b\n$$\n:::\n\nSee @thm-line.\n```\n\n![](images/crossref-theorem.png){fig-alt=\"A snippet of a LaTeX document. The first line reads: 'Thereom 1 (Line) The equation of any straight line, called a linear equation, can be written as:' Cenetered on a separate line is the equation 'y = mx + b'. The text 'See thm. 1' is aligned to the left underneath that.\"}\n\nFor LaTeX output, the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used for typesetting theorems. For other formats an appropriate treatment is used (the above is an example of HTML output).\n\nThere are a number of theorem variations supported, each with their own label prefix:\n\n| **Label Prefix** | **Printed Name** | **LaTeX Environment** |\n|------------------|------------------|-----------------------|\n| `#thm-` | Theorem | theorem |\n| `#lem-` | Lemma | lemma |\n| `#cor-` | Corollary | corollary |\n| `#prp-` | Proposition | proposition |\n| `#cnj-` | Conjecture | conjecture |\n| `#def-` | Definition | definition |\n| `#exm-` | Example | example |\n| `#exr-` | Exercise | exercise |\n| `#sol-` | Solution | solution |\n| `#rem-` | Remark | remark |\n\nThe `proof` environment receives similar typesetting as theorems, however it is not numbered (and therefore cannot be cross-referenced). To create a proof add the `.proof` class to a div:\n\n``` markdown\n::: {.proof}\nBy induction.\n:::\n```\n\nAs with theorems you can optionally include a heading as the first element of the div (or a `name` attribute) to give the environment a caption for typesetting (this typically appears in parentheses after the environment title).\n\nFor LaTeX output the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used to typeset these environments. For other formats a similar treatment is used, but you can further customizing this using CSS.\n\n## Equations\n\nProvide an `#eq-` label immediately after an equation to make it referenceable. For example:\n\n``` markdown\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm C^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n```\n\nBlack-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options:\n\n$$\n\\frac{\\partial \\mathrm C}{ \\partial \\mathrm t } + \\frac{1}{2}\\sigma^{2} \\mathrm S^{2}\n\\frac{\\partial^{2} \\mathrm C}{\\partial \\mathrm S^2}\n + \\mathrm r \\mathrm S \\frac{\\partial \\mathrm C}{\\partial \\mathrm S}\\ =\n \\mathrm r \\mathrm C \n$$ {#eq-black-scholes}\n\nNote that the equation number is included (via `\\qquad`) in the right margin of the equation.\n\n## Sections\n\nTo reference a section, add a `#sec-` identifier to any heading. For example:\n\n``` markdown\n## Introduction {#sec-introduction}\n\nSee @sec-introduction for additional context.\n```\n\nNote that when using section cross-references, you will also need to enable the `number-sections` option (so that section numbering is visible to readers). For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nnumber-sections: true\n---\n```\n\n", "supporting": [ "cross-references_files" ], diff --git a/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png b/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png new file mode 100644 index 0000000000..db01a62e33 Binary files /dev/null and b/_freeze/docs/authoring/cross-references/figure-html/fig-plot-output-1.png differ diff --git a/_freeze/docs/authoring/penguins-qmd/execute-results/html.json b/_freeze/docs/authoring/penguins-qmd/execute-results/html.json new file mode 100644 index 0000000000..a38dd52db3 --- /dev/null +++ b/_freeze/docs/authoring/penguins-qmd/execute-results/html.json @@ -0,0 +1,17 @@ +{ + "hash": "2824ad66844e803d9073ac9a3449a8eb", + "result": { + "engine": "knitr", + "markdown": "---\ntitle: \"Palmer Penguins (`.qmd`)\"\n---\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(tidyverse)\n```\n\n::: {.cell-output .cell-output-stderr}\n\n```\n── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──\n✔ dplyr 1.1.2 ✔ readr 2.1.4\n✔ forcats 1.0.0 ✔ stringr 1.5.0\n✔ ggplot2 3.4.2 ✔ tibble 3.2.1\n✔ lubridate 1.9.2 ✔ tidyr 1.3.0\n✔ purrr 1.0.1 \n── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──\n✖ dplyr::filter() masks stats::filter()\n✖ dplyr::lag() masks stats::lag()\nℹ Use the conflicted package () to force all conflicts to become errors\n```\n\n\n:::\n\n```{.r .cell-code}\nlibrary(palmerpenguins)\n```\n:::\n\n\nData from [Palmer Penguins R package](https://allisonhorst.github.io/palmerpenguins/)\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\npenguins |> count(species)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n# A tibble: 3 × 2\n species n\n \n1 Adelie 152\n2 Chinstrap 68\n3 Gentoo 124\n```\n\n\n:::\n:::\n\n::: {.cell}\n\n```{.r .cell-code}\ncolors <- c(\"#FF8C00\", \"#A020F0\", \"#008B8B\")\n```\n:::\n\n::: {.cell}\n\n```{.r .cell-code}\nggplot(penguins, aes(body_mass_g, flipper_length_mm)) +\n geom_point(aes(color = species)) +\n scale_color_manual(values = colors) +\n theme_minimal()\n```\n\n::: {.cell-output .cell-output-stderr}\n\n```\nWarning: Removed 2 rows containing missing values (`geom_point()`).\n```\n\n\n:::\n\n::: {.cell-output-display}\n![](penguins-qmd_files/figure-html/fig-size-scatter-1.png){#fig-size-scatter width=672}\n:::\n:::", + "supporting": [ + "penguins-qmd_files" + ], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": {}, + "postProcess": true + } +} \ No newline at end of file diff --git a/_freeze/docs/authoring/penguins-qmd/execute-results/ipynb.json b/_freeze/docs/authoring/penguins-qmd/execute-results/ipynb.json new file mode 100644 index 0000000000..d16e08e4c1 --- /dev/null +++ b/_freeze/docs/authoring/penguins-qmd/execute-results/ipynb.json @@ -0,0 +1,17 @@ +{ + "hash": "7c58eb46b87208792a5f71c912c1c658", + "result": { + "engine": "knitr", + "markdown": "---\ntitle: \"Palmer Penguins (.qmd)\"\n---\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(tidyverse)\n```\n\n::: {.cell-output .cell-output-stderr}\n\n```\n── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──\n✔ dplyr 1.1.2 ✔ readr 2.1.4\n✔ forcats 1.0.0 ✔ stringr 1.5.0\n✔ ggplot2 3.4.2 ✔ tibble 3.2.1\n✔ lubridate 1.9.2 ✔ tidyr 1.3.0\n✔ purrr 1.0.1 \n── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──\n✖ dplyr::filter() masks stats::filter()\n✖ dplyr::lag() masks stats::lag()\nℹ Use the conflicted package () to force all conflicts to become errors\n```\n\n\n:::\n\n```{.r .cell-code}\nlibrary(palmerpenguins)\n```\n:::\n\n\nData from [Palmer Penguins R package](https://allisonhorst.github.io/palmerpenguins/)\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\npenguins |> count(species)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n# A tibble: 3 × 2\n species n\n \n1 Adelie 152\n2 Chinstrap 68\n3 Gentoo 124\n```\n\n\n:::\n:::\n\n::: {.cell}\n\n```{.r .cell-code}\ncolors <- c(\"#FF8C00\", \"#A020F0\", \"#008B8B\")\n```\n:::\n\n::: {#cell-fig-size-scatter .cell}\n\n```{.r .cell-code}\n#| label: fig-size-scatter\nggplot(penguins, aes(body_mass_g, flipper_length_mm)) +\n geom_point(aes(color = species)) +\n scale_color_manual(values = colors) +\n theme_minimal()\n```\n\n::: {.cell-output .cell-output-stderr}\n\n```\nWarning: Removed 2 rows containing missing values (`geom_point()`).\n```\n\n\n:::\n\n::: {.cell-output-display}\n![](penguins-qmd_files/figure-ipynb/fig-size-scatter-1.png){#fig-size-scatter}\n:::\n:::", + "supporting": [ + "penguins-qmd_files/figure-ipynb" + ], + "filters": [ + "rmarkdown/pagebreak.lua" + ], + "includes": {}, + "engineDependencies": {}, + "preserve": null, + "postProcess": false + } +} \ No newline at end of file diff --git a/_freeze/docs/authoring/penguins-qmd/figure-html/fig-size-scatter-1.png b/_freeze/docs/authoring/penguins-qmd/figure-html/fig-size-scatter-1.png new file mode 100644 index 0000000000..fef43796bf Binary files /dev/null and b/_freeze/docs/authoring/penguins-qmd/figure-html/fig-size-scatter-1.png differ diff --git a/_freeze/docs/authoring/penguins-qmd/figure-ipynb/fig-size-scatter-1.png b/_freeze/docs/authoring/penguins-qmd/figure-ipynb/fig-size-scatter-1.png new file mode 100644 index 0000000000..ff249d32ff Binary files /dev/null and b/_freeze/docs/authoring/penguins-qmd/figure-ipynb/fig-size-scatter-1.png differ diff --git a/_freeze/docs/authoring/tables/execute-results/html.json b/_freeze/docs/authoring/tables/execute-results/html.json index d8e0851754..d16a31db88 100644 --- a/_freeze/docs/authoring/tables/execute-results/html.json +++ b/_freeze/docs/authoring/tables/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "3dcd5f575ffba90f8a40ba6bf1ca1957", + "hash": "4fdbfaec54c087b4c0b117e4af067e72", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Tables\nengine: jupyter\n---\n\n## Overview\n\nQuarto includes a number of features aimed at making it easy to to author and customize markdown table output, including:\n\n- Specifying column alignment and widths.\n- Providing captions, subcaptions, and cross-references.\n- Generating tables dynamically from executable code cells.\n\nThis article covers using these features in-depth.\n\n## Markdown Tables\n\nThe most commonly used markdown table is known as a pipe table. Pipe tables support specifying per column alignment as well as captions. For example:\n\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n```\n\n::::\n\n:::: {}\n\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n\n::::\n\n:::\n\nThe beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. The header cannot be omitted, however you can simulate a headerless table by including a header with blank cells.\n\nSince the pipes indicate column boundaries, columns need not be vertically aligned, as they are in the above example. So, this is a perfectly legal (though ugly) pipe table:\n\n``` markdown\nfruit| price\n-----|-----:\napple|2.05\npear|1.37\norange|3.09\n```\n\nThe cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. If a pipe table contains a row whose markdown content is wider than the column width (see `columns` option), then the table will take up the full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body.\n\nFor example `---|-` would make the first column 3/4 and the second column 1/4 of the full text width. On the other hand, if no lines are wider than column width, then cell contents will not be wrapped, and the cells will be sized to their contents.\n\n### Using Bootstrap classes\n\nBootstrap table classes given as attributes next to a table caption are inserted into the `` element.\nThe classes permitted are those that apply expressly to the entire table, and these are:\n`\"primary\"`, `\"secondary\"`, `\"success\"`, `\"danger\"`, `\"warning\"`, `\"info\"`, `\"light\"`, `\"dark\"`, `\"striped\"`, `\"hover\"`, `\"active\"`, `\"bordered\"`, `\"borderless\"`, `\"sm\"`, `\"responsive\"`, `\"responsive-sm\"`, `\"responsive-md\"`, `\"responsive-lg\"`, `\"responsive-xl\"`, `\"responsive-xxl\"`.\nFor example, the following Markdown table will be rendered with row stripes and the rows will also be highlighted on hover:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n\n::::\n\n:::\n\n### Authoring\n\nFor simple tables with only a few cells it's straightforward to create them directly in markdown. As tables get larger, it makes sense to use an authoring tool. Some table authoring tools to consider include:\n\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [TablesGenerator](https://tablesgenerator.com/markdown_tables) | Online tool for generating markdown tables |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Emacs TableMode](https://www.emacswiki.org/emacs/TableMode) | Text based table creation and editing capabilities for Emacs. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Quarto Visual Editor](/docs/visual-editor/content.qmd#editing-tables) | Visual editor for `.qmd` files with table editing support. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n\n: {tbl-colwidths=\"\\[35,65\\]\"}\n\n## Column Widths\n\nAbove we describe a means of specifying column widths using the relative number of dashes in each column header (_e.g._, `---|-` to get a 75% / 25% split for a two-column table).\n\nYou can also explicitly specify columns widths using the `tbl-colwidths` attribute or document-level option. For an individual markdown table, add the attribute after the caption. For example:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nIf your table doesn't have a caption, then you can still specify only `tbl-colwidths`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nColumn widths can also be specified at the document level (_e.g._, to have uniform widths across a set of tables):\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\ntbl-colwidths: [75,25]\n---\n```\n\n## Cross References\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable.\nFor example:\n\n::: {#tbl-planets .cell tbl-cap='Astronomical object' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\n\n\nFor markdown tables, add a caption below the table, then include a `#tbl-` label in braces at the end of the caption. For example:\n\n``` markdown\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: My Caption {#tbl-letters}\n\nSee @tbl-letters.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](images/crossref-table.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\n\n\n### Subtables\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## Caption Location\n\nBy default, table captions are positioned above tables. You can modify this behavior using the `tbl-cap-location` option. For example:\n\n``` yaml\n---\ntbl-cap-location: top\n---\n```\n\nNote that this option is specified at the top level so that it can be shared by both PDF and HTML formats. If you are only targeting a single format you can place it alongside other `format` specific options.\n\nValid values for the caption location include:\n\n| Value | Description |\n|----------|---------------------------------------|\n| `top` | Position the caption above the table. |\n| `bottom` | Position the caption below the table. |\n| `margin` | Position the caption in the margin. |\n\nSee the article on [Article Layout](article-layout.qmd#margin-captions) for additional details on placing captions in the margin.\n\n## Computations\n\nAll of the options described above work for tables produced by executable code cells. For example, here we use the Python [tabulate](https://pypi.org/project/tabulate/) package along with the `Markdown()` function from the IPython [display](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#) module to print a markdown table:\n\n::: {#tbl-planet-measures .cell tbl-cap='Astronomical object' execution_count=2}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planet-measures\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=2}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\nHere we apply the `tbl-cap` and `tbl-colwidths` options to a code cell that uses the knitr `kable()` function to write a markdown table:\n\n```{{r}}\n#| label: tbl-cars\n#| tbl-cap: \"Cars\"\n#| tbl-colwidths: [60,40]\n\nkable(head(cars))\n```\n\nIf your code cell produces multiple tables, you can also specify subcaptions and layout using cell options:\n\n::: {.panel-tabset group=\"language\"}\n\n## Python\n\n````python\n```{{python}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"MPG\"\n#| - \"Taxis\"\n#| layout-ncol: 2\n\nimport seaborn as sns\nfrom IPython.display import Markdown, display\nmpg = sns.load_dataset(\"mpg\").head(10)\ntaxis = sns.load_dataset(\"taxis\").head(10)\n\ndisplay(Markdown(mpg.to_markdown(index = False)))\ndisplay(Markdown(taxis.to_markdown(index = False)))\n```\n````\n\nNote that we use the [`display()`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display) function imported from `IPython` so that we can render multiple outputs from a single cell (by default cells only output their last expressions).\n\n## R\n\n````python\n```{{r}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n````\n\n\n:::\n\n## Grid Tables\n\nGrid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). For example:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n```\n\n::::\n\n:::: {}\n\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n\n::::\n\n:::\n\nThe row of `=`s separates the header from the table body, and can be omitted for a headerless table. Cells that span multiple columns or rows are not supported.\n\nAlignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n```\n\n::::\n\n:::: {}\n\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n\n::::\n\n:::\n\nFor headerless tables, the colons go on the top line instead:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n```\n\n::::\n\n:::: {}\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n::::\n\n:::\n\nNote that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). Here are some tools that can assist with creating grid tables:\n\n- Emacs' [table-mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Based-Tables.html) (`M-x table-insert`)\n- Quarto [Visual Editor](https://quarto.org/docs/visual-editor/content.html#editing-tables)\n- Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled\n\n## HTML Tables\n\nQuarto can process HTML tables in `html` `RawBlock` nodes (_i.e._, `{=html}`) and convert them to Markdown tables, regardless of the output format (intentionally including non-HTML formats).\nAs a result, you can use HTML table syntax in your documents and it will be converted to Markdown syntax for all formats.\nAdditionally, libraries that emit computational tables in HTML format can work in other output formats.\n\nFor example, consider the following raw HTML block:\n\n````markdown\n```{=html}\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n````\n\nWhen rendered, this results in the following output for HTML and PDF formats:\n\n::: {layout-ncol=2}\n\n:::: {}\n### HTML Output\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n\n::::\n\n:::: {}\n### PDF Output\n\n![](images/raw-table-pdf.png){.border fig-alt=\"Screenshot of PDF output showing a table with a caption and two columns. The column headers are Header 1 and Header 2, and the cell contents are an image of an elephant and text that reads Regular Output.\"}\n::::\n\n:::\n\nIn addition, Quarto supports the specification of embedded Markdown content in tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese nodes can appear anywhere that such content is allowed: table headers, footers, cells, captions, _etc._ \n\nFor example, the following table includes a cross reference, markdown formatting and a shortcode:\n\n:::: {layout-nrow=\"2\"}\n\n::: {}\n\n```` markdown\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}}\">Regular output
\n```\n````\n\n:::\n\n::: {}\n\nWhich renders as follows:\n\n## HTML Tables Example {#sec-html-tables}\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}\">Regular output
\n```\n\n\n:::\n\n::::\n\n\n## Disabling Quarto Table Processing\n\nIt's possible that Quarto's processing of HTML tables interferes with your library's processing.\nIf this is the case, you can disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing=\"true\"` to your table, for example:\n\n```html\n\n ...\n
\n```\n\n", + "markdown": "---\ntitle: Tables\nengine: jupyter\n---\n\n## Overview\n\nQuarto includes a number of features aimed at making it easy to to author and customize markdown table output, including:\n\n- Specifying column alignment and widths.\n- Providing captions, subcaptions, and cross-references.\n- Generating tables dynamically from executable code cells.\n\nThis article covers using these features in-depth.\n\n## Markdown Tables\n\nThe most commonly used markdown table is known as a pipe table. Pipe tables support specifying per column alignment as well as captions. For example:\n\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n```\n\n::::\n\n:::: {}\n\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n\n::::\n\n:::\n\nThe beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. The header cannot be omitted, however you can simulate a headerless table by including a header with blank cells.\n\nSince the pipes indicate column boundaries, columns need not be vertically aligned, as they are in the above example. So, this is a perfectly legal (though ugly) pipe table:\n\n``` markdown\nfruit| price\n-----|-----:\napple|2.05\npear|1.37\norange|3.09\n```\n\nThe cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. If a pipe table contains a row whose markdown content is wider than the column width (see `columns` option), then the table will take up the full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body.\n\nFor example `---|-` would make the first column 3/4 and the second column 1/4 of the full text width. On the other hand, if no lines are wider than column width, then cell contents will not be wrapped, and the cells will be sized to their contents.\n\n### Using Bootstrap classes\n\nBootstrap table classes given as attributes next to a table caption are inserted into the `` element.\nThe classes permitted are those that apply expressly to the entire table, and these are:\n`\"primary\"`, `\"secondary\"`, `\"success\"`, `\"danger\"`, `\"warning\"`, `\"info\"`, `\"light\"`, `\"dark\"`, `\"striped\"`, `\"hover\"`, `\"active\"`, `\"bordered\"`, `\"borderless\"`, `\"sm\"`, `\"responsive\"`, `\"responsive-sm\"`, `\"responsive-md\"`, `\"responsive-lg\"`, `\"responsive-xl\"`, `\"responsive-xxl\"`.\nFor example, the following Markdown table will be rendered with row stripes and the rows will also be highlighted on hover:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n\n::::\n\n:::\n\n### Authoring\n\nFor simple tables with only a few cells it's straightforward to create them directly in markdown. As tables get larger, it makes sense to use an authoring tool. Some table authoring tools to consider include:\n\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [TablesGenerator](https://tablesgenerator.com/markdown_tables) | Online tool for generating markdown tables |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Emacs TableMode](https://www.emacswiki.org/emacs/TableMode) | Text based table creation and editing capabilities for Emacs. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Quarto Visual Editor](/docs/visual-editor/content.qmd#editing-tables) | Visual editor for `.qmd` files with table editing support. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n\n: {tbl-colwidths=\"\\[35,65\\]\"}\n\n## Column Widths\n\nAbove we describe a means of specifying column widths using the relative number of dashes in each column header (_e.g._, `---|-` to get a 75% / 25% split for a two-column table).\n\nYou can also explicitly specify columns widths using the `tbl-colwidths` attribute or document-level option. For an individual markdown table, add the attribute after the caption. For example:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nIf your table doesn't have a caption, then you can still specify only `tbl-colwidths`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nColumn widths can also be specified at the document level (_e.g._, to have uniform widths across a set of tables):\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\ntbl-colwidths: [75,25]\n---\n```\n\n## Cross References\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable.\nFor example:\n\n::: {#tbl-planets .cell tbl-cap='Astronomical object' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\n\n\nFor markdown tables, add a caption below the table, then include a `#tbl-` label in braces at the end of the caption. For example:\n\n``` markdown\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: My Caption {#tbl-letters}\n\nSee @tbl-letters.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](images/crossref-table.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\n\n\n\nSee the article on [Cross References](cross-references.qmd) for additional details.\n\n### Subtables\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## Caption Location\n\nBy default, table captions are positioned above tables. You can modify this behavior using the `tbl-cap-location` option. For example:\n\n``` yaml\n---\ntbl-cap-location: top\n---\n```\n\nNote that this option is specified at the top level so that it can be shared by both PDF and HTML formats. If you are only targeting a single format you can place it alongside other `format` specific options.\n\nValid values for the caption location include:\n\n| Value | Description |\n|----------|---------------------------------------|\n| `top` | Position the caption above the table. |\n| `bottom` | Position the caption below the table. |\n| `margin` | Position the caption in the margin. |\n\nSee the article on [Article Layout](article-layout.qmd#margin-captions) for additional details on placing captions in the margin.\n\n## Computations\n\nAll of the options described above work for tables produced by executable code cells. For example, here we use the Python [tabulate](https://pypi.org/project/tabulate/) package along with the `Markdown()` function from the IPython [display](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#) module to print a markdown table:\n\n::: {#tbl-planet-measures .cell tbl-cap='Astronomical object' execution_count=2}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planet-measures\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=2}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\nHere we apply the `tbl-cap` and `tbl-colwidths` options to a code cell that uses the knitr `kable()` function to write a markdown table:\n\n```{{r}}\n#| label: tbl-cars\n#| tbl-cap: \"Cars\"\n#| tbl-colwidths: [60,40]\n\nkable(head(cars))\n```\n\nIf your code cell produces multiple tables, you can also specify subcaptions and layout using cell options:\n\n::: {.panel-tabset group=\"language\"}\n\n## Python\n\n````python\n```{{python}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"MPG\"\n#| - \"Taxis\"\n#| layout-ncol: 2\n\nimport seaborn as sns\nfrom IPython.display import Markdown, display\nmpg = sns.load_dataset(\"mpg\").head(10)\ntaxis = sns.load_dataset(\"taxis\").head(10)\n\ndisplay(Markdown(mpg.to_markdown(index = False)))\ndisplay(Markdown(taxis.to_markdown(index = False)))\n```\n````\n\nNote that we use the [`display()`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display) function imported from `IPython` so that we can render multiple outputs from a single cell (by default cells only output their last expression).\n\n## R\n\n````python\n```{{r}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n````\n\n\n:::\n\n## Grid Tables\n\nGrid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). For example:\n\n\n``` markdown\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n```\n\nWhich looks like this when rendered to HTML:\n\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n\n\nThe row of `=`s separates the header from the table body, and can be omitted for a headerless table. Cells that span multiple columns or rows are not supported.\n\nAlignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:\n\n\n``` markdown\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n```\nWhich looks like this when rendered to HTML:\n\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n\n\nFor headerless tables, the colons go on the top line instead:\n\n``` markdown\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n```\n\nWhich looks like this when rendered to HTML:\n\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n\n\nNote that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). Here are some tools that can assist with creating grid tables:\n\n- Emacs' [table-mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Based-Tables.html) (`M-x table-insert`)\n- Quarto [Visual Editor](https://quarto.org/docs/visual-editor/content.html#editing-tables)\n- Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled\n\n## HTML Tables\n\nQuarto can process HTML tables in `html` `RawBlock` nodes (_i.e._, `{=html}`) and convert them to Markdown tables, regardless of the output format (intentionally including non-HTML formats).\nAs a result, you can use HTML table syntax in your documents and it will be converted to Markdown syntax for all formats.\nAdditionally, libraries that emit computational tables in HTML format can work in other output formats.\n\nFor example, consider the following raw HTML block:\n\n````markdown\n```{=html}\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n````\n\nWhen rendered, this results in the following output for HTML and PDF formats:\n\n::: {layout-ncol=2}\n\n:::: {}\n### HTML Output\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n\n::::\n\n:::: {}\n### PDF Output\n\n![](images/raw-table-pdf.png){.border fig-alt=\"Screenshot of PDF output showing a table with a caption and two columns. The column headers are Header 1 and Header 2, and the cell contents are an image of an elephant and text that reads Regular Output.\"}\n::::\n\n:::\n\nIn addition, Quarto supports the specification of embedded Markdown content in tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese nodes can appear anywhere that such content is allowed: table headers, footers, cells, captions, _etc._ \n\nFor example, the following table includes a cross reference, markdown formatting and a shortcode:\n\n:::: {layout-nrow=\"2\"}\n\n::: {}\n\n```` markdown\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}}\">Regular output
\n```\n````\n\n:::\n\n::: {}\n\nWhich renders as follows:\n\n## HTML Tables Example {#sec-html-tables}\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}\">Regular output
\n```\n\n\n:::\n\n::::\n\n\n## Disabling Quarto Table Processing\n\nIt's possible that Quarto's processing of HTML tables may interfere with the HTML produced computationally with table packages in R and Python (or other supported languages).\n\nYou can disable Quarto's HTML table processing at a document level or project level with the option `html-table-processing`:\n\n```{.yaml}\n---\nformat:\n html:\n html-table-processing: none\n---\n```\n\nThis option is also available as a code cell option for Knitr and Jupyter, e.g. \n\n\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\n````\n\n\nTo disable Quarto's HTML table processing for parts of a document use a div with the attribute `html-table-processing=\"none\"`:\n\n````{.markdown}\n::: {html-table-processing=\"none\"}\n\nContent with HTML tables you don't want processed.\n\n:::\n````\n\n### Library authors\n\nIf you are the author of a library that emits HTML tables you might like to disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing=\"true\"` to the `` element. For example:\n\n```html\n
\n ...\n
\n```\n\n", "supporting": [ "tables_files" ], diff --git a/_freeze/docs/computations/execution-options/execute-results/html.json b/_freeze/docs/computations/execution-options/execute-results/html.json index 8d361d5bc7..a3c1b2219c 100644 --- a/_freeze/docs/computations/execution-options/execute-results/html.json +++ b/_freeze/docs/computations/execution-options/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "4e63b5e802e61105e3d467833c884672", + "hash": "feab90b6b2979de9a01c4187e27200e1", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+===========+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `output` | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\n::: callout-tip\nWhen using the Knitr engine, you can also use any of the available native options (e.g. `collapse`, `tidy`, `comment`, etc.). See the [Knitr options documentation](https://yihui.org/knitr/options/) for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the `{r}` as shown in the Knitr documentation.\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Knitr engine, `fig-width` and `fig-height` are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). The syntax for this varies across the engines.\n\n### Jupyter\n\nTo include executable expressions within markdown in a Python notebook, you use [`IPython.display.Markdown`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html) to dynamically generate markdown from within an ordinary code cell. For example, if we have a variable `radius` we can use it within markdown as follows:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\nYou can do the same in a Julia notebook using the [`Markdown`](https://docs.julialang.org/en/v1/stdlib/Markdown/) package:\n\n```{{julia}}\n#| echo: false\nradius = 10\nusing Markdown\nMarkdown.parse(\"\"\"\nThe radius of the circle is $radius.\n\"\"\")\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\n### Knitr\n\nTo include executable expressions within markdown for Knitr, enclose the expression in `` `r ` ``. For example, if we have a variable `radius` we can use it within markdown as follows:\n\n``` markdown\n## Circle\n\nThe radius of the circle is `r radius`.\n```\n\n### OJS\n\nTo include reactive OJS expressions within markdown, use the syntax `${expr}`. For example, if we have a reactive called `radius` we can use it within markdown as follows:\n\n``` markdown\n## Circle\n\nThe radius of the circle is ${radius}\n```\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#078ac42d .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#7fbf7d74 .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", + "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+===========+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `output` | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\n::: callout-tip\nWhen using the Knitr engine, you can also use any of the available native options (e.g. `collapse`, `tidy`, `comment`, etc.). See the [Knitr options documentation](https://yihui.org/knitr/options/) for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the `{r}` as shown in the Knitr documentation.\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Knitr engine, `fig-width` and `fig-height` are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). The syntax for this varies across the engines. See [Inline Code](inline-code.qmd) for details.\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#78b09d79 .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#d1fde019 .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", "supporting": [ "execution-options_files" ], diff --git a/_freeze/docs/computations/ojs/execute-results/html.json b/_freeze/docs/computations/ojs/execute-results/html.json deleted file mode 100644 index d671b42b28..0000000000 --- a/_freeze/docs/computations/ojs/execute-results/html.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "hash": "7f3fb6210ccac98c057ffa5a2b0f9f0e", - "result": { - "markdown": "---\ntitle: \"Using Observable\"\nexecute:\n echo: false\nsearch: false\n---\n\n## Overview\n\nQuarto includes native support for [Observable JS](https://observablehq.com/@observablehq/observables-not-javascript), a set of enhancements to vanilla JavaScript created by [Mike Bostock](https://en.wikipedia.org/wiki/Mike_Bostock) (also the author of [D3](https://d3js.org/)). Observable JS is distinguished by its [reactive runtime](https://github.com/observablehq/runtime), which is especially well suited for interactive data exploration and analysis.\n\nThe creators of Observable JS (Observable, Inc.) run a hosted service at where you can create and publish notebooks. Additionally, you can use Observable JS (\"OJS\") in standalone documents and websites via its [core libraries](https://github.com/observablehq). Quarto uses these libraries along with a [compiler](https://github.com/asg017/unofficial-observablehq-compiler/tree/beta) that is run at render time to enable the use of OJS within Quarto documents.\n\nOJS works in any Quarto document (plain markdown as well as Jupyter and Knitr documents). Just include your code in an `{ojs}` executable code block. The rest of this article explains the basics of using OJS with Quarto.\n\n## Example\n\nWe'll start with a simple example based on Allison Horst's [Palmer Penguins](https://allisonhorst.github.io/palmerpenguins/) dataset. Here we look at how penguin body mass varies across both sex and species (use the provided inputs to filter the dataset by bill length and island):\n\n\n```{ojs}\nfiltered = transpose(data).filter(function(penguin) {\n return bill_length_min < penguin.bill_length_mm &&\n islands.includes(penguin.island);\n})\n```\n\n```{ojs}\nviewof bill_length_min = Inputs.range(\n [32, 50], \n {value: 35, step: 1, label: \"Bill length (min):\"}\n)\nviewof islands = Inputs.checkbox(\n [\"Torgersen\", \"Biscoe\", \"Dream\"], \n { value: [\"Torgersen\", \"Biscoe\"], \n label: \"Islands:\"\n }\n)\n```\n\n```{ojs}\nPlot.rectY(filtered, \n Plot.binX(\n {y: \"count\"}, \n {x: \"body_mass_g\", fill: \"species\", thresholds: 20}\n ))\n .plot({\n facet: {\n data: filtered,\n x: \"sex\",\n y: \"species\",\n marginRight: 80\n },\n marks: [\n Plot.frame(),\n ]\n }\n)\n```\n\n\nLet's take a look at the source code for this example. First we create an `{ojs}` cell that reads in some data from a CSV file using a [FileAttachment](https://observablehq.com/@observablehq/file-attachments):\n\n``` {{ojs}}\ndata = FileAttachment(\"palmer-penguins.csv\").csv({ typed: true })\n```\n\nThe example above doesn't plot all of the data but rather a filtered subset. To create our filter we'll need some inputs, and we'll want to be able to use the values of these inputs in our filtering function. To do this, we use the `viewof` keyword and with some standard [Inputs](https://observablehq.com/@observablehq/inputs):\n\n``` {{ojs}}\nviewof bill_length_min = Inputs.range(\n [32, 50], \n {value: 35, step: 1, label: \"Bill length (min):\"}\n)\nviewof islands = Inputs.checkbox(\n [\"Torgersen\", \"Biscoe\", \"Dream\"], \n { value: [\"Torgersen\", \"Biscoe\"], \n label: \"Islands:\"\n }\n)\n```\n\nNow we write the filtering function that will transform the `data` read from the CSV using the values of `bill_length_min` and `island`.\n\n``` {{ojs}}\nfiltered = data.filter(function(penguin) {\n return bill_length_min < penguin.bill_length &&\n islands.includes(penguin.island);\n})\n```\n\nHere we see reactivity in action: we don't need any special syntax to refer to the dynamic input values, they \"just work\", and the filtering code is automatically re-run when the inputs change. This works in much the same way a spreadsheet works when you update a cell and other cells that refer to it are recalculated.\n\nFinally, we'll plot the filtered data using [Observable Plot](https://observablehq.com/@observablehq/plot) (an open-source JavaScript library for quick visualization of tabular data):\n\n``` {{ojs}}\nPlot.rectY(filtered, \n Plot.binX(\n {y: \"count\"}, \n {x: \"body_mass\", fill: \"species\", thresholds: 20}\n ))\n .plot({\n facet: {\n data: filtered,\n x: \"sex\",\n y: \"species\",\n marginRight: 80\n },\n marks: [\n Plot.frame(),\n ]\n }\n)\n```\n\nNote that as with our inputs, we refer to the `filtered` variable with no special syntax---the plotting code will be automatically re-run whenever `filtered` changes (which in turn is updated whenever an input changes).\n\nThat covers a basic end-to-end use of OJS (see the [Penguins](/docs/interactive/ojs/examples/penguins.qmd) examples for the full source code).\n\n::: {.callout-tip appearance=\"simple\"}\nIf you take a look at the [Penguins](/docs/interactive/ojs/examples/penguins.qmd) code, you'll notice something curious: the inputs and plotting code are defined *before* the data processing code. This demonstrates a critical difference between OJS cell execution and traditional notebooks: cells do not need to be defined in any particular order.\n\nBecause execution is fully reactive, the runtime will automatically execute cells in the correct order based on how they reference each other. This is more akin to a spreadsheet than a traditional notebook with linear cell execution.\n:::\n\n## Libraries\n\nOur example above made use of several standard libraries, including:\n\n1. [Observable stdlib](https://github.com/observablehq/stdlib) --- Core primitives for DOM manipulation, file handling, importing code, and much more.\n\n2. [Observable Inputs](https://github.com/observablehq/inputs) --- Standard inputs controls including sliders, drop-downs, tables, check-boxes, etc.\n\n3. [Observable Plot](https://github.com/observablehq/plot) --- High level plotting library for exploratory data visualization.\n\nThe libraries are somewhat special because they are automatically available within notebooks on as well as within `{ojs}` cells in Quarto documents.\n\nUsing other JavaScript libraries is also straightforward, they just need to be explicitly imported. For example, here we import a some libraries using the [require](https://github.com/observablehq/stdlib#require) function (which in turn loads NPM modules from [jsDelivr](https://www.jsdelivr.com/){.uri}):\n\n``` {{ojs}}\nd3 = require(\"d3@7\")\ntopojson = require(\"topojson\")\n```\n\nSee the article on [Libraries](/docs/interactive/ojs/libraries.qmd) to learn more about using standard and third-party libraries.\n\n## Data Sources\n\nIn our initial example we used a [FileAttachment](https://github.com/observablehq/stdlib#file-attachments) as our data source. File attachments support many formats including CSV, TSV, JSON, Arrow (uncompressed), and SQLite so are a convenient way to read a dataset that has already been prepared for analysis.\n\nFrequently though you'll need to do some pre-processing of your data in Python or R before it's ready for visualization. Within Quarto, you can do this pre-processing during document render then make the results available to OJS.\n\nUse the `ojs_define()` function from Python or R to define variables that you want to use within JavaScript. For example, to reproduce the simple CSV read in Python you might do this:\n\n::: {.cell execution_count=1}\n```` { .cell-code}\n```{{python}}\nimport pandas as pd\npenguins = pd.read_csv(\"palmer-penguins.csv\")\nojs_define(data = penguins)\n```\n\n````\n\n::: {.cell-output .cell-output-display}\n```{=html}\n\n```\n:::\n:::\n\n\nThe call to `ojs_define(data = penguins)` says that we want to make a variable named `data` (with the value of the `penguins` data frame) available to OJS\n\nDepending on the visualization library you use, one additional step may be required to consume the data from JavaScript. In this case, the `Plot` function expects data by row rather than by column, so we `transpose()` it before filtering:\n\n``` {{ojs}}\nfiltered = transpose(data).filter(function(penguin) {\n return bill_length_min < penguin.bill_length &&\n islands.includes(penguin.island);\n})\n```\n\nSee the article on [Data Sources](/docs/interactive/ojs/data-sources.qmd) to learn more about the various ways to prepare and read data.\n\n## OJS Cells\n\nThere are many options available to customize the behavior of `{ojs}` code cells, including showing, hiding, and collapsing code as well as controlling the visibility and layout of outputs.\n\nThe most important cell option to be aware of is the `echo` option, which controls whether source code is displayed. You'll have different preferences depending on whether you are embedding visualizations in an article or creating a notebook or full-on tutorial.\n\nCode in `{ojs}` cells is displayed by default. To prevent display of code for an entire document, set the `echo: false` option in YAML metadata:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\n---\n```\n\nYou can also specify this option on a per-cell basis. For example:\n\n``` {{ojs}}\n//| echo: false\ndata = FileAttachment(\"palmer-penguins.csv\").csv({ typed: true })\n```\n\nTo learn about all of the options available, see the article on [OJS Cells](/docs/interactive/ojs/ojs-cells.qmd).\n\n## Learning More\n\nThese articles go into more depth on using OJS in Quarto documents:\n\n- [Libraries](/docs/interactive/ojs/libraries.qmd) covers using standard libraries and external JavaScript libraries.\n\n- [Data Sources](/docs/interactive/ojs/data-sources.qmd) outlines the various ways to read and pre-process data.\n\n- [OJS Cells](/docs/interactive/ojs/ojs-cells.qmd) goes into more depth on cell execution, output, and layout.\n\n- [Shiny Reactives](/docs/interactive/ojs/shiny.qmd) describes how to integrate Shiny with OJS.\n\n- [Code Reuse](/docs/interactive/ojs/code-reuse.qmd) delves into ways to re-use OJS code across multiple documents.\n\nIf you want to learn more about the underlying mechanics of reactivity, check out these notebooks from [Mike Bostock](https://observablehq.com/@mbostock):\n\n- [Five Minute Introduction](https://observablehq.com/@observablehq/five-minute-introduction)\n\n- [Observable's not JavaScript](https://observablehq.com/@observablehq/observables-not-javascript)\n\n- [Introduction to Views](https://observablehq.com/@observablehq/introduction-to-views)\n\n\n- [How Observable Runs](https://observablehq.com/@observablehq/how-observable-runs)\n\n", - "supporting": [ - "ojs_files" - ], - "filters": [], - "includes": { - "include-in-header": [ - "\n\n\n" - ] - } - } -} \ No newline at end of file diff --git a/_quarto.yml b/_quarto.yml index c589d96992..2e890aba31 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -122,7 +122,7 @@ website: - docs/authoring/tables.qmd - docs/authoring/diagrams.qmd - docs/authoring/videos.qmd - - text: "Jupyter Notebooks" + - text: "Embeds" href: docs/authoring/notebook-embed.qmd - docs/authoring/callouts.qmd - docs/authoring/code-annotation.qmd @@ -132,7 +132,16 @@ website: - docs/authoring/front-matter.qmd - docs/authoring/title-blocks.qmd - docs/authoring/footnotes-and-citations.qmd - - docs/authoring/cross-references.qmd + - section: Cross-References + contents: + - text: Basics + href: docs/authoring/cross-references.qmd + - text: Options + href: docs/authoring/cross-reference-options.qmd + - text: Div Syntax + href: docs/authoring/cross-references-divs.qmd + - text: Custom Floats + href: docs/authoring/cross-references-custom.qmd - docs/authoring/create-citeable-articles.qmd - docs/authoring/appendices.qmd - section: "Computations" @@ -141,6 +150,8 @@ website: - docs/computations/r.qmd - docs/computations/julia.qmd - docs/computations/ojs.qmd + - docs/computations/inline-code.qmd + - docs/computations/render-scripts.qmd - docs/computations/execution-options.qmd - docs/computations/parameters.qmd - section: "Tools" @@ -184,6 +195,7 @@ website: - docs/output-formats/html-code.qmd - docs/output-formats/html-themes.qmd - docs/output-formats/html-multi-format.qmd + - docs/output-formats/html-lightbox-figures.qmd - docs/output-formats/html-publishing.qmd - section: "PDF" contents: @@ -193,6 +205,11 @@ website: contents: - docs/output-formats/ms-word.qmd - docs/output-formats/ms-word-templates.qmd + - section: "Typst" + contents: + - docs/output-formats/typst.qmd + - text: "Custom Formats" + href: docs/output-formats/typst-custom.qmd - section: "Markdown" contents: - docs/output-formats/gfm.qmd @@ -282,6 +299,29 @@ website: - docs/books/book-crossrefs.qmd - text: "Customizing Output" href: docs/books/book-output.qmd + + - section: "Manuscripts" + href: docs/manuscripts/index.qmd + contents: + - text: Getting Started + href: docs/manuscripts/index.qmd + contents: + - text: "Authoring Manuscripts" + href: docs/manuscripts/authoring/jupyterlab.qmd + contents: + - text: Jupyter Lab + href: docs/manuscripts/authoring/jupyterlab.qmd + - text: VS Code + href: docs/manuscripts/authoring/vscode.qmd + - text: RStudio + href: docs/manuscripts/authoring/rstudio.qmd + - text: "Publishing Manuscripts" + href: docs/manuscripts/publishing.qmd + - text: "Next Steps" + href: docs/manuscripts/next-steps.qmd + - text: "Using Manuscripts" + href: docs/manuscripts/components.qmd + - section: "Interactivity" contents: - text: "Overview" @@ -340,6 +380,7 @@ website: - docs/publishing/quarto-pub.qmd - docs/publishing/github-pages.qmd - docs/publishing/rstudio-connect.qmd + - docs/publishing/posit-cloud.qmd - docs/publishing/netlify.qmd - docs/publishing/confluence.qmd - docs/publishing/other.qmd @@ -353,6 +394,7 @@ website: - docs/projects/environment.qmd - docs/projects/scripts.qmd - docs/projects/virtual-environments.qmd + - docs/projects/binder.qmd - section: "Advanced" contents: - docs/authoring/includes.qmd @@ -400,31 +442,7 @@ website: - docs/extensions/revealjs.qmd - docs/extensions/project-types.qmd - docs/extensions/starter-templates.qmd - - id: manuscripts - title: "Manuscripts" - style: "floating" - collapse-level: 2 - align: left - contents: - - text: Manuscripts Overview - href: docs/manuscripts/index.qmd - - text: "Authoring Manuscripts" - contents: - - text: Jupyter Lab - href: docs/manuscripts/authoring/jupyterlab.qmd - - text: VS Code - href: docs/manuscripts/authoring/vscode.qmd - - text: RStudio - href: docs/manuscripts/authoring/rstudio.qmd - - text: "Publishing Manuscripts" - href: docs/manuscripts/publishing.qmd - - text: "Next Steps" - href: docs/manuscripts/next-steps.qmd - - text: "---" - - text: "Manuscript Components" - href: docs/manuscripts/components.qmd - - + - id: reference title: "Reference" collapse-level: 3 @@ -440,6 +458,8 @@ website: href: docs/reference/formats/pdf.qmd - text: "MS Word" href: docs/reference/formats/docx.qmd + - text: Typst + href: docs/reference/formats/typst.qmd - text: "OpenOffice" href: docs/reference/formats/odt.qmd - text: "ePub" @@ -529,6 +549,8 @@ website: href: docs/reference/projects/websites.qmd - text: "Books" href: docs/reference/projects/books.qmd + - text: "Manuscripts" + href: docs/reference/projects/manuscripts.qmd - section: "More" contents: - text: "Dates" @@ -537,6 +559,8 @@ website: href: docs/reference/globs.qmd - text: "Citations" href: docs/reference/metadata/citation.qmd + - text: "Cross-References" + href: docs/reference/metadata/crossref.qmd - id: prerelease title: "Quarto 1.3" contents: @@ -578,7 +602,7 @@ website: - text: "Dashboards" href: docs/dashboards/index.qmd - text: "Typst Format" - href: docs/prerelease/1.4/typst.qmd + href: docs/output-formats/typst.qmd - section: "Cross-References" contents: - text: Div Syntax @@ -586,29 +610,25 @@ website: - text: Custom Types href: docs/authoring/cross-references-custom.qmd - text: Listings for Executable Code - href: docs/authoring/cross-references-listings.qmd + href: docs/authoring/cross-references.qmd#code-listings - text: Callouts - href: docs/authoring/cross-references-callouts.qmd + href: docs/authoring/cross-references.qmd#callouts - text: Behind the Scenes href: docs/prerelease/1.4/crossref.qmd - text: Shiny for Python href: docs/dashboards/interactivity/shiny-python/index.qmd - text: Jupyter Inline Execution - href: docs/prerelease/1.4/inline.qmd - - section: Script Rendering - contents: - - text: Jupyter - href: docs/prerelease/1.4/script.qmd - - text: Knitr - href: docs/prerelease/1.4/script-r.qmd + href: docs/computations/inline-code.qmd + - text: Script Rendering + href: docs/computations/render-scripts.qmd - text: Binder Config - href: docs/prerelease/1.4/binder.qmd + href: docs/projects/binder.qmd - text: Connect Emails href: docs/prerelease/1.4/email.qmd - text: Cloud Publishing href: docs/publishing/posit-cloud.qmd - text: Lightbox Images - href: docs/prerelease//1.4/lightbox.qmd + href: docs/output-formats/html-lightbox-figures.qmd - text: Lua Changes href: docs/prerelease/1.4/lua_changes.qmd - text: AST Processing diff --git a/docs/_require-1.3.qmd b/docs/_require-1.3.qmd index 1b2bbd6be7..e69de29bb2 100644 --- a/docs/_require-1.3.qmd +++ b/docs/_require-1.3.qmd @@ -1,5 +0,0 @@ -::: {.callout-note} -## Quarto 1.3 Feature - -This feature is new in Quarto 1.3, which you can download at -::: \ No newline at end of file diff --git a/docs/_require-1.4.qmd b/docs/_require-1.4.qmd new file mode 100644 index 0000000000..daf547742b --- /dev/null +++ b/docs/_require-1.4.qmd @@ -0,0 +1,5 @@ +::: {.callout-note} +## Quarto 1.4 Feature + +This feature is new in Quarto 1.4. Download the latest version of Quarto at . +::: \ No newline at end of file diff --git a/docs/authoring/_cross-reference-divs-diagram.qmd b/docs/authoring/_cross-reference-divs-diagram.qmd new file mode 100644 index 0000000000..f0b2112a05 --- /dev/null +++ b/docs/authoring/_cross-reference-divs-diagram.qmd @@ -0,0 +1,28 @@ +To create a cross-references to a diagram using div syntax, treat it like a figure. For example, @fig-simple is created using: + +````markdown +::: {#fig-simple} + +```{dot} +graph { + A -- B +} +``` + +This is a simple graphviz graph +::: +```` + +::: {#fig-simple .column-margin} + +```{dot} +//| fig-width: 1.5 +graph { + A -- B +} +``` + +This is a simple graphviz graph +::: + +If you would rather give diagrams a label and counter distinct from figures, consider defining [Custom Cross-Reference Types](cross-references-custom.qmd). \ No newline at end of file diff --git a/docs/authoring/_cross-reference-divs-figure.qmd b/docs/authoring/_cross-reference-divs-figure.qmd new file mode 100644 index 0000000000..e8b58c2f04 --- /dev/null +++ b/docs/authoring/_cross-reference-divs-figure.qmd @@ -0,0 +1,10 @@ +To create a cross-reference to a figure using div syntax, create a fenced div with an id starting with `fig-`, include the image followed by the caption inside the div: + +````markdown +::: {#fig-elephant} + +![](elephant.png) + +An Elephant +::: +```` diff --git a/docs/authoring/_cross-reference-divs-listing.qmd b/docs/authoring/_cross-reference-divs-listing.qmd new file mode 100644 index 0000000000..eaed98ae1a --- /dev/null +++ b/docs/authoring/_cross-reference-divs-listing.qmd @@ -0,0 +1,13 @@ +To create a cross-reference to a code listing using div syntax, create a fenced div with an id starting with `lst-`, include the code cell followed by the caption inside the div: + +````markdown +::: {#lst-customers} + +```{.sql} +SELECT * FROM Customers +``` + +Customers Query + +::: +```` \ No newline at end of file diff --git a/docs/authoring/_cross-reference-divs-table.qmd b/docs/authoring/_cross-reference-divs-table.qmd new file mode 100644 index 0000000000..dba82206f4 --- /dev/null +++ b/docs/authoring/_cross-reference-divs-table.qmd @@ -0,0 +1,15 @@ +To create a cross-reference to a table using div syntax, create a fenced div with an id starting with `tbl-`, include the table followed by the caption inside the div: + +````markdown +::: {#tbl-letters} + +| Col1 | Col2 | Col3 | +|------|------|------| +| A | B | C | +| E | F | G | +| A | G | G | + +My Caption + +::: +```` \ No newline at end of file diff --git a/docs/authoring/_cross-reference-divs-video.qmd b/docs/authoring/_cross-reference-divs-video.qmd new file mode 100644 index 0000000000..c0bc9f9413 --- /dev/null +++ b/docs/authoring/_cross-reference-divs-video.qmd @@ -0,0 +1,19 @@ +To add a cross-reference to a video, use the [cross-reference div syntax](cross-references-divs.qmd) and treat it like a figure. For example, + +````{.markdown shortcodes=false} +::: {#fig-cern} + +{{< video https://www.youtube.com/embed/wo9vZccmqwc >}} + +The video "CERN: The Journey of Discovery" + +::: + +In @fig-cern... +```` + +Which renders as: + +![](images/crossrefs-video.png){fig-alt="Screenshot that shows a YouTube video followed by the caption, 'Figure 1: The video CERN: The Journey of Discovery'. Below the caption is the text 'In Figure 1 ...'."} + +If you would rather give videos a label and counter distinct from figures, consider defining [Custom Cross-Reference Types](cross-references-custom.qmd). \ No newline at end of file diff --git a/docs/authoring/cross-references-callouts.qmd b/docs/authoring/_cross-references-callouts.qmd similarity index 89% rename from docs/authoring/cross-references-callouts.qmd rename to docs/authoring/_cross-references-callouts.qmd index fc78dfd33f..8287101b77 100644 --- a/docs/authoring/cross-references-callouts.qmd +++ b/docs/authoring/_cross-references-callouts.qmd @@ -1,9 +1,3 @@ ---- -title: Cross-Referencing Callouts ---- - -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} - To cross-reference a callout, add an ID attribute that starts with the appropriate callout prefix (see @tbl-callout-prefixes). You can then reference the callout using the usual `@` syntax. For example, here we add the ID `#tip-example` to the callout, and then refer back to it: ``` markdown diff --git a/docs/authoring/cross-references-listings.qmd b/docs/authoring/_cross-references-listings.qmd similarity index 91% rename from docs/authoring/cross-references-listings.qmd rename to docs/authoring/_cross-references-listings.qmd index 7840c31e74..01c814519f 100644 --- a/docs/authoring/cross-references-listings.qmd +++ b/docs/authoring/_cross-references-listings.qmd @@ -1,9 +1,3 @@ ---- -title: Cross-References for Executable Code Blocks ---- - -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} - To cross-reference code from an executable code block, add the code cell options `lst-label` and `lst-cap`. The option `lst-label` provides the cross reference identifier and must begin with the prefix `lst-` to be treated as a code listing. The value of `lst-cap` provides the caption for the code listing. For example: ````{.markdown} diff --git a/docs/authoring/_table-crossrefs-subtables.md b/docs/authoring/_table-crossrefs-subtables.md new file mode 100644 index 0000000000..90bd6a67d9 --- /dev/null +++ b/docs/authoring/_table-crossrefs-subtables.md @@ -0,0 +1,31 @@ +You may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example: + +``` markdown +::: {#tbl-panel layout-ncol=2} +| Col1 | Col2 | Col3 | +|------|------|------| +| A | B | C | +| E | F | G | +| A | G | G | + +: First Table {#tbl-first} + +| Col1 | Col2 | Col3 | +|------|------|------| +| A | B | C | +| E | F | G | +| A | G | G | + +: Second Table {#tbl-second} + +Main Caption +::: + +See @tbl-panel for details, especially @tbl-second. +``` + +Which looks like this when rendered to HTML: + +![](/docs/authoring/images/crossref-subtable.png){fig-alt="Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that."} + +Note that the "Main Caption" for the table is provided as the last block within the containing div. diff --git a/docs/authoring/_table-crossrefs.md b/docs/authoring/_table-crossrefs.md index db565e98d4..4ecf522057 100644 --- a/docs/authoring/_table-crossrefs.md +++ b/docs/authoring/_table-crossrefs.md @@ -17,38 +17,3 @@ See @tbl-letters. Which looks like this when rendered to HTML: ![](images/crossref-table.png){fig-alt="A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column." width="500"} - - -### Subtables - -You may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example: - -``` markdown -::: {#tbl-panel layout-ncol=2} -| Col1 | Col2 | Col3 | -|------|------|------| -| A | B | C | -| E | F | G | -| A | G | G | - -: First Table {#tbl-first} - -| Col1 | Col2 | Col3 | -|------|------|------| -| A | B | C | -| E | F | G | -| A | G | G | - -: Second Table {#tbl-second} - -Main Caption -::: - -See @tbl-panel for details, especially @tbl-second. -``` - -Which looks like this when rendered to HTML: - -![](/docs/authoring/images/crossref-subtable.png){fig-alt="Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that."} - -Note that the "Main Caption" for the table is provided as the last block within the containing div. diff --git a/docs/authoring/callouts.qmd b/docs/authoring/callouts.qmd index 48f25d3774..cd27f6689d 100644 --- a/docs/authoring/callouts.qmd +++ b/docs/authoring/callouts.qmd @@ -157,3 +157,9 @@ The following formats render callouts as illustrated above: Note that callout rendering for HTML is not available when you disable the standard HTML theme (e.g. if you specify the `theme: none` option). Also, some features are specific to document using Bootstrap, like collapsible callouts, and won't work in other documents. When the target format doesn't support callouts, they are rendered as a simple blockquote with the title in bold. + +## Cross-References + +{{< include _cross-references-callouts.qmd >}} + +Cross-referencing callouts is currently only supported for HTML, PDF and MS Word. \ No newline at end of file diff --git a/docs/authoring/conditional.qmd b/docs/authoring/conditional.qmd index 5740b1454f..33b11cafb4 100644 --- a/docs/authoring/conditional.qmd +++ b/docs/authoring/conditional.qmd @@ -91,7 +91,7 @@ The `when-format` and `unless-format` clauses do some aliasing of related format ## Matching against metadata -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} It's possible to match against boolean metadata values. Use the attributes `unless-meta` and `when-meta`, and use periods `.` to separate metadata keys. diff --git a/docs/authoring/cross-reference-options.qmd b/docs/authoring/cross-reference-options.qmd new file mode 100644 index 0000000000..fac6ae5959 --- /dev/null +++ b/docs/authoring/cross-reference-options.qmd @@ -0,0 +1,103 @@ +--- +title: "Cross-Reference Options" +format: html +--- + +## Overview + +There are a wide variety of options available for customizing caption labels and references. These options are all specified within the `crossref` key of document metadata. + +On this page we highlight some of the most useful, but you can find all available `crossref` options on the [Cross-Reference Options](/docs/reference/metadata/crossref.qmd) reference page. + +::: {.callout-note appearance="simple"} +Note that since LaTeX does its own formatting and layout of figures and tables, not all of these options will apply when rendering to PDF. Specifically, delimiter options like `title-delim` and numbering options like `labels` don't work for PDF output. Additionally, formatting directives are not applied (e.g. italicizing the figure title) for LaTeX titles. +::: + +## Titles + +You can specify the title prefix used for captions using `*-title` options. You can also specify the delimiter used between the prefix and the caption using the `title-delim` option. For example: + +``` yaml +--- +title: "My Document" +crossref: + fig-title: Fig # (default is "Figure") + tbl-title: Tbl # (default is "Table") + title-delim: "—" # (default is ":") +--- +``` + +## References {#references} + +You can specify the prefix used for inline reference type using `*-prefix` options. You can also specify whether references should be hyper-linked using the `ref-hyperlink` option. For example: + +``` yaml +--- +title: "My Document" +crossref: + fig-prefix: figure # (default is "Figure") + tbl-prefix: table # (default is "Table") + ref-hyperlink: false # (default is true) +--- +``` + +## Numbering + +There are a variety of numbering schemes available for cross-references, including: + +- `arabic` (1, 2, 3) + +- `roman` (I, II, III, IV) + +- `roman i` (i, ii, iii, iv) + +- `alpha x` (start from letter 'x') + +- `alpha X` (start from letter 'X') + +You can specify the numbering scheme used for all types (other than sub-references) using the `labels` option. For sub-references (e.g. subfigures), you can specify the number scheme using the `subref-labels` option. For example: + +``` yaml +--- +title: "My Document" +crossref: + labels: alpha a # (default is arabic) + subref-labels: roman i # (default is alpha a) +--- +``` + +If you would like, you can specify the number scheme for a specific type using the `*-labels` options. For example: + +``` yaml +--- +title: "My Document" +crossref: + fig-labels: alpha a # (default is arabic) + tbl-labels: alpha a # (default is arabic) + subref-labels: roman i # (default is alpha a) +--- +``` + +If both `labels` and a type specific label option is provided, the type specific option will override the `labels` option. + +## Chapter Numbering + +You can use the `crossref: chapters` option to indicate that top-level headings (H1) in your document correspond to chapters, and that cross-references should be sub-numbered by chapter. For example: + +``` markdown +--- +title: "My Document" +author: "Jane Doe" +number-sections: true +crossref: + chapters: true +--- + +# Introduction + +![Elephant](elephant.png){#fig-elephant} + +See @fig-elephant for an illustration. +``` + +![](images/crossref-chapters.png){fig-alt="A line drawing of an elephant. Above it is the text '1 Introduction' in large, bold font. The label 'Figure 1.1: Elephant' is centered underneath it. The text 'See fig. 1.1 for an illustration' is aligned to the left underneath that."} \ No newline at end of file diff --git a/docs/authoring/cross-references-custom.qmd b/docs/authoring/cross-references-custom.qmd index e6a08ad36b..1378f75ce5 100644 --- a/docs/authoring/cross-references-custom.qmd +++ b/docs/authoring/cross-references-custom.qmd @@ -1,5 +1,5 @@ --- -title: Custom Cross-Reference Types +title: Custom Float Cross-Reference Types crossref: custom: - kind: float @@ -7,11 +7,13 @@ crossref: key: vid --- -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} ## Overview -You can define custom cross-reference types using the `custom` key to the `crossref` option either in your document or project metadata. At a minimum, a custom type needs: +Cross-referenceable [figures](#figures), [tables](#tables) and [code listings](#code-listings) are examples of *float* cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions. + +You can define custom float cross-reference types using the `custom` key to the `crossref` option either in your document or project metadata. At a minimum, a custom type needs: - `kind`, which currently can only be `float` - `key`, the abbreviation used in the reference identifier ("In `@fig-1`, ...") @@ -52,11 +54,14 @@ Which renders as: In @vid-cern... +You can find a complete listing of the options available for the `custom` key on the [Cross-Reference Options](/docs/reference/metadata/crossref.html#custom) reference page. + ## PDF Output If your output format is PDF you'll also need to specify `latex-env`, a name to be used for the float environment wrapped around the element in the intermediate TeX. For example, to use the custom video reference type in PDF you could add `latex-env: video`: ``` yaml +format: pdf crossref: custom: - kind: float @@ -65,22 +70,24 @@ crossref: latex-env: video ``` -You can add a listing of your custom cross-references to your document by including a raw LaTeX `\listof` command. The name of the command is `listof` followed by the value of `latex-env` value, followed by an `s`. For example, for the custom video type above, where the `latex-env` was `video`, the command is `\listofvideos{}`: +You can add a listing of your custom cross-references to your document by including a raw LaTeX `\listof` command. The name of the command is `listof` followed by the value of `latex-env`, followed by an `s`. For example, for the custom video type above, where the `latex-env` was `video`, the command is `\listofvideos{}`: ``` yaml --- +format: pdf crossref: custom: - kind: float reference-prefix: Video key: vid + latex-env: video --- \listofvideos{} ``` -By default, the title of the listing is constructed from the `reference-prefix` value. You can specify something else with the `latex-list-of-description` value. +By default, the title of the listing (e.g "List of Videos") is constructed from the `reference-prefix` value. You can specify something else with the `latex-list-of-description` value. ## Example: Supplemental Figures @@ -103,4 +110,4 @@ crossref: latex-list-of-description: Supplementary Figure ``` -Note the use of `space-before-numbering: false`, which prevents a space between the `reference-prefix` or `caption-prefix` and the counter, so that labels will appear as "Figure S1", "Figure S2" etc. +Note the use of `space-before-numbering: false`, which prevents a space between the `reference-prefix` or `caption-prefix` and the counter, so that labels will appear as "Figure S1", "Figure S2" etc. \ No newline at end of file diff --git a/docs/authoring/cross-references-divs.qmd b/docs/authoring/cross-references-divs.qmd index ae1b000541..f5a798e62f 100644 --- a/docs/authoring/cross-references-divs.qmd +++ b/docs/authoring/cross-references-divs.qmd @@ -2,13 +2,13 @@ title: Cross-Reference Div Syntax --- -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} ## Overview -Along with compact syntax for the most common uses of cross-references, Quarto also provides a more general div syntax for declaring elements that can be cross-referenced. +Cross-referenceable [figures](#figures), [tables](#tables) and [code listings](#code-listings) are known as *float* cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions. -To declare a cross-referenceable element place the content inside a fenced div with the reference identifier as an attribute. The last paragraph inside the fenced div will be treated as the caption. For example: +Along with compact syntax for the most common uses of cross-references, Quarto also provides a more general div syntax for declaring floats that can be cross-referenced. To declare a cross-referenceable float, place the content inside a fenced div with the reference identifier as an attribute. The last paragraph inside the fenced div will be treated as the caption. For example: ````{.markdown} ::: {#fig-example} @@ -20,7 +20,7 @@ Caption ::: ```` -To be recognized as a cross-reference the identifier must begin with one of the built-in reference types (Figures (`fig-`), Tables (`tbl-`) and Listings (`lst-`)), or be defined as a custom cross-reference type. +To be recognized as a cross-reference the identifier must begin with one of the built-in float reference types (Figures (`fig-`), Tables (`tbl-`) and Listings (`lst-`)), or be defined as a [custom float cross-reference](cross-references-custom.qmd) type. You can then refer to the element as usual with the `@` syntax, e.g. @@ -103,20 +103,16 @@ A code cell treated like a figure. ::: -The following sections demonstrate this div syntax for common use cases. +On this page, we illustrate common use cases for [Figures](#figures), [Tables](#tables) and [Code Listings](#listings) then some applications of the div syntax to: -## Figures +* [Cross-reference a video](#videos) +* [Cross-reference a diagram](#diagrams) +* [Produce subreferences to mixed content](#subreferences) +* [Use computed values in a caption](#computed-captions) -To create a cross-reference to a figure using div syntax, create a fenced div with an id starting with `fig-`, include the image followed by the caption inside the div: +## Figures {#figures} -````markdown -::: {#fig-elephant} - -![](elephant.png) - -An Elephant -::: -```` +{{< include _cross-reference-divs-figure.qmd >}} You can cross-reference a figure created by an executable code cell by including the code cell as the content: @@ -133,26 +129,12 @@ A line plot ::: ```` -In the above example, you can reference the figure with `@fig-line-plot`, but not the code, which appears inline. If you would also like to be able to refer to the code, you can do so using code chunk options rather than the div syntax, see [Cross-References for Executable Code Blocks](cross-references-listings.qmd) for details. +In the above example, you can reference the figure with `@fig-line-plot`, but not the code, which appears inline. If you would also like to be able to refer to the code, you can do so using code chunk options rather than the div syntax, see [Cross-References for Executable Code Blocks](cross-references.qmd#code-listings) for details. ## Tables -To create a cross-reference to a table using div syntax, create a fenced div with an id starting with `tbl-`, include the table followed by the caption inside the div: - -````markdown -::: {#tbl-letters} - -| Col1 | Col2 | Col3 | -|------|------|------| -| A | B | C | -| E | F | G | -| A | G | G | - -My Caption - -::: -```` +{{< include _cross-reference-divs-table.qmd >}} If the table is produced by an executable code cell, put the cell inside the div as content, e.g: @@ -177,23 +159,11 @@ Astronomical object ::: ```` -In the above example, you can reference the table with `@tbl-planets`, but not the code, which appears inline. If you would also like to be able to refer to the code, you can do so using code chunk options rather than the div syntax, see [Cross-References for Executable Code Blocks](cross-references-listings.qmd) for details. +In the above example, you can reference the table with `@tbl-planets`, but not the code, which appears inline. If you would also like to be able to refer to the code, you can do so using code chunk options rather than the div syntax, see [Cross-References for Executable Code Blocks](cross-references.qmd#code-listings) for details. ## Listings -To create a cross-reference to a code listing using div syntax, create a fenced div with an id starting with `lst-`, include the code cell followed by the caption inside the div: - -````markdown -::: {#lst-customers} - -```{.sql} -SELECT * FROM Customers -``` - -Customers Query - -::: -```` +{{< include _cross-reference-divs-listing.qmd >}} This also works for executable code cells that produce no output: @@ -253,61 +223,16 @@ Assignment in R ```` -When the output is a figure or table, you can reference the code and the output individually by using code cell options, rather than the div syntax, as described in [Cross-References for Executable Code Blocks](cross-references-listings.qmd). +When the output is a figure or table, you can reference the code and the output individually by using code cell options, rather than the div syntax, as described in [Cross-References for Executable Code Blocks](cross-references.qmd#code-listings). ## Diagrams -You can also use div syntax to create a cross-references to a diagram by treating it like a figure. For example, @fig-simple is created using: - -````markdown -::: {#fig-simple} - -```{dot} -graph { - A -- B -} -``` - -This is a simple graphviz graph -::: -```` - -::: {#fig-simple .column-margin} - -```{dot} -//| fig-width: 1.5 -graph { - A -- B -} -``` - -This is a simple graphviz graph -::: - -If you would rather give diagrams a label and counter distinct from figures, consider defining [Custom Cross-Reference Types](cross-references-custom.qmd). +{{< include _cross-reference-divs-diagram.qmd >}} ## Videos -To add a cross-reference to a video, use the cross-reference div syntax and treat it like a figure. For example, - -````{.markdown shortcodes=false} -::: {#fig-cern} - -{{< video https://www.youtube.com/embed/wo9vZccmqwc >}} - -The video "CERN: The Journey of Discovery" - -::: - -In @fig-cern... -```` - -Which renders as: - -![](images/crossrefs-video.png){fig-alt="Screenshot that shows a YouTube video followed by the caption, 'Figure 1: The video CERN: The Journey of Discovery'. Below the caption is the text 'In Figure 1 ...'."} - -If you would rather give videos a label and counter distinct from figures, consider defining [Custom Cross-Reference Types](cross-references-custom.qmd). +{{< include _cross-reference-divs-video.qmd >}} ## Subreferences @@ -413,7 +338,7 @@ This renders as: ![](images/crossrefs-complex-layout.png){fig-alt="A screenshot of a figure layout with two rows. The top row has two columns: on the left an image of an elephant silhouetted against a sunset with the caption (a) An image file; on the right a scatterplot with the caption (b) A computational figure. In the bottom row is a flow chart with a node Transform linked to the node Visualize with the caption (c) A diagram. Below the layout is the caption: Figure 1: Example figure combining different types of content."} -## Computed Values in Captions +## Computed Captions If you want to include computed values in a caption, use the cross-reference div syntax, along with an [inline code expression](http://localhost:6234/docs/computations/execution-options.html#inline-code). For example: @@ -460,7 +385,7 @@ This dataset has `{r} length(x)` observations. :::: -## Cross-references with Conditional Content +## Conditional Content The cross-reference div syntax combined with [conditional content](docs/authoring/conditional.html) allows the content of your reference to vary by format. For example, you might want an interactive JavaScript based plot when the format is HTML, but otherwise produce a static plot: diff --git a/docs/authoring/cross-references.qmd b/docs/authoring/cross-references.qmd index d1c041da51..dbdcc9b339 100644 --- a/docs/authoring/cross-references.qmd +++ b/docs/authoring/cross-references.qmd @@ -1,17 +1,22 @@ --- title: "Cross References" format: html +toc-expand: 2 +toc-depth: 4 +aliases: + - /docs/authoring/cross-references-listings.html + - /docs/authoring/cross-references-callouts.html --- ## Overview -Cross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables. Every cross-referenceable entity requires a label (unique identifier prefixed with type e.g. `#fig-element`) and caption (description). For example, this is a cross-referenceable figure: +Cross-references make it easier for readers to navigate your document by providing numbered references and hyperlinks to various entities like figures and tables. Every cross-referenceable entity requires a label---a unique identifier prefixed with a cross-reference type e.g. `#fig-element`. For example, this is a cross-referenceable figure: ``` markdown ![Elephant](elephant.png){#fig-elephant} ``` -The presence of the caption (`Elephant`) and label (`#fig-elephant`) make this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document: +The presence of the label (`#fig-elephant`) makes this figure referenceable. This enables you to use the following syntax to refer to it elsewhere in the document: ``` markdown See @fig-elephant for an illustration. @@ -21,23 +26,79 @@ Here is what this would look like rendered to HTML: ![](images/crossref-figure.png){.border fig-alt="A line drawing of an elephant. The caption 'Figure 1: Elephant' is centered beneath it." width="100%"} -Quarto enables you to create cross-references to figures, tables, equations, sections, code listings, theorems, proofs, and more. Cross references can also be applied to dynamic output from Knitr and Jupyter. - Note that cross reference identifiers must start with their type (e.g. `fig-` or `tbl-`). So the identifier `#fig-elephant` is valid for a cross-reference but the identifiers `#elephant` and `#elephant-fig` are not. -There are options available that control the text used for titles and references. For example, you could change "Figure 1" to read "Fig 1" or "fig. 1". See the [options documentation](#options) for details on how to customize the text used for cross-references. +Quarto enables you to create cross-references to figures, tables, equations, sections, code listings, theorems, proofs, and more. Cross references can also be applied to dynamic output from Knitr and Jupyter. -::: {.callout-note style="padding-bottom: 16px"} -Quarto's syntax for cross-references is based on [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) (which is in turn based on this discussion: ). There are however several differences (mostly related to handling computational output) to note: +On this page you'll learn: -1. Quarto uses the prefix `#fig-` rather than `#fig:` (which is more compatible with Jupyter notebook [cell ids](https://jupyter.org/enhancement-proposals/62-cell-id/cell-id.html)). -2. Quarto is able to reference raw HTML and LaTeX figures and tables (which are often produced by executable code blocks). -3. Quarto has support for referencing theorems and proofs (and related types). -::: +* Different ways to use the `@` syntax to create [References](#references). +* How to add [Lists](#lists) of references in LaTeX / PDF output. + +Then, we enumerate the syntax for the different types of elements you might want to reference: + +* [Floats](#floats): [Figures](#figures), [Tables](#tables) and [Code Listings](#code-listings) +* Blocks: [Callouts](#callouts), [Theorems and Proofs](#theorems-and-proofs) and [Equations](#equations) +* [Sections](#sections) + +There are options available that control the text used for titles and references. For example, you could change "Figure 1" to read "Fig 1" or "fig. 1". See the [options documentation](cross-reference-options.qmd) for details on how to customize the text used for cross-references. + +## References -## Figures +The examples on this page all use the default syntax for inline references (e.g. `@fig-elephant`), which results in the reference text "Figure 1", "Table 1", etc. -As described above, this is the markdown used to create a cross-referenceable figure and then refer to it: +You can customize the appearance of inline references by either changing the syntax of the inline reference or by setting options. Here are the various ways to compose a cross-reference and their resulting output: + +| Type | Syntax | Output | +|---------------|-----------------------|----------| +| Default | `@fig-elephant` | Figure 1 | +| Capitalized | `@Fig-elephant` | Figure 1 | +| Custom Prefix | `[Fig @fig-elephant]` | Fig 1 | +| No Prefix | `[-@fig-elephant]` | 1 | + +Note that the capitalized syntax makes no difference for the default output, but would indeed capitalize the first letter if the default prefix had been changed via an [option](cross-reference-options.qmd#references) to use lower case (e.g. "fig."). + +These syntax variations work not only for Figures, but for all cross-referenceable elements in Quarto such as Tables, Equations, Theorems, and so on. + +You can also group cross-references using the following syntax: + +``` markdown +As illustrated in [@fig-elephant; @fig-panther; @fig-rabbit]. +``` + +There are a number of options that can be used to further customize the treatment of cross-references. See the guide on [Cross Reference Options](cross-reference-options.qmd#references) for additional details. + +## Lists + +For LaTeX / PDF output, you can use the raw LaTeX commands `\listoffigures`, `\listoftables` and `\listoflistings` to produce listings of all figures, tables, etc. within a document. You can use the `lof-title`, `lot-title`, and `lol-title` crossref options to customize the title of the listing. + +For example: + +``` markdown +--- +title: "My Document" +crossref: + lof-title: "List of Figures" +format: pdf +--- + +\listoffigures +``` + +Note that the default titles for the lists use the form displayed above (i.e. "List of \"). + +## Floats + +[Figures](#figures), [tables](#tables) and [code listings](#code-listings) are known as "float" cross-references. Floats can appear in the rendered document at locations other than where they are defined, i.e. they float, and usually have captions. + +In addition to the compact syntax for the most common uses of float cross-references, you can also define float cross-references with a div syntax. Use the div syntax when you need more flexibility in the content of your cross-reference, for example, to have a [video](cross-references-divs.qmd#videos) be referenced as a figure. Basic examples of the div syntax are included in the sections below, but you can find more complicated examples in [Cross-Reference Div Syntax](cross-references-divs.qmd). + +You can also define custom types of float cross-reference to reference elements beyond figures, tables and code listings. Read more at [Custom Float Cross-References](cross-references-custom.qmd). + + +### Figures + +As described on the Overview above, this is the markdown used to create a cross-referenceable figure and then refer to it: ``` markdown ![Elephant](elephant.png){#fig-elephant} @@ -47,7 +108,11 @@ See @fig-elephant for an illustration. Note again that cross-reference identifiers must start with their type (e.g. `#fig-`) and that cross-reference identifiers must be all lower case. -### Subfigures +{{< include _cross-reference-divs-figure.qmd >}} + +You can read about using div syntax with figures at [Cross-Reference Div Syntax](cross-references-divs.qmd#figures). + +#### Subfigures You may want to create a figure composed of multiple subfigures. To do this, enclose the figures in a div (with its own label and caption) and give each subfigure its own label and (optionally) caption. You can then refer to either the entire figure in a reference or a single subfigure: @@ -70,12 +135,12 @@ Here is what this looks like when rendered as HTML: Note that we also used the `layout-ncol` attribute to specify a two-column layout. See the article on [Figures](figures.qmd) for more details on laying out panels of figures. -### Computations +#### Computations Figures produced by Jupyter and Knitr can also be cross-referenced. To do this, add a `label` and `fig-cap` option at the top of the code block. For example: ::: panel-tabset -#### Jupyter +##### Jupyter ```{{python}} #| label: fig-plot @@ -90,7 +155,7 @@ Figures produced by Jupyter and Knitr can also be cross-referenced. To do this, ![](images/crossref-figure-jupyter.png){fig-alt="A line plot with the label 'Figure 1: Plot' centered underneath it. The text 'For example, see fig. 1' is underneath this label and aligned to the left."} -#### Knitr +##### Knitr ```{{r}} #| label: fig-plot @@ -137,26 +202,9 @@ If you'd like subfigure captions that include only an identifier, e.g. "(a)", an #| layout-ncol: 2 ``` -## Tables - -For tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable. For example: - -```{python} -#| label: tbl-planets -#| tbl-cap: "Planets" -#| echo: fenced - -from IPython.display import Markdown -from tabulate import tabulate -table = [["Sun",696000,1989100000], - ["Earth",6371,5973.6], - ["Moon",1737,73.5], - ["Mars",3390,641.85]] -Markdown(tabulate( - table, - headers=["Planet","R (km)", "mass (x 10^29 kg)"] -)) -``` +### Tables + +{{< include _table-crossrefs.md >}} ::: callout-important ## Label Prefix @@ -164,9 +212,15 @@ Markdown(tabulate( In order for a table to be cross-referenceable, its label must start with the `tbl-` prefix. ::: -{{< include _table-crossrefs.md >}} +{{< include _cross-reference-divs-table.qmd >}} + +You can read more about using div syntax with tables at [Cross-Reference Div Syntax](cross-references-divs.qmd#tables). + +#### Subtables + +{{< include _table-crossrefs-subtables.md >}} -### Computations +#### Computations You can also cross-reference tables created from code executed via computations. To do this, add the `label` and `tbl-cap` cell options. For example: @@ -212,52 +266,8 @@ kable(head(pressure)) ![](/docs/authoring/images/crossref-subtable-nocaption-knitr.png){fig-align="center" width="80%"} -## Equations - -Provide an `#eq-` label immediately after an equation to make it referenceable. For example: - -``` markdown -Black-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options: - -$$ -\frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2} -\frac{\partial^{2} \mathrm C}{\partial \mathrm C^2} - + \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ = - \mathrm r \mathrm C -$$ {#eq-black-scholes} -``` - -Black-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options: - -$$ -\frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2} -\frac{\partial^{2} \mathrm C}{\partial \mathrm S^2} - + \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ = - \mathrm r \mathrm C -$$ {#eq-black-scholes} - -Note that the equation number is included (via `\qquad`) in the right margin of the equation. - -## Sections - -To reference a section, add a `#sec-` identifier to any heading. For example: - -``` markdown -## Introduction {#sec-introduction} - -See @sec-introduction for additional context. -``` -Note that when using section cross-references, you will also need to enable the `number-sections` option (so that section numbering is visible to readers). For example: - -``` yaml ---- -title: "My Document" -number-sections: true ---- -``` - -## Code Listings +### Code Listings To create a reference-able code block, add a `#lst-` identifier along with a `lst-cap` attribute. For example: @@ -269,13 +279,15 @@ SELECT * FROM Customers Then we query the customers database (@lst-customers). ```` -::: {.callout-note} +{{< include _cross-reference-divs-listing.qmd >}} -Note that code listings currently only work with _display code blocks_ (as opposed to executable code blocks). If you wish to both execute and reference a code block, use a combination of a display block and a code block with `echo: false` in the cell YAML. +You can read more about using div syntax for code listings in [Cross-Reference Div Syntax](cross-references-divs.qmd). -::: +{{< include _cross-references-listings.qmd >}} +## Callouts +{{< include _cross-references-callouts.qmd >}} ## Theorems and Proofs @@ -312,12 +324,14 @@ There are a number of theorem variations supported, each with their own label pr | `#def-` | Definition | definition | | `#exm-` | Example | example | | `#exr-` | Exercise | exercise | +| `#sol-` | Solution | solution | +| `#rem-` | Remark | remark | -The `proof`, `remark`, and `solution` environments generally receive similar typesetting as theorems, however they are not numbered (and therefore cannot be cross-referenced). To create these environments just use them as the class name of a div: +The `proof` environment receives similar typesetting as theorems, however it is not numbered (and therefore cannot be cross-referenced). To create a proof add the `.proof` class to a div: ``` markdown -::: {.solution} -The solution. +::: {.proof} +By induction. ::: ``` @@ -325,143 +339,49 @@ As with theorems you can optionally include a heading as the first element of th For LaTeX output the [amsthm](https://ctan.org/pkg/amsthm?lang=en) package is used to typeset these environments. For other formats a similar treatment is used, but you can further customizing this using CSS. -## References - -The examples above have all used the default syntax for inline references (e.g. `@fig-elephant`), which results in the reference text "Figure 1", "Table 1", etc. - -You can customize the appearance of inline references by either changing the syntax of the inline reference or by setting options. Here are the various ways to compose a cross-reference and their resulting output: - -| Type | Syntax | Output | -|---------------|-----------------------|----------| -| Default | `@fig-elephant` | Figure 1 | -| Capitalized | `@Fig-elephant` | Figure 1 | -| Custom Prefix | `[Fig @fig-elephant]` | Fig 1 | -| No Prefix | `[-@fig-elephant]` | 1 | - -Note that the capitalized syntax makes no difference for the default output, but would indeed capitalize the first letter if the default had been change via an option to use lower case (e.g. "fig."). - -These syntax variations work not only for Figures, but for all cross-referenceable elements in Quarto such as Tables, Equations, Theorems, and so on. - -You can also group cross-references using the following syntax: - -``` markdown -As illustrated in [@fig-elephant; @fig-panther; @fig-rabbit]. -``` - -There are a number of options that can be used to further customize the treatment of cross-references. See the section below on [References Options](#references-1) for additional details. - -## Chapter Numbering - -You can use the `crossref: chapters` option to indicate that top-level headings (H1) in your document correspond to chapters, and that cross-references should be sub-numbered by chapter. For example: - -``` markdown ---- -title: "My Document" -author: "Jane Doe" -number-sections: true -crossref: - chapters: true ---- - -# Introduction - -![Elephant](elephant.png){#fig-elephant} - -See @fig-elephant for an illustration. -``` - -![](images/crossref-chapters.png){fig-alt="A line drawing of an elephant. Above it is the text '1 Introduction' in large, bold font. The label 'Figure 1.1: Elephant' is centered underneath it. The text 'See fig. 1.1 for an illustration' is aligned to the left underneath that."} - -## Lists - -For LaTeX / PDF output, you can use the raw LaTeX commands `\listoffigures`, `\listoftables` and `\listoflistings` to produce listings of all figures, tables, etc. within a document. You can use the `lof-title`, `lot-title`, and `lol-title` crossref options to customize the title of the listing. +## Equations -For example: +Provide an `#eq-` label immediately after an equation to make it referenceable. For example: ``` markdown ---- -title: "My Document" -crossref: - lof-title: "List of Figures" -format: pdf ---- +Black-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options: -\listoffigures +$$ +\frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2} +\frac{\partial^{2} \mathrm C}{\partial \mathrm C^2} + + \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ = + \mathrm r \mathrm C +$$ {#eq-black-scholes} ``` -Note that the default titles for the lists use the form displayed above (i.e. "List of \"). - -## Options {#options} - -There are a wide variety of options available for customizing caption labels and references. These options are all specified within the `crossref` key of document metadata. - -::: {.callout-note appearance="simple"} -Note that since LaTeX does its own formatting and layout of figures and tables, not all of these options will apply when rendering to PDF. Specifically, delimiter options like `title-delim` and numbering options like `labels` don't work for PDF output. Additionally, formatting directives are not applied (e.g. italicizing the figure title) for LaTeX titles. -::: +Black-Scholes (@eq-black-scholes) is a mathematical model that seeks to explain the behavior of financial derivatives, most commonly options: -### Titles +$$ +\frac{\partial \mathrm C}{ \partial \mathrm t } + \frac{1}{2}\sigma^{2} \mathrm S^{2} +\frac{\partial^{2} \mathrm C}{\partial \mathrm S^2} + + \mathrm r \mathrm S \frac{\partial \mathrm C}{\partial \mathrm S}\ = + \mathrm r \mathrm C +$$ {#eq-black-scholes} -You can specify the title prefix used for captions using `*-title` options. You can also specify the delimiter used between the prefix and the caption using the `title-delim` option. For example: +Note that the equation number is included (via `\qquad`) in the right margin of the equation. -``` yaml ---- -title: "My Document" -crossref: - fig-title: Fig # (default is "Figure") - tbl-title: Tbl # (default is "Table") - title-delim: "—" # (default is ":") ---- -``` +## Sections -### References {#references-1} +To reference a section, add a `#sec-` identifier to any heading. For example: -You can specify the prefix used for inline reference type using `*-prefix` options. You can also specify whether references should be hyper-linked using the `ref-hyperlink` option. For example: +``` markdown +## Introduction {#sec-introduction} -``` yaml ---- -title: "My Document" -crossref: - fig-prefix: figure # (default is "Figure") - tbl-prefix: table # (default is "Table") - ref-hyperlink: false # (default is true) ---- +See @sec-introduction for additional context. ``` -### Numbering - -There are a variety of numbering schemes available for cross-references, including: - -- `arabic` (1, 2, 3) - -- `roman` (I, II, III, IV) - -- `roman i` (i, ii, iii, iv) - -- `alpha x` (start from letter 'x') - -- `alpha X` (start from letter 'X') - -You can specify the number scheme used for all types (other than sub-references) using the `labels` option. For sub-references (e.g. subfigures), you can specify the number scheme using the `subref-labels` option. For example: +Note that when using section cross-references, you will also need to enable the `number-sections` option (so that section numbering is visible to readers). For example: ``` yaml --- title: "My Document" -crossref: - labels: alpha a # (default is arabic) - subref-labels: roman i # (default is alpha a) +number-sections: true --- ``` -If you would like, you can specify the number scheme for a specific type using the `*-labels` options. For example: - -``` yaml ---- -title: "My Document" -crossref: - fig-labels: alpha a # (default is arabic) - tbl-labels: alpha a # (default is arabic) - subref-labels: roman i # (default is alpha a) ---- -``` -If both `labels` and a type specific label option is provided, the type specific option will override the `labels` option. diff --git a/docs/authoring/diagrams.qmd b/docs/authoring/diagrams.qmd index 7b22254e75..ebefa23503 100644 --- a/docs/authoring/diagrams.qmd +++ b/docs/authoring/diagrams.qmd @@ -100,7 +100,7 @@ There are a variety of tools available to improve your productivity authoring di Note that you should be sure to have installed the [very latest](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) version of the Quarto VS Code extension to try this out. -## Figures +## Cross-References Diagrams can be treated as figures the same way that images and plot output are. For example, if we added the following figure options to the diagram above: @@ -132,6 +132,14 @@ graph G { } ``` +We could then create a cross-reference to the diagram with: + +```markdown +@fig-simple +``` + +{{< include _cross-reference-divs-diagram.qmd >}} + ## File Include You might find it more convenient to edit your diagram in a standalone `.dot` or `.mmd` file and then reference it from within your `.qmd` document. You can do this by adding the `file` option to a Mermaid or Graphviz cell. diff --git a/docs/authoring/figures.qmd b/docs/authoring/figures.qmd index 5a300de0aa..c17c31676b 100644 --- a/docs/authoring/figures.qmd +++ b/docs/authoring/figures.qmd @@ -103,6 +103,20 @@ format: default-image-extension: tex ``` +### Lightbox Figures + +In HTML output formats you can add lightbox styling and behavior to images to allow a reader to click to see a larger version of the image. For example, the following image has lightbox treatment (click on the image to see lightbox in action): + +![An elephant](elephant.png){.lightbox width=50%} + +Lightbox treatment can be added by adding the class `.lightbox` to an image: + +```markdown +![An elephant](elephant.png){.lightbox} +``` + +For further details and other ways to enable and disable lightbox treatment see [Lightbox Figures](/docs/output-formats/html-lightbox-figures.qmd). + ### Applying Multiple Parameters To combine the above methods, separate arguments by a space, for example: ``` markdown diff --git a/docs/authoring/front-matter.qmd b/docs/authoring/front-matter.qmd index 5aab3799b7..40e87d2301 100644 --- a/docs/authoring/front-matter.qmd +++ b/docs/authoring/front-matter.qmd @@ -53,7 +53,7 @@ The documents produced by the above metadata for the HTML and JATS formats are s ![](images/scholarly-front-matter-html.png){fig-alt="Screenshot of the HTML preview from the document with the above metadata."} ::: -Not all of the metadata keys are used in every format. For example, the HTML format does not display the `keywords`. However, the tags described on this page will generally be supported in [journal article formats](/docs/extensions/listing-journals.html). Currently the JATS format makes use of the broadest set of metadata tags, so if you want to check how things render we recommend previewing with `format: jats`. +Not all of the metadata keys are used in every format. However, the tags described on this page will generally be supported in [journal article formats](/docs/extensions/listing-journals.html). Currently the JATS format makes use of the broadest set of metadata tags, so if you want to check how things render we recommend previewing with `format: jats`. ## Authors & Affiliations {#authors-and-affiliations} @@ -109,6 +109,8 @@ Beyond `name` and `affiliation`, `author` can also take any of the following: | `fax`\ | | | | `url` | | | +----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `degrees` | string(s) | Academic titles or professional certifications displayed following a personal name. | ++----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `orcid` | string | Author's Open Researcher and Contributor ID ([ORCID](https://orcid.org/)), in the form `0000-0000-0000-0000`. Creates a link to the author's ORCID in many formats. | +----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `note`\ | string | Notes to attach to an author, such as contribution details;\ | @@ -160,6 +162,18 @@ author: --- ``` +#### Degrees + +You may specify degrees or academic titles using the `degrees` field of authors: + +```yaml +author: + - name: Josiah Carberry + degrees: + - B.S. + - PhD +``` + #### Author Roles {#roles} Use `roles` to describe an author's contributions to the work. You can use free form text as a string: @@ -252,6 +266,8 @@ In addition to `name`, `affiliation` can take any of the following: +-------------------------+-----------+----------------------------------------------------------------------------------------------------+ | `department` | String | | +-------------------------+-----------+----------------------------------------------------------------------------------------------------+ +| `group` | String | Team or research group within the affiliation | ++-------------------------+-----------+----------------------------------------------------------------------------------------------------+ | `address`\ | String | Affiliation's location. Provide one of `region` or `state`, and any combination of the other keys. | | `city`\ | | | | `region` or `state`\ | | | diff --git a/docs/authoring/images/scholarly-front-matter-html.png b/docs/authoring/images/scholarly-front-matter-html.png index 992d0b14ef..b142dddeac 100644 Binary files a/docs/authoring/images/scholarly-front-matter-html.png and b/docs/authoring/images/scholarly-front-matter-html.png differ diff --git a/docs/authoring/includes.qmd b/docs/authoring/includes.qmd index c605969048..fa41adff67 100644 --- a/docs/authoring/includes.qmd +++ b/docs/authoring/includes.qmd @@ -28,9 +28,9 @@ Include shortcodes need to appear by themselves in a line, and they need to be s ## Content -A concrete example would be if you have several articles about a topic that share a common introduction. Here we have an article titled "Revealjs Presentations" that wants to include some basic information on presentations not specific to Revealjs (we do that by including `_basics.qmd`): +A concrete example would be if you have several articles about a topic that share a common introduction. Here, we have an article titled "Revealjs Presentations" that wants to include some basic information on presentations not specific to Revealjs (we do that by including `_basics.qmd`). We also have some demo code stored as scripts that we want to include as non-executed examples (we do that by including `_demo.R` and `_demo.py` inside source code blocks): -``` markdown +```` markdown --- title: "Revealjs Presentations" --- @@ -45,9 +45,27 @@ present your ideas to others! ## Revealjs Options More content here... + +## Do it yourself with R + +```r +{{{< include _demo.R >}}} ``` -Note that we use an underscore (`_`) prefix for the included file. You should always use an underscore prefix with included files so that they are automatically ignored (i.e. not treated as standalone files) by a `quarto render` of a project. +Copy the R code above in your session. + +## Do it yourself with Python + +```python +{{{< include _demo.py >}}} +``` + +Copy the Python code above and run it. + + +```` + +Note that we use an underscore (`_`) prefix for the included files. You should always use an underscore prefix with included files so that they are automatically ignored (i.e. not treated as standalone files) by a `quarto render` of a project. ## Computations @@ -64,16 +82,32 @@ title: "My Document" Use the data... ``` +where the content would be + +````{.markdown filename="_data.qmd"} + +Load the `sp500` from [`great_tables`](https://posit-dev.github.io/great-tables/) + +```{{python}} +import great_tables as gt +from great_tables.data import sp500 +sp500.head() +``` + +```` + A couple of important things to remember when using computational includes: 1) All computations still share a single engine (e.g. knitr or jupyter) 2) Computational includes work only in `.qmd` files (they don't work in `.ipynb` notebook files) +Note that you can't use the `include` shortcode within a computational code block itself - as the example above shows, the executable code block needs to be inside the included document. + ```{=html} -``` +``` \ No newline at end of file diff --git a/docs/authoring/notebook-embed.qmd b/docs/authoring/notebook-embed.qmd index 0c3329af7a..5e726ef9e5 100644 --- a/docs/authoring/notebook-embed.qmd +++ b/docs/authoring/notebook-embed.qmd @@ -1,16 +1,16 @@ --- -title: Embedding Jupyter Notebook Cells +title: Embedding from Other Documents aliases: - /docs/prerelease/1.3/embed.html --- -{{< include ../_require-1.3.qmd >}} +{{< include ../_require-1.4.qmd >}} ## Overview -You can include the output of an external Jupyter notebook in a Quarto document with the `embed` shortcode. To embed a notebook cell, provide the path to a Jupyter Notebook and a cell identifier. For example, this notebook called `penguins.ipynb` has a cell labelled `fig-bill-scatter`: +You can include the output of an another Quarto document (`.qmd` or `.ipynb`) with the `embed` shortcode. To embed the output of a code block or notebook cell, provide the path to document and an identifier for the block or cell. For example, this Jupyter notebook called `penguins.ipynb` has a cell labelled `fig-bill-scatter`: -![](images/notebook-simple.png){fig-alt="A screenshot of a Jupyter Notebook with the name 'penguins.ipynb', with a cell highlighted that has the code chunk option label set to fig-bill-scatter. Below the cell is the resulting plot."} +![](images/notebook-simple.png){fig-alt="A screenshot of a Jupyter Notebook with the name 'penguins.ipynb', with a cell highlighted that has the code chunk option label set to fig-bill-scatter. Below the cell is the resulting plot." width=80%} You can use the following shortcode to embed the output of this cell: @@ -26,21 +26,50 @@ A link to the source notebook is automatically provided beneath the plot. Follow ![](images/notebook-view.png){.border fig-alt="A screenshot of webpage with the title 'penguins.ipynb', a large blue button labelled 'Download Notebook', followed by the notebook contents."} +You can embed output to and from both Jupyter Notebooks (`.ipynb`) and Quarto documents (`.qmd`). In this article, we'll refer to the source document generically as a *notebook*. + Beyond this basic usage, you can also: -- Specify cells in multiple ways, see [Specifying Cells](#specifying-cells). +- Specify cells or blocks in multiple ways, see [Specifying Cells](#specifying-cells). -- Control the output using code cell options in the source Notebook, including things like figure captions, figure layout, and code display, see [Code Cell Options](#code-cell-options). +- Control the output using code cell options in the source notebook, including things like figure captions, figure layout, and code display, see [Code Cell Options](#code-cell-options). -- Include the cell code along with the output by adding an `echo` option to the shortcode, see [Embedding Code](#embedding-code). +- Include the code along with the output by adding an `echo` option to the shortcode, see [Embedding Code](#embedding-code). -- Customize or exclude the link to the the source notebooks, see [Links to Source Notebooks](#linked-source-notebooks). +- Customize or exclude the link to the the source notebook, see [Links to Source Notebooks](#linked-source-notebooks). ## Specifying Cells {#specifying-cells} -The `embed` shortcode specifies target notebooks using a relative path followed by a cell identifier (e.g. `penguins.ipynb#fig-bill-scatter`). If the cell identifier is omitted, all of the cells in the notebook will be embedded in the document. +The `embed` shortcode specifies source notebooks using a relative path followed by a cell or code block identifier (e.g. `penguins.ipynb#fig-bill-scatter`). If the identifier is omitted, all of the cells or code blocks in the notebook will be embedded in the document. + +### Quarto Documents + +When the source is a Quarto document (`.qmd`), use the `label` of the code block as the identifer. For example, if the source document `penguins.qmd` contained the following code block: + +````{.markdown filename="penguins.qmd"} +```{{r}} +#| label: fig-size-scatter +ggplot(penguins, aes(body_mass_g, flipper_length_mm)) + + geom_point(aes(color = species)) + + scale_color_manual(values = colors) + + theme_minimal() +``` +```` + +You would embed the output of that block with: + +```{.markdown shortcodes=false} +{{< embed penguins.qmd#fig-size-scatter >}} +``` + +Which results in the following output: + +{{< embed penguins-qmd.qmd#fig-size-scatter >}} + + +### Jupyter Notebooks -The cell identifier is used to locate the proper cell using the following heuristics: +When the source is a Jupyter Notebook, the identifier used to locate the proper cell follows these heuristics: 1. **Cell `id`**\ First, the cell metadata will be checked for a matching `id`. ([Cell IDs](https://jupyter.org/enhancement-proposals/62-cell-id/cell-id.html) are a newer feature of Jupyter Notebooks that are not yet well supported in Jupyter front ends, but `id` is checked first to allow for future compatibility as they become more common). @@ -49,11 +78,11 @@ The cell identifier is used to locate the proper cell using the following heuris 3. **Tags**\ If no cell has been found, Quarto will use a cell or cell(s) whose tag matches the cell identifier. -### Cell Tags +#### Cell Tags For example, to embed the output of a cell that you have given the tag `bill-ratio` within Jupyter Lab: -![](images/notebook-tag.png){.border fig-alt="Screenshot of a code cell in a Jupyter Notebook with the cell tags open in the cell toolbar and displaying the tag 'bill-ratio'."} +![](images/notebook-tag.png){.border fig-alt="Screenshot of a code cell in a Jupyter Notebook with the cell tags open in the cell toolbar and displaying the tag 'bill-ratio'." width=80%} You would use the following embed: @@ -67,7 +96,7 @@ Which results in the following output: ## Code Cell Options {#code-cell-options} -Code cell options from the source Jupyter Notebook are propagated to the document in which they are embedded. For instance, you may specify code cell options like `fig-cap`, `fig-alt` and `layout-ncol`, to control aspects of embedded figures. For example, this cell in the Notebook specifies figure options including a caption, sub-caption, alt text and layout: +Code cell options from the source notebook are propagated to the document in which they are embedded. For instance, you may specify code cell options like `fig-cap`, `fig-alt` and `layout-ncol`, to control aspects of embedded figures. For example, this cell in `penguins.ipynb` specifies figure options including a caption, sub-caption, alt text and layout: ```{.python filename="penguins.ipynb"} #| label: fig-bill-marginal @@ -104,7 +133,7 @@ The following output is produced: ## Embedding Code {#embedding-code} -You may include the code from a cell along with the output by using the `echo=true` option. For example, to include the code and the plot from the cell labelled `species-counts` the embed would be: +You may include the code from a cell or block along with the output by using the `echo=true` option to the `embed` shortcode. For example, to include the code and the plot from the cell labelled `species-counts` in `penguins.ipynb` the embed would be: ```{.markdown shortcodes=false} {{< embed penguins.ipynb#species-counts echo=true >}} @@ -114,7 +143,7 @@ The result in the document is both the code and output for the cell: {{< embed penguins.ipynb#species-counts echo=true >}} -Like figure options, options for displaying the code will propagate from the source Jupyter Notebook. For example, to fold the code for this cell, you could add `code-fold: true` to the options for the `species-counts` cell: +Like figure options, options for displaying the code will propagate from the source notebook. For example, to fold the code for this cell, you could add `code-fold: true` to the options for the `species-counts` cell: ```{.python filename="penguins.ipynb"} #| label: species-counts @@ -135,7 +164,7 @@ format: ## Links to Source Notebooks {#linked-source-notebooks} -When you embed the contents of Notebooks in a Quarto document and render the document to HTML, Quarto will automatically include links to the source Notebooks that provided the embedded content. These links will by default appear both inline below the embedded content as well as below the table of contents. For example, the following document embeds content from the notebook `penguins.ipynb`. You can see the links in the rendered HTML document below: +When you embed the contents of notebooks in a Quarto document and render the document to HTML, Quarto will automatically include links to the source notebooks that provided the embedded content. These links will by default appear both inline below the embedded content, as well as below the table of contents. For example, the following document embeds content from the notebook `penguins.ipynb`. You can see the links in the rendered HTML document below: ![](images/notebook-links.png){.border fig-alt="Screenshot of a rendered page with an embedded plot. A link to the Source 'penguins.ipynb' is shown directly below the plot. A similar link is shown below the table of contents under the heading 'Notebooks'."} @@ -161,11 +190,11 @@ You can control the placement of the links to source notebooks by specifying the ### Notebook Views -By default, the link to the source notebook goes to an automatically generated HTML render of the notebook. This makes it easier for users to view the Notebook contents without needing to download and run the Notebook locally. This notebook view displays the contents of the notebook and includes a button to download the notebook. For example: +By default, the link to the source notebook goes to an automatically generated HTML render of the notebook. This makes it easier for users to view the notebook contents without needing to download and run the notebook locally. This notebook view displays the contents of the notebook and includes a button to download the notebook. For example: ![](images/notebook-view.png){.border fig-alt="A screenshot of webpage with the title 'penguins.ipynb', a large blue button labelled 'Download Notebook', followed by the notebook contents."} -As an example, you can view the [live preview for the \`penguins.ipynb\` notebook](penguins.ipynb.html) used in this document. +As an example, you can view the live previews for the [`penguins.ipynb` notebook](penguins-preview.html) and [`penguins.qmd` notebook](penguins-qmd.embed-preview.html) used in this document. ### View Options @@ -184,4 +213,4 @@ will result in links to the source notebook like so: ![](images/notebook-links-updated.png){.border fig-alt="Screenshot of a rendered page with an embedded plot. A link to the Source 'Plots and Computations' is shown directly below the plot. A similar link is shown below the table of contents under the heading 'Notebooks'."} -To disable the notebook views, and instead link directly to the Jupyter notebook (so the user may download the notebook with no intermediary view), set `notebook-view` to `false`. +To disable the notebook views, and instead link directly to the notebook (so the user may download the notebook with no intermediary view), set `notebook-view` to `false`. diff --git a/docs/authoring/penguins-qmd.qmd b/docs/authoring/penguins-qmd.qmd new file mode 100644 index 0000000000..ddfa719cd9 --- /dev/null +++ b/docs/authoring/penguins-qmd.qmd @@ -0,0 +1,30 @@ +--- +title: "Palmer Penguins (.qmd)" +--- + +```{r} +library(tidyverse) +library(palmerpenguins) +``` + +Data from [Palmer Penguins R package](https://allisonhorst.github.io/palmerpenguins/) + + +```{r} +penguins |> count(species) +``` + + +```{r} +colors <- c("#FF8C00", "#A020F0", "#008B8B") +``` + +```{r} +#| label: fig-size-scatter +#| fig-width: 3 +#| fig-height: 3 +ggplot(penguins, aes(body_mass_g, flipper_length_mm)) + + geom_point(aes(color = species)) + + scale_color_manual(values = colors) + + theme_minimal() +``` \ No newline at end of file diff --git a/docs/authoring/penguins.ipynb b/docs/authoring/penguins.ipynb index dd753596e1..b623b0df40 100644 --- a/docs/authoring/penguins.ipynb +++ b/docs/authoring/penguins.ipynb @@ -6,7 +6,7 @@ "metadata": {}, "source": [ "---\n", - "title: Palmer Penguins\n", + "title: Palmer Penguins (.ipynb)\n", "---" ] }, diff --git a/docs/authoring/tables.qmd b/docs/authoring/tables.qmd index a1538defdf..b66c851ad9 100644 --- a/docs/authoring/tables.qmd +++ b/docs/authoring/tables.qmd @@ -224,6 +224,12 @@ In order for a table to be cross-referenceable, its label must start with the `t {{< include _table-crossrefs.md >}} +See the article on [Cross References](cross-references.qmd) for additional details. + +### Subtables + +{{< include _table-crossrefs-subtables.md >}} + ## Caption Location By default, table captions are positioned above tables. You can modify this behavior using the `tbl-cap-location` option. For example: @@ -527,11 +533,44 @@ Which renders as follows: ## Disabling Quarto Table Processing -It's possible that Quarto's processing of HTML tables interferes with your library's processing. -If this is the case, you can disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing="true"` to your table, for example: +It's possible that Quarto's processing of HTML tables may interfere with the HTML produced computationally with table packages in R and Python (or other supported languages). + +You can disable Quarto's HTML table processing at a document level or project level with the option `html-table-processing`: + +```{.yaml} +--- +format: + html: + html-table-processing: none +--- +``` + +This option is also available as a code cell option for Knitr and Jupyter, e.g. + +````{markdown} +```{{r}} +#| html-table-processing: none + +# R Code that generates an HTML table +``` +```` + +To disable Quarto's HTML table processing for parts of a document use a div with the attribute `html-table-processing="none"`: + +````{.markdown} +::: {html-table-processing="none"} + +Content with HTML tables you don't want processed. + +::: +```` + +### Library authors + +If you are the author of a library that emits HTML tables you might like to disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing="true"` to the `` element. For example: ```html
...
-``` +``` \ No newline at end of file diff --git a/docs/authoring/videos.qmd b/docs/authoring/videos.qmd index d4461e9fb9..e9e8d10134 100644 --- a/docs/authoring/videos.qmd +++ b/docs/authoring/videos.qmd @@ -144,3 +144,8 @@ For videos on slides without titles, you might prefer to have the video fill the Note that when using `background-video` for video files (as distinct from services like YouTube) you can specify a number of other attributes, including: {{< include ../presentations/revealjs/_background-video.md >}} + +## Cross-References + +{{< include _cross-reference-divs-video.qmd >}} + diff --git a/docs/computations/execution-options.qmd b/docs/computations/execution-options.qmd index 60b379c7a7..7c74e71892 100644 --- a/docs/computations/execution-options.qmd +++ b/docs/computations/execution-options.qmd @@ -140,51 +140,7 @@ plt.show() ## Inline Code -Jupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). The syntax for this varies across the engines. - -### Jupyter - -To include executable expressions within markdown in a Python notebook, you use [`IPython.display.Markdown`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html) to dynamically generate markdown from within an ordinary code cell. For example, if we have a variable `radius` we can use it within markdown as follows: - -```{{python}} -#| echo: false -radius = 10 -from IPython.display import Markdown -Markdown(f"The _radius_ of the circle is **{radius}**.") -``` - -You can do the same in a Julia notebook using the [`Markdown`](https://docs.julialang.org/en/v1/stdlib/Markdown/) package: - -```{{julia}} -#| echo: false -radius = 10 -using Markdown -Markdown.parse(""" -The radius of the circle is $radius. -""") -``` - -Note that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output. - -### Knitr - -To include executable expressions within markdown for Knitr, enclose the expression in `` `r ` ``. For example, if we have a variable `radius` we can use it within markdown as follows: - -``` markdown -## Circle - -The radius of the circle is `r radius`. -``` - -### OJS - -To include reactive OJS expressions within markdown, use the syntax `${expr}`. For example, if we have a reactive called `radius` we can use it within markdown as follows: - -``` markdown -## Circle - -The radius of the circle is ${radius} -``` +Jupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). The syntax for this varies across the engines. See [Inline Code](inline-code.qmd) for details. ## Raw Output diff --git a/docs/computations/inline-code.qmd b/docs/computations/inline-code.qmd new file mode 100644 index 0000000000..a04f6969ce --- /dev/null +++ b/docs/computations/inline-code.qmd @@ -0,0 +1,177 @@ +--- +title: "Inline Code" +format: html +aliases: + - /docs/prerelease/1.4/inline.html +--- + +## Overview + +Inline code allows you to execute code within markdown, e.g. to automatically use the most up-to-date computations in narrative. Quarto provides an inline code syntax that works across all three engines (Jupyter, Knitr and OJS). + +The syntax for inline code is similar to code blocks, except you use a single tick (`` ` ``) rather than triple ticks (```` ``` ````), and you can use it in the middle of markdown. For example, the following code stores the variable `radius` in a code block and then accesses it in a sentence using inline code: + +::: {.panel-tabset group="engine"} +## Jupyter + +```` markdown +```{{python}} +radius = 5 +``` + +The radius of the circle is `{python} x` +```` + +This syntax works for any Jupyter kernel---so for Julia you would write an inline expression as `` `{julia} x` ``). + +## Knitr + +```` markdown +```{{r}} +radius <- 5 +``` + +The radius of the circle is `{r} x` +```` + +## OJS + +```` markdown +```{{ojs}} +radius = 5 +``` + +The radius of the circle is `{ojs} x` +```` +::: + +The result of the code is this markdown output: + +``` markdown +The radius of the circle is 5. +``` + +::: callout-caution +Inline expressions should be confined to simple values that you have pre-computed within normal code cells (rather than function calls that do non-trivial work). This is because the protocol used for inline expressions is not compatible with some Python libraries (especially those that use multi-threading or multi-processing). +::: + +Quarto also supports the native syntaxes of Knitr and OJS. Read more below in [Syntax Compatibility]. + +## Usage in Notebooks + +Inline expressions are always evaluated when rendering and previewing `.qmd` files. However, for notebooks you need to execute the notebook with Quarto to evaluate inline expressions (i.e. they won't be evaluated within the JupyterLab, VS Code, or PyCharm notebook editor). + +You can work in your favorite notebook front-end without Quarto execution, then once you are ready to publish execute the notebook during rendering as follows: + +``` {.bash filename="Terminal"} +$ quarto render notebook.ipynb --execute +``` + +You can also turn on execution within the YAML options of a notebook. For example: + +``` yaml +--- +title: "My Notebooks" +execute: + enabled: true +--- +``` + +## Markdown Output + +By default, the output of inline expressions is treated as ordinary text (i.e. markdown within it is not rendered). Any markdown-like syntax within the output of inline expressions will be automatically escaped. For example, the following inline expression: + +``` markdown + `{python} '**not bold**'` +``` + +Will produce the following markdown: + +``` markdown +\*\*not bold\*\* +``` + +To explicitly create markdown output, you'll need to use a function specific to your engine: + +::: {.panel-tabset group="engine"} +### Jupyter + +Use the `Markdown()` function from `IPython.display`: + +```` markdown +```{{python}} +from IPython.display import Markdown +``` + +This is `{python} Markdown('**bold**')` +```` + +### Knitr + +Use the `I()` function: + +``` markdown +This is `{r} I("**bold**")` +``` + +### OJS + +Use the `md` function: + +```` markdown +```{{ojs}} +text = md`This is **bold**` +``` + +`{ojs} text` +```` +::: + +## Escaping + +If you are writing documentation about inline expressions (as we are in this article!) then you may need to escape the syntax so that it doesn't execute. You can do that in one of two ways: + +1) Use a double-brace around the expression. For example: `` `{{{python}}} x` `` + +2) Enclose the expression in an extra backtick. For example: ``` ``{python} x`` ``` + +Each of the expressions above will render (unevaluated) as `` `{{python}} x` `` within the output document. + +## Engine Binding + +If you use inline expressions in a document that does not have any other executable code blocks then you should explicitly set the `engine` document option to ensure that your expressions are evaluated (automatic engine binding works for blocks but not inlines). For example: + +``` markdown +--- +title: "My Document" +engine: jupyter +--- + +`{python} "hello"` +``` + +## Syntax Compatibility + +To make it easier to learn and use expressions across engines, Quarto provides a single syntax that works for all engines. However, you can also use the native syntaxes of Knitr and Observable. + +### Knitr + +The native Knitr syntax also uses single backticks (`` ` ``) but doesn't enclose `r` in curly braces. For example: + +``` markdown +The radius of the circle is `r radius`. +``` + +The native Knitr inline syntax has a different default behavior for handling [Markdown Output]. Specifically, it treats all inline output as *containing markdown*. This means the above example is equivalent to: + +```markdown +The radius of the circle is `{r} I(radius)`. +``` + +### OJS + +Natively, OJS uses the syntax `${expr}`. For example: + +``` markdown +The radius of the circle is ${radius} +``` \ No newline at end of file diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index 432c93687f..d1b6c6f0ae 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -57,6 +57,8 @@ You can produce a wide variety of output types from executable code blocks, incl There are many options which control the behavior of code execution and output, you can read more about them in the article on [Execution Options](execution-options.qmd). +In addition to code blocks which interupt the flow of markdown, you can also include code inline. Read more about inline code in the [Inline Code](inline-code.qmd) article. + ### Multiple Outputs By default Julia cells will automatically print the value of their last statement (as with the example above where the call to `plot()` resulted in plot output). If you want to display multiple plots (or other types of output) from a single cell you should call the `display()` function explicitly. For example, here we output two plots side-by-side with sub-captions: diff --git a/docs/computations/ojs.qmd b/docs/computations/ojs.qmd index 78eb5365dc..e667cef12f 100644 --- a/docs/computations/ojs.qmd +++ b/docs/computations/ojs.qmd @@ -150,8 +150,7 @@ Frequently though you'll need to do some pre-processing of your data in Python o Use the `ojs_define()` function from Python or R to define variables that you want to use within JavaScript. For example, to reproduce the simple CSV read in Python you might do this: -```{python} -#| echo: fenced +```{{python}} import pandas as pd penguins = pd.read_csv("palmer-penguins.csv") ojs_define(data = penguins) @@ -195,6 +194,8 @@ data = FileAttachment("palmer-penguins.csv").csv({ typed: true }) To learn about all of the options available, see the article on [OJS Cells](/docs/interactive/ojs/ojs-cells.qmd). +In addition to OJS cells which interupt the flow of markdown, you can also include code inline. Read more about inline code in the [Inline Code](inline-code.qmd) article. + ## Learning More These articles go into more depth on using OJS in Quarto documents: diff --git a/docs/computations/python.qmd b/docs/computations/python.qmd index 785992ddd7..2676744e08 100644 --- a/docs/computations/python.qmd +++ b/docs/computations/python.qmd @@ -56,6 +56,8 @@ You can produce a wide variety of output types from executable code blocks, incl There are many options which control the behavior of code execution and output, you can read more about them in the article on [Execution Options](execution-options.qmd). +In addition to code blocks which interupt the flow of markdown, you can also include code inline. Read more about inline code in the [Inline Code](inline-code.qmd) article. + {{< include _jupyter-rendering.md >}} ## Installation {#installation} diff --git a/docs/computations/r.qmd b/docs/computations/r.qmd index 8516d57993..2e3621bc1d 100644 --- a/docs/computations/r.qmd +++ b/docs/computations/r.qmd @@ -47,7 +47,9 @@ This document results in the following rendered output: You can produce a wide variety of output types from executable code blocks, including plots, tabular output from data frames, and plain text output (e.g. printing the results of statistical summaries). -There are many options which control the behavior of code execution and output, you can read more about them in the article on [Execution Options](execution-options.qmd). +There are many options which control the behavior of code execution and output, you can read more about them in the article on [Execution Options](execution-options.qmd). + +In addition to code blocks which interupt the flow of markdown, you can also include code inline. Read more about inline code in the [Inline Code](inline-code.qmd) article. ### Rendering diff --git a/docs/computations/render-scripts.qmd b/docs/computations/render-scripts.qmd new file mode 100644 index 0000000000..5bc6d8ce48 --- /dev/null +++ b/docs/computations/render-scripts.qmd @@ -0,0 +1,197 @@ +--- +title: "Rendering Script Files" +format: html +code-annotations: select +aliases: + - /docs/prerelease/1.4/script-r.html + - /docs/prerelease/1.4/script.html +--- + +{{< include /docs/_require-1.4.qmd >}} + +## Overview + +Quarto supports rendering script files (e.g. `.py`, `.jl`, or `.r`) that are specially formatted as notebooks. The specific syntax for the format is different for the Jupyter and Knitr engines. The Jupyter engine can render Python, Julia, and R (using the [IRkernel](https://irkernel.github.io)) scripts, whereas the Knitr engine only renders R scripts. + +On this page you can learn the [syntax](#syntax) for Jupyter and Knitr notebook scripts, how to [Render and Preview](#render-and-preview) notebook scripts as well as using notebook [Scripts in Projects](#scripts-in-projects). + +## Syntax {#syntax} + +The syntax for delineating YAML, code and Markdown depends on whether you are rendering with the Jupyter or Knitr engine. For Python and Julia scripts use the Jupyter engine. For R scripts, you can use either the Jupyter or Knitr engine. + +### Jupyter + +Script rendering for Jupyter makes use of the [percent format](https://jupytext.readthedocs.io/en/latest/formats-scripts.html) that is supported by several other other tools including Spyder, VS Code, PyCharm, and Jupytext. + +In the percent format: + +- Markdown cells are delimited by `# %% [markdown]`, and can include content as single line comments (`#`) or multi-line strings (`"""`). + +- Code cells are delimited by `# %%`. + +There are also Quarto-specific additions: + +- The script must start with a markdown cell that includes a YAML header block (including the usual `---` YAML delimiters). + +- You can add code cell options in the usual way with `#|` comments. + +For example, here is a Python script that includes both markdown and code cells (you can click on the numbers on the right for further details): + +``` {.python filename="script.py"} +# %% [markdown] #<1> +# --- #<1> +# title: Palmer Penguins #<1> +# author: Norah Jones #<1> +# date: 3/12/23 #<1> +# --- #<1> + +# %% #<2> +#| echo: false #<2> +import pandas as pd #<2> +df = pd.read_csv("palmer-penguins.csv") #<2> + +# %% [markdown] #<3> +""" #<3> +## Exploring the data #<3> + #<3> +See @fig-bill-sizes for an exploration of bill sizes by species. #<3> +""" #<3> + +# %% +#| label: fig-bill-sizes #<4> +#| fig-cap: Bill Sizes by Species #<4> + +import matplotlib.pyplot as plt +import seaborn as sns + #<5> +g = sns.FacetGrid(df, hue="species", height=3, aspect=3.5/1.5) +g.map(plt.scatter, "bill_length_mm", "bill_depth_mm").add_legend() +``` + +1. Scripts rendered with Quarto must begin with a markdown cell containing the YAML header. +2. A code cell. +3. A markdown cell containing a multiline string (`"""`). +4. Code cell options specified with `#|` comments. +5. You can include blank lines within cells---cells continue until another cell is encountered. + +#### Generating Markdown + +Jupyter scripts are especially convenient when most of your document consists of code that dynamically generates markdown. You can write markdown from Python using functions in the `IPython.display` module. For example: + +``` python +# %% +#| echo: false +radius = 10 +from IPython.display import Markdown +Markdown(f"The _radius_ of the circle is **{radius}**.") +``` + +Note that dynamically generated markdown will still be enclosed in the standard Quarto output divs. If you want to remove all of Quarto's default output enclosures use the `output: asis` option. For example: + +``` python +# %% +#| echo: false +#| output: asis +radius = 10 +from IPython.display import Markdown +Markdown(f"The _radius_ of the circle is **{radius}**.") +``` + +#### Raw Cells + +You can include raw cells (e.g. HTML or LaTeX) within scripts using the `# %% [raw]` cell delimiter along with a `format` attribute, for example: + +``` python +# %% [raw] format="html" +""" + +""" +``` + +### Knitr + +Script rendering for Knitr is based on the `knitr::spin()` feature and makes use of the same [syntax rules](https://bookdown.org/yihui/rmarkdown-cookbook/spin.html): + +- Markdown content is included on lines starting with a the special `#'` comment. + +- Lines that don't start with `#` are code. Code blocks are split when Markdown content occurs , e.g. use `#'` to create another code block. + +There are also Quarto-specific additions: + +- The R script must start with YAML header block using the special `#'` comment. + +- You can add code cell options in the usual way with `#|` comments. + +For example, here is an R script that includes both markdown and code cells (you can click on the numbers on the right for further details): + +``` {.r filename="script.R"} +#' --- #<1> +#' title: Palmer Penguins #<1> +#' author: Norah Jones #<1> +#' date: 3/12/23 #<1> +#' format: html #<1> +#' --- #<1> + +library(palmerpenguins) #<2> + +#' ## Exploring the data #<3> +#' See @fig-bill-sizes for an exploration of bill sizes by species. #<3> + +#| label: fig-bill-sizes #<4> +#| fig-cap: Bill Sizes by Species #<4> +#| warning: false #<4> +library(ggplot2) +ggplot(data = penguins, + aes(x = bill_length_mm, + y = bill_depth_mm, + group = species)) + + geom_point(aes(color = species, + shape = species), + size = 3, + alpha = 0.8) + + labs(title = "Penguin bill dimensions", + subtitle = "Bill length and depth for Adelie, Chinstrap and Gentoo Penguins at Palmer Station LTER", + x = "Bill length (mm)", + y = "Bill depth (mm)", + color = "Penguin species", + shape = "Penguin species") +``` + +1. Scripts rendered with Quarto must begin with a YAML header using `#'` comments. +2. R code is the main content of the R script and is included without any delimitation. +3. Preface Markdown content with the `#'` comment. +4. Code cell options are specified with `#|` comments and apply to code below them. + +## Render and Preview {#render-and-preview} + +You can render and preview notebook scripts just as you would a `.qmd` or `.ipynb` file. For example, the following commands are all valid: + +``` bash +$ quarto render script.py +$ quarto render script.jl +$ quarto render script.R + +$ quarto preview script.py +$ quarto preview script.jl +$ quarto preview script.R +``` + +The script must begin with the appropriate [syntax](#syntax) for the YAML block to be rendered with Quarto. Based on the syntax detected Quarto will render with the Jupyter or Knitr engine. + +The [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) also implements support for rendering and previewing scripts. + +## Scripts in Projects {#scripts-in-projects} + +Notebook scripts can also be included within [projects](/docs/projects/quarto-projects.qmd) (e.g. websites, blogs, etc.). Scripts within projects are only rendered by Quarto when they start with the appropriate [syntax](#syntax). + +If for some reason you need to ignore such a script, you can create an explict render list in `_quarto.yml` that excludes individual scripts as required, for example: + +``` yaml +project: + type: website + render: + - "*.{qmd,R,py}" + - "!utils.py" +``` + +Note that this technique is documented for the sake of completeness---in practice you should almost never need to do this since scripts rarely begin with a YAML block unless you are authoring them specifically for report rendering. \ No newline at end of file diff --git a/docs/dashboards/data-display.qmd b/docs/dashboards/data-display.qmd index e7ee7a7c2e..4cf58fd9be 100644 --- a/docs/dashboards/data-display.qmd +++ b/docs/dashboards/data-display.qmd @@ -5,7 +5,7 @@ aliases: - data-presentation.html --- -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} Dashboards are compositions of components used to provide navigation and present data. Below we'll cover presenting data using plots, tables, and value boxes, as well how to include narrative content within dashboards. @@ -487,7 +487,7 @@ rows/columns, with no border. ### Dynamic Content -You can use [inline expressions](/docs/prerelease/1.4/inline.qmd) to make text content dynamic. For example, here we have a row with text content that makes use of Python expressions: +You can use [inline expressions](/docs/computations/inline-code.qmd) to make text content dynamic. For example, here we have a row with text content that makes use of Python expressions: ``` {.python .pymd} ::: {.card} diff --git a/docs/dashboards/interactivity/shiny-python/index.qmd b/docs/dashboards/interactivity/shiny-python/index.qmd index 7ae519140f..dac29143f3 100644 --- a/docs/dashboards/interactivity/shiny-python/index.qmd +++ b/docs/dashboards/interactivity/shiny-python/index.qmd @@ -6,7 +6,7 @@ aliases: - /docs/dashboards/interactivity/shiny-python.html --- -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} diff --git a/docs/dashboards/layout.qmd b/docs/dashboards/layout.qmd index 9248f39f65..7b4b412ed9 100644 --- a/docs/dashboards/layout.qmd +++ b/docs/dashboards/layout.qmd @@ -6,7 +6,7 @@ aliases: - layouts.html --- -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} Dashboards are compositions of components used to provide navigation and present data. Below we'll describe the components that are used to structure the navigation and layout of dashboards. diff --git a/docs/get-started/authoring/_authoring-complete.qmd b/docs/get-started/authoring/_authoring-complete.qmd index 1ad86ad020..49fe1102aa 100644 --- a/docs/get-started/authoring/_authoring-complete.qmd +++ b/docs/get-started/authoring/_authoring-complete.qmd @@ -37,7 +37,7 @@ We're going to do this analysis using literate programming [@knuth1984]. ## Exploratory data analysis {#sec-eda} -The data contains `r nrow(duke_forest)` houses. As part of the exploratory analysis let's visualize and summarize the relationship between areas and prices of these houses. +The data contains `{r} nrow(duke_forest)` houses. As part of the exploratory analysis let's visualize and summarize the relationship between areas and prices of these houses. ### Data visualization diff --git a/docs/get-started/authoring/_authoring.qmd b/docs/get-started/authoring/_authoring.qmd index d837678137..152dae6f1a 100644 --- a/docs/get-started/authoring/_authoring.qmd +++ b/docs/get-started/authoring/_authoring.qmd @@ -26,7 +26,7 @@ We present the results of exploratory data analysis in @sec-eda and the regressi ## Exploratory data analysis {#sec-eda} -The data contains `r nrow(duke_forest)` houses. +The data contains `{r} nrow(duke_forest)` houses. As part of the exploratory analysis let's visualize and summarize the relationship between areas and prices of these houses. ### Data visualization diff --git a/docs/get-started/computations/_computations-complete.qmd b/docs/get-started/computations/_computations-complete.qmd index 32f1251f8e..490cb7b777 100644 --- a/docs/get-started/computations/_computations-complete.qmd +++ b/docs/get-started/computations/_computations-complete.qmd @@ -12,7 +12,7 @@ format: library(ggplot2) ``` -There are `r nrow(mpg)` observations in our data. +There are `{r} nrow(mpg)` observations in our data. ```{r} #| echo: false @@ -21,7 +21,7 @@ mean_cty <- round(mean(mpg$cty), 2) mean_hwy <- round(mean(mpg$hwy), 2) ``` -The average city mileage of the cars in our data is `r mean_cty` and the average highway mileage is `r mean_hwy`. +The average city mileage of the cars in our data is `{r} mean_cty` and the average highway mileage is `{r} mean_hwy`. The plots in @fig-mpg show the relationship between city and highway mileage for 38 popular models of cars. In @fig-mpg-1 the points are colored by the number of cylinders while in @fig-mpg-2 the points are colored by engine displacement. diff --git a/docs/get-started/computations/rstudio.qmd b/docs/get-started/computations/rstudio.qmd index 92f5512cfb..c3f13c5829 100644 --- a/docs/get-started/computations/rstudio.qmd +++ b/docs/get-started/computations/rstudio.qmd @@ -232,19 +232,14 @@ See the documentation on [Article Layout](../../authoring/article-layout.qmd) to ## Inline Code -To include executable expressions within markdown, enclose the expression in `` `r ` ``. +To include executable expressions within markdown, enclose the expression in `` `{r} ` ``^[Quarto also supports the Knitr syntax `` `r ` ``, read more in [Inline Code](/docs/computations/inline-code.qmd)]. For example, we can use inline code to state the number of observations in our data. Try adding the following markdown text to your Quarto document. -```{=html} -
-
-
-There are `r nrow(mpg)` observations in our data. 
-
-
-
-``` +````markdown +There are `{r} nrow(mpg)` observations in our data. +```` + Save your document and inspect the rendered output. The expression inside the backticks has been executed and the sentence includes the actual number of observations. diff --git a/docs/get-started/hello/rstudio/_hello.qmd b/docs/get-started/hello/rstudio/_hello.qmd index 0587339d5f..1ec48a8e45 100644 --- a/docs/get-started/hello/rstudio/_hello.qmd +++ b/docs/get-started/hello/rstudio/_hello.qmd @@ -20,7 +20,7 @@ Quarto enables you to weave together content and executable code into a finished ![](https://raw.githubusercontent.com/quarto-dev/quarto-web/main/docs/get-started/hello/rstudio/lter_penguins.png){style="float:right;" fig-alt="Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst." width="401"} -The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins "palmerpenguins R package") package contains size measurements for `r nrow(penguins)` penguins from three species observed on three islands in the Palmer Archipelago, Antarctica. +The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins "palmerpenguins R package") package contains size measurements for `{r} nrow(penguins)` penguins from three species observed on three islands in the Palmer Archipelago, Antarctica. The plot below shows the relationship between flipper and bill lengths of these penguins. diff --git a/docs/guide/guide.yml b/docs/guide/guide.yml index 0cc9b44ed6..bcb8543a92 100644 --- a/docs/guide/guide.yml +++ b/docs/guide/guide.yml @@ -58,6 +58,8 @@ href: ../output-formats/pdf-basics.qmd - text: MS Word href: ../output-formats/ms-word.qmd + - text: Typst + href: ../output-formats/typst.qmd - text: Markdown href: ../output-formats/gfm.qmd - text: All Formats @@ -113,7 +115,19 @@ - text: "Book Crossrefs" href: ../books/book-crossrefs.qmd - text: "Customizing Output" - href: ../books/book-output.qmd + href: ../books/book-output.qmd + +- title: Manuscripts + subtitle: Write and publish notebook-first scholarly articles + links: + - text: Getting Started + href: /docs/manuscripts/index.qmd + - text: "Authoring Manuscripts" + href: /docs/manuscripts/authoring/jupyterlab.qmd + - text: "Publishing Manuscripts" + href: /docs/manuscripts/publishing.qmd + - text: "Using Manuscripts" + href: /docs/manuscripts/components.qmd - title: Interactivity subtitle: Engage readers with interactivity @@ -140,6 +154,8 @@ href: ../publishing/github-pages.qmd - text: Posit Connect href: ../publishing/rstudio-connect.qmd + - text: Posit Cloud + href: ../publishing/posit-cloud.qmd - text: Netlify href: ../publishing/netlify.qmd - text: Confluence diff --git a/docs/journals/authors.qmd b/docs/journals/authors.qmd index 17c8923247..9d6b122ffc 100644 --- a/docs/journals/authors.qmd +++ b/docs/journals/authors.qmd @@ -85,6 +85,8 @@ author: email: string phone: string fax: string + degrees: + # see schema below orcid: string note: string acknowledgements: string @@ -133,6 +135,27 @@ name: dropping-particle: von ``` +### Degrees + +Degrees or academic titles can specified with `degrees` and can be either of: + +- A single string: + + ``` yaml + author: + degrees: PhD + ``` +- An array of strings: + + ``` yaml + author: + degrees: + - PhD + - MsSc + ``` + +It will always be normalized into an array of degrees. + ### Attributes Recognized attribute keys that appear at the top level (for example, `corresponding`) will automatically be normalized under attributes. For example: @@ -222,6 +245,7 @@ affiliations: number: number name: string department: string + group: string address: string city: string region: string diff --git a/docs/journals/templates.qmd b/docs/journals/templates.qmd index ccca034a13..beac1da68f 100644 --- a/docs/journals/templates.qmd +++ b/docs/journals/templates.qmd @@ -98,6 +98,10 @@ doc-class.tex : Contains the document class declaration and options. By default we provide the identical document class that Pandoc provides, implementing many features. If you override this (which will be common), you will need to either implement support for the document class options or be aware that those options (e.g. font-size, paper-size, classoption, etc...) will not be supported in your output. +before-title.tex + +: Appears in the document premable just before the title block. By default, this partial is empty. + title.tex : Provides configuration of document metadata for writing the title block. Note that in addition to these templates and partials, Quarto will also make normalized authors and affiliations data available to the template, making is easy to write custom title blocks against a standard schema. @@ -116,7 +120,7 @@ toc.tex before-bib.tex -: Placed after the content of the document, but before the bibliography. By default contains nothing. s +: Placed after the content of the document, but before the bibliography. By default contains nothing. biblio.tex diff --git a/docs/manuscripts/_metadata.yml b/docs/manuscripts/_metadata.yml index ed152382f8..18a771409e 100644 --- a/docs/manuscripts/_metadata.yml +++ b/docs/manuscripts/_metadata.yml @@ -1,6 +1,4 @@ page-navigation: false -sidebar: manuscripts css: tutorial.css execute: - eval: false -draft: true \ No newline at end of file + eval: false \ No newline at end of file diff --git a/docs/manuscripts/authoring/_front-matter.qmd b/docs/manuscripts/authoring/_front-matter.qmd index 5a73a7d40b..b9d916f8a8 100644 --- a/docs/manuscripts/authoring/_front-matter.qmd +++ b/docs/manuscripts/authoring/_front-matter.qmd @@ -43,6 +43,6 @@ number-sections: true For example, at the top level the header in `{{< meta tool.article-file >}}` sets the following keys: `title`, `author`, `keywords`, `abstract`, `plain-language-summary`, `key-points`, `date`, `bibliography`, `citation`, and `number-sections`. -You've seen how editing the `title` key updated the title of the article on the manuscript webpage. The `title` key is also used by the PDF and Word formats, but not all of the keys are used in all formats. For instance, `keywords` is not used in the HTML, PDF or Word formats, but it is used inside the MECA archive. +You've seen how editing the `title` key updated the title of the article on the manuscript webpage. The `title` key is also used by the PDF and Word formats, but not all of the keys are used in all formats. You can read more about setting the front matter for your article in [Scholarly Front Matter](/docs/authoring/front-matter.qmd). diff --git a/docs/manuscripts/authoring/_inline-computations.qmd b/docs/manuscripts/authoring/_inline-computations.qmd index e145b9794e..4ae622948a 100644 --- a/docs/manuscripts/authoring/_inline-computations.qmd +++ b/docs/manuscripts/authoring/_inline-computations.qmd @@ -209,7 +209,7 @@ avg_years_between_eruptions ::: ::: {.content-visible unless-meta="tool.is_rstudio"} -You can also use computed values directly in your article text by using the `Markdown()` function from the IPython display module. Read more in [Inline Code](/docs/computations/execution-options.html#inline-code). +You can also use computed values directly in your article text by using inline code. Read more in [Inline Code](/docs/computations/inline-code.qmd). ::: ::: {.content-visible when-meta="tool.is_rstudio"} diff --git a/docs/manuscripts/authoring/_setup.qmd b/docs/manuscripts/authoring/_setup.qmd index 9350d44f85..dc7ff19ad0 100644 --- a/docs/manuscripts/authoring/_setup.qmd +++ b/docs/manuscripts/authoring/_setup.qmd @@ -13,7 +13,7 @@ To follow along, you'll need to install the VS Code Quarto extension, install so ::: callout-important ## Install Quarto First -If you haven't already, make sure you've installed the pre-release version of Quarto, as described in the [Manuscript Overview](../index.qmd#install). +If you haven't already, make sure you've installed the latest release version of Quarto, as described in the [Manuscript Overview](../index.qmd#install). ::: ::: {.content-visible when-meta="tool.is_jupyterlab"} diff --git a/docs/manuscripts/components.qmd b/docs/manuscripts/components.qmd index 8b2669e4f6..e0c0b47836 100644 --- a/docs/manuscripts/components.qmd +++ b/docs/manuscripts/components.qmd @@ -1,7 +1,9 @@ --- -title: "Manuscript Basics" +title: "Using Manuscripts" --- +{{< include /docs/_require-1.4.qmd >}} + ## Overview Manuscripts are a type of Quarto project that allow you to write scholarly articles where computational notebooks are both the source of the article, and part of the published record. @@ -134,6 +136,12 @@ manuscript: manuscript-url: www.posit.co ``` +## Using Binder + +[Binder](https://mybinder.org/) allows you to provide readers with a link that restores your computing environment so they can interact with your manuscript notebooks in a cloud computing environment. + +Quarto can help you configure your manuscript to use Binder. Read more at [Using Binder](/docs/projects/binder.qmd). + ## Customizing Pages The article page and notebook views on your manuscript site are HTML pages, and can be customized using options for the `html` format. diff --git a/docs/manuscripts/index.qmd b/docs/manuscripts/index.qmd index d311c58c3f..76cab5e67e 100644 --- a/docs/manuscripts/index.qmd +++ b/docs/manuscripts/index.qmd @@ -11,10 +11,10 @@ format: window['quarto-download-prerelease'] = true; window['quarto-download-nonews'] = true; window["quarto-prerelease-mode"] = '{{< meta prerelease-mode >}}'; - + --- -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} ## Overview @@ -57,9 +57,19 @@ Links that leave the manuscript webpage, for example to take a reader to the man ### Install Quarto {#install} -Manuscripts are a feature in the upcoming 1.4 release of Quarto and are still under active development. Before you get started, make sure you install the **latest pre-release** version of Quarto. +Manuscripts are a feature in the 1.4 release of Quarto. Before you get started, make sure you install the **latest release** version of Quarto. -{{< include ../download/_download-pre.md >}} +{{< include ../download/_download.md >}} + +```{=html} + +``` + +You can find release notes and installers for all platforms at ### Choose Your Tool {#choose} diff --git a/docs/output-formats/html-basics.qmd b/docs/output-formats/html-basics.qmd index e69923cd0b..7de8d22271 100644 --- a/docs/output-formats/html-basics.qmd +++ b/docs/output-formats/html-basics.qmd @@ -59,6 +59,8 @@ format: toc-location: left ``` +If you would like to display a table of contents both in the body and floating left or right, you can specify `left-body` or `right-body` respectively. + The floating table of contents can be used to navigate to sections of the document and also will automatically highlight the appropriate section as the user scrolls. The table of contents is responsive and will become hidden once the viewport becomes too narrow. See an example on the right of this page. Note that the `toc-location` option is not available when you disable the standard HTML theme (e.g. if you specify the `theme: none` or `theme: pandoc` option). @@ -312,18 +314,21 @@ You can also specify one or both of these behaviors for an individual link using ## Reference Popups -If you hover your mouse over the citation and footnote in this sentence you'll see a popup displaying the reference contents: +If you hover your mouse over the citation, footnote and cross-reference in this sentence you'll see a popup displaying the reference contents: -   Hover over @xie2015 to see a reference to the definitive book on knitr[^1]. +   Hover over @xie2015 to see a reference to the definitive book on knitr[^1]. @lst-hover shows you how to disable hover behaviour. This behavior is enabled by default. You can disable it with the following options: -``` yaml +::: {#lst-hover} +```{.yaml} format: html: citations-hover: false footnotes-hover: false + crossrefs-hover: false ``` +::: ## Commenting @@ -334,7 +339,7 @@ comments: hypothesis: true ``` -You can see the Hypothesis UI at the far right of the page. Rather than `true`, you can specify any of the available Hypothesis [embedding options](https://h.readthedocs.io/projects/client/en/latest/publishers/config.html) as a sub-key of `hypothesis`. For example: +You can see the Hypothesis UI at the far right of the page. Rather than `true`, you can specify any of the available Hypothesis [embedding options](/docs/reference/projects/websites.html#hypothesis) as a sub-key of `hypothesis`. For example: ``` yaml comments: @@ -350,7 +355,7 @@ comments: repo: quarto-dev/quarto-docs ``` -You can also specify the other options [documented here](https://utteranc.es/). +You can also specify the other options [documented here](/docs/reference/projects/websites.html#utterances). You may also enable [Giscus](https://giscus.app) for commenting using the `giscus` option. Giscus will store comments in the 'Discussions' of a Github repo. diff --git a/docs/prerelease/1.4/lightbox.qmd b/docs/output-formats/html-lightbox-figures.qmd similarity index 88% rename from docs/prerelease/1.4/lightbox.qmd rename to docs/output-formats/html-lightbox-figures.qmd index c3bcea641a..16847630a5 100644 --- a/docs/prerelease/1.4/lightbox.qmd +++ b/docs/output-formats/html-lightbox-figures.qmd @@ -1,23 +1,25 @@ --- -title: "Lightbox Support" +title: "Lightbox Figures" lightbox: true +aliases: + - /docs/prerelease/1.4/lightbox.html --- -{{< include _pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} ## Overview -The new lightbox feature in Quarto uses the [GLightbox javascript library](https://biati-digital.github.io/glightbox/) to add lightbox styling and behavior to images in your HTML documents. +Quarto uses the [GLightbox javascript library](https://biati-digital.github.io/glightbox/) to add lightbox styling and behavior to images in your HTML documents. Lightbox images allow a reader to click to see a larger version of the image (including any caption). -Lightbox images allow a reader to click to see a larger version of the image (including any caption). For example, the following images have lightbox treatment: +For example, the following images have lightbox treatment: ::: {layout-ncol=3} -![Photo by Hush Naidoo Jade Photography on Unsplash](images/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg){group="lightbulbs" fig-alt="A photo of a lightbulb with a flower growing inside against a black background."} +![Photo by Hush Naidoo Jade Photography on Unsplash](images/lightbox/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg){group="lightbulbs" fig-alt="A photo of a lightbulb with a flower growing inside against a black background."} -![Photo by Alessandro Bianchi on Unsplash](images/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg){group="lightbulbs" fig-alt="A photo of a lightbulb with a glowing filament against a black background."} +![Photo by Alessandro Bianchi on Unsplash](images/lightbox/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg){group="lightbulbs" fig-alt="A photo of a lightbulb with a glowing filament against a black background."} -![Photo by Joshua Melo on Unsplash](images/joshua-melo-peFHn8r4t1o-unsplash.jpg){group="lightbulbs" fig-alt="A photo of a lightbulb with a glowing filament in front of a background of other lightbulbs."} +![Photo by Joshua Melo on Unsplash](images/lightbox/joshua-melo-peFHn8r4t1o-unsplash.jpg){group="lightbulbs" fig-alt="A photo of a lightbulb with a glowing filament in front of a background of other lightbulbs."} ::: @@ -32,6 +34,7 @@ lightbox: true ![A Lovely Image](mv-1.jpg) ``` + ## Enabling Lightbox You can enable lightbox either for all images within a document, or for only selected images within a document. To enable lightbox for all images within a document, use the following yaml: diff --git a/docs/output-formats/html-publishing.qmd b/docs/output-formats/html-publishing.qmd index 593c60c5d5..d29413f132 100644 --- a/docs/output-formats/html-publishing.qmd +++ b/docs/output-formats/html-publishing.qmd @@ -30,6 +30,7 @@ Here's a brief overview of the various supported services and when they might be | [Quarto Pub](../publishing/quarto-pub.html) | Publishing service for Quarto documents, websites, and books. Use Quarto Pub when you want a free, easy to use service for publicly available content. | | [GitHub Pages](../publishing/github-pages.html) | Publish content based on source code managed within a GitHub repository. Use GitHub Pages when the source code for your document or site is hosted on GitHub. | | [Posit Connect](../publishing/rstudio-connect.html) | Publishing platform for secure sharing of data products within an organization. Use Posit Connect when you want to publish content within an organization rather than on the public internet. | +| [Posit Cloud](../docs/publishing/posit-cloud.html) | Create data projects and publish results from your web browser. Use Posit Cloud when you want to organize all your static documents and interactive applications in one place. | | [Netlify](../publishing/netlify.html) | Professional web publishing platform. Use Netlify when you want support for custom domains, authentication, previewing branches, and other more advanced capabilities. | | [Other Services](../publishing/other.html) | Content rendered with Quarto uses standard formats (HTML, PDFs, MS Word, etc.) that can be published anywhere. Use this if one of the methods above don't meet your requirements. | diff --git a/docs/output-formats/images/lightbox/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg b/docs/output-formats/images/lightbox/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg new file mode 100644 index 0000000000..75364505c0 Binary files /dev/null and b/docs/output-formats/images/lightbox/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg differ diff --git a/docs/output-formats/images/lightbox/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg b/docs/output-formats/images/lightbox/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg new file mode 100644 index 0000000000..3c7f8f9774 Binary files /dev/null and b/docs/output-formats/images/lightbox/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg differ diff --git a/docs/output-formats/images/lightbox/joshua-melo-peFHn8r4t1o-unsplash.jpg b/docs/output-formats/images/lightbox/joshua-melo-peFHn8r4t1o-unsplash.jpg new file mode 100644 index 0000000000..85d96b7f3b Binary files /dev/null and b/docs/output-formats/images/lightbox/joshua-melo-peFHn8r4t1o-unsplash.jpg differ diff --git a/docs/prerelease/1.4/images/typst-custom-page.png b/docs/output-formats/images/typst-custom-page.png similarity index 100% rename from docs/prerelease/1.4/images/typst-custom-page.png rename to docs/output-formats/images/typst-custom-page.png diff --git a/docs/prerelease/1.4/images/typst-default-page.png b/docs/output-formats/images/typst-default-page.png similarity index 100% rename from docs/prerelease/1.4/images/typst-default-page.png rename to docs/output-formats/images/typst-default-page.png diff --git a/docs/prerelease/1.4/images/typst-format-dept-news.png b/docs/output-formats/images/typst-format-dept-news.png similarity index 100% rename from docs/prerelease/1.4/images/typst-format-dept-news.png rename to docs/output-formats/images/typst-format-dept-news.png diff --git a/docs/prerelease/1.4/images/typst-format-ieee.png b/docs/output-formats/images/typst-format-ieee.png similarity index 100% rename from docs/prerelease/1.4/images/typst-format-ieee.png rename to docs/output-formats/images/typst-format-ieee.png diff --git a/docs/prerelease/1.4/images/typst-format-letter.png b/docs/output-formats/images/typst-format-letter.png similarity index 100% rename from docs/prerelease/1.4/images/typst-format-letter.png rename to docs/output-formats/images/typst-format-letter.png diff --git a/docs/prerelease/1.4/images/typst-format-poster.png b/docs/output-formats/images/typst-format-poster.png similarity index 100% rename from docs/prerelease/1.4/images/typst-format-poster.png rename to docs/output-formats/images/typst-format-poster.png diff --git a/docs/output-formats/typst-custom.qmd b/docs/output-formats/typst-custom.qmd new file mode 100644 index 0000000000..d854404e14 --- /dev/null +++ b/docs/output-formats/typst-custom.qmd @@ -0,0 +1,80 @@ +--- +title: "Custom Typst Formats" +--- + +{{< include /docs/_require-1.4.qmd >}} + +## Overview + +When you author a Typst document in Quarto, you’ll be using a Quarto format that is in turn based on a Typst template. The default template provides a basic article layout, but Typst provides an easy way to [define your own templates](https://typst.app/docs/tutorial/making-a-template/) to produce highly customized documents. + +Typst templates can be packaged as custom formats for Quarto to allow them to be easily used and shared. On this page, learn about some custom Typst formats available from the Quarto team, as well as how to create your own. + +## Custom Formats {#custom-formats} + +You can create highly customized output with Typst by defining a new format based on a custom Typst template. The Typst team has created several useful [templates](https://github.com/typst/templates), a few which which have been adapted for use with Quarto as custom formats. These formats include: + +| Format | Usage | +|--------------------------|----------------------------------------------| +| [Poster](https://github.com/quarto-ext/typst-templates/tree/main/poster) | `quarto use template quarto-ext/typst-templates/poster` | +| [IEEE](https://github.com/quarto-ext/typst-templates/tree/main/ieee) | `quarto use template quarto-ext/typst-templates/ieee` | +| [AMS](https://github.com/quarto-ext/typst-templates/tree/main/ams) | `quarto use template quarto-ext/typst-templates/ams` | +| [Letter](https://github.com/quarto-ext/typst-templates/tree/main/letter) | `quarto use template quarto-ext/typst-templates/letter` | +| [Fiction](https://github.com/quarto-ext/typst-templates/tree/main/fiction) | `quarto use template quarto-ext/typst-templates/fiction` | +| [Dept News](https://github.com/quarto-ext/typst-templates/tree/main/dept-news) | `quarto use template quarto-ext/typst-templates/dept-news` | + +: {tbl-colwidths=\[20,80\]} + +The source code for these formats is available at . + +## Create a Format + +To create a new custom Typst format (or package an existing Typst template for use with Quarto) use the `quarto create` command to get started: + +``` {.bash filename="Terminal"} +$ quarto create extension format +``` + +Then, choose `typst` as the base format and provide a name for the extension (e.g. `letter`). A sample Typst format extension will be created based on the code used in the default template that ships with Quarto. It will include the following files which you can edit to implement your custom format: + +| File | Description | +|-------------------------|-----------------------------------------------| +| `_extension.yml` | Basic extension metadata (name, author, description, etc.) and format definition. | +| `README.md` | Documentation on how to install and use the format. | +| `template.qmd` | A starter document that demonstrates the basics of the format. | +| `typst-template.typ` | The core Typst template function (documentation on creating Typst templates can be found here: ). | +| `typst-show.typ` | File that calls the template's function (mapping Pandoc metadata to function arguments). | + +Additional resources you might find useful when creating custom formats include: + +- The official Typst tutorial on [Making a Template](https://typst.app/docs/tutorial/making-a-template/) + +- List of third party templates from the [Awesome Quarto](https://github.com/qjcg/awesome-typst#templates--libraries) repo. + +## Advanced Customization + +::: callout-note +This section covers advanced customization of Typst format output and can be safely ignored unless you have found the method of defining custom Typst formats described above too limited. +::: + +Above we describe a method of creating a Typst format based on specifying two [template partials](https://quarto.org/docs/journals/templates.html#template-partials) (`typst-template.typ` and `typst-show.typ`). These partials customize components of the default Typst Pandoc template, but leave some of the core scaffolding including definitions required by Pandoc for its Typst output as well as handling of bibliographies and footnotes (this means that your own custom Typst formats do not need to explicitly handle them). + +If you would like to fully override the Pandoc template used for rendering Typst, use the `template` option in your custom format (rather than `template-partials`) and provide an alternate implementation of the default template. For example, your `_extensions.yml` might look like this: + +``` {.yaml filename="_extensions.yml"} +title: Typst Custom Format +author: Jane Smith +version: "0.2.0" +quarto-required: ">=1.4.11" +contributes: + formats: + typst: + template: template.typ + template-partials: + - typst-template.typ + - typst-show.typ +``` + +Use the [source code](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/typst/pandoc/quarto/template.typ) of the default template as a starting point for your `template.typ`. Note that you can call all of the template partials provided by Quarto (e.g. `biblio.typ()` or `notes.typ()`) from within your custom template implementation. + +The [AMS](https://github.com/quarto-ext/typst-templates/tree/main/ams) format provides an example of redefining the main template (in that case, it is to prevent automatic bibliography processing by Quarto in deference to the built-in handling of the Typst AMS template). diff --git a/docs/output-formats/typst.qmd b/docs/output-formats/typst.qmd new file mode 100644 index 0000000000..84978ccc50 --- /dev/null +++ b/docs/output-formats/typst.qmd @@ -0,0 +1,263 @@ +--- +title: "Typst Basics" +tbl-colwidths: [35,65] +aliases: + - /docs/prerelease/1.4/typst.html +--- + +{{< include /docs/_require-1.4.qmd >}} + +## Overview + +[Typst](https://github.com/typst/typst) is a new open-source markup-based typesetting system that is designed to be as powerful as LaTeX while being much easier to learn and use. Typst creates beautiful PDF output with blazing fast render times. + +Use the `typst` format to create a PDF document via Typst. For example: + +```{.yaml filename="hello-typst.qmd"} +--- +title: "Hello Typst!" +format: + typst: + toc: true + section-numbering: 1.1.a + columns: 2 +--- +``` + +Rendering or previewing this document will invoke the Typst CLI to create `hello-typst.pdf`, a PDF file, from your markdown source file. Quarto includes the Typst CLI so no separate installation of Typst is required. + +The above example highlights a few of the options available for Typst output. This document covers these and other options in detail. See the Typst [format reference](/docs/reference/formats/typst.qmd) for a complete list of all available options. + +One of the highlights of Typst is the ease of creating highly customized templates. For example, here are some Typst templates that you can use in Quarto as custom formats: + +::: {layout-ncol=4} + +![IEEE](images/typst-format-ieee.png){.lightbox group="custom-formats" fig-alt="Screenshot of a page showing a article styled according IEEE standards. The title is centered with authors below in two columns."} + +![Poster](images/typst-format-poster.png){.lightbox group="custom-formats" fig-alt="Screenshot of a poster in landscape orientiation. The poster includes a logo in the top right, a title in the top left, and content arranged in three columns."} + +![Letter](images/typst-format-letter.png){.lightbox group="custom-formats" fig-alt="Screenshot of a page showing a letter. A sender address is across the top of the page, followed by a recipient address left justified. The body of the letter includes a subject line in bold."} + +![Dept News](images/typst-format-dept-news.png){.lightbox group="custom-formats" fig-alt="Screenshot of a page showing a department newsletter. The page is split vertically with a white column on the left and a red one on the right. An image spans across the column with the text \"Award Winning Science\" oriented to run vertically down its right side."} + +::: + + Learn more about how to use them, and how to create your own in [Custom Formats](typst-custom.qmd). + +## Known Limitations + +Since Typst is under active development, there are still some limitations to Quarto's Typst support: + +- The default size of images may not reflect the behavior you are used to in other output formats. This is a problem that Typst, pandoc and Quarto are actively working to fix. In the meantime, you can manually [specify image widths](/docs/authoring/figures.qmd#figure-sizing). + +- Advanced page layout (e.g. using the `.column` classes as explained in [Article Layout](https://quarto.org/docs/authoring/article-layout.html)) is not implemented. + +- Various other small things might not yet be implemented. Please [let us know](https://github.com/quarto-dev/quarto-cli/issues/new/choose) if you see things that could use improvement! + +## Page Layout + +You can control the size of the page (`papersize`), the page margins (`margin`), and the number of columns used for page content (`columns`). For example, the following YAML modifies all three options: + +```yaml +--- +title: Page Layout +format: + typst: + papersize: a5 + margin: + x: 1cm + y: 1cm + columns: 2 +--- +``` + +The resulting layout is shown below alongside an example of the default layout: + +:::{layout-ncol=2} + +![Customized Layout](images/typst-custom-page.png){.border fig-alt="Screenshot of one page of PDF document. The document shows a two columns of text. Compared to the previous screenshot, the page is narrower and longer, and the margins are smaller."} + +![Default Layout](images/typst-default-page.png){.border fig-alt="Screenshot of one page of PDF document. The document shows a single column of text."} + +::: + +You can read more about these page layout options in the sections below. + +### Paper Size + +The `papersize` option expects a string matching one of Typst's supported [paper sizes](https://typst.app/docs/reference/layout/page/#parameters-paper). The default template is equivalent to: + +```yaml +papersize: us-letter +``` + +### Margins + +The `margin` option expects one or more of the suboptions: `x`, `y`, `top`, `bottom`, `left` and `right`. The default template uses margins equivalent to: + +```yaml +margin: + x: 1.25in + y: 1.25in +``` + +This sets the margins in the horizontal direction (`x`), i.e. `left` and `right`, as well as the margins in the vertical direction (`y`), i.e. `top` and `bottom` to 1.25 inches. + +The values for the margins are specfied using Typst's [length](https://typst.app/docs/reference/layout/length/), (e.g. `5cm`) or [relative length](https://typst.app/docs/reference/layout/relative/) (e.g. `10%`) types. You can specify a single margin: + +```yaml +margin: + left: 1cm +``` + +Then, any unspecified margins will inherit from the default margins. + +### Columns + +The `columns` option expects a number - the number of columns your body content should have. The default template sets `columns` to `1`. + + +{{< include /docs/output-formats/_document-options-toc.md >}} + +{{< include /docs/output-formats/_document-options-section-numbering.md >}} + +You can also customize the display of the section numbers with the `section-numbering` YAML option. This option expects a string that describes the numbering schema. For example, the following schema describes numbering sections with numerals, subsection with uppercase letters, and subsubsections with lower case letters, using `.` as a separator: + +```yaml +--- +section-numbering: 1.A.a +--- +``` + +You can read more about sepcifying the numbering schema in the [Typst documentation for numbering](https://typst.app//docs/reference/model/numbering#parameters-numbering). + +{{< include /docs/output-formats/_code-annotation.md >}} + +## Bibliography + +Typst comes with its [own citation processing system for bibliographies](https://typst.app/docs/reference/meta/bibliography/) and using `format: typst` defaults to it. To specify a bibliography style using Typst's system, use the `bibliographystyle` option. Provide a string from [Typst's list of built-in styles](https://typst.app/docs/reference/model/bibliography/#parameters-style), e.g.: + +``` yaml +bibliography: refs.bib +bibliographystyle: apa +``` + +Or alternatively, provide a path to a local CSL file: + +``` yaml +bibliography: refs.bib +bibliographystyle: my-csl-style.csl +``` + +If you prefer to use Pandoc's citation processing, set `citeproc: true` explicitly in YAML header: + +``` yaml +citeproc: true +bibliography: refs.bib + csl: https://www.zotero.org/styles/apa-with-abstract +``` + +To provide a citation style file to Pandoc's citation processing system use the `csl` option, as described in [Citation Style](https://quarto.org/docs/authoring/footnotes-and-citations.html#sec-citations-style). + + +## Typst Blocks + +If you want to change the appearance of blocks using native [Typst `#block()`](https://typst.app/docs/reference/layout/block/) calls, you can add the `.block` class to a Div and provide whatever arguments are appropriate. For example: + +```` markdown +::: {.block fill="luma(230)" inset="8pt" radius="4pt"} + +This is a block with gray background and slightly rounded corners. + +::: +```` + +This gets compiled to + +```` default +#block(fill:luma(230), inset=8pt, radius=4pt, +[This is a block with gray background and slightly rounded corners]) +```` + +## Raw Typst + +If you want to use raw `typst` markup, use a raw `typst` block. For example: + +```` default +```{=typst} +#set par(justify: true) + +== Background +In the case of glaciers, fluid dynamics principles can be used to understand how the movement and behavior of the ice is influenced by factors such as temperature, pressure, and the presence of other fluids (such as water). +``` +```` + +To learn more about `typst` markup, see the tutorial here: . + + +## Typst File (`.typ`) + +The rendering process produces a native Typst file (`.typ)` which is then compiled to PDF using the Typst CLI. This intermediate file is then automatically removed. If you want to preserve the `.typ` file, use the `keep-typ` option. For example: + +``` yaml +--- +title: "My Document" +format: + typst: + keep-typ: true +--- +``` + +You can compile a `.typ` file to PDF directly using the `quarto typst compile` command in a terminal. For example: + +``` {.bash filename="Terminal"} +$ quarto typst compile article.typ +``` + +The `quarto typst` command uses the version of Typst built in to Quarto and supports all Typst CLI actions and flags. For example, to determine the version of Typst embedded in Quarto: + +``` {.bash filename="Terminal"} +$ quarto typst --version +``` + +## Fonts Support + +The main font used for the document can be specified with the `mainfont` YAML option. Typst will search by default in installed system fonts. You can set additional paths to search using `font-paths`. For example: + +``` yaml +--- +title: "My Document" +format: + typst: + mainfont: "Agbalumo" + font-paths: myfonts +--- +``` + +This will search for a `*.ttf` or `*.otf` file matching the font name in the `./myfonts/` directory, in addition to searching in installed system fonts. + +The `TYPST_FONT_PATHS` environment variable is also taken into account for compatibility with Typst configuration, but setting `font-paths` will take precedence over any path set in the `TYPST_FONT_PATHS` environment variable. + +Set the base size of the font used in the document with `fontsize`. The size used in the default template is equivalent to: + +```yaml +--- +fontsize: 11pt +--- +``` + + +## Includes + +{{< include /docs/output-formats/_document-options-includes.md >}} + +For example: + +``` yaml +format: + typst: + include-before-body: + - text: | + #show heading: set text(navy) +``` + diff --git a/docs/prerelease/1.4/_highlights.qmd b/docs/prerelease/1.4/_highlights.qmd index ab01f882f0..c28f7f54d4 100644 --- a/docs/prerelease/1.4/_highlights.qmd +++ b/docs/prerelease/1.4/_highlights.qmd @@ -4,7 +4,7 @@ Quarto 1.4 includes the following new features: - [Quarto Dashboards](/docs/dashboards/index.qmd)--A new format for creating interactive dashboards. -- [Typst Format](/docs/prerelease/1.4/typst.qmd)---Support for the `typst` output format. [Typst](https://github.com/typst/typst) is a new open-source markup-based typesetting system that is designed to be as powerful as LaTeX while being much easier to learn and use. +- [Typst Format](/docs/output-formats/typst.qmd)---Support for the `typst` output format. [Typst](https://github.com/typst/typst) is a new open-source markup-based typesetting system that is designed to be as powerful as LaTeX while being much easier to learn and use. - Cross-reference changes: @@ -12,9 +12,9 @@ Quarto 1.4 includes the following new features: - Allows the definition of [Custom Cross-Reference Types](/docs/authoring/cross-references-custom.qmd) via document or project YAML. - - Adds `lst-label` and `lst-cap` code cell options to create [Cross-referenceable Listings for Executable Code](/docs/authoring/cross-references-listings.qmd). + - Adds `lst-label` and `lst-cap` code cell options to create [Cross-referenceable Listings for Executable Code](/docs/authoring/cross-references.qmd#code-listings). - - Allows [Cross-Referencing Callouts](/docs/authoring/cross-references-callouts.qmd). + - Allows [Cross-Referencing Callouts](/docs/authoring/cross-references.qmd#callouts). - Adds the prefixes `rem-` and `sol-` to cross-reference Remarks and Solutions in addition to the [existing theorem types](/docs/authoring/cross-references.html#theorems-and-proofs). @@ -22,19 +22,21 @@ Quarto 1.4 includes the following new features: - [Shiny for Python](/docs/dashboards/interactivity/shiny-python/index.qmd)---Support for using Shiny for Python within Quarto documents. -- [Inline Execution for Jupyter](/docs/prerelease/1.4/inline.qmd)---Support for executing inline expressions when using Jupyter kernels. +- [Inline Execution for Jupyter](/docs/computations/inline-code.qmd)---Support for executing inline expressions when using Jupyter kernels. -- [Script Rendering for Jupyter](/docs/prerelease/1.4/script.qmd)---Support for rendering script files (e.g. `.py`, `.jl`, or `.r`) that are [specially formatted](https://jupytext.readthedocs.io/en/latest/formats-scripts.html) as notebooks. +- [Script Rendering](/docs/computations/render-scripts.qmd) + + - Jupyter---Support for rendering script files (e.g. `.py`, `.jl`, or `.r`) that are [specially formatted](https://jupytext.readthedocs.io/en/latest/formats-scripts.html) as notebooks. -- [Script Rendering for Knitr](/docs/prerelease/1.4/script-r.qmd)---Support for rendering R script files (e.g. `.r` or `.R`) that are formatted for report using [`knitr::spin()` syntax](https://bookdown.org/yihui/rmarkdown-cookbook/spin.html). + - Knitr---Support for rendering R script files (e.g. `.r` or `.R`) that are formatted for report using [`knitr::spin()` syntax](https://bookdown.org/yihui/rmarkdown-cookbook/spin.html). -- [Easy Binder Configuration for Quarto Projects](/docs/prerelease/1.4/binder.qmd)---Support for generating files required to deploy a Quarto project using Binder. +- [Easy Binder Configuration for Quarto Projects](/docs/projects/binder.qmd)---Support for generating files required to deploy a Quarto project using Binder. - [Connect Email Generation](/docs/prerelease/1.4/email.qmd)---Extends the `html` output format so that HTML/text emails can be created and selectively delivered through Posit Connect. - [Publish to Posit Cloud](/docs/publishing/posit-cloud.qmd)---Adds `posit-cloud` as a venue for `quarto publish`. -- [Lightbox Treatment for Images and Figures](/docs/prerelease//1.4/lightbox.qmd)---Support for zooming into images and figures using a `lightbox`. Includes support for grouping multiple images into a gallery. +- [Lightbox Treatment for Images and Figures](/docs/output-formats/html-lightbox-figures.qmd)---Support for zooming into images and figures using a `lightbox`. Includes support for grouping multiple images into a gallery. - [Lua changes](/docs/prerelease/1.4/lua_changes.qmd)---Quarto v1.4 adds new features to writers of Lua filters. diff --git a/docs/prerelease/1.4/images/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg b/docs/prerelease/1.4/images/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg deleted file mode 100644 index 7427e3d708..0000000000 Binary files a/docs/prerelease/1.4/images/alessandro-bianchi-_kdTyfnUFAc-unsplash.jpg and /dev/null differ diff --git a/docs/prerelease/1.4/images/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg b/docs/prerelease/1.4/images/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg deleted file mode 100644 index c5dc14471f..0000000000 Binary files a/docs/prerelease/1.4/images/hush-naidoo-jade-photography-SutAduhzdRQ-unsplash.jpg and /dev/null differ diff --git a/docs/prerelease/1.4/images/joshua-melo-peFHn8r4t1o-unsplash.jpg b/docs/prerelease/1.4/images/joshua-melo-peFHn8r4t1o-unsplash.jpg deleted file mode 100644 index 395131804f..0000000000 Binary files a/docs/prerelease/1.4/images/joshua-melo-peFHn8r4t1o-unsplash.jpg and /dev/null differ diff --git a/docs/prerelease/1.4/inline.qmd b/docs/prerelease/1.4/inline.qmd deleted file mode 100644 index 8f467ea293..0000000000 --- a/docs/prerelease/1.4/inline.qmd +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Inline Execution for Jupyter" ---- - -{{< include _pre-release-feature.qmd >}} - -## Overview - -Quarto v1.4 includes support for executing inline expressions when using Jupyter kernels. Inline expressions are similar to code blocks, except that they use a single tick (`` ` ``) rather than triple tick (```` ``` ````) and can appear anywhere. For example, the following code: - -```` markdown -```{{python}} -x = 5 -``` - -The answer is `{python} x` -```` - -Will create this markdown output: - -``` -The answer is 5. -``` - -This syntax works for any Jupyter kernel---so for Julia you would write an inline expression as `` `{julia} x` ``). - -::: callout-caution -One important consideration with inline expressions is that they should be confined to simple values that you have pre-computed within normal code cells (rather than function calls that do non-trivial work). This is because the protocol used for inline expressions is not compatible with some Python libraries (especially those that use multi-threading or multi-processing). -::: - -## Usage in Notebooks - -Inline expressions are always evaulated when rendering and previewing `.qmd` files. However, for notebooks you need to execute the notebook with Quarto in order to evaluate inline expressions (i.e. they won't be evaluated within the JupyterLab, VS Code, or PyCharm notebook editor). - -You can work in your favorite notebook front-end without Quarto execution, then once you are ready to publish execute the notebook during rendering as follows: - -``` {.bash filename="Terminal"} -$ quarto render notebook.ipynb --execute -``` - -You can also turn on execution within the YAML options of a notebook. For example: - -``` yaml ---- -title: "My Notebooks" -execute: - enabled: true ---- -``` - -## Markdown Output - -Note that by default, the output of inline expressions is treated as ordinary text (i.e. markdown within it is not rendered). Any markdown like syntax within the output of inline expressions will be automatically escaped. For example, the following inline expression: - -`` `{{python}} '**not bold**'` `` - -Will produce the following markdown: - -`\*\*not bold\*\*` - -If you want to explicitly create markdown output, use the `Markdown()` function from `IPython.display`. For example, the following inline expression will result in bolded text: - -```` markdown -```{{python}} -from IPython.display import Markdown -``` - -`{python} Markdown('**bold**')` -```` - -Note that for the Knitr engine, you use the `I()` function to designate that inline output has markdown to render. For example: - -``` markdown -`{r} I('**bold**')` -``` - -## Escaping - -If you are writing documentation about inline expressions (as we are in this article!) then you may need to escape the syntax so that it doesn't execute. You can do that in one of two ways: - -1) Use a double-brace around the expression. For example: `` `{{{python}}} x` `` - -2) Enclose the expression in an extra backtick. For example: ``` ``{python} x`` ``` - -Each of the expressions above will render (unexpected) as `` `{{python}} x` `` within the output document. - -## Engine Binding - -If you use inline expressions in a document that does not have any other executable code blocks then you should explicitly set the `engine` document option to ensure that your expressions are evaluated (automatic engine binding works for blocks but not inlines). For example: - -``` markdown ---- -title: "My Document" -engine: jupyter ---- - -`{python} "hello"` -``` - -## Syntax Compatibility - -The Knitr and Observable engines each have their own syntax for inline expressions. To make it easier to learn and use expressions across engines, there is also a mapping from the Jupyter-compatible syntax to the native synaxes of Knitr and Observable. For example: - -| Engine | Example | Converted | -|------------|-------------------|-------------| -| Knitr | `` `{{r}} x` `` | `` `r x` `` | -| Observable | `` `{{ojs}} x` `` | `${x}` | - -So you can use either the standard Quarto inline expression syntax or the native syntax with these engines. - -Note that native Knitr inline syntax has a different default behavior for handling of markdown content. Specificially, it treats all inline output as *containing markdown* (whereas Quarto assumes that it doesn't). So a strict equivalency between the Knitr and Quarto syntax would be: - -| Knitr | Quarto | -|----------------------|---------------------------| -| `` `r "**bold**"` `` | `` `{r} I("**bold**")` `` | \ No newline at end of file diff --git a/docs/prerelease/1.4/script-r.qmd b/docs/prerelease/1.4/script-r.qmd deleted file mode 100644 index cc3ade5ad1..0000000000 --- a/docs/prerelease/1.4/script-r.qmd +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Script Rendering for Knitr" ---- - -{{< include _pre-release-feature.qmd >}} - -## Overview - -Quarto v1.4 includes support for rendering R script files (e.g. `.r` or `.R`) that are specially formatted as a report. Script rendering is based on the `knitr::spin()` feature and makes use of the same [syntax rules](https://bookdown.org/yihui/rmarkdown-cookbook/spin.html), with slight additions: - -- The R script must start with YAML block header inside roxygen comments i.e. using the special `#'` comment. -- Cell options can be passed using YAML syntax as in `.qmd` i.e. using the special `#|` comment. - -For example, here is an R script that includes both markdown and code cells: - -``` {.r filename="script.R"} -#' --- -#' title: Palmer Penguins -#' author: Norah Jones -#' date: 3/12/23 -#' format: html -#' --- - -library(palmerpenguins) - -#' ## Exploring the data -#' See @fig-bill-sizes for an exploration of bill sizes by species. - -#| label: fig-bill-sizes -#| fig-cap: Bill Sizes by Species -#| warning: false -library(ggplot2) -ggplot(data = penguins, - aes(x = bill_length_mm, - y = bill_depth_mm, - group = species)) + - geom_point(aes(color = species, - shape = species), - size = 3, - alpha = 0.8) + - labs(title = "Penguin bill dimensions", - subtitle = "Bill length and depth for Adelie, Chinstrap and Gentoo Penguins at Palmer Station LTER", - x = "Bill length (mm)", - y = "Bill depth (mm)", - color = "Penguin species", - shape = "Penguin species") - -``` - -Lines that would be content in a `.qmd` start with `#'` and include the YAML header block and any in-document Markdown content. R code is the main content of the R script and is included without any delimitation. Cell options are included as normal using `#|` prefixed comments (e.g. `#| echo: false`), and apply to any R code below. Code cells are split when Markdown content occurs , e.g. use `#'` to create another code block. - -## Render and Preview - -Rendering and previewing notebook scripts works exactly like `.qmd`. For example, the following commands are all valid: - -```bash -$ quarto render script.R - -$ quarto preview script.R -``` - -R scripts rendered with Quarto must begin with a YAML block whose lines start with `#'` (which normally includes the `title` and other YAML options). This convention is how Quarto knows that it should render the `.R` script. The YAML block must follow the usual rules and be indented properly. - -## Scripts in Projects - -R scripts can also be included within [projects](/docs/projects/quarto-projects.qmd) (e.g. websites, blogs, etc.). Scripts within projects are only rendered by Quarto when they start with a YAML block header prefixed by `#'` comments. - -If for some reason you need to ignore such a script, you can create an explict render list in `_quarto.yml` that excludes individual scripts as required, for example: - -```yaml -project: - type: website - render: - - "*.{qmd,R}" - - "!utils.R" -``` - -Note that this technique is documented for the sake of completeness---in practice you should almost never need to do this since R scripts rarely begin with a YAML block unless you are authoring them specifically for report rendering. diff --git a/docs/prerelease/1.4/script.qmd b/docs/prerelease/1.4/script.qmd deleted file mode 100644 index 0787adf0ae..0000000000 --- a/docs/prerelease/1.4/script.qmd +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: "Script Rendering for Jupyter" ---- - -{{< include _pre-release-feature.qmd >}} - -## Overview - -Quarto v1.4 includes support for rendering script files (e.g. `.py`, `.jl`, or `.r`) that are specially formatted as notebooks. Script rendering makes use of the [percent format](https://jupytext.readthedocs.io/en/latest/formats-scripts.html) that is supported by several other other tools including Spyder, VS Code, PyCharm, and Jupytext. - -For example, here is a Python script that includes both markdown and code cells: - -``` {.python filename="script.py"} -# %% [markdown] -# --- -# title: Palmer Penguins -# author: Norah Jones -# date: 3/12/23 -# --- - -# %% -#| echo: false -import pandas as pd -df = pd.read_csv("palmer-penguins.csv") - -# %% [markdown] -""" -## Exploring the data - -See @fig-bill-sizes for an exploration of bill sizes by species. -""" - -# %% -#| label: fig-bill-sizes -#| fig-cap: Bill Sizes by Species - -import matplotlib.pyplot as plt -import seaborn as sns - -g = sns.FacetGrid(df, hue="species", height=3, aspect=3.5/1.5) -g.map(plt.scatter, "bill_length_mm", "bill_depth_mm").add_legend() -``` - -Code cells are delimited by `# %%` and markdown cells are delimited by `# %% [markdown]`. Markdown content can either be included in single line comments (`#`) or multi-line strings (`"""`), both of which are illustrated above. - -Note that cell options are included as normal using `#|` prefixed comments (e.g. `#| echo: false`). Also note that you can include blank lines within cells (cells continue until another cell is encountered). - -## Render and Preview - -Rendering and previewing notebook scripts works exactly like `.qmd` and `.ipynb` files. For example, the following commands are all valid: - -```bash -$ quarto render script.py -$ quarto render script.jl - -$ quarto preview script.py -$ quarto preview script.jl -``` - -Jupyter scripts rendered with Quarto must begin with a `# %% [markdown]` cell (which normally includes the `title` and other YAML options). This convention is how Quarto knows that it should parse code cells using the percent format (as opposed to other notebook as script formats that may be supported in the future). - -Jupyter script rendering is supported for Python, Julia, and R. Note that for R scripts, the [IRkernel](https://irkernel.github.io) will be used to execute code cells rather than Knitr (support for the Knitr [spin](https://bookdown.org/yihui/rmarkdown-cookbook/spin.html) script format is planned but not yet implemented). - -The latest version (v1.97.0) of the [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) also implements support for render and preview of Jupyter scripts. - - -## Generating Markdown - -Jupyter scripts are especially convenient when most of your document consists of code that dynamically generates markdown. You can write markdown from Python using functions in the `IPython.display` module. For example: - -```python -# %% -#| echo: false -radius = 10 -from IPython.display import Markdown -Markdown(f"The _radius_ of the circle is **{radius}**.") -``` - -Note that dynamically generated markdown will still be enclosed in the standard Quarto output divs. If you want to remove all of Quarto's default output enclosures use the `output: asis` option. For example: - -```python -# %% -#| echo: false -#| output: asis -radius = 10 -from IPython.display import Markdown -Markdown(f"The _radius_ of the circle is **{radius}**.") -``` - - -## Raw Cells - -You can include raw cells (e.g. HTML or LaTeX) within scripts using the `# %% [raw]` cell delimiter along with a `format` attribute, for example: - -```python -# %% [raw] format="html" -""" - -""" -``` - -## Scripts in Projects - -Jupyter scripts can also be included within [projects](/docs/projects/quarto-projects.qmd) (e.g. websites, blogs, etc.). Scripts within projects are only rendered by Quarto when they have a markdown cell at the top (e.g. `# %% [markdown]`). - -If for some reason you need to ignore a script that begins with a markdown cell, you can create an explict render list in `_quarto.yml` that excludes individual scripts as required, for example: - -```yaml -project: - type: website - render: - - "*.{qmd,ipynb,py}" - - "!utils.py" -``` - -Note that this technique is documented for the sake of completeness---in practice you should almost never need to do this since Python scripts rarely begin with `# %% [markdown]` unless you are authoring them specifically as notebooks. - - - - - - diff --git a/docs/prerelease/1.4/typst.qmd b/docs/prerelease/1.4/typst.qmd deleted file mode 100644 index 8e08038a11..0000000000 --- a/docs/prerelease/1.4/typst.qmd +++ /dev/null @@ -1,381 +0,0 @@ ---- -title: "Typst Format" -tbl-colwidths: [35,65] ---- - -{{< include _pre-release-feature.qmd >}} - -## Overview - -Quarto v1.4 includes support for the `typst` output format. [Typst](https://github.com/typst/typst) is a new open-source markup-based typesetting system that is designed to be as powerful as LaTeX while being much easier to learn and use. Typst creates beautiful PDF output with blazing fast render times. - -One of the highlights of Typst is the ease of creating highly customized templates. For example, here are some Typst templates that you can use in Quarto as custom formats: - -::: {layout-ncol=4} - -![IEEE](images/typst-format-ieee.png){.lightbox group="custom-formats" fig-alt="Screenshot of a page showing a article styled according IEEE standards. The title is centered with authors below in two columns."} - -![Poster](images/typst-format-poster.png){.lightbox group="custom-formats" fig-alt="Screenshot of a poster in landscape orientiation. The poster includes a logo in the top right, a title in the top left, and content arranged in three columns."} - -![Letter](images/typst-format-letter.png){.lightbox group="custom-formats" fig-alt="Screenshot of a page showing a letter. A sender address is across the top of the page, followed by a recipient address left justified. The body of the letter includes a subject line in bold."} - -![Dept News](images/typst-format-dept-news.png){.lightbox group="custom-formats" fig-alt="Screenshot of a page showing a department newsletter. The page is split vertically with a white column on the left and a red one on the right. An image spans across the column with the text \"Award Winning Science\" oriented to run vertically down its right side."} - -::: - - Learn more about how to use them, and how to create your own in [Custom Formats](#custom-formats). - -## Known Limitations - -Since Typst is under active development, there are still some limitations to Quarto's Typst support: - -- The default size of images may not reflect the behavior you are used to in other output formats. This is a problem that Typst, pandoc and Quarto are actively working to fix. In the meantime, you can manually [specify image widths](/docs/authoring/figures.qmd#figure-sizing). - -- Advanced page layout (e.g. using the `.column` classes as explained in [Article Layout](https://quarto.org/docs/authoring/article-layout.html)) is not implemented. - -- Various other small things might not yet be implemented. Please [let us know](https://github.com/quarto-dev/quarto-cli/issues/new/choose) if you see things that could use improvement! - -## Getting Started - -To try out the `typst` format: - -1. Download and install the [latest pre-release](https://quarto.org/docs/download/prerelease) of Quarto 1.4 (ensure you have installed Quarto v1.4.145 or higher). - -2. Create a document that uses `format: typst`. For example: - - ```{.yaml filename="hello-typst.qmd"} - --- - title: "My document" - format: typst - --- - - Hello, typst! - ``` - -Rendering or previewing this document will invoke the Typst CLI to create a PDF from your markdown source file. Note that Quarto includes the Typst CLI so no separate installation of Typst is required. - -## Typst Format - -When authoring a Typst document you'll be using a Quarto format that is in turn based on a Typst template, which defines its structure, layout, and available options. The default Typst format and template that ships with Quarto (`format: typst`) includes options for specifying title, author, and abstract information along with basic layout and appearance (numbering, margins, fonts, columns, etc.). - -The following options are available for customizing Typst output: - -| Option | Description | -|---------------------------|---------------------------------------------| -| `title` | Main document title | -| `author` | One or more document authors. | -| `date` | Date of publication | -| `abstract` | Article abstract | -| `toc` | Include a table of contents. | -| `toc-depth` | Specify the number of section levels to include in the table of contents. | -| `toc-title` | The title used for the table of contents. | -| `number-sections` | Apply numbering to sections and sub-sections | -| `number-depth` | The number of section levels that should receive numbering | -| `section-numbering` | Schema to use for numbering sections, e.g. `1.1.a`. | -| `margin` | Margins: `x`, `y`, `top`, `bottom`, `left`, `right`. Specified with units (e.g. `y: 1.25in` or `x: 2cm`). | -| `papersize` | Paper size: `a4`, `us-letter`, etc. See the docs on [paper sizes](https://typst.app/docs/reference/layout/page/#parameters–paper) for all available sizes. | -| `columns` | Number of columns for body text. | -| `include-in-header` | `.typ` file to include in header | -| `include-before-body` | `.typ` file to include before body | -| `include-after-body` | `.typ` file to include after the body | -| `keep-typ` | Keep the intermediate `.typ` file after render. | -| `bibliography` | `.bib` file to use for citations processing | -| `bibliographystyle` | Style to use with Typst's bibliography processing - See the doc about [bibliography](https://typst.app/docs/reference/meta/bibliography/#parameters–style) to see supported styles.| -| `citeproc` | If `true`, Pandoc's citeproc will be used for citation processing instead of Typst's own system (which is the default). | -| `csl` | `.csl` file to use when Pandoc's citeproc is used. | -| `fontsize` | Font size (e.g., `12pt`) | -| `mainfont` | Name of font to use for the main font, search among system fonts or `font-paths` if specified. | -| `font-paths` | Adds additional directories to search for fonts when compiling with Typst. | | - -For example: - -``` yaml ---- -title: "My Document" -format: - typst: - toc: true - section-numbering: 1.1.a - columns: 2 -bibliography: refs.bib -bibliographystyle: chicago-author-date ---- -``` - -See the section below on [Custom Formats](#custom-formats) for details on creating your own specialized formats for use with Typst. - -## Page Layout - -You can control the size of the page (`papersize`), the page margins (`margin`), and the number of columns used for page content (`columns`). For example, the following YAML modifies all three options: - -```yaml ---- -title: Page Layout -format: - typst: - papersize: a5 - margin: - x: 1cm - y: 1cm - columns: 2 ---- -``` - -The resulting layout is shown below alongside an example of the default layout: - -:::{layout-ncol=2} - -![Customized Layout](images/typst-custom-page.png){.border fig-alt="Screenshot of one page of PDF document. The document shows a two columns of text. Compared to the previous screenshot, the page is narrower and longer, and the margins are smaller."} - -![Default Layout](images/typst-default-page.png){.border fig-alt="Screenshot of one page of PDF document. The document shows a single column of text."} - -::: - -You can read more about these page layout options in the sections below. - -### Paper Size - -The `papersize` option expects a string matching one of Typst's supported [paper sizes](https://typst.app/docs/reference/layout/page/#parameters-paper). The default template is equivalent to: - -```yaml -papersize: us-letter -``` - -### Margins - -The `margin` option expects one or more of the suboptions: `x`, `y`, `top`, `bottom`, `left` and `right`. The default template uses margins equivalent to: - -```yaml -margin: - x: 1.25in - y: 1.25in -``` - -This sets the margins in the horizontal direction (`x`), i.e. `left` and `right`, as well as the margins in the vertical direction (`y`), i.e. `top` and `bottom` to 1.25 inches. - -The values for the margins are specfied using Typst's [length](https://typst.app/docs/reference/layout/length/), (e.g. `5cm`) or [relative length](https://typst.app/docs/reference/layout/relative/) (e.g. `10%`) types. You can specify a single margin: - -```yaml -margin: - left: 1cm -``` - -Then, any unspecified margins will inherit from the default margins. - -### Columns - -The `columns` option expects a number - the number of columns your body content should have. The default template sets `columns` to `1`. - - -{{< include /docs/output-formats/_document-options-toc.md >}} - -{{< include /docs/output-formats/_document-options-section-numbering.md >}} - -You can also customize the display of the section numbers with the `section-numbering` YAML option. This option expects a string that describes the numbering schema. For example, the following schema describes numbering sections with numerals, subsection with uppercase letters, and subsubsections with lower case letters, using `.` as a separator: - -```yaml ---- -section-numbering: 1.A.a ---- -``` - -You can read more about sepcifying the numbering schema in the [Typst documentation for numbering](https://typst.app//docs/reference/model/numbering#parameters-numbering). - -{{< include /docs/output-formats/_code-annotation.md >}} - -## Bibliography - -Typst comes with its [own citation processing system for bibliographies](https://typst.app/docs/reference/meta/bibliography/) and using `format: typst` defaults to it. To specify a bibliography style using Typst's system, use the `bibliographystyle` option. Provide a string from [Typst's list of built-in styles](https://typst.app/docs/reference/model/bibliography/#parameters-style), e.g.: - -``` yaml -bibliography: refs.bib -bibliographystyle: apa -``` - -Or alternatively, provide a path to a local CSL file: - -``` yaml -bibliography: refs.bib -bibliographystyle: my-csl-style.csl -``` - -If you prefer to use Pandoc's citation processing, set `citeproc: true` explicitly in YAML header: - -``` yaml -citeproc: true -bibliography: refs.bib - csl: https://www.zotero.org/styles/apa-with-abstract -``` - -To provide a citation style file to Pandoc's citation processing system use the `csl` option, as described in [Citation Style](https://quarto.org/docs/authoring/footnotes-and-citations.html#sec-citations-style). - - -## Typst Blocks - -If you want to change the appearance of blocks using native [Typst `#block()`](https://typst.app/docs/reference/layout/block/) calls, you can add the `.block` class to a Div and provide whatever arguments are appropriate. For example: - -```` markdown -::: {.block fill="luma(230)" inset="8pt" radius="4pt"} - -This is a block with gray background and slightly rounded corners. - -::: -```` - -This gets compiled to - -```` default -#block(fill:luma(230), inset=8pt, radius=4pt, -[This is a block with gray background and slightly rounded corners]) -```` - -## Raw Typst - -If you want to use raw `typst` markup, use a raw `typst` block. For example: - -```` default -```{=typst} -#set par(justify: true) - -== Background -In the case of glaciers, fluid dynamics principles can be used to understand how the movement and behavior of the ice is influenced by factors such as temperature, pressure, and the presence of other fluids (such as water). -``` -```` - -To learn more about `typst` markup, see the tutorial here: . - - -## Typst File (`.typ`) - -The rendering process produces a native Typst file (`.typ)` which is then compiled to PDF using the Typst CLI. This intermediate file is then automatically removed. If you want to preserve the `.typ` file, use the `keep-typ` option. For example: - -``` yaml ---- -title: "My Document" -format: - typst: - keep-typ: true ---- -``` - -You can compile a `.typ` file to PDF directly using the `quarto typst compile` command in a terminal. For example: - -``` {.bash filename="Terminal"} -$ quarto typst compile article.typ -``` - -The `quarto typst` command uses the version of Typst built in to Quarto and supports all Typst CLI actions and flags. For example, to determine the version of Typst embedded in Quarto: - -``` {.bash filename="Terminal"} -$ quarto typst --version -``` - -## Fonts Support - -The main font used for the document can be specified with the `mainfont` YAML option. Typst will search by default in installed system fonts. You can set additional paths to search using `font-paths`. For example: - -``` yaml ---- -title: "My Document" -format: - typst: - mainfont: "Agbalumo" - font-paths: myfonts ---- -``` - -This will search for a `*.ttf` or `*.otf` file matching the font name in the `./myfonts/` directory, in addition to searching in installed system fonts. - -The `TYPST_FONT_PATHS` environment variable is also taken into account for compatibility with Typst configuration, but setting `font-paths` will take precedence over any path set in the `TYPST_FONT_PATHS` environment variable. - -Set the base size of the font used in the document with `fontsize`. The size used in the default template is equivalent to: - -```yaml ---- -fontsize: 11pt ---- -``` - - -## Includes - -{{< include /docs/output-formats/_document-options-includes.md >}} - -For example: - -``` yaml -format: - typst: - include-before-body: - - text: | - #show heading: set text(navy) -``` - -## Custom Formats {#custom-formats} - -You can create highly customized output with Typst by defining a new format based on a custom Typst template. The Typst team has created several useful [templates](https://github.com/typst/templates), a few which which have been adapted for use with Quarto as custom formats. These formats include: - -| Format | Usage | -|--------------------------|----------------------------------------------| -| [Poster](https://github.com/quarto-ext/typst-templates/tree/main/poster) | `quarto use template quarto-ext/typst-templates/poster` | -| [IEEE](https://github.com/quarto-ext/typst-templates/tree/main/ieee) | `quarto use template quarto-ext/typst-templates/ieee` | -| [AMS](https://github.com/quarto-ext/typst-templates/tree/main/ams) | `quarto use template quarto-ext/typst-templates/ams` | -| [Letter](https://github.com/quarto-ext/typst-templates/tree/main/letter) | `quarto use template quarto-ext/typst-templates/letter` | -| [Fiction](https://github.com/quarto-ext/typst-templates/tree/main/fiction) | `quarto use template quarto-ext/typst-templates/fiction` | -| [Dept News](https://github.com/quarto-ext/typst-templates/tree/main/dept-news) | `quarto use template quarto-ext/typst-templates/dept-news` | - -: {tbl-colwidths=\[20,80\]} - -The source code for these formats is available at . - -### Create a Format - -To create a new custom Typst format (or package an existing Typst template for use with Quarto) use the `quarto create` command to get started: - -``` {.bash filename="Terminal"} -$ quarto create extension format -``` - -Then, choose `typst` as the base format and provide a name for the extension (e.g. `letter`). A sample Typst format extension will be created based on the code used in the default template that ships with Quarto. It will include the following files which you can edit to implement your custom format: - -| File | Description | -|-------------------------|-----------------------------------------------| -| `_extension.yml` | Basic extension metadata (name, author, description, etc.) and format definition. | -| `README.md` | Documentation on how to install and use the format. | -| `template.qmd` | A starter document that demonstrates the basics of the format. | -| `typst-template.typ` | The core Typst template function (documentation on creating Typst templates can be found here: ). | -| `typst-show.typ` | File that calls the template's function (mapping Pandoc metadata to function arguments). | - -Additional resources you might find useful when creating custom formats include: - -- The official Typst tutorial on [Making a Template](https://typst.app/docs/tutorial/making-a-template/) - -- List of third party templates from the [Awesome Quarto](https://github.com/qjcg/awesome-typst#templates--libraries) repo. - -### Template Partials - -::: callout-note -This section covers advanced customization of Typst format output and can be safely ignored unless you have found the method of defining custom Typst formats described above too limited. -::: - -Above we describe a method of creating a Typst format based on specifying two [template partials](https://quarto.org/docs/journals/templates.html#template-partials) (`typst-template.typ` and `typst-show.typ`). These partials customize components of the default Typst Pandoc template, but leave some of the core scaffolding including definitions required by Pandoc for its Typst output as well as handling of bibliographies and footnotes (this means that your own custom Typst formats do not need to explicitly handle them). - -If you would like to fully override the Pandoc template used for rendering Typst, use the `template` option in your custom format (rather than `template-partials`) and provide an alternate implementation of the default template. For example, your `_extensions.yml` might look like this: - -``` {.yaml filename="_extensions.yml"} -title: Typst Custom Format -author: Jane Smith -version: "0.2.0" -quarto-required: ">=1.4.11" -contributes: - formats: - typst: - template: template.typ - template-partials: - - typst-template.typ - - typst-show.typ -``` - -Use the [source code](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/typst/pandoc/quarto/template.typ) of the default template as a starting point for your `template.typ`. Note that you can call all of the template partials provided by Quarto (e.g. `biblio.typ()` or `notes.typ()`) from within your custom template implementation. - -The [AMS](https://github.com/quarto-ext/typst-templates/tree/main/ams) format provides an example of redefining the main template (in that case, it is to prevent automatic bibliography processing by Quarto in deference to the built-in handling of the Typst AMS template). diff --git a/docs/presentations/revealjs/advanced.qmd b/docs/presentations/revealjs/advanced.qmd index 6a4172dd47..f349324398 100644 --- a/docs/presentations/revealjs/advanced.qmd +++ b/docs/presentations/revealjs/advanced.qmd @@ -224,7 +224,13 @@ You can also disable auto-stretch for an individual slide by adding the `.nostre ## Slide Title {.nostretch} ``` -`auto-stretch` will only apply on non-nested image, which means an image in a feature blocks (e.g fragments, layout panel, columns, ... ) or a custom Divs will be ignored. For custom Divs, you can opt-in `auto-stretch` behavior by adding the class `.r-stretch` to the outer divs. In that the image within the blocks will be unwrapped below. +Or apply `.nostretch` directly to an individual image: + +```markdown +![](image.png){.nostretch fig-align="center" width="800px"} +``` + +`auto-stretch` will only apply to non-nested images, which means an image in a feature block (e.g fragments, layout panel, columns, ... ) or a custom Div will be ignored. For custom Divs, you can opt-in to `auto-stretch` behavior by adding the class `.r-stretch` to the outer div. {{< include _callout-auto-stretch-scrollable.qmd >}} diff --git a/docs/prerelease/1.4/binder.qmd b/docs/projects/binder.qmd similarity index 96% rename from docs/prerelease/1.4/binder.qmd rename to docs/projects/binder.qmd index 1281133d26..b070957f0f 100644 --- a/docs/prerelease/1.4/binder.qmd +++ b/docs/projects/binder.qmd @@ -1,8 +1,10 @@ --- title: "Using Binder With Quarto" +aliases: + - /docs/prerelease/1.4/binder.qmd --- -{{< include _pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} ## Overview @@ -154,3 +156,10 @@ code-links: binder When rendered you'll see a "Launch Binder" link under Code Links: ![](images/code-links-binder.png){fig-alt="Screenshot of the Code Links section on a rendered HTML page showing a link with the text Launch Binder."} + +If you have a manuscript project, you can also use `code-links: binder` in your manuscript configuration to get a link on your manuscript webpage: + +```{.yaml filename="_quarto.yml"} +manuscript: + code-links: binder +``` \ No newline at end of file diff --git a/docs/prerelease/1.4/images/code-links-binder.png b/docs/projects/images/code-links-binder.png similarity index 100% rename from docs/prerelease/1.4/images/code-links-binder.png rename to docs/projects/images/code-links-binder.png diff --git a/docs/projects/virtual-environments.qmd b/docs/projects/virtual-environments.qmd index 906e4fcdaa..94ce3c474d 100644 --- a/docs/projects/virtual-environments.qmd +++ b/docs/projects/virtual-environments.qmd @@ -17,6 +17,8 @@ Below we'll provide some example workflows for using these tools with Quarto. In We'll also cover using virtual environments with [JupyterLab](#jupyterlab), [RStudio](#rstudio), and [VS Code](#vs-code). +Quarto can also detect the virtual environments discussed on this page to configure your project for Binder. Read more at [Using Quarto with Binder](binder.qmd). + ## Using venv {#using-venv .platform-table} Here we'll provide a brief run through of creating a venv for a Quarto project. See the [full documentation](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) on using virtual environments with Python for additional details. diff --git a/docs/publishing/_providers.md b/docs/publishing/_providers.md index 8dc2a9a755..7cfeb6a6e8 100644 --- a/docs/publishing/_providers.md +++ b/docs/publishing/_providers.md @@ -5,6 +5,7 @@ | [Quarto Pub](/docs/publishing/quarto-pub.qmd) | Publishing service for Quarto documents, websites, and books. Use Quarto Pub when you want a free, easy to use service for publicly available content. | | [GitHub Pages](/docs/publishing/github-pages.qmd) | Publish content based on source code managed within a GitHub repository. Use GitHub Pages when the source code for your document or site is hosted on GitHub. | | [Posit Connect](/docs/publishing/rstudio-connect.qmd) | Publishing platform for secure sharing of data products within an organization. Use Posit Connect when you want to publish content within an organization rather than on the public internet. | +| [Posit Cloud](/docs/publishing/posit-cloud.qmd) | Create data projects and publish results from your web browser. Use Posit Cloud when you want to organize all your static documents and interactive applications in one place. | | [Netlify](/docs/publishing/netlify.qmd) | Professional web publishing platform. Use Netlify when you want support for custom domains, authentication, previewing branches, and other more advanced capabilities. | | [Confluence](/docs/publishing/confluence.qmd) | Publishing platform for supporting team collaboration. Use Confluence to share documents in team Spaces. | | [Other Services](/docs/publishing/other.qmd) | Content rendered with Quarto uses standard formats (HTML, PDFs, MS Word, etc.) that can be published anywhere. Use this if none of the methods above meets your requirements. | diff --git a/docs/publishing/posit-cloud.qmd b/docs/publishing/posit-cloud.qmd index 925ee06498..f74e4f5f89 100644 --- a/docs/publishing/posit-cloud.qmd +++ b/docs/publishing/posit-cloud.qmd @@ -4,7 +4,7 @@ editor: visual heading-pad: '#' --- -{{< include /docs/prerelease/1.4/_pre-release-feature.qmd >}} +{{< include /docs/_require-1.4.qmd >}} ## Overview diff --git a/docs/reference/cells/cells-jupyter.json b/docs/reference/cells/cells-jupyter.json index f1d8f6a454..0f3454d086 100644 --- a/docs/reference/cells/cells-jupyter.json +++ b/docs/reference/cells/cells-jupyter.json @@ -68,9 +68,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -138,9 +140,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -208,9 +212,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "jupyter" }, @@ -279,9 +285,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "jupyter" } @@ -356,9 +364,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -366,7 +376,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n", + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n", "formats": [ "asciidoc", "asciidoctor", @@ -429,9 +439,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -441,6 +453,7 @@ "name": "code-fold", "description": "Collapse code into an HTML `
` tag so the user can display it on-demand.\n\n- `true`: collapse code\n- `false` (default): do not collapse code\n- `show`: use the `
` tag, but show the expanded code initially.\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -461,6 +474,7 @@ "name": "code-summary", "description": "Summary text to use for code blocks collapsed using `code-fold`", "formats": [ + "dashboard", "html", "html4", "html5", @@ -481,6 +495,7 @@ "name": "code-overflow", "description": "Choose how to handle code overflow, when code lines are too wide for their container. One of:\n\n- `scroll`\n- `wrap`\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -502,6 +517,7 @@ "description": "Include line numbers in code block output (`true` or `false`).\n\nFor revealjs output only, you can also specify a string to highlight\nspecific lines (and/or animate between sets of highlighted lines).\n\n* Sets of lines are denoted with commas:\n * `3,4,5`\n * `1,10,12`\n* Ranges can be denoted with dashes and combined with commas:\n * `1-3,5` \n * `5-10,12,14`\n* Finally, animation steps are separated by `|`:\n * `1-3|1-3,5` first shows `1-3`, then `1-3,5`\n * `|5|5-10,12` first shows no numbering, then 5, then lines 5-10\n and 12\n", "formats": [ "ms", + "dashboard", "html", "html4", "html5", @@ -586,9 +602,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -656,9 +674,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] } ] @@ -732,9 +752,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -805,9 +827,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -878,9 +902,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -951,9 +977,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -1024,14 +1052,16 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "output-location", - "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- 'column': In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n", + "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- `column`: In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n", "formats": [ "revealjs" ] @@ -1107,9 +1137,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1177,9 +1209,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1247,9 +1281,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1263,6 +1299,7 @@ "latex", "pdf", "beamer", + "dashboard", "html", "html4", "html5", @@ -1283,6 +1320,7 @@ "name": "fig-alt", "description": "Alternative text to be used in the `alt` attribute of HTML images.\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -1400,9 +1438,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1470,14 +1510,44 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "tbl-colwidths", "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n", + "formats": [ + "latex", + "pdf", + "beamer", + "dashboard", + "html", + "html4", + "html5", + "slidy", + "slideous", + "s5", + "revealjs", + "dzslides", + "epub", + "epub2", + "epub3" + ], + "contexts": [ + "document-tables" + ], + "engine": [ + "knitr", + "jupyter" + ] + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process raw HTML table in cell output and leave it as-is", "formats": [ "asciidoc", "asciidoctor", @@ -1540,16 +1610,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" - ], - "contexts": [ - "document-tables" - ], - "engine": [ - "knitr", - "jupyter" + "md", + "dashboard" ] } ] @@ -1623,9 +1688,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1693,9 +1760,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1763,9 +1832,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1833,9 +1904,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1903,9 +1976,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] } ] @@ -1979,9 +2054,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -2049,9 +2126,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -2119,15 +2198,18 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "cap-location", "description": "Where to place figure and table captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", @@ -2148,6 +2230,7 @@ "name": "fig-cap-location", "description": "Where to place figure captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", @@ -2169,6 +2252,7 @@ "name": "tbl-cap-location", "description": "Where to place table captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", diff --git a/docs/reference/cells/cells-knitr.json b/docs/reference/cells/cells-knitr.json index 1b526d1f0c..6609ab2b56 100644 --- a/docs/reference/cells/cells-knitr.json +++ b/docs/reference/cells/cells-knitr.json @@ -68,9 +68,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -138,9 +140,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] } ] @@ -214,9 +218,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -224,7 +230,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n", + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n", "formats": [ "asciidoc", "asciidoctor", @@ -287,9 +293,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -299,6 +307,7 @@ "name": "code-fold", "description": "Collapse code into an HTML `
` tag so the user can display it on-demand.\n\n- `true`: collapse code\n- `false` (default): do not collapse code\n- `show`: use the `
` tag, but show the expanded code initially.\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -319,6 +328,7 @@ "name": "code-summary", "description": "Summary text to use for code blocks collapsed using `code-fold`", "formats": [ + "dashboard", "html", "html4", "html5", @@ -339,6 +349,7 @@ "name": "code-overflow", "description": "Choose how to handle code overflow, when code lines are too wide for their container. One of:\n\n- `scroll`\n- `wrap`\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -360,6 +371,7 @@ "description": "Include line numbers in code block output (`true` or `false`).\n\nFor revealjs output only, you can also specify a string to highlight\nspecific lines (and/or animate between sets of highlighted lines).\n\n* Sets of lines are denoted with commas:\n * `3,4,5`\n * `1,10,12`\n* Ranges can be denoted with dashes and combined with commas:\n * `1-3,5` \n * `5-10,12,14`\n* Finally, animation steps are separated by `|`:\n * `1-3|1-3,5` first shows `1-3`, then `1-3,5`\n * `|5|5-10,12` first shows no numbering, then 5, then lines 5-10\n and 12\n", "formats": [ "ms", + "dashboard", "html", "html4", "html5", @@ -444,9 +456,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -514,9 +528,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -584,9 +600,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -655,9 +673,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -726,9 +746,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -797,9 +819,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -868,9 +892,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -939,9 +965,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" } @@ -1016,9 +1044,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -1089,9 +1119,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -1162,9 +1194,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -1235,9 +1269,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -1308,14 +1344,16 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "output-location", - "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- 'column': In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n", + "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- `column`: In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n", "formats": [ "revealjs" ] @@ -1385,9 +1423,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1456,9 +1496,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1527,9 +1569,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1598,9 +1642,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1669,9 +1715,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1740,9 +1788,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1811,9 +1861,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1882,9 +1934,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -1953,9 +2007,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2024,9 +2080,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2095,9 +2153,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" } @@ -2172,9 +2232,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2243,9 +2305,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2314,9 +2378,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -2384,9 +2450,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -2454,9 +2522,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -2470,6 +2540,7 @@ "latex", "pdf", "beamer", + "dashboard", "html", "html4", "html5", @@ -2490,6 +2561,7 @@ "name": "fig-alt", "description": "Alternative text to be used in the `alt` attribute of HTML images.\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -2601,9 +2673,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2672,9 +2746,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2743,9 +2819,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2814,9 +2892,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2885,9 +2965,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -2956,9 +3038,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -3027,9 +3111,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -3098,9 +3184,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -3189,9 +3277,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -3260,9 +3350,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -3331,9 +3423,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" } @@ -3408,9 +3502,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -3478,14 +3574,44 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "tbl-colwidths", "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n", + "formats": [ + "latex", + "pdf", + "beamer", + "dashboard", + "html", + "html4", + "html5", + "slidy", + "slideous", + "s5", + "revealjs", + "dzslides", + "epub", + "epub2", + "epub3" + ], + "contexts": [ + "document-tables" + ], + "engine": [ + "knitr", + "jupyter" + ] + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process raw HTML table in cell output and leave it as-is", "formats": [ "asciidoc", "asciidoctor", @@ -3548,16 +3674,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" - ], - "contexts": [ - "document-tables" - ], - "engine": [ - "knitr", - "jupyter" + "md", + "dashboard" ] } ] @@ -3631,9 +3752,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -3701,9 +3824,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -3771,9 +3896,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -3841,9 +3968,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -3911,9 +4040,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] } ] @@ -3987,9 +4118,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -4057,9 +4190,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -4127,15 +4262,18 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "cap-location", "description": "Where to place figure and table captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", @@ -4156,6 +4294,7 @@ "name": "fig-cap-location", "description": "Where to place figure captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", @@ -4177,6 +4316,7 @@ "name": "tbl-cap-location", "description": "Where to place table captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", @@ -4265,9 +4405,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4336,9 +4478,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4407,9 +4551,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4478,9 +4624,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4549,9 +4697,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4620,9 +4770,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4691,9 +4843,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4762,9 +4916,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" } @@ -4839,9 +4995,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4910,9 +5068,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -4981,9 +5141,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" }, @@ -5052,9 +5214,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "engine": "knitr" } diff --git a/docs/reference/cells/cells-ojs.json b/docs/reference/cells/cells-ojs.json index 8261669148..4e83e14d16 100644 --- a/docs/reference/cells/cells-ojs.json +++ b/docs/reference/cells/cells-ojs.json @@ -68,9 +68,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -138,9 +140,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] } ] @@ -214,9 +218,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -224,7 +230,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n", + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n", "formats": [ "asciidoc", "asciidoctor", @@ -287,9 +293,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -299,6 +307,7 @@ "name": "code-fold", "description": "Collapse code into an HTML `
` tag so the user can display it on-demand.\n\n- `true`: collapse code\n- `false` (default): do not collapse code\n- `show`: use the `
` tag, but show the expanded code initially.\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -319,6 +328,7 @@ "name": "code-summary", "description": "Summary text to use for code blocks collapsed using `code-fold`", "formats": [ + "dashboard", "html", "html4", "html5", @@ -339,6 +349,7 @@ "name": "code-overflow", "description": "Choose how to handle code overflow, when code lines are too wide for their container. One of:\n\n- `scroll`\n- `wrap`\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -360,6 +371,7 @@ "description": "Include line numbers in code block output (`true` or `false`).\n\nFor revealjs output only, you can also specify a string to highlight\nspecific lines (and/or animate between sets of highlighted lines).\n\n* Sets of lines are denoted with commas:\n * `3,4,5`\n * `1,10,12`\n* Ranges can be denoted with dashes and combined with commas:\n * `1-3,5` \n * `5-10,12,14`\n* Finally, animation steps are separated by `|`:\n * `1-3|1-3,5` first shows `1-3`, then `1-3,5`\n * `|5|5-10,12` first shows no numbering, then 5, then lines 5-10\n and 12\n", "formats": [ "ms", + "dashboard", "html", "html4", "html5", @@ -444,9 +456,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -514,9 +528,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] } ] @@ -590,9 +606,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -663,9 +681,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -736,9 +756,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -809,9 +831,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ], "contexts": [ "document-execute" @@ -882,14 +906,16 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "output-location", - "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- 'column': In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n", + "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- `column`: In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n", "formats": [ "revealjs" ] @@ -965,9 +991,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1035,9 +1063,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1105,9 +1135,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1121,6 +1153,7 @@ "latex", "pdf", "beamer", + "dashboard", "html", "html4", "html5", @@ -1141,6 +1174,7 @@ "name": "fig-alt", "description": "Alternative text to be used in the `alt` attribute of HTML images.\n", "formats": [ + "dashboard", "html", "html4", "html5", @@ -1258,9 +1292,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1328,9 +1364,83 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" + ] + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process raw HTML table in cell output and leave it as-is", + "formats": [ + "asciidoc", + "asciidoctor", + "beamer", + "biblatex", + "bibtex", + "chunkedhtml", + "commonmark", + "commonmark_x", + "context", + "csljson", + "docbook", + "docbook4", + "docbook5", + "docx", + "dokuwiki", + "dzslides", + "epub", + "epub2", + "epub3", + "fb2", + "gfm", + "haddock", + "html", + "html4", + "html5", + "icml", + "ipynb", + "jats", + "jats_archiving", + "jats_articleauthoring", + "jats_publishing", + "jira", + "json", + "latex", + "man", + "markdown", + "markdown_github", + "markdown_mmd", + "markdown_phpextra", + "markdown_strict", + "markua", + "mediawiki", + "ms", + "muse", + "native", + "odt", + "opendocument", + "opml", + "org", + "pdf", + "plain", + "pptx", + "revealjs", + "rst", + "rtf", + "s5", + "slideous", + "slidy", + "tei", + "texinfo", + "textile", + "typst", + "xwiki", + "zimwiki", + "md", + "dashboard" ] } ] @@ -1404,9 +1514,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1474,9 +1586,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1544,9 +1658,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1614,9 +1730,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1684,9 +1802,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] } ] @@ -1760,9 +1880,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1830,9 +1952,11 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { @@ -1900,15 +2024,18 @@ "tei", "texinfo", "textile", + "typst", "xwiki", "zimwiki", - "md" + "md", + "dashboard" ] }, { "name": "cap-location", "description": "Where to place figure and table captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", @@ -1929,6 +2056,7 @@ "name": "fig-cap-location", "description": "Where to place figure captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", @@ -1950,6 +2078,7 @@ "name": "tbl-cap-location", "description": "Where to place table captions (`top`, `bottom`, or `margin`)", "formats": [ + "dashboard", "html", "html4", "html5", diff --git a/docs/reference/formats/asciidoc.json b/docs/reference/formats/asciidoc.json index fc4f733dee..8e86f50b4d 100644 --- a/docs/reference/formats/asciidoc.json +++ b/docs/reference/formats/asciidoc.json @@ -98,7 +98,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -156,10 +156,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -188,6 +184,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -296,6 +302,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -315,6 +325,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -328,7 +342,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/context.json b/docs/reference/formats/context.json index 51183c988e..58c6a48384 100644 --- a/docs/reference/formats/context.json +++ b/docs/reference/formats/context.json @@ -196,7 +196,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -254,10 +254,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -286,6 +282,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -406,6 +412,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -425,6 +435,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -456,7 +470,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/dashboards.json b/docs/reference/formats/dashboards.json new file mode 100644 index 0000000000..0637a088a0 --- /dev/null +++ b/docs/reference/formats/dashboards.json @@ -0,0 +1 @@ +[] \ No newline at end of file diff --git a/docs/reference/formats/docbook.json b/docs/reference/formats/docbook.json index f5539cb02c..3eba1773ca 100644 --- a/docs/reference/formats/docbook.json +++ b/docs/reference/formats/docbook.json @@ -88,7 +88,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -146,10 +146,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -178,6 +174,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -276,6 +282,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -295,6 +305,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] } diff --git a/docs/reference/formats/docx.json b/docs/reference/formats/docx.json index e5365545f9..1049c28b96 100644 --- a/docs/reference/formats/docx.json +++ b/docs/reference/formats/docx.json @@ -7,6 +7,10 @@ "name": "title", "description": "Document title" }, + { + "name": "subtitle", + "description": "Identifies the subtitle of the document." + }, { "name": "date", "description": "Document date" @@ -15,6 +19,14 @@ "name": "author", "description": "Author or authors of the document" }, + { + "name": "abstract", + "description": "Summary of document" + }, + { + "name": "abstract-title", + "description": "Title used to label document abstract" + }, { "name": "order", "description": "Order for document when included in a website automatic sidebar menu." @@ -122,7 +134,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -184,10 +196,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -224,7 +232,17 @@ }, { "name": "notes-after-punctuation", - "description": "If true (the default for note styles), Quarto (via Pandoc) will put footnote references or superscripted numerical citations after \nfollowing punctuation. For example, if the source contains blah blah [@jones99]., the result will look like blah blah.[^1], with \nthe note moved after the period and the space collapsed. \n\nIf false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used \nin numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).\n" + "description": "If true (the default for note styles), Quarto (via Pandoc) will put footnote references or superscripted numerical citations after \nfollowing punctuation. For example, if the source contains `blah blah [@jones99]`., the result will look like `blah blah.[^1]`, with \nthe note moved after the period and the space collapsed. \n\nIf false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used \nin numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).\n" + } + ] + }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." } ] }, @@ -270,6 +288,10 @@ "name": "metadata", "title": "Metadata", "options": [ + { + "name": "keywords", + "description": "List of keywords to be included in the document metadata." + }, { "name": "subject", "description": "The document subject" @@ -324,6 +346,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -343,6 +369,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] } diff --git a/docs/reference/formats/epub.json b/docs/reference/formats/epub.json index f34f282a43..de6b14a15b 100644 --- a/docs/reference/formats/epub.json +++ b/docs/reference/formats/epub.json @@ -250,7 +250,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -348,6 +348,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -460,6 +470,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -479,6 +493,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, diff --git a/docs/reference/formats/fb2.json b/docs/reference/formats/fb2.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/fb2.json +++ b/docs/reference/formats/fb2.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/haddock.json b/docs/reference/formats/haddock.json index 8415534e50..5902d34acf 100644 --- a/docs/reference/formats/haddock.json +++ b/docs/reference/formats/haddock.json @@ -98,7 +98,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -156,10 +156,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -188,6 +184,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -286,6 +292,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -305,6 +315,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -318,7 +332,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/html.json b/docs/reference/formats/html.json index e5755ae0f0..297141a6b0 100644 --- a/docs/reference/formats/html.json +++ b/docs/reference/formats/html.json @@ -105,7 +105,7 @@ }, { "name": "toc-location", - "description": "Location for table of contents (`body`, `left`, or `right` (default)).\n" + "description": "Location for table of contents:\n\n- `body`: Show the Table of Contents in the center body of the document. \n- `left`: Show the Table of Contents in left margin of the document.\n- `right`(default): Show the Table of Contents in right margin of the document.\n- `left-body`: Show two Tables of Contents in both the center body and the left margin of the document.\n- `right-body`: Show two Tables of Contents in both the center body and the right margin of the document.\n" }, { "name": "toc-title", @@ -291,11 +291,11 @@ }, { "name": "code-tools", - "description": "Include a code tools menu (for hiding and showing code).\nUse `true` or `false` to enable or disable the standard code \ntools menu. Specify sub-properties `source`, `toggle`, and\n`caption` to customize the behavior and appearnce of code tools.\n" + "description": "Include a code tools menu (for hiding and showing code).\nUse `true` or `false` to enable or disable the standard code \ntools menu. Specify sub-properties `source`, `toggle`, and\n`caption` to customize the behavior and appearance of code tools.\n" }, { "name": "code-block-border-left", - "description": "Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is\nenabled as well as the color of the border.=\n" + "description": "Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is\nenabled as well as the color of the border.\n" }, { "name": "code-block-bg", @@ -326,7 +326,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -392,6 +392,16 @@ } ] }, + { + "name": "lightbox", + "title": "Lightbox Figures", + "options": [ + { + "name": "lightbox", + "description": "Enable or disable lightbox treatment for images in this document. See [Lightbox Figures](https://quarto.org/docs/output-formats/html-lightbox-figures.html) for more details." + } + ] + }, { "name": "tables", "title": "Tables", @@ -434,9 +444,25 @@ "name": "notebook-links", "description": "Controls the display of links to notebooks that provided embedded content or are created from documents.\n\nSpecify `false` to disable linking to source Notebooks. Specify `inline` to show links to source notebooks beneath the content they provide. \nSpecify `global` to show a set of global links to source notebooks.\n" }, + { + "name": "other-links", + "description": "A list of links that should be displayed below the table of contents in an `Other Links` section." + }, + { + "name": "code-links", + "description": "A list of links that should be displayed below the table of contents in an `Code Links` section." + }, { "name": "notebook-view", "description": "Configures the HTML viewer for notebooks that provide embedded content." + }, + { + "name": "notebook-preview-options", + "description": "Options for controlling the display and behavior of Notebook previews." + }, + { + "name": "canonical-url", + "description": "Include a canonical link tag in website pages. You may pass either `true` to \nautomatically generate a canonical link, or pass a canonical url that you'd like\nto have placed in the `href` attribute of the tag.\n\nCanonical links can only be generated for websites with a known `site-url`.\n" } ] }, @@ -484,6 +510,20 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + }, + { + "name": "crossrefs-hover", + "description": "Enables a hover popup for cross references that shows the item being referenced." + } + ] + }, { "name": "citation", "title": "Citation", @@ -552,7 +592,7 @@ }, { "name": "license", - "description": "The license for this document, if any. \n\nCreative Commons licenses `CC BY`, `CC BY-SA`, `CC BY-ND`, `CC BY-NC` will automatically generate a license link\nin the document appendix. Other license text will be placed in the appendix verbatim.\n" + "description": "The license for this document, if any. \n\nCreative Commons licenses `CC BY`, `CC BY-SA`, `CC BY-ND`, `CC BY-NC`, `CC BY-NC-SA`, and `CC BY-NC-ND` will automatically generate a license link\nin the document appendix. Other license text will be placed in the appendix verbatim.\n" }, { "name": "pagetitle", @@ -608,10 +648,6 @@ "name": "embed-resources", "description": "Produce a standalone HTML file with no external dependencies, using\n`data:` URIs to incorporate the contents of linked scripts, stylesheets,\nimages, and videos. The resulting file should be \"self-contained,\" in the\nsense that it needs no external files and no net access to be displayed\nproperly by a browser. This option works only with HTML output formats,\nincluding `html4`, `html5`, `html+lhs`, `html5+lhs`, `s5`, `slidy`,\n`slideous`, `dzslides`, and `revealjs`. Scripts, images, and stylesheets at\nabsolute URLs will be downloaded; those at relative URLs will be sought\nrelative to the working directory (if the first source\nfile is local) or relative to the base URL (if the first source\nfile is remote). Elements with the attribute\n`data-external=\"1\"` will be left alone; the documents they\nlink to will not be incorporated in the document.\nLimitation: resources that are loaded dynamically through\nJavaScript cannot be incorporated; as a result, some\nadvanced features (e.g. zoom or speaker notes) may not work\nin an offline \"self-contained\" `reveal.js` slide show.\n" }, - { - "name": "self-contained", - "description": "Produce a standalone HTML file with no external dependencies. Note that\nthis option has been deprecated in favor of `embed-resources`.\n" - }, { "name": "self-contained-math", "description": "Embed math libraries (e.g. MathJax) within `self-contained` output.\nNote that math libraries are not embedded by default because they are \n quite large and often time consuming to download.\n" @@ -636,6 +672,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -655,6 +695,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -666,6 +710,10 @@ "name": "search", "description": "Setting this to false prevents this document from being included in searches." }, + { + "name": "repo-actions", + "description": "Setting this to false prevents the `repo-actions` from appearing on this page." + }, { "name": "aliases", "description": "URLs that alias this document, when included in a website." diff --git a/docs/reference/formats/icml.json b/docs/reference/formats/icml.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/icml.json +++ b/docs/reference/formats/icml.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/ipynb.json b/docs/reference/formats/ipynb.json index 1920269254..11b0a7e6c3 100644 --- a/docs/reference/formats/ipynb.json +++ b/docs/reference/formats/ipynb.json @@ -102,7 +102,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -160,10 +160,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -192,6 +188,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -270,6 +276,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -289,6 +299,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -302,7 +316,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/jats.json b/docs/reference/formats/jats.json index 95913fd89a..c788803f27 100644 --- a/docs/reference/formats/jats.json +++ b/docs/reference/formats/jats.json @@ -112,7 +112,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -170,16 +170,22 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" } ] }, + { + "name": "links", + "title": "Links", + "options": [ + { + "name": "notebook-subarticles", + "description": "Controls the display of links to notebooks that provided embedded content or are created from documents.\n\nDefaults to `true` - specify `false` to disable embedding Notebook as subarticles with the JATS output.\n" + } + ] + }, { "name": "references", "title": "References", @@ -202,6 +208,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -250,7 +266,7 @@ }, { "name": "license", - "description": "The license for this document, if any. \n\nCreative Commons licenses `CC BY`, `CC BY-SA`, `CC BY-ND`, `CC BY-NC` will automatically generate a license link\nin the document appendix. Other license text will be placed in the appendix verbatim.\n" + "description": "The license for this document, if any. \n\nCreative Commons licenses `CC BY`, `CC BY-SA`, `CC BY-ND`, `CC BY-NC`, `CC BY-NC-SA`, and `CC BY-NC-ND` will automatically generate a license link\nin the document appendix. Other license text will be placed in the appendix verbatim.\n" } ] }, @@ -302,6 +318,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -321,6 +341,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -334,7 +358,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/man.json b/docs/reference/formats/man.json index 28a1f700f1..48587065c0 100644 --- a/docs/reference/formats/man.json +++ b/docs/reference/formats/man.json @@ -98,7 +98,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -156,10 +156,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -188,6 +184,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -294,6 +300,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -313,6 +323,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -326,7 +340,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/markdown/commonmark.json b/docs/reference/formats/markdown/commonmark.json index 0f33f79989..c6fef7ca66 100644 --- a/docs/reference/formats/markdown/commonmark.json +++ b/docs/reference/formats/markdown/commonmark.json @@ -110,7 +110,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -168,10 +168,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -210,6 +206,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -308,6 +314,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -327,6 +337,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -340,7 +354,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/markdown/gfm.json b/docs/reference/formats/markdown/gfm.json index 214f7a7c8f..4fbc3c8c24 100644 --- a/docs/reference/formats/markdown/gfm.json +++ b/docs/reference/formats/markdown/gfm.json @@ -118,7 +118,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -176,10 +176,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -218,6 +214,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -316,6 +322,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -335,6 +345,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -348,7 +362,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/markdown/markua.json b/docs/reference/formats/markdown/markua.json index 0f33f79989..c6fef7ca66 100644 --- a/docs/reference/formats/markdown/markua.json +++ b/docs/reference/formats/markdown/markua.json @@ -110,7 +110,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -168,10 +168,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -210,6 +206,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -308,6 +314,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -327,6 +337,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -340,7 +354,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/ms.json b/docs/reference/formats/ms.json index d054215d4a..90f276e8d6 100644 --- a/docs/reference/formats/ms.json +++ b/docs/reference/formats/ms.json @@ -144,7 +144,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -202,10 +202,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -234,6 +230,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -332,6 +338,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -351,6 +361,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -364,7 +378,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/muse.json b/docs/reference/formats/muse.json index 6ffba5c155..94d5bd86f5 100644 --- a/docs/reference/formats/muse.json +++ b/docs/reference/formats/muse.json @@ -98,7 +98,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -156,10 +156,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -198,6 +194,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -296,6 +302,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -315,6 +325,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -328,7 +342,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/odt.json b/docs/reference/formats/odt.json index 81ecee887c..7b37db46a6 100644 --- a/docs/reference/formats/odt.json +++ b/docs/reference/formats/odt.json @@ -114,7 +114,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -176,10 +176,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -208,6 +204,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -258,6 +264,24 @@ } ] }, + { + "name": "metadata", + "title": "Metadata", + "options": [ + { + "name": "keywords", + "description": "List of keywords to be included in the document metadata." + }, + { + "name": "subject", + "description": "The document subject" + }, + { + "name": "description", + "description": "The document description. Some applications show this as `Comments` metadata." + } + ] + }, { "name": "render", "title": "Rendering", @@ -306,6 +330,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -325,6 +353,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] } diff --git a/docs/reference/formats/opml.json b/docs/reference/formats/opml.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/opml.json +++ b/docs/reference/formats/opml.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/org.json b/docs/reference/formats/org.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/org.json +++ b/docs/reference/formats/org.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/pdf.json b/docs/reference/formats/pdf.json index ff6a560fd2..477f3d9dd5 100644 --- a/docs/reference/formats/pdf.json +++ b/docs/reference/formats/pdf.json @@ -45,6 +45,10 @@ "name": "pdf-engine-opt", "description": "Use the given string as a command-line argument to the pdf-engine.\nFor example, to use a persistent directory foo for latexmk’s auxiliary\nfiles, use `pdf-engine-opt: -outdir=foo`. Note that no check for \nduplicate options is done.\n" }, + { + "name": "beamerarticle", + "description": "Whether to produce a Beamer article from this presentation." + }, { "name": "quarto-required", "description": "A semver version range describing the supported quarto versions for this document\nor project.\n\nExamples:\n\n- `>= 1.1.0`: Require at least quarto version 1.1\n- `1.*`: Require any quarto versions whose major version number is 1\n" @@ -233,7 +237,7 @@ }, { "name": "papersize", - "description": "The paper size for the document." + "description": "The paper size for the document.\n" }, { "name": "grid", @@ -287,7 +291,7 @@ }, { "name": "code-block-border-left", - "description": "Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is\nenabled as well as the color of the border.=\n" + "description": "Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is\nenabled as well as the color of the border.\n" }, { "name": "code-block-bg", @@ -322,7 +326,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -464,7 +468,7 @@ }, { "name": "notes-after-punctuation", - "description": "If true (the default for note styles), Quarto (via Pandoc) will put footnote references or superscripted numerical citations after \nfollowing punctuation. For example, if the source contains blah blah [@jones99]., the result will look like blah blah.[^1], with \nthe note moved after the period and the space collapsed. \n\nIf false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used \nin numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).\n" + "description": "If true (the default for note styles), Quarto (via Pandoc) will put footnote references or superscripted numerical citations after \nfollowing punctuation. For example, if the source contains `blah blah [@jones99]`., the result will look like `blah blah.[^1]`, with \nthe note moved after the period and the space collapsed. \n\nIf false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used \nin numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).\n" } ] }, @@ -482,6 +486,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -606,6 +620,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "keep-tex", "description": "Keep the intermediate tex file used during render." @@ -629,6 +647,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, diff --git a/docs/reference/formats/presentations/beamer.json b/docs/reference/formats/presentations/beamer.json index 685f2f84f6..2a7f7c82ce 100644 --- a/docs/reference/formats/presentations/beamer.json +++ b/docs/reference/formats/presentations/beamer.json @@ -53,10 +53,6 @@ "name": "pdf-engine-opt", "description": "Use the given string as a command-line argument to the pdf-engine.\nFor example, to use a persistent directory foo for latexmk’s auxiliary\nfiles, use `pdf-engine-opt: -outdir=foo`. Note that no check for \nduplicate options is done.\n" }, - { - "name": "beamerarticle", - "description": "Whether to produce a Beamer article from this presentation." - }, { "name": "beameroption", "description": "Add an extra Beamer option using `\\setbeameroption{}`." @@ -67,7 +63,7 @@ }, { "name": "logo", - "description": "The logo image for slides." + "description": "The logo image." }, { "name": "titlegraphic", @@ -115,10 +111,6 @@ "name": "toc", "description": "Include an automatically generated table of contents (or, in\nthe case of `latex`, `context`, `docx`, `odt`,\n`opendocument`, `rst`, or `ms`, an instruction to create\none) in the output document. This option has no effect\nif `standalone` is `false`.\n\nNote that if you are producing a PDF via `ms`, the table\nof contents will appear at the beginning of the\ndocument, before the title. If you would prefer it to\nbe at the end of the document, use the option\n`pdf-engine-opt: --no-toc-relocation`.\n" }, - { - "name": "toc-depth", - "description": "Specify the number of section levels to include in the table of contents.\nThe default is 3\n" - }, { "name": "toc-title", "description": "The title used for the table of contents." @@ -303,7 +295,7 @@ }, { "name": "papersize", - "description": "The paper size for the document." + "description": "The paper size for the document.\n" }, { "name": "grid", @@ -357,7 +349,7 @@ }, { "name": "code-block-border-left", - "description": "Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is\nenabled as well as the color of the border.=\n" + "description": "Specifies to apply a left border on code blocks. Provide a hex color to specify that the border is\nenabled as well as the color of the border.\n" }, { "name": "code-block-bg", @@ -392,7 +384,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -534,7 +526,7 @@ }, { "name": "notes-after-punctuation", - "description": "If true (the default for note styles), Quarto (via Pandoc) will put footnote references or superscripted numerical citations after \nfollowing punctuation. For example, if the source contains blah blah [@jones99]., the result will look like blah blah.[^1], with \nthe note moved after the period and the space collapsed. \n\nIf false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used \nin numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).\n" + "description": "If true (the default for note styles), Quarto (via Pandoc) will put footnote references or superscripted numerical citations after \nfollowing punctuation. For example, if the source contains `blah blah [@jones99]`., the result will look like `blah blah.[^1]`, with \nthe note moved after the period and the space collapsed. \n\nIf false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used \nin numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).\n" } ] }, @@ -548,6 +540,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -672,6 +674,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "keep-tex", "description": "Keep the intermediate tex file used during render." @@ -695,6 +701,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, diff --git a/docs/reference/formats/presentations/pptx.json b/docs/reference/formats/presentations/pptx.json index 3a348a951d..acf508bdf1 100644 --- a/docs/reference/formats/presentations/pptx.json +++ b/docs/reference/formats/presentations/pptx.json @@ -116,7 +116,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -174,10 +174,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -206,6 +202,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -248,6 +254,10 @@ "name": "metadata", "title": "Metadata", "options": [ + { + "name": "keywords", + "description": "List of keywords to be included in the document metadata." + }, { "name": "subject", "description": "The document subject" @@ -302,6 +312,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -321,6 +335,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] } diff --git a/docs/reference/formats/presentations/revealjs.json b/docs/reference/formats/presentations/revealjs.json index f09a0e276b..b11e1a0236 100644 --- a/docs/reference/formats/presentations/revealjs.json +++ b/docs/reference/formats/presentations/revealjs.json @@ -41,10 +41,6 @@ "name": "css", "description": "One or more CSS style sheets." }, - { - "name": "section-divs", - "description": "Wrap sections in `
` tags and attach identifiers to the enclosing `
`\nrather than the heading itself.\n" - }, { "name": "identifier-prefix", "description": "Specify a prefix to be added to all identifiers and internal links in HTML and\nDocBook output, and to footnote numbers in Markdown and Haddock output. \nThis is useful for preventing duplicate identifiers when generating fragments\nto be included in other pages.\n" @@ -167,7 +163,7 @@ }, { "name": "output-location", - "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- 'column': In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n" + "description": "Location of output relative to the code that generated it. The possible values are as follows:\n\n- `default`: Normal flow of the slide after the code\n- `fragment`: In a fragment (not visible until you advance)\n- `slide`: On a new slide after the curent one\n- `column`: In an adjacent column \n- `column-fragment`: In an adjacent column (not visible until you advance)\n\nNote that this option is supported only for the `revealjs` format.\n" } ] }, @@ -349,6 +345,10 @@ "name": "reveal-print", "title": "Print to PDF", "options": [ + { + "name": "pdf-max-pages-per-slide", + "description": "Slides that are too tall to fit within a single page will expand onto multiple pages. You can limit how many pages a slide may expand to using this option.\n" + }, { "name": "pdf-separate-fragments", "description": "Prints each fragment on a separate slide" @@ -419,7 +419,7 @@ }, { "name": "margin", - "description": "Factor of the display size that should remain empty around the content" + "description": "For `revealjs`, the factor of the display size that should remain empty around the content (e.g. 0.1).\n\nFor `typst`, a dictionary with the fields defined in the Typst documentation:\n`x`, `y`, `top`, `bottom`, `left`, `right` (margins are specified in `cm` units,\ne.g. `5cm`).\n" }, { "name": "min-scale", @@ -436,6 +436,10 @@ { "name": "disable-layout", "description": "Disables the default reveal.js slide layout (scaling and centering)\n" + }, + { + "name": "code-block-height", + "description": "Sets the maximum height for source code blocks that appear in the presentation.\n" } ] }, @@ -511,7 +515,7 @@ }, { "name": "code-link", - "description": "Enables hyper-linking of functions within code blocks \nto their online documentation.\n\nCode linking is currently implemented only for the knitr engine \n(via the [downlit](https://downlit.r-lib.org/) package).\n" + "description": "Enables hyper-linking of functions within code blocks \nto their online documentation.\n\nCode linking is currently implemented only for the knitr engine \n(via the [downlit](https://downlit.r-lib.org/) package). \nA limitation of downlit currently prevents code linking \nif `code-line-numbers` is also `true`.\n" }, { "name": "code-annotations", @@ -542,7 +546,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -684,6 +688,20 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + }, + { + "name": "crossrefs-hover", + "description": "Enables a hover popup for cross references that shows the item being referenced." + } + ] + }, { "name": "citation", "title": "Citation", @@ -800,10 +818,6 @@ "name": "embed-resources", "description": "Produce a standalone HTML file with no external dependencies, using\n`data:` URIs to incorporate the contents of linked scripts, stylesheets,\nimages, and videos. The resulting file should be \"self-contained,\" in the\nsense that it needs no external files and no net access to be displayed\nproperly by a browser. This option works only with HTML output formats,\nincluding `html4`, `html5`, `html+lhs`, `html5+lhs`, `s5`, `slidy`,\n`slideous`, `dzslides`, and `revealjs`. Scripts, images, and stylesheets at\nabsolute URLs will be downloaded; those at relative URLs will be sought\nrelative to the working directory (if the first source\nfile is local) or relative to the base URL (if the first source\nfile is remote). Elements with the attribute\n`data-external=\"1\"` will be left alone; the documents they\nlink to will not be incorporated in the document.\nLimitation: resources that are loaded dynamically through\nJavaScript cannot be incorporated; as a result, some\nadvanced features (e.g. zoom or speaker notes) may not work\nin an offline \"self-contained\" `reveal.js` slide show.\n" }, - { - "name": "self-contained", - "description": "Produce a standalone HTML file with no external dependencies. Note that\nthis option has been deprecated in favor of `embed-resources`.\n" - }, { "name": "self-contained-math", "description": "Embed math libraries (e.g. MathJax) within `self-contained` output.\nNote that math libraries are not embedded by default because they are \n quite large and often time consuming to download.\n" @@ -828,6 +842,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -847,6 +865,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -869,7 +891,7 @@ "title": "Library", "options": [ { - "name": "reveal-js-url", + "name": "revealjs-url", "description": "Directory containing reveal.js files." } ] diff --git a/docs/reference/formats/rst.json b/docs/reference/formats/rst.json index 41eddcf5e8..896fe5dbb4 100644 --- a/docs/reference/formats/rst.json +++ b/docs/reference/formats/rst.json @@ -104,7 +104,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -162,10 +162,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -194,6 +190,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -292,6 +298,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -311,6 +321,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -324,7 +338,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/rtf.json b/docs/reference/formats/rtf.json index 91eed52b33..4ca0b003ed 100644 --- a/docs/reference/formats/rtf.json +++ b/docs/reference/formats/rtf.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -156,10 +156,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -188,6 +184,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -286,6 +292,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -305,6 +315,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -318,7 +332,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/tei.json b/docs/reference/formats/tei.json index dbff89926b..a5484a13d8 100644 --- a/docs/reference/formats/tei.json +++ b/docs/reference/formats/tei.json @@ -98,7 +98,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -156,10 +156,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -188,6 +184,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -286,6 +292,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -305,6 +315,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -318,7 +332,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/texinfo.json b/docs/reference/formats/texinfo.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/texinfo.json +++ b/docs/reference/formats/texinfo.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/textile.json b/docs/reference/formats/textile.json index 36e2d51343..fb07f84399 100644 --- a/docs/reference/formats/textile.json +++ b/docs/reference/formats/textile.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/typst.json b/docs/reference/formats/typst.json new file mode 100644 index 0000000000..90e4f39515 --- /dev/null +++ b/docs/reference/formats/typst.json @@ -0,0 +1,391 @@ +[ + { + "name": "attributes", + "title": "Title & Author", + "options": [ + { + "name": "title", + "description": "Document title" + }, + { + "name": "date", + "description": "Document date" + }, + { + "name": "author", + "description": "Author or authors of the document" + }, + { + "name": "order", + "description": "Order for document when included in a website automatic sidebar menu." + } + ] + }, + { + "name": "options", + "title": "Format Options", + "options": [ + { + "name": "quarto-required", + "description": "A semver version range describing the supported quarto versions for this document\nor project.\n\nExamples:\n\n- `>= 1.1.0`: Require at least quarto version 1.1\n- `1.*`: Require any quarto versions whose major version number is 1\n" + } + ] + }, + { + "name": "toc", + "title": "Table of Contents", + "options": [ + { + "name": "toc", + "description": "Include an automatically generated table of contents (or, in\nthe case of `latex`, `context`, `docx`, `odt`,\n`opendocument`, `rst`, or `ms`, an instruction to create\none) in the output document. This option has no effect\nif `standalone` is `false`.\n\nNote that if you are producing a PDF via `ms`, the table\nof contents will appear at the beginning of the\ndocument, before the title. If you would prefer it to\nbe at the end of the document, use the option\n`pdf-engine-opt: --no-toc-relocation`.\n" + }, + { + "name": "toc-depth", + "description": "Specify the number of section levels to include in the table of contents.\nThe default is 3\n" + } + ] + }, + { + "name": "numbering", + "title": "Numbering", + "options": [ + { + "name": "number-sections", + "description": "Number section headings rendered output. By default, sections are not numbered.\nSections with class `.unnumbered` will never be numbered, even if `number-sections`\nis specified.\n" + }, + { + "name": "number-offset", + "description": "Offset for section headings in output (offsets are 0 by default)\nThe first number is added to the section number for\ntop-level headings, the second for second-level headings, and so on.\nSo, for example, if you want the first top-level heading in your\ndocument to be numbered \"6\", specify `number-offset: 5`. If your\ndocument starts with a level-2 heading which you want to be numbered\n\"1.5\", specify `number-offset: [1,4]`. Implies `number-sections`\n" + }, + { + "name": "section-numbering", + "description": "Schema to use for numbering sections, e.g. `1.A.1`" + }, + { + "name": "shift-heading-level-by", + "description": "Shift heading levels by a positive or negative integer.\nFor example, with `shift-heading-level-by: -1`, level 2\nheadings become level 1 headings, and level 3 headings\nbecome level 2 headings. Headings cannot have a level\nless than 1, so a heading that would be shifted below level 1\nbecomes a regular paragraph. Exception: with a shift of -N,\na level-N heading at the beginning of the document\nreplaces the metadata title.\n" + } + ] + }, + { + "name": "reveal-layout", + "title": "Slide Layout", + "options": [ + { + "name": "margin", + "description": "For `revealjs`, the factor of the display size that should remain empty around the content (e.g. 0.1).\n\nFor `typst`, a dictionary with the fields defined in the Typst documentation:\n`x`, `y`, `top`, `bottom`, `left`, `right` (margins are specified in `cm` units,\ne.g. `5cm`).\n" + } + ] + }, + { + "name": "fonts", + "title": "Fonts", + "options": [ + { + "name": "mainfont", + "description": "For HTML output, sets the CSS `font-family` on the HTML element.\n\nFor LaTeX output, the main font family for use with `xelatex` or \n`lualatex`. Takes the name of any system font, using the\n[`fontspec`](https://ctan.org/pkg/fontspec) package. \n\nFor ConTeXt output, the main font family. Use the name of any \nsystem font. See [ConTeXt Fonts](https://wiki.contextgarden.net/Fonts) for more\ninformation.\n" + }, + { + "name": "fontsize", + "description": "For HTML output, sets the base CSS `font-size` property.\n\nFor LaTeX and ConTeXt output, sets the font size for the document body text.\n" + }, + { + "name": "font-paths", + "description": "Locally, Typst uses installed system fonts. In addition, some custom path \ncan be specified to add directories that should be scanned for fonts.\nSetting this configuration will take precedence over any path set in TYPST_FONT_PATHS environment variable.\n" + } + ] + }, + { + "name": "layout", + "title": "Layout", + "options": [ + { + "name": "papersize", + "description": "The paper size for the document.\n" + }, + { + "name": "grid", + "description": "Properties of the grid system used to layout Quarto HTML pages." + } + ] + }, + { + "name": "code", + "title": "Code", + "options": [ + { + "name": "code-annotations", + "description": "The style to use when displaying code annotations. Set this value\nto false to hide code annotations.\n" + } + ] + }, + { + "name": "execute", + "title": "Execution", + "description": "Execution options should be specified within the `execute` key. For example:\n\n```yaml\nexecute:\n echo: false\n warning: false\n```\n", + "options": [ + { + "name": "eval", + "description": "Evaluate code cells (if `false` just echos the code into output).\n\n- `true` (default): evaluate code cell\n- `false`: don't evaluate code cell\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines \n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + }, + { + "name": "echo", + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + }, + { + "name": "output", + "description": "Include the results of executing the code in the output. Possible values:\n\n- `true`: Include results.\n- `false`: Do not include results.\n- `asis`: Treat output as raw markdown with no enclosing containers.\n" + }, + { + "name": "warning", + "description": "Include warnings in rendered output." + }, + { + "name": "error", + "description": "Include errors in the output (note that this implies that errors executing code\nwill not halt processing of the document).\n" + }, + { + "name": "include", + "description": "Catch all for preventing any output (code or results) from being included in output.\n" + }, + { + "name": "cache", + "description": "Cache results of computations (using the [knitr cache](https://yihui.org/knitr/demo/cache/) \nfor R documents, and [Jupyter Cache](https://jupyter-cache.readthedocs.io/en/latest/) \nfor Jupyter documents).\n\nNote that cache invalidation is triggered by changes in chunk source code \n(or other cache attributes you've defined). \n\n- `true`: Cache results\n- `false`: Do not cache results\n- `refresh`: Force a refresh of the cache even if has not been otherwise invalidated.\n" + }, + { + "name": "freeze", + "description": "Control the re-use of previous computational output when rendering.\n\n- `true`: Never recompute previously generated computational output during a global project render\n- `false` (default): Recompute previously generated computational output\n- `auto`: Re-compute previously generated computational output only in case their source file changes\n" + } + ] + }, + { + "name": "figures", + "title": "Figures", + "options": [ + { + "name": "fig-width", + "description": "Default width for figures generated by Matplotlib or R graphics.\n\nNote that with the Jupyter engine, this option has no effect when\nprovided at the cell level; it can only be provided with\ndocument or project metadata.\n" + }, + { + "name": "fig-height", + "description": "Default height for figures generated by Matplotlib or R graphics.\n\nNote that with the Jupyter engine, this option has no effect when\nprovided at the cell level; it can only be provided with\ndocument or project metadata.\n" + }, + { + "name": "fig-format", + "description": "Default format for figures generated by Matplotlib or R graphics (`retina`, `png`, `jpeg`, `svg`, or `pdf`)" + }, + { + "name": "fig-dpi", + "description": "Default DPI for figures generated by Matplotlib or R graphics.\n\nNote that with the Jupyter engine, this option has no effect when\nprovided at the cell level; it can only be provided with\ndocument or project metadata.\n" + }, + { + "name": "fig-asp", + "description": "The aspect ratio of the plot, i.e., the ratio of height/width. When `fig-asp` is specified,\nthe height of a plot (the option `fig-height`) is calculated from `fig-width * fig-asp`.\n\nThe `fig-asp` option is only available within the knitr engine.\n" + } + ] + }, + { + "name": "tables", + "title": "Tables", + "options": [ + { + "name": "df-print", + "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" + } + ] + }, + { + "name": "references", + "title": "References", + "options": [ + { + "name": "bibliography", + "description": "Document bibliography (BibTeX or CSL). May be a single file or a list of files\n" + }, + { + "name": "csl", + "description": "Citation Style Language file to use for formatting references." + }, + { + "name": "citeproc", + "description": "Turn on built-in citation processing. To use this feature, you will need\nto have a document containing citations and a source of bibliographic data: \neither an external bibliography file or a list of `references` in the \ndocument's YAML metadata. You can optionally also include a `csl` \ncitation style file.\n" + }, + { + "name": "bibliographystyle", + "description": "The bibliography style to use (e.g. `#set bibliography(style: \"apa\")`) when using typst built-in citation system (e.g when not `citeproc: true`)." + }, + { + "name": "citation-abbreviations", + "description": "JSON file containing abbreviations of journals that should be\nused in formatted bibliographies when `form=\"short\"` is\nspecified. The format of the file can be illustrated with an\nexample:\n\n```json\n{ \"default\": {\n \"container-title\": {\n \"Lloyd's Law Reports\": \"Lloyd's Rep\",\n \"Estates Gazette\": \"EG\",\n \"Scots Law Times\": \"SLT\"\n }\n }\n}\n```\n" + } + ] + }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, + { + "name": "citation", + "title": "Citation", + "options": [ + { + "name": "citation", + "description": "Citation information for the document itself specified as [CSL](https://docs.citationstyles.org/en/stable/specification.html) \nYAML in the document front matter.\n\nFor more on supported options, see [Citation Metadata](https://quarto.org/docs/reference/metadata/citation.html).\n" + } + ] + }, + { + "name": "language", + "title": "Language", + "options": [ + { + "name": "lang", + "description": "Identifies the main language of the document using IETF language tags \n(following the [BCP 47](https://www.rfc-editor.org/info/bcp47) standard), \nsuch as `en` or `en-GB`. The [Language subtag lookup](https://r12a.github.io/app-subtags/) \ntool can look up or verify these tags. \n\nThis affects most formats, and controls hyphenation \nin PDF output when using LaTeX (through [`babel`](https://ctan.org/pkg/babel) \nand [`polyglossia`](https://ctan.org/pkg/polyglossia)) or ConTeXt.\n" + }, + { + "name": "language", + "description": "YAML file containing custom language translations" + }, + { + "name": "dir", + "description": "The base script direction for the document (`rtl` or `ltr`).\n\nFor bidirectional documents, native pandoc `span`s and\n`div`s with the `dir` attribute can\nbe used to override the base direction in some output\nformats. This may not always be necessary if the final\nrenderer (e.g. the browser, when generating HTML) supports\nthe [Unicode Bidirectional Algorithm].\n\nWhen using LaTeX for bidirectional documents, only the\n`xelatex` engine is fully supported (use\n`--pdf-engine=xelatex`).\n" + } + ] + }, + { + "name": "includes", + "title": "Includes", + "options": [ + { + "name": "include-before-body", + "description": "Include contents at the beginning of the document body\n(e.g. after the `` tag in HTML, or the `\\begin{document}` command\nin LaTeX).\n\nA string value or an object with key \"file\" indicates a filename whose contents are to be included\n\nAn object with key \"text\" indicates textual content to be included\n" + }, + { + "name": "include-after-body", + "description": "Include content at the end of the document body immediately after the markdown content. While it will be included before the closing `` tag in HTML and the `\\end{document}` command in LaTeX, this option refers to the end of the markdown content.\n\nA string value or an object with key \"file\" indicates a filename whose contents are to be included\n\nAn object with key \"text\" indicates textual content to be included\n" + }, + { + "name": "include-in-header", + "description": "Include contents at the end of the header. This can\nbe used, for example, to include special CSS or JavaScript in HTML\ndocuments.\n\nA string value or an object with key \"file\" indicates a filename whose contents are to be included\n\nAn object with key \"text\" indicates textual content to be included\n" + }, + { + "name": "metadata-files", + "description": "Read metadata from the supplied YAML (or JSON) files. This\noption can be used with every input format, but string scalars\nin the YAML file will always be parsed as Markdown. Generally,\nthe input will be handled the same as in YAML metadata blocks.\nValues in files specified later in the list will be preferred\nover those specified earlier. Metadata values specified inside\nthe document, or by using `-M`, overwrite values specified with\nthis option.\n" + } + ] + }, + { + "name": "render", + "title": "Rendering", + "options": [ + { + "name": "from", + "description": "Format to read from. Extensions can be individually enabled or disabled by appending +EXTENSION or -EXTENSION to the format name (e.g. markdown+emoji).\n" + }, + { + "name": "output-file", + "description": "Output file to write to" + }, + { + "name": "output-ext", + "description": "Extension to use for generated output file\n" + }, + { + "name": "template", + "description": "Use the specified file as a custom template for the generated document.\n" + }, + { + "name": "template-partials", + "description": "Include the specified files as partials accessible to the template for the generated content.\n" + }, + { + "name": "standalone", + "description": "Produce output with an appropriate header and footer (e.g. a standalone HTML, LaTeX, TEI, or RTF file, not a fragment)\n" + }, + { + "name": "filters", + "description": "Specify executables or Lua scripts to be used as a filter transforming\nthe pandoc AST after the input is parsed and before the output is written.\n" + }, + { + "name": "shortcodes", + "description": "Specify Lua scripts that implement shortcode handlers\n" + }, + { + "name": "keep-md", + "description": "Keep the markdown file generated by executing code" + }, + { + "name": "keep-ipynb", + "description": "Keep the notebook file generated from executing code." + }, + { + "name": "ipynb-filters", + "description": "Filters to pre-process ipynb files before rendering to markdown" + }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, + { + "name": "keep-typ", + "description": "Keep the intermediate typst file used during render." + }, + { + "name": "extract-media", + "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" + }, + { + "name": "resource-path", + "description": "List of paths to search for images and other resources.\n" + }, + { + "name": "default-image-extension", + "description": "Specify a default extension to use when image paths/URLs have no\nextension. This allows you to use the same source for formats that\nrequire different kinds of images. Currently this option only affects\nthe Markdown and LaTeX readers.\n" + }, + { + "name": "abbreviations", + "description": "Specifies a custom abbreviations file, with abbreviations one to a line.\nThis list is used when reading Markdown input: strings found in this list\nwill be followed by a nonbreaking space, and the period will not produce sentence-ending space in formats like LaTeX. The strings may not contain\nspaces.\n" + }, + { + "name": "dpi", + "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." + } + ] + }, + { + "name": "text", + "title": "Text Output", + "options": [ + { + "name": "wrap", + "description": "Determine how text is wrapped in the output (the source code, not the rendered\nversion). \n\n- `auto` (default): Pandoc will attempt to wrap lines to the column width specified by `columns` (default 72). \n- `none`: Pandoc will not wrap lines at all. \n- `preserve`: Pandoc will attempt to preserve the wrapping from the source\n document. Where there are nonsemantic newlines in the source, there will be\n nonsemantic newlines in the output as well.\n" + }, + { + "name": "columns", + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" + }, + { + "name": "tab-stop", + "description": "Specify the number of spaces per tab (default is 4). Note that tabs\nwithin normal textual input are always converted to spaces. Tabs \nwithin code are also converted, however this can be disabled with\n`preserve-tabs: false`.\n" + }, + { + "name": "preserve-tabs", + "description": "Preserve tabs within code instead of converting them to spaces.\n(By default, pandoc converts tabs to spaces before parsing its input.) \nNote that this will only affect tabs in literal code spans and code blocks. \nTabs in regular text are always treated as spaces.\n" + }, + { + "name": "eol", + "description": "Manually specify line endings: \n\n- `crlf`: Use Windows line endings\n- `lf`: Use macOS/Linux/UNIX line endings\n- `native` (default): Use line endings appropriate to the OS on which pandoc is being run).\n" + } + ] + } +] \ No newline at end of file diff --git a/docs/reference/formats/typst.qmd b/docs/reference/formats/typst.qmd new file mode 100644 index 0000000000..288fcd9ff3 --- /dev/null +++ b/docs/reference/formats/typst.qmd @@ -0,0 +1,8 @@ +--- +title: "Typst Options" +spec: https://typst.app/docs/ +--- + +[Typst](https://github.com/typst/typst) is a new open-source markup-based typesetting system that is designed to be as powerful as LaTeX while being much easier to learn and use. Typst creates beautiful PDF output with blazing fast render times. + +See the Typst format [user guide](../../output-formats/typst.qmd) for more details on creating Typst output with Quarto. diff --git a/docs/reference/formats/wiki/dokuwiki.json b/docs/reference/formats/wiki/dokuwiki.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/wiki/dokuwiki.json +++ b/docs/reference/formats/wiki/dokuwiki.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/wiki/jira.json b/docs/reference/formats/wiki/jira.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/wiki/jira.json +++ b/docs/reference/formats/wiki/jira.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/wiki/mediawiki.json b/docs/reference/formats/wiki/mediawiki.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/wiki/mediawiki.json +++ b/docs/reference/formats/wiki/mediawiki.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/wiki/xwiki.json b/docs/reference/formats/wiki/xwiki.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/wiki/xwiki.json +++ b/docs/reference/formats/wiki/xwiki.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/formats/wiki/zimwiki.json b/docs/reference/formats/wiki/zimwiki.json index 1a1f8d484f..1db095840b 100644 --- a/docs/reference/formats/wiki/zimwiki.json +++ b/docs/reference/formats/wiki/zimwiki.json @@ -94,7 +94,7 @@ }, { "name": "echo", - "description": "Include cell source code in rendered output.\n\n- `true` (default): include source code in output\n- `false`: do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" + "description": "Include cell source code in rendered output.\n\n- `true` (default in most formats): include source code in output\n- `false` (default in presentation formats like `beamer`, `revealjs`, and `pptx`): do not include source code in output\n- `fenced`: in addition to echoing, include the cell delimiter as part of the output.\n- `[...]`: A list of positive or negative line numbers to selectively include or exclude lines\n (explicit inclusion/excusion of lines is available only when using the knitr engine)\n" }, { "name": "output", @@ -152,10 +152,6 @@ "name": "tables", "title": "Tables", "options": [ - { - "name": "tbl-colwidths", - "description": "Apply explicit table column widths for markdown grid tables and pipe\ntables that are more than `columns` characters wide (72 by default). \n\nSome formats (e.g. HTML) do an excellent job automatically sizing\ntable columns and so don't benefit much from column width specifications.\nOther formats (e.g. LaTeX) require table column sizes in order to \ncorrectly flow longer cell content (this is a major reason why tables \n> 72 columns wide are assigned explicit widths by Pandoc).\n\nThis can be specified as:\n\n- `auto`: Apply markdown table column widths except when there is a\n hyperlink in the table (which tends to throw off automatic\n calculation of column widths based on the markdown text width of cells).\n (`auto` is the default for HTML output formats)\n\n- `true`: Always apply markdown table widths (`true` is the default\n for all non-HTML formats)\n\n- `false`: Never apply markdown table widths.\n\n- An array of numbers (e.g. `[40, 30, 30]`): Array of explicit width percentages.\n" - }, { "name": "df-print", "description": "Method used to print tables in Knitr engine documents:\n\n- `default`: Use the default S3 method for the data frame.\n- `kable`: Markdown table using the `knitr::kable()` function.\n- `tibble`: Plain text table using the `tibble` package.\n- `paged`: HTML table with paging for row and column overflow.\n\nThe default printing method is `kable`.\n" @@ -184,6 +180,16 @@ } ] }, + { + "name": "crossref", + "title": "Cross-References", + "options": [ + { + "name": "crossref", + "description": "Configuration for crossref labels and prefixes. See [Cross-Reference Options](https://quarto.org/docs/reference/metadata/crossref.html) for more details." + } + ] + }, { "name": "citation", "title": "Citation", @@ -282,6 +288,10 @@ "name": "ipynb-filters", "description": "Filters to pre-process ipynb files before rendering to markdown" }, + { + "name": "ipynb-shell-interactivity", + "description": "Specify which nodes should be run interactively (displaying output from expressions)\n" + }, { "name": "extract-media", "description": "Extract images and other media contained in or linked from the source document to the\npath DIR, creating it if necessary, and adjust the images references in the document\nso they point to the extracted files. Media are downloaded, read from the file\nsystem, or extracted from a binary container (e.g. docx), as needed. The original\nfile paths are used if they are relative paths not containing ... Otherwise filenames\nare constructed from the SHA1 hash of the contents.\n" @@ -301,6 +311,10 @@ { "name": "dpi", "description": "Specify the default dpi (dots per inch) value for conversion from pixels to inch/\ncentimeters and vice versa. (Technically, the correct term would be ppi: pixels per\ninch.) The default is `96`. When images contain information about dpi internally, the\nencoded value is used instead of the default specified by this option.\n" + }, + { + "name": "html-table-processing", + "description": "If `none`, do not process tables in HTML input." } ] }, @@ -314,7 +328,7 @@ }, { "name": "columns", - "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables.\n" + "description": "Specify length of lines in characters. This affects text wrapping in generated source\ncode (see `wrap`). It also affects calculation of column widths for plain text\ntables. \n\nFor `typst`, number of columns for body text.\n" }, { "name": "tab-stop", diff --git a/docs/reference/metadata/crossref.json b/docs/reference/metadata/crossref.json new file mode 100644 index 0000000000..c45115773c --- /dev/null +++ b/docs/reference/metadata/crossref.json @@ -0,0 +1,247 @@ +[ + { + "name": "crossref", + "title": "Crossref", + "options": [ + { + "name": "custom", + "description": "A custom cross reference type. See [Custom](#custom) for more details." + }, + { + "name": "chapters", + "description": "Use top level sections (H1) in this document as chapters." + }, + { + "name": "title-delim", + "description": "The delimiter used between the prefix and the caption." + }, + { + "name": "fig-title", + "description": "The title prefix used for figure captions." + }, + { + "name": "tbl-title", + "description": "The title prefix used for table captions." + }, + { + "name": "eq-title", + "description": "The title prefix used for equation captions." + }, + { + "name": "lst-title", + "description": "The title prefix used for listing captions." + }, + { + "name": "thm-title", + "description": "The title prefix used for theorem captions." + }, + { + "name": "lem-title", + "description": "The title prefix used for lemma captions." + }, + { + "name": "cor-title", + "description": "The title prefix used for corollary captions." + }, + { + "name": "prp-title", + "description": "The title prefix used for proposition captions." + }, + { + "name": "cnj-title", + "description": "The title prefix used for conjecture captions." + }, + { + "name": "def-title", + "description": "The title prefix used for definition captions." + }, + { + "name": "exm-title", + "description": "The title prefix used for example captions." + }, + { + "name": "exr-title", + "description": "The title prefix used for exercise captions." + }, + { + "name": "fig-prefix", + "description": "The prefix used for an inline reference to a figure." + }, + { + "name": "tbl-prefix", + "description": "The prefix used for an inline reference to a table." + }, + { + "name": "eq-prefix", + "description": "The prefix used for an inline reference to an equation." + }, + { + "name": "sec-prefix", + "description": "The prefix used for an inline reference to a section." + }, + { + "name": "lst-prefix", + "description": "The prefix used for an inline reference to a listing." + }, + { + "name": "thm-prefix", + "description": "The prefix used for an inline reference to a theorem." + }, + { + "name": "lem-prefix", + "description": "The prefix used for an inline reference to a lemma." + }, + { + "name": "cor-prefix", + "description": "The prefix used for an inline reference to a corollary." + }, + { + "name": "prp-prefix", + "description": "The prefix used for an inline reference to a proposition." + }, + { + "name": "cnj-prefix", + "description": "The prefix used for an inline reference to a conjecture." + }, + { + "name": "def-prefix", + "description": "The prefix used for an inline reference to a definition." + }, + { + "name": "exm-prefix", + "description": "The prefix used for an inline reference to an example." + }, + { + "name": "exr-prefix", + "description": "The prefix used for an inline reference to an exercise." + }, + { + "name": "fig-labels", + "description": "The numbering scheme used for figures." + }, + { + "name": "tbl-labels", + "description": "The numbering scheme used for tables." + }, + { + "name": "eq-labels", + "description": "The numbering scheme used for equations." + }, + { + "name": "sec-labels", + "description": "The numbering scheme used for sections." + }, + { + "name": "lst-labels", + "description": "The numbering scheme used for listings." + }, + { + "name": "thm-labels", + "description": "The numbering scheme used for theorems." + }, + { + "name": "lem-labels", + "description": "The numbering scheme used for lemmas." + }, + { + "name": "cor-labels", + "description": "The numbering scheme used for corollaries." + }, + { + "name": "prp-labels", + "description": "The numbering scheme used for propositions." + }, + { + "name": "cnj-labels", + "description": "The numbering scheme used for conjectures." + }, + { + "name": "def-labels", + "description": "The numbering scheme used for definitions." + }, + { + "name": "exm-labels", + "description": "The numbering scheme used for examples." + }, + { + "name": "exr-labels", + "description": "The numbering scheme used for exercises." + }, + { + "name": "lof-title", + "description": "The title used for the list of figures." + }, + { + "name": "lot-title", + "description": "The title used for the list of tables." + }, + { + "name": "lol-title", + "description": "The title used for the list of listings." + }, + { + "name": "labels", + "description": "The number scheme used for references." + }, + { + "name": "subref-labels", + "description": "The number scheme used for sub references." + }, + { + "name": "ref-hyperlink", + "description": "Whether cross references should be hyper-linked." + }, + { + "name": "appendix-title", + "description": "The title used for appendix." + }, + { + "name": "appendix-delim", + "description": "The delimiter beween appendix number and title." + } + ] + }, + { + "name": "crossref-custom", + "title": "Custom", + "description": "Use the `custom` option to `crossref` to define new types of cross reference. For example: \n\n```yaml\n---\ncrossref:\n custom:\n - key: vid\n kind: float\n reference-prefix: Video\n---\n```\n", + "options": [ + { + "name": "kind", + "description": "The kind of cross reference (currently only \"float\" is supported)." + }, + { + "name": "reference-prefix", + "description": "The prefix used in rendered references when referencing this type." + }, + { + "name": "caption-prefix", + "description": "The prefix used in rendered captions when referencing this type. If omitted, the field `reference-prefix` is used." + }, + { + "name": "space-before-numbering", + "description": "If false, use no space between crossref prefixes and numbering." + }, + { + "name": "key", + "description": "The key used to prefix reference labels of this type, such as \"fig\", \"tbl\", \"lst\", etc." + }, + { + "name": "latex-env", + "description": "In LaTeX output, the name of the custom environment to be used." + }, + { + "name": "latex-list-of-file-extension", + "description": "In LaTeX output, the extension of the auxiliary file used by LaTeX to collect names to be used in the custom \"list of\" command. If omitted, a string with prefix `lo` and suffix with the value of `ref-type` is used." + }, + { + "name": "latex-list-of-description", + "description": "The description of the crossreferenceable object to be used in the title of the \"list of\" command. If omitted, the field `reference-prefix` is used." + }, + { + "name": "caption-location", + "description": "The location of the caption relative to the crossreferenceable content." + } + ] + } +] \ No newline at end of file diff --git a/docs/reference/metadata/crossref.qmd b/docs/reference/metadata/crossref.qmd new file mode 100644 index 0000000000..5f13bb0509 --- /dev/null +++ b/docs/reference/metadata/crossref.qmd @@ -0,0 +1,13 @@ +--- +title: Cross Reference Options +--- + +The `crossref` option is used to customize the appearance and behavior of cross-references. You can read more about using [Cross-References in the Guide](/docs/authoring/cross-references.qmd). + +```yaml +--- +crossref: + labels: roman + title-delim: "-" +--- +``` \ No newline at end of file diff --git a/docs/reference/projects/_websites.md b/docs/reference/projects/_websites.md index 225d67160b..9caf5f5510 100644 --- a/docs/reference/projects/_websites.md +++ b/docs/reference/projects/_websites.md @@ -15,7 +15,7 @@ Options that define the top navigation bar for a {{< meta project-type >}} For e ## Nav Items -Nav items appear in the `left` or `right` key of `navbar` definitions. For example: +Nav items appear in the `left` or `right` key of `navbar` definitions, or `contents` key of `sidebar` definitions. For example: ``` yaml --- @@ -91,6 +91,7 @@ Action buttons that appear on the sidebar. For example: Search options are specified under the `search` key of `{{< meta project-type >}}`. For example: ``` yaml +--- {{< meta project-type >}}: search: location: navbar diff --git a/docs/reference/projects/about.json b/docs/reference/projects/about.json index 870162f113..ccabe1d42e 100644 --- a/docs/reference/projects/about.json +++ b/docs/reference/projects/about.json @@ -11,6 +11,14 @@ "name": "image", "description": "The path to the main image on the about page. If not specified, \nthe `image` provided for the document itself will be used.\n" }, + { + "name": "image-alt", + "description": "The alt text for the main image on the about page." + }, + { + "name": "image-title", + "description": "The title for the main image on the about page." + }, { "name": "image-width", "description": "A valid CSS width for the about page image.\n" diff --git a/docs/reference/projects/book.json b/docs/reference/projects/book.json index 5b501d06fe..7920111c35 100644 --- a/docs/reference/projects/book.json +++ b/docs/reference/projects/book.json @@ -211,6 +211,10 @@ "name": "host", "description": "Host of the item (e.g. of a TV show or podcast)." }, + { + "name": "id", + "description": "A value which uniquely identifies this item." + }, { "name": "illustrator", "description": "Illustrator (e.g. of a children’s book or graphic novel)." @@ -455,6 +459,14 @@ "name": "repo-url", "description": "Base URL for website source code repository" }, + { + "name": "repo-link-target", + "description": "The value of the target attribute for repo links" + }, + { + "name": "repo-link-rel", + "description": "The value of the rel attribute for repo links" + }, { "name": "repo-subdir", "description": "Subdirectory of repository containing website" @@ -519,6 +531,10 @@ "name": "back-to-top-navigation", "description": "Provide a 'back to top' navigation button" }, + { + "name": "bread-crumbs", + "description": "Whether to show navigation breadcrumbs for pages more than 1 level deep" + }, { "name": "page-footer", "description": "Page footer. Text content or [page footer](#page-footer) definition." @@ -527,6 +543,10 @@ "name": "image", "description": "Default site thumbnail image for `twitter` /`open-graph`\n" }, + { + "name": "image-alt", + "description": "Default site thumbnail image alt text for `twitter` /`open-graph`\n" + }, { "name": "comments", "description": "" @@ -538,5 +558,13 @@ { "name": "twitter-card", "description": "Generate Twitter Card metadata (see [Twitter Card](#twitter-card) options)" + }, + { + "name": "other-links", + "description": "A list of other links to appear below the TOC." + }, + { + "name": "code-links", + "description": "A list of code links to appear with this document." } ] \ No newline at end of file diff --git a/docs/reference/projects/feed.json b/docs/reference/projects/feed.json index 9eb25e59fa..7238ad7724 100644 --- a/docs/reference/projects/feed.json +++ b/docs/reference/projects/feed.json @@ -5,7 +5,7 @@ }, { "name": "type", - "description": "Whether to include full or partial content in the feed.\n\n- `full` (default): Include the complete content of the document in the feed.\n- `partial`: Include only the first paragraph of the document in the feed.\n" + "description": "Whether to include full or partial content in the feed.\n\n- `full` (default): Include the complete content of the document in the feed.\n- `partial`: Include only the first paragraph of the document in the feed.\n- `metadata`: Use only the title, description, and other document metadata in the feed.\n" }, { "name": "title", @@ -25,6 +25,10 @@ }, { "name": "categories", - "description": "A list of categories for which to create separate RSS feeds containing only posts with that category." + "description": "A list of categories for which to create separate RSS feeds containing only posts with that category" + }, + { + "name": "xml-stylesheet", + "description": "The path to an XML stylesheet (XSL file) used to style the RSS feed." } ] \ No newline at end of file diff --git a/docs/reference/projects/giscus.json b/docs/reference/projects/giscus.json index 3fbedef98e..6236414eaf 100644 --- a/docs/reference/projects/giscus.json +++ b/docs/reference/projects/giscus.json @@ -33,7 +33,7 @@ }, { "name": "theme", - "description": "The giscus theme to use when displaying comments." + "description": "The light theme name." }, { "name": "language", diff --git a/docs/reference/projects/hypothesis.json b/docs/reference/projects/hypothesis.json index a6592a8437..0a590b3969 100644 --- a/docs/reference/projects/hypothesis.json +++ b/docs/reference/projects/hypothesis.json @@ -1,4 +1,8 @@ [ + { + "name": "client-url", + "description": "Override the default hypothesis client url with a custom client url." + }, { "name": "openSidebar", "description": "Controls whether the sidebar opens automatically on startup." diff --git a/docs/reference/projects/listing.json b/docs/reference/projects/listing.json index ea14313bc7..114fdb11b9 100644 --- a/docs/reference/projects/listing.json +++ b/docs/reference/projects/listing.json @@ -1,7 +1,7 @@ [ { "name": "id", - "description": "The id of this listing. When the listing is rendered, it will \nplace the contents into a `div` with this id. If no such `div` is defined on the \npage, a `div` with this id will be created and appended to the end of the page.\n\nIn no `id` is provided for a listing, Quarto will synthesize one when rendering the page.\n" + "description": "The id of this listing. When the listing is rendered, it will \nplace the contents into a `div` with this id. If no such `div` is defined on the \npage, a `div` with this id will be created and appended to the end of the page.\n\nIf no `id` is provided for a listing, Quarto will synthesize one when rendering the page.\n" }, { "name": "type", diff --git a/docs/reference/projects/manuscript.json b/docs/reference/projects/manuscript.json new file mode 100644 index 0000000000..cf4057b0ef --- /dev/null +++ b/docs/reference/projects/manuscript.json @@ -0,0 +1,30 @@ +[ + { + "name": "article", + "description": "The input document that will serve as the root document for this manuscript" + }, + { + "name": "code-links", + "description": "Code links to display for this manuscript." + }, + { + "name": "manuscript-url", + "description": "The deployed url for this manuscript" + }, + { + "name": "meca-bundle", + "description": "Whether to generate a MECA bundle for this manuscript" + }, + { + "name": "notebooks", + "description": "Options for notebooks included under the heading \"Notebooks\". See [Including Notebooks](/docs/manuscripts/components.html#including-notebooks) for more details." + }, + { + "name": "resources", + "description": "Additional file resources to be copied to output directory" + }, + { + "name": "environment", + "description": "Files that specify the execution environment (e.g. renv.lock, requirements.text, etc...)" + } +] \ No newline at end of file diff --git a/docs/reference/projects/manuscripts.qmd b/docs/reference/projects/manuscripts.qmd new file mode 100644 index 0000000000..a3008d1ea1 --- /dev/null +++ b/docs/reference/projects/manuscripts.qmd @@ -0,0 +1,13 @@ +--- +title: "Manuscript Options" +project-type: manuscript +project-type-upper: Manuscript +project-output-dir: _manuscript +--- + +All available options for `manuscript` projects are documented below. See [Quarto Manuscripts](../../manuscripts/) for an in-depth guide to creating manuscripts with Quarto. + +::: {#table-manuscript} +::: + + diff --git a/docs/reference/projects/navbar.json b/docs/reference/projects/navbar.json index 3de2680ace..ffc63f309e 100644 --- a/docs/reference/projects/navbar.json +++ b/docs/reference/projects/navbar.json @@ -46,5 +46,9 @@ { "name": "right", "description": "List of items for the left side of the navbar (see [Nav Items](#nav-items))" + }, + { + "name": "toggle-position", + "description": "The position of the collapsed navbar toggle when in responsive mode" } ] \ No newline at end of file diff --git a/docs/reference/projects/project.json b/docs/reference/projects/project.json index 5774cacb7a..72fba90f20 100644 --- a/docs/reference/projects/project.json +++ b/docs/reference/projects/project.json @@ -5,7 +5,7 @@ }, { "name": "type", - "description": "Project type (`default`, `website`, or `book`)" + "description": "Project type (`default`, `website`, `book`, or `manuscript`)" }, { "name": "render", diff --git a/docs/reference/projects/search.json b/docs/reference/projects/search.json index 89d5d9023c..35f5bb5d29 100644 --- a/docs/reference/projects/search.json +++ b/docs/reference/projects/search.json @@ -19,6 +19,14 @@ "name": "copy-button", "description": "Provide button for copying search link" }, + { + "name": "keyboard-shortcut", + "description": "One or more keys that will act as a shortcut to launch search (single characters)" + }, + { + "name": "show-item-context", + "description": "Whether to include search result parents when displaying items in search results (when possible)." + }, { "name": "algolia", "description": "Use an Algolia index for site search (see [Algolia Options](#algolia-options))" diff --git a/docs/reference/projects/website.json b/docs/reference/projects/website.json index a1a3d0f8c4..fc8b5cb46c 100644 --- a/docs/reference/projects/website.json +++ b/docs/reference/projects/website.json @@ -23,6 +23,14 @@ "name": "repo-url", "description": "Base URL for website source code repository" }, + { + "name": "repo-link-target", + "description": "The value of the target attribute for repo links" + }, + { + "name": "repo-link-rel", + "description": "The value of the rel attribute for repo links" + }, { "name": "repo-subdir", "description": "Subdirectory of repository containing website" @@ -87,6 +95,10 @@ "name": "back-to-top-navigation", "description": "Provide a 'back to top' navigation button" }, + { + "name": "bread-crumbs", + "description": "Whether to show navigation breadcrumbs for pages more than 1 level deep" + }, { "name": "page-footer", "description": "Page footer. Text content or [page footer](#page-footer) definition." @@ -95,6 +107,10 @@ "name": "image", "description": "Default site thumbnail image for `twitter` /`open-graph`\n" }, + { + "name": "image-alt", + "description": "Default site thumbnail image alt text for `twitter` /`open-graph`\n" + }, { "name": "comments", "description": "" @@ -106,5 +122,13 @@ { "name": "twitter-card", "description": "Generate Twitter Card metadata (see [Twitter Card](#twitter-card) options)" + }, + { + "name": "other-links", + "description": "A list of other links to appear below the TOC." + }, + { + "name": "code-links", + "description": "A list of code links to appear with this document." } ] \ No newline at end of file diff --git a/docs/reference/reference.yml b/docs/reference/reference.yml index 41965d6198..81a1447532 100644 --- a/docs/reference/reference.yml +++ b/docs/reference/reference.yml @@ -6,6 +6,8 @@ href: formats/pdf.qmd - text: MS Word href: formats/docx.qmd + - text: Typst + href: formats/typst.qmd - text: Open Office href: formats/odt.qmd - text: ePub @@ -59,6 +61,8 @@ href: projects/websites.qmd - text: "Books" href: projects/books.qmd + - text: "Manuscripts" + href: projects/manuscripts.qmd - title: "Metadata" links: @@ -68,4 +72,6 @@ href: globs.qmd - text: "Citations" href: metadata/citation.qmd + - text: "Cross-References" + href: metadata/crossref.qmd diff --git a/docs/visual-editor/technical.qmd b/docs/visual-editor/technical.qmd index 85cfdf0759..bc3209c7fc 100644 --- a/docs/visual-editor/technical.qmd +++ b/docs/visual-editor/technical.qmd @@ -82,7 +82,7 @@ To insert an executable code chunk, use the **Insert -\> Code Chunk** menu item, Then press the **Enter** key. Note that `r` could be another language supported by knitr (e.g. `python` or `sql`) and you can also include a chunk label and other chunk options. -To include inline R code, you just create normal inline code (e.g. by using backticks or the ⌘ D shortcut) but preface it with `r`. For example, this inline code will be executed by knitr: `` `r Sys.Date()` ``. Note that when the code displays in visual mode it won't have the backticks (but they will still appear in source mode). +To include inline R code, you just create normal inline code (e.g. by using backticks or the ⌘ D shortcut) but preface it with `r` or `{r}`. For example, this inline code will be executed by knitr: `` `r Sys.Date()` ``. Note that when the code displays in visual mode it won't have the backticks (but they will still appear in source mode). ### Running Chunks diff --git a/docs/websites/_page-navigation.md b/docs/websites/_page-navigation.md index 92b51eced7..a2688e94b9 100644 --- a/docs/websites/_page-navigation.md +++ b/docs/websites/_page-navigation.md @@ -9,3 +9,16 @@ If you have a {{< meta project-type >}} with several pages in a section or subse When enabled, page navigation will be displayed at the bottom of the page whenever there is a next or previous page (including in the next or previous section). This option is enabled by default for books but not for websites. +You can also enable or disable page navigation at the page level by specifying `page-navigation` in the YAML header, e.g.: + +```{.yaml filename="basics.qmd"} +--- +page-navigation: false +--- +``` + +Or to control page navigation for all pages in a directory specify `page-navigation` in [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.qmd#directory-metadata): + +``` {.yaml filename="_metadata.yml"} +page-navigation: false +``` diff --git a/docs/websites/images/nav-breadcrumbs.png b/docs/websites/images/nav-breadcrumbs.png new file mode 100644 index 0000000000..249730b2ec Binary files /dev/null and b/docs/websites/images/nav-breadcrumbs.png differ diff --git a/docs/websites/images/search-item-context.png b/docs/websites/images/search-item-context.png new file mode 100644 index 0000000000..a76fdb9776 Binary files /dev/null and b/docs/websites/images/search-item-context.png differ diff --git a/docs/websites/images/search-placeholder-text.png b/docs/websites/images/search-placeholder-text.png new file mode 100644 index 0000000000..0eaa562239 Binary files /dev/null and b/docs/websites/images/search-placeholder-text.png differ diff --git a/docs/websites/website-navigation.qmd b/docs/websites/website-navigation.qmd index c74e5938ee..061d83f5e1 100644 --- a/docs/websites/website-navigation.qmd +++ b/docs/websites/website-navigation.qmd @@ -66,6 +66,8 @@ Here are all of the options available for top navigation: | `pinned` | Always show the navbar (true or false). Defaults to false, and uses [headroom.js](https://wicky.nillia.ms/headroom.js/) to automatically show the navbar when the user scrolls up on the page. | | `collapse` | Collapse the navbar items into a hamburger menu when the display gets narrow (defaults to true). | | `collapse-below` | Responsive breakpoint at which to collapse navbar items to a hamburger menu ("sm", "md", "lg", "xl", or "xxl", defaults to "lg"). | +| `toggle-position`| The position of the collapsed navbar hamburger menu when in responsive mode ("left" or "right", defaults to "left"). | + Here are the options available for individual navigation items: @@ -156,7 +158,7 @@ Here are all of the options available for side navigation: | `logo` | Optional logo image. | | `search` | Include a search box (true or false). Note that if there is already a search box on the top navigation bar it won't be displayed on the sidebar. | | `tools` | List of sidebar tools (e.g. link to github or twitter, etc.). See the next section for details. | -| `items` | List of navigation items to display (typically top level items will in turn have a list of sub-items). | +| `contents` | List of navigation items to display (typically top level items will in turn have a list of sub-items). | | `style` | "docked" or "floating". | | `type` | "dark" or "light" (hint to make sure the text color is the inverse of the background). | | `background` | Background color ("none", "primary", "secondary", "success", "danger", "warning", "info", "light", "dark", or "white"). Defaults to "light". | @@ -166,6 +168,8 @@ Here are all of the options available for side navigation: | `collapse-level` | Whether to show sidebar navigation collapsed by default. The default is 2, which shows the top and next level fully expanded (but leaves the 3rd and subsequent levels collapsed). | | `pinned` | Always show a title bar that expands to show the sidebar at narrower screen widths (true or false). Defaults to false, and uses [headroom.js](https://wicky.nillia.ms/headroom.js/) to automatically show the navigation bar when the user scrolls up on the page. | +A single `sidebar` item without an `id` or `title` will result in a global sidebar applied to all pages. A sidebar with an `id` or `title` will only be applied to pages within the contents of the sidebar or pages that specify the sidebar id. + For more information on controlling the appearance of the side navigation using HTML themes, see [HTML Themes - Navigation](/docs/output-formats/html-themes.qmd#navigation). If you need to control the width of the sidebar, see [Page Layout - Grid Customization](/docs/output-formats/page-layout.qmd#grid-customization). ### Auto Generation @@ -317,7 +321,7 @@ Note that the first sidebar definition contains a few options (e.g. `style` and An alternative approach is to make the `sidebar` entries available from a drop down menu from the `navbar` items they're grouped with. To do this, provide a list of `sidebar` entries and give them each an `id`, which you then use to reference them from the `navbar`. ::: callout-note -A page that doesn't appear in any sidebar will inherit and display the first sidebar- you can prevent the sidebar from showing on a page by setting `sidebar: false` in it's front matter. +A page that doesn't appear in any sidebar will inherit and display the first sidebar without an `id` or `title` - you can prevent the sidebar from showing on a page by setting `sidebar: false` in it's front matter. ::: ![](images/nav-bar-hybrid-dropdown.png){fig-alt="A navigation bar titled 'ProjectX' on the left. To the right of the title are the menu items 'Home', 'Tutorials', 'How-To', 'Fundamentals', and 'Reference'. 'Home' is in a lighter color than the other menu options. The other menu options have a triangle pointing down next to each one, indicating the existence of a drop-down menu. There is a search bar on the far right side of the navigation bar."} @@ -364,6 +368,31 @@ website: ``` +## Breadcrumbs + +By default, navigational breadcrumbs are displayed above the page title on each page that is nested deeper than one level in the sidebar navigation. For example, given this `sidebar` definition: + +``` .yaml +website: + sidebar: + - contents: + - section: "Tutorials" + contents: + - text: "Tutorial Landing" + href: tutorials.qmd +``` + +The page `tutorials.html` contains the following breadcrumb: + +![](images/nav-breadcrumbs.png){.border fig-alt="Screenshot of a webpage. Above the header 'Tutorials' is the linked text 'Tutorials > Tutorial Landing'." width=50%} + +You can disable breadcrumbs for a website using the `bread-crumbs` option: + +```{.yaml filename="_quarto.yml"} +website: + bread-crumbs: false +``` + {{< include _page-navigation.md >}} ### Separators @@ -465,9 +494,19 @@ There are a couple of additional options that enable you to customize the behavi | `repo-subdir` | Subdirectory of repository containing source files (defaults to root directory). | | `repo-branch` | Repository branch containing the source files (defaults to `main`) | | `issue-url` | Provide an explicit URL for the 'Report an Issue' action. | +| `repo-link-target` | The `target` attribute to use for repo action links. E.g. set to "_blank" to open in a new tab or window. | +| `repo-link-rel` | The `rel` attribute to use for repo action links. | : {tbl-colwidths="\[40,60\]"} +If you want to suppress the GitHub links on a specific page, you can set `repo-actions` to `false` in the document YAML: + +```{.yaml filename="page.qmd"} +--- +repo-actions: false +--- +``` + ## Redirects If you rename or move a page on your site, you may want to create redirects from the old URLs so that existing links don't break. You can do this by adding `aliases` from old pages to renamed pages. diff --git a/docs/websites/website-search.qmd b/docs/websites/website-search.qmd index 5740076388..7f7b9c6c4b 100644 --- a/docs/websites/website-search.qmd +++ b/docs/websites/website-search.qmd @@ -34,23 +34,48 @@ The `textbox` option displays search like this: ![](images/navbar-textbox.png){.border .column-page-outset-right fig-alt="Algolia search with textbox in navbar. The search dialog opens as a dropdown in the right-hand side of the screen as an expansion of the textbox."} +When the search is displayed as a textbox, by default, there is no placeholder text. You can specify placeholder text using the `search-box-placeholder` key of the `language` option (note that this is at the top-level, not inside the `website` option): + +::: {layout-ncol="2"} +``` yaml +language: + search-box-placeholder: Search +``` + +![](images/search-placeholder-text.png){fig-alt="Search box showing the placeholder text 'Search'."} +::: + +## Keyboard Shortcut + +In addition to clicking on the search UI, users can activate search using the keyboard shortcuts {{< kbd s >}}, {{< kbd f >}} or {{< kbd / >}}. You can override these shortcuts by specifying the `keyboard-shortcut` option. In this example, search will be activated with {{< kbd ? >}} or {{< kbd H >}}: + +``` yaml +website: + search: + keyboard-shortcut: ["?", "H"] +``` + ## Customizing Results You can use the following `search` options to customize how search results are displayed: -+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Option | Description | -+==================+===================================================================================================================================================================================================================================+ -| `limit` | The number of results to display in the search results. Defaults to 20. | -+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `collapse-after` | The number of sections matching a document to show before hiding additional sections behind a 'more matches' link. Defaults to 2. | -| | | -| | ![](images/collapse-after.png){.border fig-alt="Part of a search result that shows a matching result for the search term, and at the bottom reads '3 more matches in this document'"} | -+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `copy-button` | If true, the search textbox will include a small icon that when clicked will copy a url to the search results to the clipboard (this is useful if users would like to share a particular search with results). Defaults to false. | -| | | -| | ![](images/copy-button.png){.border fig-alt="search box with clickable clipboard icon on the right hand side that, if clicked, will copy the resulting url."} | -+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Option | Description | ++====================+===================================================================================================================================================================================================================================+ +| `limit` | The number of results to display in the search results. Defaults to 20. | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `collapse-after` | The number of sections matching a document to show before hiding additional sections behind a 'more matches' link. Defaults to 2. | +| | | +| | ![](images/collapse-after.png){.border fig-alt="Part of a search result that shows a matching result for the search term, and at the bottom reads '3 more matches in this document'"} | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `copy-button` | If true, the search textbox will include a small icon that when clicked will copy a url to the search results to the clipboard (this is useful if users would like to share a particular search with results). Defaults to false. | +| | | +| | ![](images/copy-button.png){.border fig-alt="search box with clickable clipboard icon on the right hand side that, if clicked, will copy the resulting url."} | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `show-item-context`| Control whether page parents are displayed next to items in search results. Use `tree`, `parent`, `root`, or boolean (if true, `tree` is the default). E.g. `tree` results in "Guide \> Authoring \> Figures": | +| | | +| | ![](images/search-item-context.png){.border fig-alt="search box with navigational context shown above the title of the first result." width="260"} | ++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ## Using Algolia diff --git a/docs/websites/website-tools.qmd b/docs/websites/website-tools.qmd index 3f6f3daa28..8b718511c7 100644 --- a/docs/websites/website-tools.qmd +++ b/docs/websites/website-tools.qmd @@ -70,7 +70,8 @@ You may also provide additional metadata to be used when generating the Twitter +---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `description` | A short description of the content. Quarto will automatically use the `description` metadata from the page metadata. If you'd like you can override this just for the Twitter Card by including a `description` in the `twitter-card` metadata. | +---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `image` | The path to a preview image for this content. By default, Quarto will use the `image` value from the document metadata. If you provide an image, you may also optionally provide an `image-width` and `image-height` to improve the appearance of your Twitter Card. | +| `image` | The path to a preview image for this content. By default, Quarto will use the `image` value from the document metadata, or if that isn't specified, the `image` value from the `website:` metadata. | +| | If you provide an image, you may also optionally provide an `image-width` and `image-height` to improve the appearance of your Twitter Card. | | | | | | If `image` is not provided, Quarto will automatically attempt to locate a preview image. For more information, see [Preview Images]. | +---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -112,13 +113,14 @@ You may also provide additional metadata to be used when generating the Open Gra +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `description` | A short description of the content. Quarto will automatically use the `description` metadata from the page metadata. If you'd like you can override this just for the Open Graph metadata by including a `description` in the `open-graph` metadata. | +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `image` | The path to a preview image for this content. By default, Quarto will use the `image` value from the `site:` metadata. If you provide an image, you may also optionally provide an `image-width` and `image-height`. | +| `image` | The path to a preview image for this content. By default, Quarto will use the `image` value from the document metadata, or if that isn't specified, the `image` value from the `website:` metadata. | +| | If you provide an image, you may also optionally provide an `image-width` and `image-height` to improve the appearance of your Twitter Card. | | | | | | If `image` is not provided, Quarto will automatically attempt to locate a preview image. For more information, see [Preview Images]. | +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `locale` | The locale that the Open Graph metadata is marked up in. | +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `site-name` | The name which should be displayed for the overall site. If not explicitly provided in the `open-graph` metadata, Quarto will use the `site:title` value. | +| `site-name` | The name which should be displayed for the overall site. If not explicitly provided in the `open-graph` metadata, Quarto will use the `website:title` value. | +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ Here is a more comprehensive example of specifying Open Graph metadata in a `quarto.yml` file: @@ -136,30 +138,28 @@ Quarto will automatically merge global metadata found in the `website: open-grap You can specify a preview image for your article in several different ways: -1. You can explicitly provide a full url to the preview image using the `image` field in the appropriate metadata. For example: +1. **Full URL**: You can explicitly provide a full url to the preview image using the `image` field in the appropriate metadata. For example: - ``` yaml + ``` {.yaml filename="page.qmd"} title: "My Document" - twitter-card: - image: "https://quarto.org/docs/websites/images/tools.png" + image: "https://quarto.org/docs/websites/images/tools.png" ``` -2. You may provide a document relative path to an image (such as `images/preview-code.png`) or a project relative path to an image (such as `/images/preview-code.png`). If you provide a relative path such as this, you must also provide a `site-url` in your site's metadata. For example in your `_quarto.yml` configuration file: +2. **Relative Path**: You may provide a document relative path to an image (such as `images/preview-code.png`) or a project relative path to an image (such as `/images/preview-code.png`). If you provide a relative path such as this, you must also provide a `site-url` in your site's metadata. For example in your `_quarto.yml` configuration file: - ``` yaml + ``` {.yaml filename="_quarto.yml"} website: site-url: "https://www.quarto.org" ``` and in your document front matter: - ``` yaml + ``` {.yaml filename="page.qmd"} title: "My Document" - twitter-card: - image: "/docs/websites/images/tools.png" + image: "/docs/websites/images/tools.png" ``` -3. Any image that is being rendered in the page may also be used as a preview image by giving it the class name `preview-image`. Quarto will select the first image it finds with this class. For example, the following image will be used as the preview image when included on a page: +3. **Image Class**: Any image that is being rendered in the page may also be used as a preview image by giving it the class name `preview-image`. Quarto will select the first image it finds with this class. For example, the following image will be used as the preview image when included on a page: ``` markdown ![](images/tools.png){.preview-image} @@ -167,7 +167,22 @@ You can specify a preview image for your article in several different ways: If you label an image with this class, you must also provide a `site-url` in your site's metadata. -4. If none of the above ways of specifying a preview image have been used, Quarto will attempt to find a preview image by looking for an image included in the rendered document with one of the following names: `preview.png`, `feature.png`, `cover.png`, or `thumbnail.png`. +4. **Image Filename**: If none of the above ways of specifying a preview image have been used, Quarto will attempt to find a preview image by looking for an image included in the rendered document with one of the following names: `preview.png`, `feature.png`, `cover.png`, or `thumbnail.png`. + +If you'd like to provide a default that is used when pages specify a preview image in none of the above ways, specify it at the site level: + +```{.yaml filename="_quarto.yml"} +website: + image: "https://quarto.org/quarto-dark-bg.jpeg" +``` + +If you would like to prevent preview image discovery on a page, set `image` to `false`: + +```{.yaml filename="page.qmd"} +--- +image: false +--- +``` ## Google Analytics @@ -216,7 +231,7 @@ If you choose `none` for storage, this will have the following effects: Quarto includes the ability to request cookie consent before enabling scripts that set cookies, using [Cookie Consent](https://www.cookieconsent.com). -The user's cookie preferences will automatically control [Google Analytics] (if enabled) and can be used to control custom scripts you add as well (see [Custom Scripts and Cookie Consent]. You can enable the default request for cookie consent using the following: +The user's cookie preferences will automatically control [Google Analytics] (if enabled) and can be used to control custom scripts you add as well (see [Custom Scripts and Cookie Consent]). You can enable the default request for cookie consent using the following: ``` yaml website: @@ -250,6 +265,9 @@ You can further customize the appearance and behavior of the consent using the f | | | | | **dark -** A dark colored banner. | +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| `language` | The language to be used when displaying the cookie consent prompt specified using an IETF language tag. | +| | If not specified, the document language will be used. | ++--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `policy-url` | The url to the website's cookie or privacy policy. | +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `prefs-text` | The text to display for the cookie preferences link in the website footer. | @@ -363,4 +381,4 @@ When enabled, a toggle that allows your reader to control the appearance of the 1. If a navbar has been specified, the toggle will appear in the top right corner of the nav bar. 2. If there is no navbar present, but a sidebar has been specified, the toggle will appear in the same location that the sidebar tools appears (adjacent to the title or logo in the sidebar). -3. If there is no navbar or sidebar present, the toggle will appear in the top right corner of the page. +3. If there is no navbar or sidebar present, the toggle will appear in the top right corner of the page. \ No newline at end of file diff --git a/tools/reference.ts b/tools/reference.ts index 37701494cb..9e6a6c6c10 100644 --- a/tools/reference.ts +++ b/tools/reference.ts @@ -120,7 +120,7 @@ const cellOptions = Object.keys(cellGroups).map(group => { // document options const documentGroups = groups["document"]; const documentOptions = Object.keys(documentGroups) - .filter(group => !["comments", "crossref"].includes(group)) + .filter(group => !["comments"].includes(group)) .map(group => { const title = documentGroups[group]["title"]; @@ -242,7 +242,7 @@ function readProjectObject(name: string, descriptions?: Record) const supers = obj["schema"]["object"]["super"]; if (supers) { (supers as { resolveRef: string }[]).forEach((sup) => { - results.push(...readDefinitionsId(sup.resolveRef)); + results.push(...readDefinitionsId(sup.resolveRef, descriptions)); }) } @@ -311,18 +311,37 @@ function findVal(object: any, key: string) { } // Metadata pages -function writeMetadataTable(name: string, options: Array