diff --git a/docs/advanced/environment-vars.qmd b/docs/advanced/environment-vars.qmd index f1ae1ef762..a254bfca4e 100644 --- a/docs/advanced/environment-vars.qmd +++ b/docs/advanced/environment-vars.qmd @@ -15,37 +15,55 @@ quarto render You can read about other ways to set environment variables in Quarto Projects in [Environment Variables](/docs/projects/environment.qmd). -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable | Description | -+=================================+=============================================================================================================================================================================================================================================================================================================================================================================================================================================================+ -| `QUARTO_R` | Explicit path to the version of `Rscript` to be used by the `knitr` engine and `quarto run *.R` command. | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_PYTHON` | Explicit path to the version of `python` to be used by the `jupyter` engine and `quarto run *.py` command. | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_JULIA` | Explicit path to the version of `julia` to be used by the `julia` engine. | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_VERSION_REQUIREMENT` | A [`semver`](https://semver.org/) string describing the Quarto version requested by the environment. If this check fails, Quarto will not run. | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_KNITR_RSCRIPT_ARGS` | Comma separated list of command line argument to pass to `Rscript` started by Quarto when rendering with `knitr` engine, e.g. | -| | | -| | ``` | -| | QUARTO_KNITR_RSCRIPT_ARGS="--no-init-file,--max-connections=258" | -| | ``` | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_TEXLIVE_BINPATH` | Explicit path to the TeX Live binaries to be passed to `tlmgr option sys_bin` used when setting `tlmgr` and related to `PATH` using `tlmgr add path` . By default, Quarto looks in known places. | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_CHROMIUM` | Explicit path to binary to use for chrome headless. Quarto uses [Chrome Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/) to do screenshot of HTML diagrams for PDF insertion. The binary must be compatible with this protocol. (e.g. Chrome, Chromium, Chrome Headless Shell, Edge, ...) | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_CHROMIUM_HEADLESS_MODE` | Used for adaption of the `--headless` mode used with `QUARTO_CHROMIUM` binary. Set to `"none"` for `--headless` , or to `"old"` or `"new"` to pass as argument, e.g. `--headless=` . Quarto 1.6 sets `"old"` as default, which works from Chrome 112 to 131. Starting Quarto 1.7.13, `"none"` is the default as [Chrome 132 removed old headless mode](https://developer.chrome.com/blog/removing-headless-old-from-chrome). | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_LOG` | Those variables controls the logging behavior: | -| | | -| `QUARTO_LOG_LEVEL` | - `QUARTO_LOG` is the same as using `--log` at command line. It is used to set the path to the log file | -| | | -| `QUARTO_LOG_FORMAT` | - `QUARTO_LOG_LEVEL` is the same as using `--log-level` at command line. It is used to set the max level that will be log. Possible values are `DEBUG`, `INFO`(default), `WARNING`, and `ERROR`. | -| | | -| | - `QUARTO_LOG_FORMAT` is the same as using `--log-format` at command line. It is used to set the format for the log. Possible values are `plain` (default) and `json-stream`. | -+---------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: {.list-table widths="0.2,0.8" header-rows="1"} + +* * Variable + * Description + +* * `QUARTO_R` + * Explicit path to the version of `Rscript` to be used by the `knitr` engine and `quarto run *.R` command. + +* * `QUARTO_PYTHON` + * Explicit path to the version of `python` to be used by the `jupyter` engine and `quarto run *.py` command. + +* * `QUARTO_JULIA` + * Explicit path to the version of `julia` to be used by the `julia` engine. + +* * `QUARTO_VERSION_REQUIREMENT` + * A [`semver`](https://semver.org/) string describing the Quarto version requested by the environment. If this check fails, Quarto will not run. + +* * `QUARTO_KNITR_RSCRIPT_ARGS` + + * Comma separated list of command line argument to pass to `Rscript` started by Quarto when rendering with `knitr` engine, e.g. + + ``` + QUARTO_KNITR_RSCRIPT_ARGS="--no-init-file,--max-connections=258" + ``` + +* * `QUARTO_TEXLIVE_BINPATH` + * Explicit path to the TeX Live binaries to be passed to `tlmgr option sys_bin` used when setting `tlmgr` and related to `PATH` using `tlmgr add path` . By default, Quarto looks in known places. + +* * `QUARTO_CHROMIUM` + * Explicit path to binary to use for chrome headless. Quarto uses [Chrome Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/) to do screenshot of HTML diagrams for PDF insertion. The binary must be compatible with this protocol. (e.g. Chrome, Chromium, Chrome Headless Shell, Edge, …) + +* * `QUARTO_CHROMIUM_HEADLESS_MODE` + * Used for adaption of the `--headless` mode used with `QUARTO_CHROMIUM` binary. Set to `"none"` for `--headless` , or to `"old"` or `"new"` to pass as argument, e.g. `--headless=` . Quarto 1.6 sets `"old"` as default, which works from Chrome 112 to 131. Starting Quarto 1.7.13, `"none"` is the default as [Chrome 132 removed old headless mode](https://developer.chrome.com/blog/removing-headless-old-from-chrome). + +* * `QUARTO_LOG` + + `QUARTO_LOG_LEVEL` + + `QUARTO_LOG_FORMAT` + + * Those variables controls the logging behavior: + + * `QUARTO_LOG` is the same as using `--log` at command line. It is used to set the path to the log file + + * `QUARTO_LOG_LEVEL` is the same as using `--log-level` at command line. It is used to set the max level that will be log. Possible values are `DEBUG`, `INFO`(default), `WARNING`, and `ERROR`. + + * `QUARTO_LOG_FORMAT` is the same as using `--log-format` at command line. It is used to set the format for the log. Possible values are `plain` (default) and `json-stream`. + +::: ## Variables Quarto sets @@ -72,22 +90,27 @@ ENV["QUARTO_DOCUMENT_PATH"] ``` ::: -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| Variable | Description | -+============================================+=================================================================================================================================================================================================+ -| `QUARTO_PROJECT_ROOT` | Root of the project, or the directory of the file if not in project mode | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_DOCUMENT_PATH` | Directory of the document being rendered | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_DOCUMENT_FILE` | Name of the file being rendered | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_PROFILE` | Profile used, e.g `QUARTO_PROFILE=advanced,production` for `quarto render --profile advanced,production` | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` | Values for `fig-width` and `fig-height` as set in the document metadata | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_RUN_NO_NETWORK` | When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `QUARTO_EXECUTE_INFO` | `QUARTO_EXECUTE_INFO` holds the path of a file containing a JSON object with [execution information for Quarto engines](./quarto-execute-info.qmd). This is accessible by code in executable code cells. | -+--------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -For more information on the JSON object referenced by `QUARTO_EXECUTE_INFO`, see [Quarto engine execution information](./quarto-execute-info.qmd). \ No newline at end of file +::: {.list-table header-rows="1" widths="0.2,0.8"} + +* * Variable + * Description + +* * `QUARTO_PROJECT_ROOT` + * Root of the project, or the directory of the file if not in project mode + +* * `QUARTO_DOCUMENT_PATH` + * Directory of the document being rendered + +* * `QUARTO_DOCUMENT_FILE` + * Name of the file being rendered + +* * `QUARTO_PROFILE` + * Profile used, e.g `QUARTO_PROFILE=advanced,production` for `quarto render --profile advanced,production` + +* * `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` + * Values for `fig-width` and `fig-height` as set in the document metadata + +* * `QUARTO_RUN_NO_NETWORK` + * When `true`, Quarto project scripts written in TypeScript won't be allowed to use the network to download sources. In this setting, those scripts will not have access to the standard library. + +::: diff --git a/docs/authoring/article-layout.qmd b/docs/authoring/article-layout.qmd index 488a2b58f8..0dcbc0322f 100644 --- a/docs/authoring/article-layout.qmd +++ b/docs/authoring/article-layout.qmd @@ -345,24 +345,32 @@ reference-location: margin All of the below options currently only support setting a value of `margin` which tells Quarto to place the corresponding element in the margin. -+----------------------+---------------------------------------------------------------------------------------------------------+ -| Option | Description | -+======================+=========================================================================================================+ -| `reference-location` | Where to place footnotes. Defaults to `document`.\ | -| | \[`document` \| `section` \| `block` \| `margin` \] | -+----------------------+---------------------------------------------------------------------------------------------------------+ -| `citation-location` | Where to place citations. Defaults to `document`.\ | -| | \[`document` \| `margin` \] | -+----------------------+---------------------------------------------------------------------------------------------------------+ -| `cap-location` | Where to place figure and table captions. Defaults to `bottom` for figures and `top` for tables.\ | -| | \[`top` \| `bottom` \| `margin`\] | -+----------------------+---------------------------------------------------------------------------------------------------------+ -| `fig-cap-location` | Where to place figure captions. Defaults to `bottom`.\ | -| | \[`top` \| `bottom` \| `margin`\] | -+----------------------+---------------------------------------------------------------------------------------------------------+ -| `tbl-cap-location` | Where to place table captions. Defaults to `top`.\ | -| | \[`top` \| `bottom` \| `margin`\] | -+----------------------+---------------------------------------------------------------------------------------------------------+ +::: {.list-table header-rows="1" widths="0.17829457364341,0.82170542635659"} + +* * Option + * Description + +* * `reference-location` + * Where to place footnotes. Defaults to `document`.\ + [`document` | `section` | `block` | `margin` ] + +* * `citation-location` + * Where to place citations. Defaults to `document`.\ + [`document` | `margin` ] + +* * `cap-location` + * Where to place figure and table captions. Defaults to `bottom` for figures and `top` for tables.\ + [`top` | `bottom` | `margin`] + +* * `fig-cap-location` + * Where to place figure captions. Defaults to `bottom`.\ + [`top` | `bottom` | `margin`] + +* * `tbl-cap-location` + * Where to place table captions. Defaults to `top`.\ + [`top` | `bottom` | `margin`] + +::: ### Code Cell Options @@ -375,24 +383,33 @@ plot(cars) ``` ::: column-page-right -+--------------------+------------------------------------------------------------------------------------------------------------------------------+ -| Option | Description | -+====================+==============================================================================================================================+ -| `column` | Layout column to use for code cell outputs. See column options below. | -+--------------------+------------------------------------------------------------------------------------------------------------------------------+ -| `fig-column` | Layout column to use for code cell figure outputs. See column options below. | -+--------------------+------------------------------------------------------------------------------------------------------------------------------+ -| `tbl-column` | Layout column to use for code cell table outputs. See column options below. | -+--------------------+------------------------------------------------------------------------------------------------------------------------------+ -| `cap-location` | Where to place figure and table captions produced by this code cell. Defaults to `bottom` for figures and `top` for tables.\ | -| | \[`top` \| `bottom` \| `margin`\] | -+--------------------+------------------------------------------------------------------------------------------------------------------------------+ -| `fig-cap-location` | Where to place captions for figures produced by this code cell. Defaults to `inline`.\ | -| | \[`inline` \| `margin`\] | -+--------------------+------------------------------------------------------------------------------------------------------------------------------+ -| `tbl-cap-location` | Where to place captions for tables produced by this code cell. Defaults to `inline`.\ | -| | \[`inline` \| `margin`\] | -+--------------------+------------------------------------------------------------------------------------------------------------------------------+ +::: {.list-table header-rows="1" widths="0.14189189189189,0.85810810810811"} + +* * Option + * Description + +* * `column` + * Layout column to use for code cell outputs. See column options below. + +* * `fig-column` + * Layout column to use for code cell figure outputs. See column options below. + +* * `tbl-column` + * Layout column to use for code cell table outputs. See column options below. + +* * `cap-location` + * Where to place figure and table captions produced by this code cell. Defaults to `bottom` for figures and `top` for tables.\ + [`top` | `bottom` | `margin`] + +* * `fig-cap-location` + * Where to place captions for figures produced by this code cell. Defaults to `inline`.\ + [`inline` | `margin`] + +* * `tbl-cap-location` + * Where to place captions for tables produced by this code cell. Defaults to `inline`.\ + [`inline` | `margin`] + +::: ::: ### Using Classes @@ -410,33 +427,109 @@ This content will appear in the margin! Here are all of the available column specifiers: ::: column-page-right -+--------------+---------------------------------+---------------------------------+ -| Column | Code Cell `column` | Class Name | -+==============+=================================+=================================+ -| Body | column: body | .column-body | -| | column: body-outset | .column-body-outset | -| | column: body-outset-left | .column-body-outset-left | -| | column: body-outset-right | .column-body-outset-right | -+--------------+---------------------------------+---------------------------------+ -| Page Inset | column: page-inset | .column-page-inset | -| | column: page-inset-left | .column-page-inset-left | -| | column: page-inset-right | .column-page-inset-right | -+--------------+---------------------------------+---------------------------------+ -| Page | column: page | .column-page | -| | column: page-left | .column-page-left | -| | column: page-right | .column-page-right | -+--------------+---------------------------------+---------------------------------+ -| Screen Inset | column: screen-inset | .column-screen-inset | -| | column: screen-inset-shaded | .column-screen-inset-shaded | -| | column: screen-inset-left | .column-screen-inset-left | -| | column: screen-inset-right | .column-screen-inset-right | -+--------------+---------------------------------+---------------------------------+ -| Screen | column: screen | .column-screen | -| | column: screen-left | .column-screen-left | -| | column: screen-right | .column-screen-right | -+--------------+---------------------------------+---------------------------------+ -| Margin | column: margin | .column-margin | -+--------------+---------------------------------+---------------------------------+ +::: {.list-table header-rows="1" widths="0.2,0.4,0.4"} + +* * Column + * Code Cell `column` + * Class Name + +* * Body + + * + ``` + column: body + column: body-outset + column: body-outset-left + column: body-outset-right + ``` + + * + ``` + .column-body + .column-body-outset + .column-body-outset-left + .column-body-outset-right + ``` + +* * Page Inset + + * + ``` + column: page-inset + column: page-inset-left + column: page-inset-right + ``` + + * + ``` + .column-page-inset + .column-page-inset-left + .column-page-inset-right + ``` + +* * Page + + * + ``` + column: page + column: page-left + column: page-right + ``` + + * + ``` + .column-page + .column-page-left + .column-page-right + ``` + +* * Screen Inset + + * + ``` + column: screen-inset + column: screen-inset-shaded + column: screen-inset-left + column: screen-inset-right + ``` + + * + ``` + .column-screen-inset + .column-screen-inset-shaded + .column-screen-inset-left + .column-screen-inset-right + ``` + +* * Screen + + * + ``` + column: screen + column: screen-left + column: screen-right + ``` + + * + ``` + .column-screen + .column-screen-left + .column-screen-right + ``` + +* * Margin + + * + ``` + column: margin + ``` + + * + ``` + .column-margin + ``` + +::: ::: ## PDF/LaTeX Layout {data-link="PDF/LaTeX Layout"} diff --git a/docs/authoring/brand.qmd b/docs/authoring/brand.qmd index e0d2a9f147..30795c1508 100644 --- a/docs/authoring/brand.qmd +++ b/docs/authoring/brand.qmd @@ -253,31 +253,45 @@ For HTML formats that use Bootstrap (`html`, `dashboard`) the remaining semantic The full list of semantic colors you can set in `color` is: -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| Name | Description | -+=======================+===============================================================================================================================+ -| `foreground` | The main text color. Typically will be close to black and must have high contrast with the background color. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `background` | The main background color. Tyically will be close to white and must have high contrast with the foreground color. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `primary` | The primary accent color, used for hyperlinks, active states, and primary action buttons. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `secondary` | The secondary accent color, often used for lighter text or disabled states. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `tertiary` | The tertiary accent color, used for hover states, accents, and wells. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `success` | The color used for positive or successful actions and information. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `info` | The color used for neutral or informational actions and information. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `warning` | The color used for warning or cautionary actions and information. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `danger` | The color used for errors, dangerous actions, or negative information. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `light` | A bright color, used as a high-contrast foreground color on dark elements or low-contrast background color on light elements. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ -| `dark` | A dark color, used as a high-contrast foreground color on light elements or high-contrast background color on light elements. | -+-----------------------+-------------------------------------------------------------------------------------------------------------------------------+ +::: {.list-table widths="0.15789473684211,0.84210526315789" header-rows="1"} + +* * Name + * Description + +* * `foreground` + * The main text color. Typically will be close to black and must have high contrast with the background color. + +* * `background` + * The main background color. Tyically will be close to white and must have high contrast with the foreground color. + +* * `primary` + * The primary accent color, used for hyperlinks, active states, and primary action buttons. + +* * `secondary` + * The secondary accent color, often used for lighter text or disabled states. + +* * `tertiary` + * The tertiary accent color, used for hover states, accents, and wells. + +* * `success` + * The color used for positive or successful actions and information. + +* * `info` + * The color used for neutral or informational actions and information. + +* * `warning` + * The color used for warning or cautionary actions and information. + +* * `danger` + * The color used for errors, dangerous actions, or negative information. + +* * `light` + * A bright color, used as a high-contrast foreground color on dark elements or low-contrast background color on light elements. + +* * `dark` + * A dark color, used as a high-contrast foreground color on light elements or high-contrast background color on light elements. + +::: ::: @@ -307,19 +321,33 @@ logo: You don't need to specify all three---Quarto will use what you provide based on the following preferences: -+---------------------------+----------------------------------------------+-------------------------------+ -| Format | Location | Logo Preference (high to low) | -+===========================+==============================================+===============================+ -| `html`/`dashboard` | Top navigation bar | `small`\> `medium`\>`large` | -+---------------------------+----------------------------------------------+-------------------------------+ -| `html` | Side navigation | `medium`\>`small`\>`large` | -+---------------------------+----------------------------------------------+-------------------------------+ -| `typst` | Top left, control with `format: typst: logo` | `medium`\>`small`\>`large` | -+---------------------------+----------------------------------------------+-------------------------------+ -| `revealjs` | Bottom right corner of slides | `medium`\>`small`\>`large` | -+---------------------------+----------------------------------------------+-------------------------------+ -| `website`/`book` project | `favicon` shown in browser tab | `small` | -+---------------------------+----------------------------------------------+-------------------------------+ +::: {.list-table header-rows="1" widths="0.25925925925926,0.43518518518519,0.2962962962963"} + +* * Format + * Location + * Logo Preference (high to low) + +* * `html`/`dashboard` + * Top navigation bar + * `small`\> `medium`\>`large` + +* * `html` + * Side navigation + * `medium`\>`small`\>`large` + +* * `typst` + * Top left, control with `format: typst: logo` + * `medium`\>`small`\>`large` + +* * `revealjs` + * Bottom right corner of slides + * `medium`\>`small`\>`large` + +* * `website`/`book` project + * `favicon` shown in browser tab + * `small` + +::: You can also specify named logos under `images` which you can reference in `small`, `medium` and `large`. In particular, this allows you to set alternative text for your logos using `alt`: @@ -446,42 +474,70 @@ The fields allowed for each element differ, expand the callout below to see what The full set of text elements that you can style with `typography` is: -+--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ -| Attribute | Description | Supported Fields | -+====================+========================================================================================================+========================+ -| `base` | Default text, primarily used in the document body. | - `family` | -| | | - `size` | -| | | - `line-height` | -| | | - `weight` | -+--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ -| `headings` | All heading levels (h1, h2, etc.). | - `family` | -| | | - `weight` | -| | | - `style` | -| | | - `line-height` | -| | | - `color` | -+--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ -| `monospace` | General monospaced text, typically used in code blocks and other programming-related content. | - `family` | -| | | - `size` | -| | | - `weight` | -+--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ -| `monospace-inline` | Inline monospaced text, usually used for code snippets within regular text. Inherits from `monospace`. | - `family` | -| | | - `size` | -| | | - `weight` | -| | | - `color` | -| | | - `background-color` | -+--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ -| `monospace-block` | Block (multi-line) monospaced text, typically used for code blocks. Inherits from `monospace`. | - `family` | -| | | - `size` | -| | | - `weight` | -| | | - `line-height` | -| | | - `color` | -| | | - `background-color` | -+--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ -| `link` | Hyperlinks. | - `weight` | -| | | - `color` | -| | | - `background-color` | -| | | - `decoration` | -+--------------------+--------------------------------------------------------------------------------------------------------+------------------------+ +::: {.list-table header-rows="1" widths="0.13815789473684,0.69078947368421,0.16447368421053"} + +* * Attribute + * Description + * Supported Fields + +* * `base` + + * Default text, primarily used in the document body. + + * * `family` + * `size` + * `line-height` + * `weight` + +* * `headings` + + * All heading levels (h1, h2, etc.). + + * * `family` + * `weight` + * `style` + * `line-height` + * `color` + +* * `monospace` + + * General monospaced text, typically used in code blocks and other programming-related content. + + * * `family` + * `size` + * `weight` + +* * `monospace-inline` + + * Inline monospaced text, usually used for code snippets within regular text. Inherits from `monospace`. + + * * `family` + * `size` + * `weight` + * `color` + * `background-color` + +* * `monospace-block` + + * Block (multi-line) monospaced text, typically used for code blocks. Inherits from `monospace`. + + * * `family` + * `size` + * `weight` + * `line-height` + * `color` + * `background-color` + +* * `link` + + * Hyperlinks. + + * * `weight` + * `color` + * `background-color` + * `decoration` + +::: The supported fields are generally described as follows: diff --git a/docs/authoring/citations.qmd b/docs/authoring/citations.qmd index 826efe23f0..8ecc8d37b6 100644 --- a/docs/authoring/citations.qmd +++ b/docs/authoring/citations.qmd @@ -43,29 +43,85 @@ See the [Pandoc Citations](https://pandoc.org/MANUAL.html#citations) documentati Quarto uses the standard Pandoc markdown representation for citations (e.g. `[@citation]`) --- citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of '\@' + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. The citation key must begin with a letter, digit, or `_`, and may contain alphanumerics, `_`, and internal punctuation characters (`:.#$%&-+?<>~/`). Here are some examples: -+-------------------------------------------+---------------------------------------------------------------------+---------------------------------------------------------------------+ -| Markdown Format | Output (default) | Output(`csl: diabetologia.csl`, see @sec-citations-style) | -+===========================================+=====================================================================+=====================================================================+ -| Blah Blah [see @knuth1984, pp. 33-35; | Blah Blah [see @knuth1984, pp. 33-35; also @wickham2015, chap. 1] | Blah Blah see [1], pp. 33-35; also [1], chap. 1 | -| also @wickham2015, chap. 1] | | | -+-------------------------------------------+---------------------------------------------------------------------+---------------------------------------------------------------------+ -| Blah Blah [@knuth1984, pp. 33-35, | Blah Blah [@knuth1984, pp. 33-35, 38-39 and passim] | Blah Blah [1], pp. 33-35, 38-39 and passim | -| 38-39 and passim] | | | -+-------------------------------------------+---------------------------------------------------------------------+---------------------------------------------------------------------+ -| Blah Blah [@wickham2015; @knuth1984]. | Blah Blah [@wickham2015; @knuth1984]. | Blah Blah [1, 2]. | -+-------------------------------------------+---------------------------------------------------------------------+---------------------------------------------------------------------+ -| Wickham says blah [-@wickham2015] | Wickham says blah [-@wickham2015] | Wickham says blah [1] | -+-------------------------------------------+---------------------------------------------------------------------+---------------------------------------------------------------------+ +::: {.list-table header-rows="1" widths="0.23783783783784,0.37837837837838,0.37837837837838"} + +* * Markdown Format + * Output (default) + * Output(`csl: diabetologia.csl`, see @sec-citations-style) + +* + * + ``` + Blah Blah [see @knuth1984, pp. 33-35; + also @wickham2015, chap. 1] + ``` + + * Blah Blah [see @knuth1984, pp. 33-35; also @wickham2015, chap. 1] + + * Blah Blah see [1], pp. 33-35; also [1], chap. 1 + +* + * + ``` + Blah Blah [@knuth1984, pp. 33-35, + 38-39 and passim] + ``` + + * Blah Blah [@knuth1984, pp. 33-35, 38-39 and passim] + + * Blah Blah [1], pp. 33-35, 38-39 and passim + +* + * + ``` + Blah Blah [@wickham2015; @knuth1984]. + ``` + + * Blah Blah [@wickham2015; @knuth1984]. + + * Blah Blah [1, 2]. + +* + * + ``` + Wickham says blah [-@wickham2015] + ``` + + * Wickham says blah [-@wickham2015] + + * Wickham says blah [1] + +::: You can also write in-text citations, as follows: -+-----------------------------------+-------------------------------+-------------------------------+ -| Markdown Format | Output (author-date format) | Output (numerical format) | -+===================================+===============================+===============================+ -| @knuth1984 says blah. | @knuth1984 says blah. | [1] says blah. | -+-----------------------------------+-------------------------------+-------------------------------+ -| @knuth1984 [p. 33] says blah. | @knuth1984 [p. 33] says blah. | [1] [p. 33] says blah. | -+-----------------------------------+-------------------------------+-------------------------------+ +::: {.list-table widths="0.35643564356436,0.31683168316832,0.31683168316832" header-rows="1"} + +* * Markdown Format + * Output (author-date format) + * Output (numerical format) + +* + * + ``` + @knuth1984 says blah. + ``` + + * @knuth1984 says blah. + + * [1] says blah. + +* + * + ``` + @knuth1984 [p. 33] says blah. + ``` + + * @knuth1984 [p. 33] says blah. + + * [1] [p. 33] says blah. + +::: See the [Pandoc Citations](https://pandoc.org/MANUAL.html#citations) documentation for additional information on citation syntax. diff --git a/docs/authoring/create-citeable-articles.qmd b/docs/authoring/create-citeable-articles.qmd index 564a32f147..4110e9d24b 100644 --- a/docs/authoring/create-citeable-articles.qmd +++ b/docs/authoring/create-citeable-articles.qmd @@ -48,15 +48,18 @@ When this metadata is available, a citation appendix is automatically added to t By default both the `bibtex` and formatted representations are displayed. You can use the `appendix-cite-as` option to control this behavior: -+-----------------------------+------------------------------------------------+ -| `appendix-cite-as: false` | Do not include any citations in the appendix. | -+-----------------------------+------------------------------------------------+ -| `appendix-cite-as: bibtex` | Show only the BibTeX version of the citation. | -+-----------------------------+------------------------------------------------+ -| `appendix-cite-as: display` | Show only the display version of the citation. | -+-----------------------------+------------------------------------------------+ +::: {.list-table widths="0.5,0.5" header-rows=0} -: {tbl-colwidths="\[50,50\]"} +* * `appendix-cite-as: false` + * Do not include any citations in the appendix. + +* * `appendix-cite-as: bibtex` + * Show only the BibTeX version of the citation. + +* * `appendix-cite-as: display` + * Show only the display version of the citation. + +::: ## Journal Articles @@ -133,106 +136,143 @@ In the addition to the citation metadata from this document described above, Qua Quarto's approach to emitting scholarly metadata is to take the standard CSL fields and make them into the corresponding Google Scholar / Zotero / Highwire metadata tags as appropriate. The following fields, when specified under the `citation` key of the document metadata, will generate scholarly meta tags in the rendered HTML document as described. These fields comprise the required Google Scholar fields as well as additional, optional fields that may also be included. -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| Document Yaml | Metadata Tag | -+===============================================================================================================================================+=========================================================================================+ -| `title`\ | `citation_title` | -| Document `title` will be used if not provided. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `author`\ | `citation_author` | -| One or more authors[^1]. Document `author` will be used if not provided as a citation subkey. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `editor`\ | `citation_editor` | -| One or more editors[^2]. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `abstract`\ | `citation_abstract` | -| Document `abstract` will be used if not provided. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `keyword`[^3]\ | `citation_keywords` | -| Document `keywords` will be used if not provided. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `issued`\ | `citation_publication_date` | -| Document `date` will be used if not provided. | | -| | In addition, the issued date will be used to populate the following fields:\ | -| | \ | -| | `citation_cover_date`\ | -| | `citation_year` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `available-date`\ | `citation_online_date` | -| Document `date` will be used if not provided. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `url`\ | `citation_fulltext_html_url` | -| `url` will be synthesized for current document if a [`site-url`](/docs/websites/website-tools.qmd#preview-images) has been specified. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `pdf-url` | `citation_pdf_url` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `language`\ | `citation_language` | -| Document `lang` will be used if not provided. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `type`\ | `` | -| A valid CSL type. See . | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `doi`\ | `citation_doi` | -| Document `doi` will be used if not provided. | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `isbn` | `citation_isbn` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `issn` | `citation_issn` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `eissn` | `citation_eissn` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `pmid` | `citation_pmid` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `issue` | `citation_issue` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `volume` | `citation_volume` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `page`\ | `citation_firstpage` | -| Will be split on `-` to create appropriate page metadata. | | -| | `citation_lastpage` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `page-first` | `citation_firstpage` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `page-last` | `citation_lastpage` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `abstract-url` | `citation_abstract_html_url` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `container-title` | `citation_journal_title` | -| | | -| | For specific types, other meta tags will be produced: | -| | | -| | - type: paper-conference\ | -| | `citation_conference_title` | -| | | -| | - type: book\ | -| | `citation_book_title` | -| | | -| | - type: chapter\ | -| | `citation_inbook_title` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `number` | `citation_technical_report_number` | -| | | -| | `citation_technical_report_number` will be created if the type is report. | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `publisher` | `citation_publisher` | -| | | -| | For specific types, other meta tags will be produced: | -| | | -| | - type: paper-conference\ | -| | `citation_conference` | -| | | -| | - type: thesis\ | -| | `citation_dissertation_institution` | -| | | -| | - type:report\ | -| | `citation_technical_report_institution` | -| | | -| | | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `container-title-short` | `citation_journal_abbrev` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| `collection-title` | `citation_series_title` | -+-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +::: {.list-table widths="0.6,0.4" header-rows="1"} + +* * Document Yaml + * Metadata Tag + +* * `title`\ + ``{=html}Document `title` will be used if not provided.``{=html} + * `citation_title` + +* * `author`\ + ``{=html}One or more authors[^1]. Document `author` will be used if not provided as a citation subkey.``{=html} + * `citation_author` + +* * `editor`\ + ``{=html}One or more editors[^2].``{=html} + * `citation_editor` + +* * `abstract`\ + ``{=html}Document `abstract` will be used if not provided.``{=html} + * `citation_abstract` + +* * `keyword`[^3]\ + ``{=html}Document `keywords` will be used if not provided.``{=html} + * `citation_keywords` + +* * `issued`\ + ``{=html}Document `date` will be used if not provided.``{=html} + + * `citation_publication_date` + + ``{=html}In addition, the issued date will be used to populate the following fields:``{=html}\ + \ + `citation_cover_date`\ + `citation_year` + +* * `available-date`\ + ``{=html}Document `date` will be used if not provided.``{=html} + * `citation_online_date` + +* * `url`\ + ``{=html}`url` will be synthesized for current document if a [`site-url`](/docs/websites/website-tools.qmd#preview-images) has been specified.``{=html} + * `citation_fulltext_html_url` + +* * `pdf-url` + * `citation_pdf_url` + +* * `language`\ + ``{=html}Document `lang` will be used if not provided.``{=html} + * `citation_language` + +* * `type`\ + ``{=html}A valid CSL type. See [https://docs.citationstyles.org/en/stable/specification.html\#appendix-iii-types](https://docs.citationstyles.org/en/stable/specification.html#appendix-iii-types){.uri}``{=html}. + * `` + +* * `doi`\ + ``{=html}Document `doi` will be used if not provided.``{=html} + * `citation_doi` + +* * `isbn` + * `citation_isbn` + +* * `issn` + * `citation_issn` + +* * `eissn` + * `citation_eissn` + +* * `pmid` + * `citation_pmid` + +* * `issue` + * `citation_issue` + +* * `volume` + * `citation_volume` + +* * `page`\ + ``{=html}Will be split on `-` to create appropriate page metadata.``{=html} + + * `citation_firstpage` + + `citation_lastpage` + +* * `page-first` + * `citation_firstpage` + +* * `page-last` + * `citation_lastpage` + +* * `abstract-url` + * `citation_abstract_html_url` + +* * `container-title` + + * `citation_journal_title` + + ``{=html} For specific types, other meta tags will be produced: + + * type: paper-conference\ + `citation_conference_title` + + * type: book\ + `citation_book_title` + + * type: chapter\ + `citation_inbook_title` ``{=html} + +* * `number` + + * `citation_technical_report_number` + + ``{=html}`citation_technical_report_number` will be created if the type is report.``{=html} + +* * `publisher` + + * `citation_publisher` + + ``{=html}For specific types, other meta tags will be produced: + + * type: paper-conference\ + `citation_conference` + + * type: thesis\ + `citation_dissertation_institution` + + * type:report\ + `citation_technical_report_institution` + + ``{=html} + +* * `container-title-short` + * `citation_journal_abbrev` + +* * `collection-title` + * `citation_series_title` + +::: [^1]: Specify one or more authors using one of the following: diff --git a/docs/authoring/front-matter.qmd b/docs/authoring/front-matter.qmd index 872901b5c7..d2f50fa8ba 100644 --- a/docs/authoring/front-matter.qmd +++ b/docs/authoring/front-matter.qmd @@ -103,30 +103,49 @@ Both of these keys can be specified using a singular (`author` and `affiliation` Beyond `name` and `affiliation`, `author` can also take any of the following: -+----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `email`\ | string | Contact details for the author. Converted to hyperlinks in many formats. | -| `phone`\ | | | -| `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;\ | -| `acknowledgements` | | Author's acknowledgements. | -+----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `roles` | string(s) | Author's roles. Read more in [Author Roles](#roles) below. | -+----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `corresponding`\ | `true`/`false` | Set this author as:\ | -| `equal-contributor`\ | | the corresponding author;\ | -| `deceased` | | as having contributed equally with all other contributors;\ | -| | | and/or deceased. | -+----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `id` | string | An identifier to be used to refer to this author in other fields. See an example in [Funding]. | -+----------------------+----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -: Available keys to `author` +::: {.list-table widths="0.11111111111111,0.082125603864734,0.80193236714976" header-rows="0"} + +Available keys to `author` + +* * `email`\ + `phone`\ + `fax`\ + `url` + * string + * Contact details for the author. Converted to hyperlinks in many formats. + +* * `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`\ + `acknowledgements` + * string + * Notes to attach to an author, such as contribution details;\ + Author's acknowledgements. + +* * `roles` + * string(s) + * Author's roles. Read more in [Author Roles](#roles) below. + +* * `corresponding`\ + `equal-contributor`\ + `deceased` + * `true`/`false` + * Set this author as:\ + the corresponding author;\ + as having contributed equally with all other contributors;\ + and/or deceased. + +* * `id` + * string + * An identifier to be used to refer to this author in other fields. See an example in [Funding]. + +::: An `affiliations-url` key can also be provided to `author`, and will be propagated to the `url` key of `affiliation`. @@ -212,39 +231,56 @@ author: ::: {#credit-roles .callout-tip collapse="true"} ## Expand to see the 14 Contributor Roles -+-------------------------------------------------------------------------------------------------+-------------+ -| Value | Alias | -+=================================================================================================+=============+ -| [conceptualization](https://credit.niso.org/contributor-roles/conceptualization/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [data curation](https://credit.niso.org/contributor-roles/data-curation/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [formal analysis](https://credit.niso.org/contributor-roles/formal-analysis/) | analysis | -+-------------------------------------------------------------------------------------------------+-------------+ -| [funding acquisition](https://credit.niso.org/contributor-roles/funding-acquisition/) | funding | -+-------------------------------------------------------------------------------------------------+-------------+ -| [investigation](https://credit.niso.org/contributor-roles/investigation/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [methodology](https://credit.niso.org/contributor-roles/methodology/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [project administration](https://credit.niso.org/contributor-roles/project-administration/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [resources](https://credit.niso.org/contributor-roles/resources/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [software](https://credit.niso.org/contributor-roles/software/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [supervision](https://credit.niso.org/contributor-roles/supervision/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [validation](https://credit.niso.org/contributor-roles/validation/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [visualization](https://credit.niso.org/contributor-roles/visualization/) | | -+-------------------------------------------------------------------------------------------------+-------------+ -| [writing – review & editing](https://credit.niso.org/contributor-roles/writing-review-editing/) | editing | -+-------------------------------------------------------------------------------------------------+-------------+ -| [writing – original draft](https://credit.niso.org/contributor-roles/writing-original-draft/) | writing | -+-------------------------------------------------------------------------------------------------+-------------+ - -: CRediT contributor values available in `roles` +::: {.list-table widths="0.875,0.125" header-rows="1"} + +CRediT contributor values available in `roles` + +* * Value + * Alias + +* * [conceptualization](https://credit.niso.org/contributor-roles/conceptualization/) + * + +* * [data curation](https://credit.niso.org/contributor-roles/data-curation/) + * + +* * [formal analysis](https://credit.niso.org/contributor-roles/formal-analysis/) + * analysis + +* * [funding acquisition](https://credit.niso.org/contributor-roles/funding-acquisition/) + * funding + +* * [investigation](https://credit.niso.org/contributor-roles/investigation/) + * + +* * [methodology](https://credit.niso.org/contributor-roles/methodology/) + * + +* * [project administration](https://credit.niso.org/contributor-roles/project-administration/) + * + +* * [resources](https://credit.niso.org/contributor-roles/resources/) + * + +* * [software](https://credit.niso.org/contributor-roles/software/) + * + +* * [supervision](https://credit.niso.org/contributor-roles/supervision/) + * + +* * [validation](https://credit.niso.org/contributor-roles/validation/) + * + +* * [visualization](https://credit.niso.org/contributor-roles/visualization/) + * + +* * [writing – review & editing](https://credit.niso.org/contributor-roles/writing-review-editing/) + * editing + +* * [writing – original draft](https://credit.niso.org/contributor-roles/writing-original-draft/) + * writing + +::: ::: ### Affiliation {#affiliation} @@ -272,26 +308,46 @@ author: 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`\ | | | -| `country`\ | | | -| `postal-code` | | | -+----------------------+-----------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| `url` | String | Affiliation's website. Converted to a link in many formats. | -+----------------------+-----------+-----------------------------------------------------------------------------------------------------------------------------------------------+ -| \ | \ | Affiliation IDs:\ | -| `isni`\ | Numeric\ | 16 digit [International Standard Name Identifier (ISNI)](https://isni.org/);\ | -| `ringgold`\ | Numeric\ | 4-6 digit [Ringgold ID](https://www.ringgold.com/ringgold-identifier/);\ | -| `ror` | String | [Research Organization Registry (ROR) ID](https://ror.org/), starting with `https://ror.org/`, followed by a 9 digit alphanumeric identifier. | -+----------------------+-----------+-----------------------------------------------------------------------------------------------------------------------------------------------+ - -: Available keys to `affiliation` +::: {.list-table widths="0.12777777777778,0.066666666666667,0.8" header-rows="0"} + +Available keys to `affiliation` + +* * `department` + + * String + + * + +* * `group` + * String + * Team or research group within the affiliation + +* * `address`\ + `city`\ + `region` or `state`\ + `country`\ + `postal-code` + * String + * Affiliation's location. Provide one of `region` or `state`, and any combination of the other keys. + +* * `url` + * String + * Affiliation's website. Converted to a link in many formats. + +* * \ + `isni`\ + `ringgold`\ + `ror` + * \ + Numeric\ + Numeric\ + String + * Affiliation IDs:\ + 16 digit [International Standard Name Identifier (ISNI)](https://isni.org/);\ + 4-6 digit [Ringgold ID](https://www.ringgold.com/ringgold-identifier/);\ + [Research Organization Registry (ROR) ID](https://ror.org/), starting with `https://ror.org/`, followed by a 9 digit alphanumeric identifier. + +::: For example, a more complete `affiliation` for an author might look like: @@ -483,23 +539,43 @@ The Creative Commons copyright licenses and tools forge a balance inside the tra Here are some of the common forms of Creative Commons content license: -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| License | Name | Description | -+===============+======================================+=======================================================================================================================================================================================================================================================================================================================================================================================+ -| `CC BY` | Attribution | This license lets others distribute, remix, tweak, and build upon your work, even commercially, as long as they credit you for the original creation. This is the most accommodating of licenses offered. | -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `CC BY-SA` | Attribution-ShareAlike | This license lets others remix, tweak, and build upon your work even for commercial purposes, as long as they credit you and license their new creations under the identical terms. This license is often compared to "copyleft" free and open source software licenses. All new works based on yours will carry the same license, so any derivatives will also allow commercial use. | -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `CC BY-ND` | Attribution-NoDerivs | This license allows for redistribution, commercial and non-commercial, as long as it is passed along unchanged and in whole, with credit to you. | -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `CC BY-NC` | Attribution-NonCommercial | This license lets others remix, tweak, and build upon your work non-commercially, and although their new works must also acknowledge you and be non-commercial, they don't have to license their derivative works on the same terms. | -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `CC BY-NC-SA` | Attribution-NonCommercial-ShareAlike | This license lets others remix, adapt, and build upon your work non-commercially, as long as they credit you and license their new creations under the identical terms. \| | -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `CC BY-NC-ND` | Attribution-NonCommercial-NoDerivs | This license is the most restrictive of the six main licenses, only allowing others to download your works and share them with others as long as they credit you, but they can't change them in any way or use them commercially. | -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| `CC0` | | CC0 (aka CC Zero) is a public dedication tool, which enables creators to give up their copyright and put their works into the worldwide public domain. CC0 enables reusers to distribute, remix, adapt, and build upon the material in any medium or format, with no conditions. | -+---------------+--------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: {.list-table widths="0.037037037037037,0.090277777777778,0.87037037037037" header-rows="1"} + +* * License + * Name + * Description + +* * `CC BY` + * Attribution + * This license lets others distribute, remix, tweak, and build upon your work, even commercially, as long as they credit you for the original creation. This is the most accommodating of licenses offered. + +* * `CC BY-SA` + * Attribution-ShareAlike + * This license lets others remix, tweak, and build upon your work even for commercial purposes, as long as they credit you and license their new creations under the identical terms. This license is often compared to "copyleft" free and open source software licenses. All new works based on yours will carry the same license, so any derivatives will also allow commercial use. + +* * `CC BY-ND` + * Attribution-NoDerivs + * This license allows for redistribution, commercial and non-commercial, as long as it is passed along unchanged and in whole, with credit to you. + +* * `CC BY-NC` + * Attribution-NonCommercial + * This license lets others remix, tweak, and build upon your work non-commercially, and although their new works must also acknowledge you and be non-commercial, they don't have to license their derivative works on the same terms. + +* * `CC BY-NC-SA` + * Attribution-NonCommercial-ShareAlike + * This license lets others remix, adapt, and build upon your work non-commercially, as long as they credit you and license their new creations under the identical terms. | + +* * `CC BY-NC-ND` + * Attribution-NonCommercial-NoDerivs + * This license is the most restrictive of the six main licenses, only allowing others to download your works and share them with others as long as they credit you, but they can't change them in any way or use them commercially. + +* * `CC0` + + * + + * CC0 (aka CC Zero) is a public dedication tool, which enables creators to give up their copyright and put their works into the worldwide public domain. CC0 enables reusers to distribute, remix, adapt, and build upon the material in any medium or format, with no conditions. + +::: If you specify a Creative Commons license for your content, Quarto will automatically include the relevant link to the appropriate license. diff --git a/docs/authoring/markdown-basics.qmd b/docs/authoring/markdown-basics.qmd index 6cf47ba337..75ce76c0ef 100644 --- a/docs/authoring/markdown-basics.qmd +++ b/docs/authoring/markdown-basics.qmd @@ -19,57 +19,101 @@ This document provides examples of the most commonly used markdown syntax. See t ## Text Formatting -+-----------------------------------------+-----------------------------------------+ -| Markdown Syntax | Output | -+=========================================+=========================================+ -| ``` markdown | *italics*, **bold**, ***bold italics*** | -| *italics*, **bold**, ***bold italics*** | | -| ``` | | -+-----------------------------------------+-----------------------------------------+ -| ``` markdown | superscript^2^ / subscript~2~ | -| superscript^2^ / subscript~2~ | | -| ``` | | -+-----------------------------------------+-----------------------------------------+ -| ``` markdown | ~~strikethrough~~ | -| ~~strikethrough~~ | | -| ``` | | -+-----------------------------------------+-----------------------------------------+ -| ``` markdown | `verbatim code` | -| `verbatim code` | | -| ``` | | -+-----------------------------------------+-----------------------------------------+ +::: {.list-table widths="0.5,0.5" header-rows="1"} + +* * Markdown Syntax + * Output + +* + * + ```markdown + *italics*, **bold**, ***bold italics*** + ``` + + * *italics*, **bold**, ***bold italics*** + +* + * + ```markdown + superscript^2^ / subscript~2~ + ``` + + * superscript^2^ / subscript~2~ + +* + * + ```markdown + ~~strikethrough~~ + ``` + + * ~~strikethrough~~ + +* + * + ```markdown + `verbatim code` + ``` + + * `verbatim code` + +::: ## Headings {#headings} -+------------------+-----------------------------------+ -| Markdown Syntax | Output | -+==================+===================================+ -| ``` markdown | # Heading 1 {.heading-output} | -| # Heading 1 | | -| ``` | | -+------------------+-----------------------------------+ -| ``` markdown | ## Heading 2 {.heading-output} | -| ## Heading 2 | | -| ``` | | -+------------------+-----------------------------------+ -| ``` markdown | ### Heading 3 {.heading-output} | -| ### Heading 3 | | -| ``` | | -+------------------+-----------------------------------+ -| ``` markdown | #### Heading 4 {.heading-output} | -| #### Heading 4 | | -| ``` | | -+------------------+-----------------------------------+ -| ``` markdown | ##### Heading 5 {.heading-output} | -| ##### Heading 5 | | -| ``` | | -+------------------+-----------------------------------+ -| ``` markdown | ###### Heading 6 {.heading-output}| -| ###### Heading 6 | | -| ``` | | -+------------------+-----------------------------------+ - -: {tbl-colwidths="[50, 50]"} +::: {.list-table widths="0.5,0.5" header-rows="1"} + +* * Markdown Syntax + * Output + +* + * + ```markdown + # Heading 1 + ``` + + * # Heading 1 {#heading-1 .heading-output} + +* + * + ```markdown + ## Heading 2 + ``` + + * ## Heading 2 {#heading-2 .heading-output} + +* + * + ```markdown + ### Heading 3 + ``` + + * ### Heading 3 {#heading-3 .heading-output} + +* + * + ```markdown + #### Heading 4 + ``` + + * #### Heading 4 {#heading-4 .heading-output} + +* + * + ```markdown + ##### Heading 5 + ``` + + * ##### Heading 5 {#heading-5 .heading-output} + +* + * + ```markdown + ###### Heading 6 + ``` + + * ###### Heading 6 {#heading-6 .heading-output} + +::: ```{=html}