diff --git a/_freeze/docs/authoring/article-layout/execute-results/html.json b/_freeze/docs/authoring/article-layout/execute-results/html.json index cc2aea1721..62a69b8809 100644 --- a/_freeze/docs/authoring/article-layout/execute-results/html.json +++ b/_freeze/docs/authoring/article-layout/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "86f5c16400d40392df16f960c641c4c4", + "hash": "ef7b9036c41ad43bdfa512437748c513", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"Article Layout\"\nformat: html\nreference-location: margin\ncitation-location: margin\naliases:\n - page-layout.html\n---\n\n\n\n\n\n## Overview\n\nQuarto supports a variety of page layout options that enable you to author content that:\n\n- Fills the main content region\n- Overflows the content region\n- Spans the entire page\n- Occupies the document margin\n- Uses landscape mode in paginated formats\n\nQuarto uses the concept of columns to describe page layout (e.g. the \"body\" column, the \"margin\" column, etc.). Below we'll describe how to arrange content into these columns. If you need to adjust the widths of the columns, see [Page Layout - Grid Customization](/docs/output-formats/page-layout.qmd#grid-customization).\n\nAll of the layout capabilities described in this document work for HTML output and many work for PDF and LaTeX output. For details about the PDF / LaTeX output, see [PDF/LaTeX Layout].\n\n## Body Column\n\nBy default, elements are position in the body of the document and are allowed to span the content of the document, like the below.\n\n::: {.layout-example .column-body}\n.column-body\n:::\n\nBut if you'd like, you can extend content slightly outside the bounds of the body by creating a div with the .`column-body-outset` class. For example:\n\n``` markdown\n:::{.column-body-outset}\nOutset content...\n:::\n```\n\n::: {.layout-example .column-body-outset}\n.column-body-outset\n:::\n\n## Page Column\n\nIf you need even more space for your content, you can use the `.column-page` class to make the content much wider, though stopping short of extending across the whole document.\n\n::: {.layout-example .column-page}\n.column-page\n:::\n\nFor example, to create a wider image, you could use:\n\n``` markdown\n:::{.column-page}\n![](images/elephant.jpg)\n:::\n```\n\n::: column-page\n![](images/elephant.jpg){fig-alt=\"Three walking elephants in silhouette against the backdrop of a sunset.\"}\n:::\n\nFor computational output, you can specify the page column in your code cell options. For example:\n\n\n\n\n\n::: {.cell .column-page}\n\n````{.cell-code}\n```{{r}}\n#| column: page\n\nknitr::kable(\n mtcars[1:6, 1:10]\n)\n```\n````\n\n::: {.cell-output-display}\n\n\n| | mpg| cyl| disp| hp| drat| wt| qsec| vs| am| gear|\n|:-----------------|----:|---:|----:|---:|----:|-----:|-----:|--:|--:|----:|\n|Mazda RX4 | 21.0| 6| 160| 110| 3.90| 2.620| 16.46| 0| 1| 4|\n|Mazda RX4 Wag | 21.0| 6| 160| 110| 3.90| 2.875| 17.02| 0| 1| 4|\n|Datsun 710 | 22.8| 4| 108| 93| 3.85| 2.320| 18.61| 1| 1| 4|\n|Hornet 4 Drive | 21.4| 6| 258| 110| 3.08| 3.215| 19.44| 1| 0| 3|\n|Hornet Sportabout | 18.7| 8| 360| 175| 3.15| 3.440| 17.02| 0| 0| 3|\n|Valiant | 18.1| 6| 225| 105| 2.76| 3.460| 20.22| 1| 0| 3|\n\n\n:::\n:::\n\n\n\n\n\nIn addition, you can use `.column-page-inset` to inset the element from the page slightly, like so:\n\n::: {.layout-example .column-page-inset}\n.column-page-inset\n:::\n\n## Screen Column\n\nYou can have content span the full width of the page with no margin (full bleed). For this, use the `.column-screen` class or specify `column: screen` on a code cell. For example:\n\n``` md\n::: {.column-screen}\n![A full screen image](/image.png)\n:::\n```\n\n::: {.layout-example .column-screen}\n.column-screen\n:::\n\nThe following code displays a Leaflet map across the whole page.\n\n\n\n\n\n::: {.cell .column-screen}\n\n````{.cell-code}\n```{{r}}\n#| column: screen\n\nlibrary(leaflet)\nleaflet() %>%\n addTiles() %>% # Add default OpenStreetMap map tiles\n addMarkers(lng=174.768, lat=-36.852, popup=\"The birthplace of R\")\n```\n````\n\n::: {.cell-output-display}\n\n```{=html}\n
\n\n```\n\n:::\n:::\n\n\n\n\n\n### Screen Inset\n\nIf you'd like a full width appearance, but would like to retain a margin, you can use inset or inset-shaded modifiers on the column. For example:\n\n``` md\n::: {.column-screen-inset}\n![A full screen image](/image.png)\n:::\n```\n\n::: {.layout-example .column-screen-inset}\n.column-screen-inset\n:::\n\nThe inset-shaded modifier results in a block spanning the full width but wrapped with a lightly shaded background. For example:\n\n\n\n\n\n::: {.cell .column-screen-inset-shaded}\n\n````{.cell-code}\n```{{r}}\n#| column: screen-inset-shaded\n\nlibrary(leaflet)\nleaflet() %>%\n addTiles() %>% # Add default OpenStreetMap map tiles\n addMarkers(lng=174.768, lat=-36.852, popup=\"The birthplace of R\")\n```\n````\n\n::: {.cell-output-display}\n\n```{=html}\n
\n\n```\n\n:::\n:::\n\n\n\n\n\nColumn layouts like `screen-inset-shaded` will work with advanced figure layout. For example, it is straightforward to create a multi column presentation of figures that spans the document:\n\n\n\n\n\n::: {.cell .column-screen-inset-shaded layout-nrow=\"1\"}\n\n````{.cell-code}\n```{{r}}\n#| column: screen-inset-shaded\n#| layout-nrow: 1\n\nplot(cars)\nplot(iris)\nplot(pressure)\n```\n````\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-4-1.png){width=672}\n:::\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-4-2.png){width=672}\n:::\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-4-3.png){width=672}\n:::\n:::\n\n\n\n\n\n## Margin Content\n\nYou can place content within the right margin of Quarto document. For example, here we use the `.column-margin` class to place an image in the margin:\n\n``` md\n::: {.column-margin}\n![A margin image](image.png)\n:::\n```\n\n::: {.layout-example .column-margin style=\"margin-top: 18px;\"}\n.column-margin\n:::\n\nThis also works for text content:\n\n``` md\n::: {.column-margin}\nWe know from *the first fundamental theorem of calculus* that for $x$ in $[a, b]$:\n\n$$\\frac{d}{dx}\\left( \\int_{a}^{x} f(u)\\,du\\right)=f(x).$$\n:::\n```\n\n::: column-margin\nWe know from *the first fundamental theorem of calculus* that for $x$ in $[a, b]$:\n\n$$\\frac{d}{dx}\\left( \\int_{a}^{x} f(u)\\,du\\right)=f(x).$$\n:::\n\n### Margin Figures\n\nFigures that you create using code cells can be placed in the margin by using the `column: margin` code cell option. If the code produces more than one figure, each of the figures will be placed in the margin.\n\n\n\n\n\n::: {.cell .column-margin}\n\n````{.cell-code}\n```{{r}}\n#| label: fig-mtcars\n#| fig-cap: \"MPG vs horsepower, colored by transmission.\"\n#| column: margin\n\nlibrary(ggplot2)\nmtcars2 <- mtcars\nmtcars2$am <- factor(\n mtcars$am, labels = c('automatic', 'manual')\n)\nggplot(mtcars2, aes(hp, mpg, color = am)) +\n geom_point() +\n geom_smooth(formula = y ~ x, method = \"loess\") +\n theme(legend.position = 'bottom')\n```\n````\n\n::: {.cell-output-display}\n![MPG vs horsepower, colored by transmission.](article-layout_files/figure-html/fig-mtcars-1.png){#fig-mtcars width=672}\n:::\n:::\n\n\n\n\n\n### Margin Tables\n\nYou can also place tables in the margin of your document by specifying `column: margin`.\n\n\n\n\n\n::: {.cell .column-margin}\n\n````{.cell-code}\n```{{r}}\n#| column: margin\n\nknitr::kable(\n mtcars[1:6, 1:3]\n)\n```\n````\n\n::: {.cell-output-display}\n\n\n| | mpg| cyl| disp|\n|:-----------------|----:|---:|----:|\n|Mazda RX4 | 21.0| 6| 160|\n|Mazda RX4 Wag | 21.0| 6| 160|\n|Datsun 710 | 22.8| 4| 108|\n|Hornet 4 Drive | 21.4| 6| 258|\n|Hornet Sportabout | 18.7| 8| 360|\n|Valiant | 18.1| 6| 225|\n\n\n:::\n:::\n\n\n\n\n\n### Multiple Outputs\n\nYou can also target specific output types (for example, figures) to be placed in the margin. For example, the following code will render a table showing part of the `mtcars` dataset and produce a plot in the margin next to the table.\n\n\n\n\n\n::: {.cell .fig-column-margin}\n\n````{.cell-code}\n```{{r}}\n#| fig-column: margin\n\nmtcars2 <- mtcars\nmtcars2$am <- factor(\n mtcars$am, labels = c('automatic', 'manual')\n)\n\nknitr::kable(\n mtcars[1:6, 1:6]\n)\n\nlibrary(ggplot2)\nggplot(mtcars2, aes(hp, mpg, color = am)) +\n geom_point() +\n geom_smooth(formula = y ~ x, method = \"loess\") +\n theme(legend.position = 'bottom')\n```\n````\n\n::: {.cell-output-display}\n\n\n| | mpg| cyl| disp| hp| drat| wt|\n|:-----------------|----:|---:|----:|---:|----:|-----:|\n|Mazda RX4 | 21.0| 6| 160| 110| 3.90| 2.620|\n|Mazda RX4 Wag | 21.0| 6| 160| 110| 3.90| 2.875|\n|Datsun 710 | 22.8| 4| 108| 93| 3.85| 2.320|\n|Hornet 4 Drive | 21.4| 6| 258| 110| 3.08| 3.215|\n|Hornet Sportabout | 18.7| 8| 360| 175| 3.15| 3.440|\n|Valiant | 18.1| 6| 225| 105| 2.76| 3.460|\n\n\n:::\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-7-1.png){width=672}\n:::\n:::\n\n\n\n\n## Page Breaks\n\nThe `pagebreak` [shortcode](shortcodes.qmd) enables you to insert a native pagebreak into a document (.e.g in LaTeX this would be a `\\newpage`, in MS Word a docx-native pagebreak, in HTML a `page-break-after: always` CSS directive, etc.):\n\n```{.markdown shortcodes=\"false\"}\npage 1\n\n{{< pagebreak >}}\n\npage 2\n```\n\nNative pagebreaks are supported for HTML, LaTeX, Context, MS Word, Open Document, and ePub (for other formats a form-feed character `\\f` is inserted).\n\n\n\n\n## Margin References\n\nFootnotes and the bibliography typically appear at the end of the document, but you can choose to have them placed in the margin by setting the following option[^1] in the document front matter:\n\n``` yaml\n---\nreference-location: margin\ncitation-location: margin\n---\n```\n\nWith these options set, footnotes and citations will (respectively) be automatically be placed in the margin of the document rather than the bottom of the page. As an example, when I cite @xie2018, the citation bibliography entry itself will now appear in the margin.\n\n### Asides\n\nAsides allow you to place content aside from the content it is placed in. Asides look like footnotes, but do not include the footnote mark (the superscript number). [This is a span that has the class `aside` which places it in the margin without a footnote number.]{.aside}\n\n``` markdown\n[This is a span that has the class `aside` which places it in the margin without a footnote number.]{.aside}\n```\n\n## Margin Captions\n\nFor figures and tables, you may leave the content in the body of the document while placing the caption in the margin of the document. Using `cap-location: margin` in a code cell or document front matter to control this. For example:\n\n\n\n\n\n::: {.cell .caption-margin}\n\n````{.cell-code}\n```{{r}}\n#| label: fig-cap-margin\n#| fig-cap: \"MPG vs horsepower, colored by transmission.\"\n#| cap-location: margin\n\nlibrary(ggplot2)\nmtcars2 <- mtcars\nmtcars2$am <- factor(\n mtcars$am, labels = c('automatic', 'manual')\n)\nggplot(mtcars2, aes(hp, mpg, color = am)) +\n geom_point() +\n geom_smooth(formula = y ~ x, method = \"loess\") +\n theme(legend.position = 'bottom')\n```\n````\n\n::: {.cell-output-display}\n![MPG vs horsepower, colored by transmission.](article-layout_files/figure-html/fig-cap-margin-1.png){#fig-cap-margin width=672}\n:::\n:::\n\n\n\n\n\n## Overflowing Content\n\nYou can also extend content outside the body region on only the left or right side of the document by using the `right` and `left` versions of the `body`, `page`, and `screen` columns to layout your content. The `left` or `right` version of these columns are as follows:\n\n::: {.layout-example .column-body-outset-right .left}\n.column-body-outset-right\n:::\n\n::: {.layout-example .column-page-inset-right .left}\n.column-page-inset-right\n:::\n\n::: {.layout-example .column-page-right .left}\n.column-page-right\n:::\n\n::: {.layout-example .column-screen-inset-right .left}\n.column-screen-inset-right\n:::\n\n::: {.layout-example .column-screen-right .left}\n.column-screen-right\n:::\n\n::: {.layout-example .column-body-outset-left .right}\n.column-body-outset-left\n:::\n\n::: {.layout-example .column-page-inset-left .right}\n.column-page-inset-left\n:::\n\n::: {.layout-example .column-page-left .right}\n.column-page-left\n:::\n\n::: {.layout-example .column-screen-inset-left .right}\n.column-screen-inset-left\n:::\n\n::: {.layout-example .column-screen-left .right}\n.column-screen-left\n:::\n\nUse a div with one of the above classes to align content into one of the overflow regions. This also works using the `column` option of executable code cells:\n\n\n\n\n\n::: {.cell .column-screen-inset-right}\n\n````{.cell-code}\n```{{r}}\n#| column: screen-inset-right\n\nlibrary(leaflet)\nleaflet() %>%\n addTiles() %>% # Add default OpenStreetMap map tiles\n addMarkers(lng=174.768, lat=-36.852, popup=\"The birthplace of R\")\n```\n````\n\n::: {.cell-output-display}\n\n```{=html}\n
\n\n```\n\n:::\n:::\n\n\n\n\n\n## Options Reference\n\n### Global Options\n\nSome layout options can be specified globally in document yaml. For example:\n\n``` yaml\n---\nfig-cap-location: margin\nreference-location: margin\n---\n```\n\nAll of the below options currently only support setting a value of `margin` which tells Quarto to place the corresponding element in the margin.\n\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+======================+=========================================================================================================+\n| `reference-location` | Where to place footnotes. Defaults to `document`.\\ |\n| | \\[`document` \\| `section` \\| `block` \\| `margin` \\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `citation-location` | Where to place citations. Defaults to `document`.\\ |\n| | \\[`document` \\| `margin` \\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `cap-location` | Where to place figure and table captions. Defaults to `bottom` for figures and `top` for tables.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `fig-cap-location` | Where to place figure captions. Defaults to `bottom`.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `tbl-cap-location` | Where to place table captions. Defaults to `top`.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n\n### Code Cell Options\n\nYou can also set layout column on specific code cells. This controls the layout of content that is produced by the code cell.\n\n```{{r}}\n#| column: page\n\nplot(cars)\n```\n\n::: column-page-right\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+====================+==============================================================================================================================+\n| `column` | Layout column to use for code cell outputs. See column options below. |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `fig-column` | Layout column to use for code cell figure outputs. See column options below. |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `tbl-column` | Layout column to use for code cell table outputs. See column options below. |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `cap-location` | Where to place figure and table captions produced by this code cell. Defaults to `bottom` for figures and `top` for tables.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `fig-cap-location` | Where to place captions for figures produced by this code cell. Defaults to `inline`.\\ |\n| | \\[`inline` \\| `margin`\\] |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `tbl-cap-location` | Where to place captions for tables produced by this code cell. Defaults to `inline`.\\ |\n| | \\[`inline` \\| `margin`\\] |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n:::\n\n### Using Classes\n\nIn addition to global and code cell specific options, you may use divs with layout classes (prefixed with `.column-`) to arrange content into columns:\n\n``` md\n::: {.column-margin}\nThis content will appear in the margin!\n:::\n```\n\n### Available Columns\n\nHere are all of the available column specifiers:\n\n::: column-page-right\n+--------------+---------------------------------+---------------------------------+\n| Column | Code Cell `column` | Class Name |\n+==============+=================================+=================================+\n| Body | column: body | .column-body |\n| | column: body-outset | .column-body-outset |\n| | column: body-outset-left | .column-body-outset-left |\n| | column: body-outset-right | .column-body-outset-right |\n+--------------+---------------------------------+---------------------------------+\n| Page Inset | column: page-inset-left | .column-page-inset-left |\n| | column: page-inset-right | .column-page-inset-right |\n+--------------+---------------------------------+---------------------------------+\n| Page | column: page | .column-page |\n| | column: page-left | .column-page-left |\n| | column: page-right | .column-page-right |\n+--------------+---------------------------------+---------------------------------+\n| Screen Inset | column: screen-inset | .column-screen-inset |\n| | column: screen-inset-shaded | .column-screen-inset-shaded |\n| | column: screen-inset-left | .column-screen-inset-left |\n| | column: screen-inset-right | .column-screen-inset-right |\n+--------------+---------------------------------+---------------------------------+\n| Screen | column: screen | .column-screen |\n| | column: screen-left | .column-screen-left |\n| | column: screen-right | .column-screen-right |\n+--------------+---------------------------------+---------------------------------+\n| Margin | column: margin | .column-margin |\n+--------------+---------------------------------+---------------------------------+\n:::\n\n## PDF/LaTeX Layout {data-link=\"PDF/LaTeX Layout\"}\n\nWhile most of the layout capabilities described are supported for both HTML and PDF output, some are available only for HTML output. You can use the full set of columns for HTML. Then, when you render PDF or LaTeX output, content will automatically be placed in the most appropriate related column (typically this will mean using the main column and right margin). Here is how columns are mapped:\n\n- Any column that uses the right margin (e.g. `page`, `screen`, `screen-right`, etc.) will be rendered as `page-right` in LaTeX.\n- Any column that uses the left margin will be rendered as normal body content.\n\n### Page Geometry\n\nWhen you render a PDF using content in the margin or content that spans the page, Quarto will automatically adjust the page geometry for the default Quarto LaTeX document classes (KOMA `scrartcl`, `scrreport`, or `scrbook`) to create a slightly narrower body content region and a slightly wider margin region. This adjustment will incorporate known paper sizes to create a reasonable page geometry for most content.\n\nYou can control the page geometry directly yourself by setting `geometry` options in your document's front matter. For example:\n\n``` yaml\n---\ngeometry:\n - left=.75in\n - textwidth=4.5in\n - marginparsep=.25in\n - marginparwidth=2.25in\n---\n```\n\nYou can use these options to control the page geometry for the built-in document classes or to customize the geometry of other document classes that you may be using.\n\n::: {.callout-tip appearance=\"simple\"}\nIf you'd like to view the page geometry in your rendered PDF, you can pass `showframe` to the `geometry` option as in the below example.\n\n``` {.yaml style=\"background: none;\"}\n---\ngeometry:\n - showframe\n---\n```\n:::\n\n### Code Blocks\n\nWhen rendering a PDF that uses the margins for content, Quarto automatically adjusts the appearance of code blocks. Rather than having a solid background color, a left border treatment is used.\n\nThis enables non-breaking code to overflow into the margin without cosmetic issues created by the code block background (which does not overflow into the margin region).\n\nYou can disable this treatment by setting the following `code-block-border-left: false` in your document front matter.\n\n## Landscape mode\n\nIn `docx`, `pdf` and `typst` formats, you can set portions of the document to landscape mode by wrapping the content around a fenced div with class `landscape`:\n\n````markdown\n---\nformat:\n docx: default\n typst: default\n pdf: default\n---\n\nThis will appear in portrait mode.\n\n::: {.landscape}\n\nThis will appear in landscape.\n\n:::\n\nThis will appear in portrait mode again.\n````\n\n\n\n[^1]: You can also position references in other location (such as the bottom of the block, section, or document).\n", + "markdown": "---\ntitle: \"Article Layout\"\nformat: html\nreference-location: margin\ncitation-location: margin\naliases:\n - page-layout.html\n---\n\n## Overview\n\nQuarto supports a variety of page layout options that enable you to author content that:\n\n- Fills the main content region\n- Overflows the content region\n- Spans the entire page\n- Occupies the document margin\n- Uses landscape mode in paginated formats\n\nQuarto uses the concept of columns to describe page layout (e.g. the \"body\" column, the \"margin\" column, etc.). Below we'll describe how to arrange content into these columns. If you need to adjust the widths of the columns, see [Page Layout - Grid Customization](/docs/output-formats/page-layout.qmd#grid-customization).\n\nAll of the layout capabilities described in this document work for HTML output and many work for PDF and LaTeX output. For details about the PDF / LaTeX output, see [PDF/LaTeX Layout].\n\n## Body Column\n\nBy default, elements are position in the body of the document and are allowed to span the content of the document, like the below.\n\n::: {.layout-example .column-body}\n.column-body\n:::\n\nBut if you'd like, you can extend content slightly outside the bounds of the body by creating a div with the .`column-body-outset` class. For example:\n\n``` markdown\n:::{.column-body-outset}\nOutset content...\n:::\n```\n\n::: {.layout-example .column-body-outset}\n.column-body-outset\n:::\n\n## Page Column\n\nIf you need even more space for your content, you can use the `.column-page` class to make the content much wider, though stopping short of extending across the whole document.\n\n::: {.layout-example .column-page}\n.column-page\n:::\n\nFor example, to create a wider image, you could use:\n\n``` markdown\n:::{.column-page}\n![](images/elephant.jpg)\n:::\n```\n\n::: column-page\n![](images/elephant.jpg){fig-alt=\"Three walking elephants in silhouette against the backdrop of a sunset.\"}\n:::\n\nFor computational output, you can specify the page column in your code cell options. For example:\n\n\n::: {.cell .column-page}\n\n````{.cell-code}\n```{{r}}\n#| column: page\n\nknitr::kable(\n mtcars[1:6, 1:10]\n)\n```\n````\n\n::: {.cell-output-display}\n\n\n| | mpg| cyl| disp| hp| drat| wt| qsec| vs| am| gear|\n|:-----------------|----:|---:|----:|---:|----:|-----:|-----:|--:|--:|----:|\n|Mazda RX4 | 21.0| 6| 160| 110| 3.90| 2.620| 16.46| 0| 1| 4|\n|Mazda RX4 Wag | 21.0| 6| 160| 110| 3.90| 2.875| 17.02| 0| 1| 4|\n|Datsun 710 | 22.8| 4| 108| 93| 3.85| 2.320| 18.61| 1| 1| 4|\n|Hornet 4 Drive | 21.4| 6| 258| 110| 3.08| 3.215| 19.44| 1| 0| 3|\n|Hornet Sportabout | 18.7| 8| 360| 175| 3.15| 3.440| 17.02| 0| 0| 3|\n|Valiant | 18.1| 6| 225| 105| 2.76| 3.460| 20.22| 1| 0| 3|\n\n\n:::\n:::\n\n\nIn addition, you can use `.column-page-inset` to inset the element from the page slightly, like so:\n\n::: {.layout-example .column-page-inset}\n.column-page-inset\n:::\n\n## Screen Column\n\nYou can have content span the full width of the page with no margin (full bleed). For this, use the `.column-screen` class or specify `column: screen` on a code cell. For example:\n\n``` md\n::: {.column-screen}\n![A full screen image](/image.png)\n:::\n```\n\n::: {.layout-example .column-screen}\n.column-screen\n:::\n\nThe following code displays a Leaflet map across the whole page.\n\n\n::: {.cell .column-screen}\n\n````{.cell-code}\n```{{r}}\n#| column: screen\n\nlibrary(leaflet)\nleaflet() %>%\n addTiles() %>% # Add default OpenStreetMap map tiles\n addMarkers(lng=174.768, lat=-36.852, popup=\"The birthplace of R\")\n```\n````\n\n::: {.cell-output-display}\n\n```{=html}\n
\n\n```\n\n:::\n:::\n\n\n### Screen Inset\n\nIf you'd like a full width appearance, but would like to retain a margin, you can use inset or inset-shaded modifiers on the column. For example:\n\n``` md\n::: {.column-screen-inset}\n![A full screen image](/image.png)\n:::\n```\n\n::: {.layout-example .column-screen-inset}\n.column-screen-inset\n:::\n\nThe inset-shaded modifier results in a block spanning the full width but wrapped with a lightly shaded background. For example:\n\n\n::: {.cell .column-screen-inset-shaded}\n\n````{.cell-code}\n```{{r}}\n#| column: screen-inset-shaded\n\nlibrary(leaflet)\nleaflet() %>%\n addTiles() %>% # Add default OpenStreetMap map tiles\n addMarkers(lng=174.768, lat=-36.852, popup=\"The birthplace of R\")\n```\n````\n\n::: {.cell-output-display}\n\n```{=html}\n
\n\n```\n\n:::\n:::\n\n\nColumn layouts like `screen-inset-shaded` will work with advanced figure layout. For example, it is straightforward to create a multi column presentation of figures that spans the document:\n\n\n::: {.cell .column-screen-inset-shaded layout-nrow=\"1\"}\n\n````{.cell-code}\n```{{r}}\n#| column: screen-inset-shaded\n#| layout-nrow: 1\n\nplot(cars)\nplot(iris)\nplot(pressure)\n```\n````\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-4-1.png){width=672}\n:::\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-4-2.png){width=672}\n:::\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-4-3.png){width=672}\n:::\n:::\n\n\n## Margin Content\n\nYou can place content within the right margin of Quarto document. For example, here we use the `.column-margin` class to place an image in the margin:\n\n``` md\n::: {.column-margin}\n![A margin image](image.png)\n:::\n```\n\n::: {.layout-example .column-margin style=\"margin-top: 18px;\"}\n.column-margin\n:::\n\nThis also works for text content:\n\n``` md\n::: {.column-margin}\nWe know from *the first fundamental theorem of calculus* that for $x$ in $[a, b]$:\n\n$$\\frac{d}{dx}\\left( \\int_{a}^{x} f(u)\\,du\\right)=f(x).$$\n:::\n```\n\n::: column-margin\nWe know from *the first fundamental theorem of calculus* that for $x$ in $[a, b]$:\n\n$$\\frac{d}{dx}\\left( \\int_{a}^{x} f(u)\\,du\\right)=f(x).$$\n:::\n\n### Margin Figures\n\nFigures that you create using code cells can be placed in the margin by using the `column: margin` code cell option. If the code produces more than one figure, each of the figures will be placed in the margin.\n\n\n::: {.cell .column-margin}\n\n````{.cell-code}\n```{{r}}\n#| label: fig-mtcars\n#| fig-cap: \"MPG vs horsepower, colored by transmission.\"\n#| column: margin\n\nlibrary(ggplot2)\nmtcars2 <- mtcars\nmtcars2$am <- factor(\n mtcars$am, labels = c('automatic', 'manual')\n)\nggplot(mtcars2, aes(hp, mpg, color = am)) +\n geom_point() +\n geom_smooth(formula = y ~ x, method = \"loess\") +\n theme(legend.position = 'bottom')\n```\n````\n\n::: {.cell-output-display}\n![MPG vs horsepower, colored by transmission.](article-layout_files/figure-html/fig-mtcars-1.png){#fig-mtcars width=672}\n:::\n:::\n\n\n### Margin Tables\n\nYou can also place tables in the margin of your document by specifying `column: margin`.\n\n\n::: {.cell .column-margin}\n\n````{.cell-code}\n```{{r}}\n#| column: margin\n\nknitr::kable(\n mtcars[1:6, 1:3]\n)\n```\n````\n\n::: {.cell-output-display}\n\n\n| | mpg| cyl| disp|\n|:-----------------|----:|---:|----:|\n|Mazda RX4 | 21.0| 6| 160|\n|Mazda RX4 Wag | 21.0| 6| 160|\n|Datsun 710 | 22.8| 4| 108|\n|Hornet 4 Drive | 21.4| 6| 258|\n|Hornet Sportabout | 18.7| 8| 360|\n|Valiant | 18.1| 6| 225|\n\n\n:::\n:::\n\n\n### Multiple Outputs\n\nYou can also target specific output types (for example, figures) to be placed in the margin. For example, the following code will render a table showing part of the `mtcars` dataset and produce a plot in the margin next to the table.\n\n\n::: {.cell .fig-column-margin}\n\n````{.cell-code}\n```{{r}}\n#| fig-column: margin\n\nmtcars2 <- mtcars\nmtcars2$am <- factor(\n mtcars$am, labels = c('automatic', 'manual')\n)\n\nknitr::kable(\n mtcars[1:6, 1:6]\n)\n\nlibrary(ggplot2)\nggplot(mtcars2, aes(hp, mpg, color = am)) +\n geom_point() +\n geom_smooth(formula = y ~ x, method = \"loess\") +\n theme(legend.position = 'bottom')\n```\n````\n\n::: {.cell-output-display}\n\n\n| | mpg| cyl| disp| hp| drat| wt|\n|:-----------------|----:|---:|----:|---:|----:|-----:|\n|Mazda RX4 | 21.0| 6| 160| 110| 3.90| 2.620|\n|Mazda RX4 Wag | 21.0| 6| 160| 110| 3.90| 2.875|\n|Datsun 710 | 22.8| 4| 108| 93| 3.85| 2.320|\n|Hornet 4 Drive | 21.4| 6| 258| 110| 3.08| 3.215|\n|Hornet Sportabout | 18.7| 8| 360| 175| 3.15| 3.440|\n|Valiant | 18.1| 6| 225| 105| 2.76| 3.460|\n\n\n:::\n\n::: {.cell-output-display}\n![](article-layout_files/figure-html/unnamed-chunk-7-1.png){width=672}\n:::\n:::\n\n\n## Page Breaks\n\nThe `pagebreak` [shortcode](shortcodes.qmd) enables you to insert a native pagebreak into a document (.e.g in LaTeX this would be a `\\newpage`, in MS Word a docx-native pagebreak, in HTML a `page-break-after: always` CSS directive, etc.):\n\n```{.markdown shortcodes=\"false\"}\npage 1\n\n{{< pagebreak >}}\n\npage 2\n```\n\nNative pagebreaks are supported for HTML, LaTeX, Context, MS Word, Open Document, and ePub (for other formats a form-feed character `\\f` is inserted).\n\n\n\n## Margin References\n\nFootnotes and the bibliography typically appear at the end of the document, but you can choose to have them placed in the margin by setting the following option[^1] in the document front matter:\n\n``` yaml\n---\nreference-location: margin\ncitation-location: margin\n---\n```\n\nWith these options set, footnotes and citations will (respectively) be automatically be placed in the margin of the document rather than the bottom of the page. As an example, when I cite @xie2018, the citation bibliography entry itself will now appear in the margin.\n\n### Asides\n\nAsides allow you to place content aside from the content it is placed in. Asides look like footnotes, but do not include the footnote mark (the superscript number). [This is a span that has the class `aside` which places it in the margin without a footnote number.]{.aside}\n\n``` markdown\n[This is a span that has the class `aside` which places it in the margin without a footnote number.]{.aside}\n```\n\n## Margin Captions\n\nFor figures and tables, you may leave the content in the body of the document while placing the caption in the margin of the document. Using `cap-location: margin` in a code cell or document front matter to control this. For example:\n\n\n::: {.cell .caption-margin}\n\n````{.cell-code}\n```{{r}}\n#| label: fig-cap-margin\n#| fig-cap: \"MPG vs horsepower, colored by transmission.\"\n#| cap-location: margin\n\nlibrary(ggplot2)\nmtcars2 <- mtcars\nmtcars2$am <- factor(\n mtcars$am, labels = c('automatic', 'manual')\n)\nggplot(mtcars2, aes(hp, mpg, color = am)) +\n geom_point() +\n geom_smooth(formula = y ~ x, method = \"loess\") +\n theme(legend.position = 'bottom')\n```\n````\n\n::: {.cell-output-display}\n![MPG vs horsepower, colored by transmission.](article-layout_files/figure-html/fig-cap-margin-1.png){#fig-cap-margin width=672}\n:::\n:::\n\n\n## Overflowing Content\n\nYou can also extend content outside the body region on only the left or right side of the document by using the `right` and `left` versions of the `body`, `page`, and `screen` columns to layout your content. The `left` or `right` version of these columns are as follows:\n\n::: {.layout-example .column-body-outset-right .left}\n.column-body-outset-right\n:::\n\n::: {.layout-example .column-page-inset-right .left}\n.column-page-inset-right\n:::\n\n::: {.layout-example .column-page-right .left}\n.column-page-right\n:::\n\n::: {.layout-example .column-screen-inset-right .left}\n.column-screen-inset-right\n:::\n\n::: {.layout-example .column-screen-right .left}\n.column-screen-right\n:::\n\n::: {.layout-example .column-body-outset-left .right}\n.column-body-outset-left\n:::\n\n::: {.layout-example .column-page-inset-left .right}\n.column-page-inset-left\n:::\n\n::: {.layout-example .column-page-left .right}\n.column-page-left\n:::\n\n::: {.layout-example .column-screen-inset-left .right}\n.column-screen-inset-left\n:::\n\n::: {.layout-example .column-screen-left .right}\n.column-screen-left\n:::\n\nUse a div with one of the above classes to align content into one of the overflow regions. This also works using the `column` option of executable code cells:\n\n\n::: {.cell .column-screen-inset-right}\n\n````{.cell-code}\n```{{r}}\n#| column: screen-inset-right\n\nlibrary(leaflet)\nleaflet() %>%\n addTiles() %>% # Add default OpenStreetMap map tiles\n addMarkers(lng=174.768, lat=-36.852, popup=\"The birthplace of R\")\n```\n````\n\n::: {.cell-output-display}\n\n```{=html}\n
\n\n```\n\n:::\n:::\n\n\n## Options Reference\n\n### Global Options\n\nSome layout options can be specified globally in document yaml. For example:\n\n``` yaml\n---\nfig-cap-location: margin\nreference-location: margin\n---\n```\n\nAll of the below options currently only support setting a value of `margin` which tells Quarto to place the corresponding element in the margin.\n\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+======================+=========================================================================================================+\n| `reference-location` | Where to place footnotes. Defaults to `document`.\\ |\n| | \\[`document` \\| `section` \\| `block` \\| `margin` \\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `citation-location` | Where to place citations. Defaults to `document`.\\ |\n| | \\[`document` \\| `margin` \\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `cap-location` | Where to place figure and table captions. Defaults to `bottom` for figures and `top` for tables.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `fig-cap-location` | Where to place figure captions. Defaults to `bottom`.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n| `tbl-cap-location` | Where to place table captions. Defaults to `top`.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+----------------------+---------------------------------------------------------------------------------------------------------+\n\n### Code Cell Options\n\nYou can also set layout column on specific code cells. This controls the layout of content that is produced by the code cell.\n\n```{{r}}\n#| column: page\n\nplot(cars)\n```\n\n::: column-page-right\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+====================+==============================================================================================================================+\n| `column` | Layout column to use for code cell outputs. See column options below. |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `fig-column` | Layout column to use for code cell figure outputs. See column options below. |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `tbl-column` | Layout column to use for code cell table outputs. See column options below. |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `cap-location` | Where to place figure and table captions produced by this code cell. Defaults to `bottom` for figures and `top` for tables.\\ |\n| | \\[`top` \\| `bottom` \\| `margin`\\] |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `fig-cap-location` | Where to place captions for figures produced by this code cell. Defaults to `inline`.\\ |\n| | \\[`inline` \\| `margin`\\] |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n| `tbl-cap-location` | Where to place captions for tables produced by this code cell. Defaults to `inline`.\\ |\n| | \\[`inline` \\| `margin`\\] |\n+--------------------+------------------------------------------------------------------------------------------------------------------------------+\n:::\n\n### Using Classes\n\nIn addition to global and code cell specific options, you may use divs with layout classes (prefixed with `.column-`) to arrange content into columns:\n\n``` md\n::: {.column-margin}\nThis content will appear in the margin!\n:::\n```\n\n### Available Columns\n\nHere are all of the available column specifiers:\n\n::: column-page-right\n+--------------+---------------------------------+---------------------------------+\n| Column | Code Cell `column` | Class Name |\n+==============+=================================+=================================+\n| Body | column: body | .column-body |\n| | column: body-outset | .column-body-outset |\n| | column: body-outset-left | .column-body-outset-left |\n| | column: body-outset-right | .column-body-outset-right |\n+--------------+---------------------------------+---------------------------------+\n| Page Inset | column: page-inset | .column-page-inset |\n| | column: page-inset-left | .column-page-inset-left |\n| | column: page-inset-right | .column-page-inset-right |\n+--------------+---------------------------------+---------------------------------+\n| Page | column: page | .column-page |\n| | column: page-left | .column-page-left |\n| | column: page-right | .column-page-right |\n+--------------+---------------------------------+---------------------------------+\n| Screen Inset | column: screen-inset | .column-screen-inset |\n| | column: screen-inset-shaded | .column-screen-inset-shaded |\n| | column: screen-inset-left | .column-screen-inset-left |\n| | column: screen-inset-right | .column-screen-inset-right |\n+--------------+---------------------------------+---------------------------------+\n| Screen | column: screen | .column-screen |\n| | column: screen-left | .column-screen-left |\n| | column: screen-right | .column-screen-right |\n+--------------+---------------------------------+---------------------------------+\n| Margin | column: margin | .column-margin |\n+--------------+---------------------------------+---------------------------------+\n:::\n\n## PDF/LaTeX Layout {data-link=\"PDF/LaTeX Layout\"}\n\nWhile most of the layout capabilities described are supported for both HTML and PDF output, some are available only for HTML output. You can use the full set of columns for HTML. Then, when you render PDF or LaTeX output, content will automatically be placed in the most appropriate related column (typically this will mean using the main column and right margin). Here is how columns are mapped:\n\n- Any column that uses the right margin (e.g. `page`, `screen`, `screen-right`, etc.) will be rendered as `page-right` in LaTeX.\n- Any column that uses the left margin will be rendered as normal body content.\n\n### Page Geometry\n\nWhen you render a PDF using content in the margin or content that spans the page, Quarto will automatically adjust the page geometry for the default Quarto LaTeX document classes (KOMA `scrartcl`, `scrreport`, or `scrbook`) to create a slightly narrower body content region and a slightly wider margin region. This adjustment will incorporate known paper sizes to create a reasonable page geometry for most content.\n\nYou can control the page geometry directly yourself by setting `geometry` options in your document's front matter. For example:\n\n``` yaml\n---\ngeometry:\n - left=.75in\n - textwidth=4.5in\n - marginparsep=.25in\n - marginparwidth=2.25in\n---\n```\n\nYou can use these options to control the page geometry for the built-in document classes or to customize the geometry of other document classes that you may be using.\n\n::: {.callout-tip appearance=\"simple\"}\nIf you'd like to view the page geometry in your rendered PDF, you can pass `showframe` to the `geometry` option as in the below example.\n\n``` {.yaml style=\"background: none;\"}\n---\ngeometry:\n - showframe\n---\n```\n:::\n\n### Code Blocks\n\nWhen rendering a PDF that uses the margins for content, Quarto automatically adjusts the appearance of code blocks. Rather than having a solid background color, a left border treatment is used.\n\nThis enables non-breaking code to overflow into the margin without cosmetic issues created by the code block background (which does not overflow into the margin region).\n\nYou can disable this treatment by setting the following `code-block-border-left: false` in your document front matter.\n\n## Landscape mode\n\nIn `docx`, `pdf` and `typst` formats, you can set portions of the document to landscape mode by wrapping the content around a fenced div with class `landscape`:\n\n````markdown\n---\nformat:\n docx: default\n typst: default\n pdf: default\n---\n\nThis will appear in portrait mode.\n\n::: {.landscape}\n\nThis will appear in landscape.\n\n:::\n\nThis will appear in portrait mode again.\n````\n\n\n\n[^1]: You can also position references in other location (such as the bottom of the block, section, or document).\n", "supporting": [ "article-layout_files" ], diff --git a/_quarto.yml b/_quarto.yml index 2e76f7b827..508ad025c8 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -134,6 +134,8 @@ website: href: docs/authoring/lipsum.qmd - text: "Rearrange Contents" href: docs/authoring/contents.qmd + - text: "Quarto Version" + href: docs/authoring/version.qmd - docs/authoring/videos.qmd - text: "Embeds" href: docs/authoring/notebook-embed.qmd diff --git a/docs/authoring/article-layout.qmd b/docs/authoring/article-layout.qmd index 9bbf53c6fb..488a2b58f8 100644 --- a/docs/authoring/article-layout.qmd +++ b/docs/authoring/article-layout.qmd @@ -418,7 +418,8 @@ Here are all of the available column specifiers: | | column: body-outset-left | .column-body-outset-left | | | column: body-outset-right | .column-body-outset-right | +--------------+---------------------------------+---------------------------------+ -| Page Inset | column: page-inset-left | .column-page-inset-left | +| 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 | diff --git a/docs/authoring/brand.qmd b/docs/authoring/brand.qmd index d11b93aaab..b6d7c65f97 100644 --- a/docs/authoring/brand.qmd +++ b/docs/authoring/brand.qmd @@ -183,17 +183,19 @@ 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` | -+----------------------+----------------------------------------------+-------------------------------+ ++---------------------------+----------------------------------------------+-------------------------------+ +| 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`: diff --git a/docs/output-formats/html-basics.qmd b/docs/output-formats/html-basics.qmd index 9ec6a7b0aa..3695d80d19 100644 --- a/docs/output-formats/html-basics.qmd +++ b/docs/output-formats/html-basics.qmd @@ -275,6 +275,24 @@ Tab content ::: ``` +### Active Tabset + +By default the first tab in the tabset will be active when a page loads. +To have a different tab active on page load, add the `.active` class to the tab heading. +For example, here the "Python" tab will be active on page load: + +```markdown +::: {.panel-tabset} +## R + +Tab content + +## Python {.active} + +Tab content +::: +``` + ## Self Contained HTML documents typically have a number of external dependencies (e.g. images, CSS style sheets, JavaScript, etc.). By default these dependencies are placed in a `_files` directory alongside your document. For example, if you render `report.qmd` to HTML: