From 526845acefa2eca3c15f28aba55b553d3933a423 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Tue, 27 Feb 2024 15:29:46 +0100 Subject: [PATCH 01/33] refactor: use internal qmd ref for all links --- docs/authoring/cross-references-custom.qmd | 4 +- docs/authoring/cross-references-divs.qmd | 5 +- docs/authoring/figures.qmd | 2 +- docs/authoring/front-matter.qmd | 2 +- docs/authoring/tables.qmd | 4 +- .../2023-03-13-code-annotation/index.qmd | 2 +- .../posts/2023-03-15-multi-format/index.qmd | 2 +- .../posts/2023-03-20-confluence/index.qmd | 2 +- .../posts/2023-04-26-1.3-release/index.qmd | 2 +- .../posts/2023-05-15-get-started/index.qmd | 14 ++--- .../2023-05-22-quarto-for-academics/index.qmd | 20 +++--- .../index.qmd | 2 +- .../posts/2024-01-24-1.4-release/index.qmd | 8 +-- docs/computations/_caching-more.md | 2 +- docs/computations/caching.qmd | 4 +- docs/computations/execution-options.qmd | 4 +- docs/computations/r.qmd | 3 +- docs/dashboards/layout.qmd | 4 +- docs/extensions/lua.qmd | 2 +- docs/faq/index.qmd | 18 +++--- docs/faq/rmarkdown.qmd | 38 ++++++------ docs/get-started/authoring/_text-editor.md | 4 +- docs/get-started/authoring/jupyter.qmd | 4 +- docs/get-started/authoring/rstudio.qmd | 8 +-- docs/get-started/computations/jupyter.qmd | 2 +- docs/get-started/computations/rstudio.qmd | 8 +-- docs/get-started/computations/text-editor.qmd | 2 +- docs/get-started/computations/vscode.qmd | 2 +- docs/get-started/hello/jupyter.qmd | 2 +- docs/get-started/hello/neovim.qmd | 2 +- docs/get-started/hello/rstudio.qmd | 8 +-- docs/get-started/hello/text-editor.qmd | 2 +- docs/get-started/hello/vscode.qmd | 2 +- docs/journals/_draft/create-extensions.qmd | 4 +- docs/manuscripts/authoring/_citations.qmd | 2 +- docs/manuscripts/authoring/_cross-refs.qmd | 2 +- .../authoring/_inline-computations.qmd | 9 ++- docs/manuscripts/authoring/_markdown.qmd | 2 +- docs/manuscripts/authoring/_overview.qmd | 2 +- docs/manuscripts/authoring/_tables.qmd | 4 +- docs/manuscripts/authoring/_visual-editor.qmd | 4 +- docs/manuscripts/components.qmd | 6 +- docs/manuscripts/next-steps.qmd | 10 +-- docs/manuscripts/publishing.qmd | 6 +- docs/output-formats/html-basics.qmd | 6 +- docs/output-formats/html-code.qmd | 2 +- docs/output-formats/html-multi-format.qmd | 4 +- docs/output-formats/page-layout.qmd | 3 +- docs/output-formats/typst-custom.qmd | 2 +- docs/output-formats/typst.qmd | 5 +- docs/prerelease/1.3/_pre-release-feature.qmd | 4 +- docs/prerelease/1.4/_highlights.qmd | 4 +- docs/prerelease/1.4/_pre-release-feature.qmd | 4 +- docs/prerelease/1.5/_pre-release-feature.qmd | 4 +- docs/presentations/revealjs/demo/index.qmd | 62 +++++++++---------- docs/publishing/confluence.qmd | 2 +- docs/reference/cells/index.qmd | 2 +- docs/reference/formats/dashboards.qmd | 4 +- docs/websites/_page-navigation.md | 2 +- docs/websites/website-listings-custom.qmd | 2 +- index.qmd | 3 +- 61 files changed, 171 insertions(+), 185 deletions(-) diff --git a/docs/authoring/cross-references-custom.qmd b/docs/authoring/cross-references-custom.qmd index 1378f75ce5..6e1163cbb5 100644 --- a/docs/authoring/cross-references-custom.qmd +++ b/docs/authoring/cross-references-custom.qmd @@ -54,7 +54,7 @@ Which renders as: In @vid-cern... -You can find a complete listing of the options available for the `custom` key on the [Cross-Reference Options](/docs/reference/metadata/crossref.html#custom) reference page. +You can find a complete listing of the options available for the `custom` key on the [Cross-Reference Options](/docs/reference/metadata/crossref.qmd#custom) reference page. ## PDF Output @@ -110,4 +110,4 @@ crossref: latex-list-of-description: Supplementary Figure ``` -Note the use of `space-before-numbering: false`, which prevents a space between the `reference-prefix` or `caption-prefix` and the counter, so that labels will appear as "Figure S1", "Figure S2" etc. \ No newline at end of file +Note the use of `space-before-numbering: false`, which prevents a space between the `reference-prefix` or `caption-prefix` and the counter, so that labels will appear as "Figure S1", "Figure S2" etc. diff --git a/docs/authoring/cross-references-divs.qmd b/docs/authoring/cross-references-divs.qmd index 3ac02a96e8..5b3b71dbfa 100644 --- a/docs/authoring/cross-references-divs.qmd +++ b/docs/authoring/cross-references-divs.qmd @@ -387,7 +387,7 @@ This dataset has `{r} length(x)` observations. ## Conditional Content -The cross-reference div syntax combined with [conditional content](/docs/authoring/conditional.html) allows the content of your reference to vary by format. For example, you might want an interactive JavaScript based plot when the format is HTML, but otherwise produce a static plot: +The cross-reference div syntax combined with [conditional content](/docs/authoring/conditional.qmd) allows the content of your reference to vary by format. For example, you might want an interactive JavaScript based plot when the format is HTML, but otherwise produce a static plot: ````markdown @@ -414,6 +414,3 @@ Scatterplot @fig-scatterplot ```` - - - diff --git a/docs/authoring/figures.qmd b/docs/authoring/figures.qmd index c17c31676b..69e83d0b5f 100644 --- a/docs/authoring/figures.qmd +++ b/docs/authoring/figures.qmd @@ -409,7 +409,7 @@ To set the ID, caption and link, use the chunk options `label`, `fig-cap` and `f Other attributes, e.g. `fig-align` and `fig-alt`, can be set using the chunk option of the same name. You can control the default size for computational figures using the `fig-width` and `fig-height` options in the document header. -Read more about these options in [Execution Options: Figure Options](https://quarto.org/docs/computations/execution-options.html#figure-options). +Read more about these options in [Execution Options: Figure Options](/docs/computations/execution-options.qmd#figure-options). ### Layout diff --git a/docs/authoring/front-matter.qmd b/docs/authoring/front-matter.qmd index ad0ccd0a28..e88ebbe469 100644 --- a/docs/authoring/front-matter.qmd +++ b/docs/authoring/front-matter.qmd @@ -53,7 +53,7 @@ The documents produced by the above metadata for the HTML and JATS formats are s ![](images/scholarly-front-matter-html.png){fig-alt="Screenshot of the HTML preview from the document with the above metadata."} ::: -Not all of the metadata keys are used in every format. However, the tags described on this page will generally be supported in [journal article formats](/docs/extensions/listing-journals.html). Currently the JATS format makes use of the broadest set of metadata tags, so if you want to check how things render we recommend previewing with `format: jats`. +Not all of the metadata keys are used in every format. However, the tags described on this page will generally be supported in [journal article formats](/docs/extensions/listing-journals.qmd). Currently the JATS format makes use of the broadest set of metadata tags, so if you want to check how things render we recommend previewing with `format: jats`. ## Authors & Affiliations {#authors-and-affiliations} diff --git a/docs/authoring/tables.qmd b/docs/authoring/tables.qmd index b66c851ad9..ac944dcb1a 100644 --- a/docs/authoring/tables.qmd +++ b/docs/authoring/tables.qmd @@ -403,7 +403,7 @@ Which looks like this when rendered to HTML: Note that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). Here are some tools that can assist with creating grid tables: - Emacs' [table-mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Based-Tables.html) (`M-x table-insert`) -- Quarto [Visual Editor](https://quarto.org/docs/visual-editor/content.html#editing-tables) +- Quarto [Visual Editor](/docs/visual-editor/content.qmd#editing-tables) - Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled ## HTML Tables @@ -573,4 +573,4 @@ If you are the author of a library that emits HTML tables you might like to disa ...
-``` \ No newline at end of file +``` diff --git a/docs/blog/posts/2023-03-13-code-annotation/index.qmd b/docs/blog/posts/2023-03-13-code-annotation/index.qmd index 24a704b4bc..a4b71fe839 100644 --- a/docs/blog/posts/2023-03-13-code-annotation/index.qmd +++ b/docs/blog/posts/2023-03-13-code-annotation/index.qmd @@ -85,4 +85,4 @@ penguins |> # <1> 2. add new columns for the bill ratio and bill area. ```` -You can read more about how to control the annotation style, and whether annotations appear at all on the [Code Annotation page](/docs/prerelease/1.3/code-annotation.html) of the pre-release highlights. +You can read more about how to control the annotation style, and whether annotations appear at all on the [Code Annotation page](/docs/prerelease/1.3/code-annotation.qmd) of the pre-release highlights. diff --git a/docs/blog/posts/2023-03-15-multi-format/index.qmd b/docs/blog/posts/2023-03-15-multi-format/index.qmd index 3fc64b20de..a89664348a 100644 --- a/docs/blog/posts/2023-03-15-multi-format/index.qmd +++ b/docs/blog/posts/2023-03-15-multi-format/index.qmd @@ -39,4 +39,4 @@ If a table of contents is enabled for the page, the additional formats will be a Links to additional formats are displayed by default, but you can control whether they are shown or even which specific formats are included with the `format-links` YAML option. -Read more about this feature on the [Multi-format page](/docs/prerelease/1.3/multi-format.html) of the pre-release highlights. +Read more about this feature on the [Multi-format page](/docs/prerelease/1.3/multi-format.qmd) of the pre-release highlights. diff --git a/docs/blog/posts/2023-03-20-confluence/index.qmd b/docs/blog/posts/2023-03-20-confluence/index.qmd index 75f1df58eb..d5aa659fd2 100644 --- a/docs/blog/posts/2023-03-20-confluence/index.qmd +++ b/docs/blog/posts/2023-03-20-confluence/index.qmd @@ -35,4 +35,4 @@ Managing Confluence content with Quarto allows you to author content in Markdown -If you're curious about using Confluence Publishing for your own project, head to the [Confluence Publishing page](/docs/prerelease/1.3/confluence.html) of the pre-release highlights to learn more. +If you're curious about using Confluence Publishing for your own project, head to the [Confluence Publishing page](/docs/prerelease/1.3/confluence.qmd) of the pre-release highlights to learn more. diff --git a/docs/blog/posts/2023-04-26-1.3-release/index.qmd b/docs/blog/posts/2023-04-26-1.3-release/index.qmd index 8ccf6f2abd..7cd41dbdac 100644 --- a/docs/blog/posts/2023-04-26-1.3-release/index.qmd +++ b/docs/blog/posts/2023-04-26-1.3-release/index.qmd @@ -86,7 +86,7 @@ Some other notable highlights include: - [`kbd` Shortcode](/docs/authoring/markdown-basics.qmd#keyboard-shortcuts)---Show well-formatted keyboard shortcuts in Quarto documents. -You can find all the other changes in 1.3, in the [Release Notes](https://quarto.org/docs/download/#download-section-news). +You can find all the other changes in 1.3, in the [Release Notes](/docs/download/index.qmd#download-section-news). ## Acknowledgements diff --git a/docs/blog/posts/2023-05-15-get-started/index.qmd b/docs/blog/posts/2023-05-15-get-started/index.qmd index d4370badca..f3ac4ba54f 100644 --- a/docs/blog/posts/2023-05-15-get-started/index.qmd +++ b/docs/blog/posts/2023-05-15-get-started/index.qmd @@ -11,19 +11,19 @@ image: "get-started-video-cover.png" image-alt: "Quarto logo on a blue background and the title of the video - Get started with Quarto" --- -Have you been hearing about Quarto but didn't give it a try yet? Perused the [Get Started](/docs/get-started/) pages but would like another intro? Or have about 20 minutes to spare and want to pick up a few Quarto tips? You've come to the right place! +Have you been hearing about Quarto but didn't give it a try yet? Perused the [Get Started](/docs/get-started/index.qmd) pages but would like another intro? Or have about 20 minutes to spare and want to pick up a few Quarto tips? You've come to the right place! {{< video "https://www.youtube.com/embed/_f3latmOhew" >}} -In this video, I walk you through creating documents, presentations, and websites and publishing with Quarto. The video features authoring Quarto documents with executable R code chunks using the [RStudio Visual Editor](/docs/visual-editor/). +In this video, I walk you through creating documents, presentations, and websites and publishing with Quarto. The video features authoring Quarto documents with executable R code chunks using the [RStudio Visual Editor](/docs/visual-editor/index.qmd). Select highlights include: -- Inserting [cross references](/docs/authoring/cross-references.html) to tables and figures -- Adding a [citation](/docs/visual-editor/technical.html#citations) from a DOI -- Seamlessly switching between output formats as well as creating [multi-format documents](/docs/output-formats/html-multi-format.html) +- Inserting [cross references](/docs/authoring/cross-references.qmd) to tables and figures +- Adding a [citation](/docs/visual-editor/technical.qmd#citations) from a DOI +- Seamlessly switching between output formats as well as creating [multi-format documents](/docs/output-formats/html-multi-format.qmd) - Customizing the [output location](/docs/presentations/revealjs/#output-location) of code in presentations -- Creating a [website](/docs/websites/) from scratch -- Publishing the website to [QuartoPub](/docs/publishing/quarto-pub.html) +- Creating a [website](/docs/websites/index.qmd) from scratch +- Publishing the website to [QuartoPub](/docs/publishing/quarto-pub.qmd) If you would like to follow along as you watch the video, you can find the source code for everything created in the video in [this GitHub repository](https://github.com/mine-cetinkaya-rundel/get-started-quarto) and the published [website on QuartoPub](https://mine.quarto.pub/welcome-to-quarto/). diff --git a/docs/blog/posts/2023-05-22-quarto-for-academics/index.qmd b/docs/blog/posts/2023-05-22-quarto-for-academics/index.qmd index dfd4755532..f5da65e0d3 100644 --- a/docs/blog/posts/2023-05-22-quarto-for-academics/index.qmd +++ b/docs/blog/posts/2023-05-22-quarto-for-academics/index.qmd @@ -17,17 +17,17 @@ Quarto offers a myriad of features that are especially useful for academics, as Select highlights include: -- Linking to documentation from code with [`code-link`](/docs/output-formats/html-code.html#code-linking). +- Linking to documentation from code with [`code-link`](/docs/output-formats/html-code.qmd#code-linking). - Informative YAML errors and YAML completion. -- Creating Quarto slides with [revealjs](/docs/presentations/revealjs/). -- [PDF export](/docs/presentations/revealjs/presenting.html#print-to-pdf) of HTML slides. -- Annotating slides with [`chalkboard`](/docs/presentations/revealjs/presenting.html#chalkboard). -- Advancing slides for your audience with [`multiplex`](/docs/presentations/revealjs/presenting.html#multiplex). +- Creating Quarto slides with [revealjs](/docs/presentations/revealjs/index.qmd). +- [PDF export](/docs/presentations/revealjs/presenting.qmd#print-to-pdf) of HTML slides. +- Annotating slides with [`chalkboard`](/docs/presentations/revealjs/presenting.qmd#chalkboard). +- Advancing slides for your audience with [`multiplex`](/docs/presentations/revealjs/presenting.qmd#multiplex). - Highlighting code with [`code-line-numbers`](/docs/presentations/revealjs/#line-highlighting). -- Customizing output location with [`output-location`](/docs/presentations/revealjs/index.html#output-location). -- Showing code chunk fences with [`echo: fenced`](/docs/computations/execution-options.html#fenced-echo). -- [Code annotation](/docs/authoring/code-annotation.html). -- Authoring manuscripts with Quarto [journal templates](/docs/journals/index.html). -- [Inserting citations](/docs/visual-editor/technical.html#citations) from Zotero or from a DOI with the [RStudio Visual Editor](/docs/visual-editor/). +- Customizing output location with [`output-location`](/docs/presentations/revealjs/index.qmd#output-location). +- Showing code chunk fences with [`echo: fenced`](/docs/computations/execution-options.qmd#fenced-echo). +- [Code annotation](/docs/authoring/code-annotation.qmd). +- Authoring manuscripts with Quarto [journal templates](/docs/journals/index.qmd). +- [Inserting citations](/docs/visual-editor/technical.qmd#citations) from Zotero or from a DOI with the [RStudio Visual Editor](/docs/visual-editor/index.qmd). If you would like to follow along as you watch, you can find the source code for everything created in the video in [this GitHub repository](https://github.com/mine-cetinkaya-rundel/quarto-for-academics). diff --git a/docs/blog/posts/2023-12-07-quarto-dashboards-demo/index.qmd b/docs/blog/posts/2023-12-07-quarto-dashboards-demo/index.qmd index cc61243a7f..3b783bb701 100644 --- a/docs/blog/posts/2023-12-07-quarto-dashboards-demo/index.qmd +++ b/docs/blog/posts/2023-12-07-quarto-dashboards-demo/index.qmd @@ -12,6 +12,6 @@ image-alt: "Quarto logo on a blue background with the title Quarto Dashboards, C Quarto has a host of exciting new features in release v1.4 with one of the most anticipated being Quarto Dashboards. In a recent internal presentation, Charles Teague demonstrated the new capabilities and we wanted to share it with community. -Please note that you can use this feature today, but to access it you need to be running on a recent [Quarto prerelease build](https://quarto.org/docs/download/prerelease.html). We also encourage users to review our [pre-release documentation](https://quarto.org/docs/dashboards/) which offers additional information and examples of the dashboard functionality. +Please note that you can use this feature today, but to access it you need to be running on a recent [Quarto prerelease build](/docs/download/prerelease.qmd). We also encourage users to review our [pre-release documentation](/docs/dashboards/index.qmd) which offers additional information and examples of the dashboard functionality. {{< video “https://www.youtube.com/watch?v=_VGJIPRGTy4&ab_channel=PositPBC” >}} diff --git a/docs/blog/posts/2024-01-24-1.4-release/index.qmd b/docs/blog/posts/2024-01-24-1.4-release/index.qmd index 9c6cc90272..4b29403d0b 100644 --- a/docs/blog/posts/2024-01-24-1.4-release/index.qmd +++ b/docs/blog/posts/2024-01-24-1.4-release/index.qmd @@ -142,9 +142,9 @@ Cross-references have been overhauled in Quarto 1.4, enabling you to do things l And notice if you hover over the reference as it appears in the text, e.g. hover over this link to @tbl-table, you'll get a floating preview of the content---that's new too. -* Define [custom types of float cross-reference](/docs/authoring/cross-references-custom.qmd), which you could use to create cross-references to Videos, Diagrams or [Supplemental Figures](https://quarto.org/docs/authoring/cross-references-custom.html#example-supplemental-figures). +* Define [custom types of float cross-reference](/docs/authoring/cross-references-custom.qmd), which you could use to create cross-references to Videos, Diagrams or [Supplemental Figures](/docs/authoring/cross-references-custom.qmd#example-supplemental-figures). -* Cross-reference [executable code cells](/docs/authoring/cross-references.qmd#code-listings), [callouts](/docs/authoring/cross-references.qmd#callouts) and [remarks and solutions](/docs/authoring/cross-references.html#theorems-and-proofs). +* Cross-reference [executable code cells](/docs/authoring/cross-references.qmd#code-listings), [callouts](/docs/authoring/cross-references.qmd#callouts) and [remarks and solutions](/docs/authoring/cross-references.qmd#theorems-and-proofs). ## Manuscripts @@ -184,7 +184,7 @@ If you build Quarto extensions, you should also be aware of some developer-facin - [AST processing changes](/docs/prerelease/1.4/ast.qmd)---Improvements to the HTML table processing added in v1.3 and a way for LaTeX raw blocks to include Quarto-compatible markdown for processing. -You can find all the other changes in 1.4 in the [Release Notes](https://quarto.org/docs/download/#download-section-news). +You can find all the other changes in 1.4 in the [Release Notes](/docs/download/#download-section-news). ## Acknowledgements @@ -192,4 +192,4 @@ We'd like to say a huge thank you to everyone who contributed to this release by {{< include _contribs.md >}} -The party popper emoji in the [listing and social card image](images/thumbnail.png) for this post comes from [OpenMoji](https://openmoji.org/){.external}– the open-source emoji and icon project. License: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/#){.external} \ No newline at end of file +The party popper emoji in the [listing and social card image](images/thumbnail.png) for this post comes from [OpenMoji](https://openmoji.org/){.external}– the open-source emoji and icon project. License: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/#){.external} diff --git a/docs/computations/_caching-more.md b/docs/computations/_caching-more.md index 63257b874e..f14ae3b803 100644 --- a/docs/computations/_caching-more.md +++ b/docs/computations/_caching-more.md @@ -38,4 +38,4 @@ If you are working within a project and your main concern is the cumulative impa {{< include ../projects/_freeze-basics.md >}} -Learn more about using `freeze` with projects in the article on [managing project execution](https://quarto.org/docs/projects/code-execution.html#freeze). +Learn more about using `freeze` with projects in the article on [managing project execution](/docs/projects/code-execution.qmd#freeze). diff --git a/docs/computations/caching.qmd b/docs/computations/caching.qmd index 3871e4c6d4..2d2611b945 100644 --- a/docs/computations/caching.qmd +++ b/docs/computations/caching.qmd @@ -89,7 +89,7 @@ You can also enable caching on a per-cell basis (in this you would *not* set the summary(cars) ``` -There are a variety of other cell-level options that affect Knitr caching behavior. You can learn about them in the Knitr [cell options](https://quarto.org/docs/reference/cells/cells-knitr.html#cache) reference. Another excellent resource is Yihui Xie's article on [cache invalidation](https://yihui.org/en/2018/06/cache-invalidation/). +There are a variety of other cell-level options that affect Knitr caching behavior. You can learn about them in the Knitr [cell options](/docs/reference/cells/cells-knitr.qmd#cache) reference. Another excellent resource is Yihui Xie's article on [cache invalidation](https://yihui.org/en/2018/06/cache-invalidation/). ## Rendering @@ -132,4 +132,4 @@ If you are working within a project and your main concern is the cumulative impa {{< include ../projects/_freeze-basics.md >}} -Learn more about using `freeze` with projects in the article on [managing project execution](https://quarto.org/docs/projects/code-execution.html#freeze). +Learn more about using `freeze` with projects in the article on [managing project execution](/docs/projects/code-execution.qmd#freeze). diff --git a/docs/computations/execution-options.qmd b/docs/computations/execution-options.qmd index 19a045f3b8..e9c1f5971b 100644 --- a/docs/computations/execution-options.qmd +++ b/docs/computations/execution-options.qmd @@ -250,7 +250,7 @@ Now the above code cell results in the output: ::: callout-note ## All Expressions are Printed in Dashboards -For [dashboards](/docs/dashboards/) the default setting of `ipynb-shell-interactivity` is `all.` +For [dashboards](/docs/dashboards/index.qmd) the default setting of `ipynb-shell-interactivity` is `all.` ::: ## Intermediates @@ -417,4 +417,4 @@ echo "foo" ``` ```` -Note that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document \ No newline at end of file +Note that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document diff --git a/docs/computations/r.qmd b/docs/computations/r.qmd index ca932d1ced..db04d75a64 100644 --- a/docs/computations/r.qmd +++ b/docs/computations/r.qmd @@ -217,7 +217,6 @@ You can also enable caching on a per-cell basis (in this you would *not* set the summary(cars) ``` -There are a variety of other cell-level options that affect Knitr caching behavior. You can learn about them in the Knitr [cell options](https://quarto.org/docs/reference/cells/cells-knitr.html#cache) reference. Another excellent resource is Yihui Xie's article on [cache invalidation](https://yihui.org/en/2018/06/cache-invalidation/). +There are a variety of other cell-level options that affect Knitr caching behavior. You can learn about them in the Knitr [cell options](/docs/reference/cells/cells-knitr.qmd#cache) reference. Another excellent resource is Yihui Xie's article on [cache invalidation](https://yihui.org/en/2018/06/cache-invalidation/). {{< include _caching-more.md >}} - diff --git a/docs/dashboards/layout.qmd b/docs/dashboards/layout.qmd index 7b4b412ed9..2ff6e41e35 100644 --- a/docs/dashboards/layout.qmd +++ b/docs/dashboards/layout.qmd @@ -29,7 +29,7 @@ format: --- ``` -The following special aliases are recognized for navigation buttons: `linkedin`, `facebook`, `reddit`, `twitter`, and `github`. You can also create custom buttons as described in [Nav Items](/docs/reference/projects/websites.html#nav-items). For example: +The following special aliases are recognized for navigation buttons: `linkedin`, `facebook`, `reddit`, `twitter`, and `github`. You can also create custom buttons as described in [Nav Items](/docs/reference/projects/websites.qmd#nav-items). For example: ```` yaml format: @@ -399,5 +399,3 @@ Quarto inspects card contents and generally choose a fill behavior that best mat [Deployment](deployment.qmd) covers how to deploy both static dashboards (which require only a web host, but not a server) and Shiny dashboards (which require a Shiny Server). [Interactivity](interactivity/index.qmd) explores the various ways to create interactive dashboards that enable more flexible data exploration. - - diff --git a/docs/extensions/lua.qmd b/docs/extensions/lua.qmd index a913da5a72..f7b01a654e 100644 --- a/docs/extensions/lua.qmd +++ b/docs/extensions/lua.qmd @@ -66,7 +66,7 @@ Diagnostics check for many common errors including failing to check for `nil`, u To get started with using VS Code for Lua extension development, install the following software: -1. Install the latest version (v1.2 or greater) of [Quarto](https://quarto.org/docs/download/) +1. Install the latest version (v1.2 or greater) of [Quarto](/docs/download/index.qmd) 2. Install the latest version (v1.40.0 or greater) of the [Quarto VS Code Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto). diff --git a/docs/faq/index.qmd b/docs/faq/index.qmd index 1121bc4e73..d8c3aa1e82 100644 --- a/docs/faq/index.qmd +++ b/docs/faq/index.qmd @@ -10,7 +10,7 @@ Quarto® is an open-source scientific and technical publishing system built on P ### How do I install Quarto? -Visit the Quarto.org [Get Started page](https://quarto.org/docs/get-started/), which provides installation instructions for Windows, Mac OS, and Linux. \ +Visit the Quarto.org [Get Started page](/docs/get-started/index.qmd), which provides installation instructions for Windows, Mac OS, and Linux. \ ### Is Quarto free to use? @@ -18,25 +18,25 @@ Yes! Quarto is [open source](https://quarto.org/license.html). Quarto version 1. ### What output formats can Quarto create? -There are many output formats available in Quarto. This includes all of the built in Pandoc formats (e.g. HTML, PDF, MS Word, Revealjs, ePub, etc.) as well as various ways to publish multiple documents (websites, blogs, and books). Learn more at [Quarto Formats](https://quarto.org/docs/output-formats/all-formats.html).  +There are many output formats available in Quarto. This includes all of the built in Pandoc formats (e.g. HTML, PDF, MS Word, Revealjs, ePub, etc.) as well as various ways to publish multiple documents (websites, blogs, and books). Learn more at [Quarto Formats](/docs/output-formats/all-formats.qmd).  ### What editing tools can I use with Quarto? -You can use a wide variety of tools with Quarto. We have provided documentation for writing and editing Quarto documents in VSCode, JupyterLab, RStudio IDE, or any text editor. Visit the [Get Started with Quarto page](https://quarto.org/docs/get-started/) to install, and then choose your tool for a brief introductory guide. +You can use a wide variety of tools with Quarto. We have provided documentation for writing and editing Quarto documents in VSCode, JupyterLab, RStudio IDE, or any text editor. Visit the [Get Started with Quarto page](/docs/get-started/index.qmd) to install, and then choose your tool for a brief introductory guide. ### Can I use Jupyter notebooks with Quarto? -Yes! Quarto can [render Jupyter notebooks](https://quarto.org/docs/tools/jupyter-lab.html) and you can use Jupyter, JupyterLab or any other .ipynb notebook editor with Quarto. You can render existing .ipynb notebooks as-is with Quarto, but adding Quarto-specific output options or a YAML header can enhance the output. Visit the[JupyterLab page](https://quarto.org/docs/tools/jupyter-lab.html) for more information. +Yes! Quarto can [render Jupyter notebooks](/docs/tools/jupyter-lab.qmd) and you can use Jupyter, JupyterLab or any other .ipynb notebook editor with Quarto. You can render existing .ipynb notebooks as-is with Quarto, but adding Quarto-specific output options or a YAML header can enhance the output. Visit the[JupyterLab page](/docs/tools/jupyter-lab.qmd) for more information. ### What programming languages are supported in Quarto? The principal languages supported by Quarto are Python, R, Julia, and Observable JavaScript. Integration with Jupyter also enables the use of many other languages.  -Each Quarto document can be optionally processed by a computational engine (the engine can be manually specified or automatically detected based on the code chunks within). Current engines include Knitr (which is also used by R Markdown and supports [a variety of languages](https://bookdown.org/yihui/rmarkdown-cookbook/other-languages.html) including R, Python, and Julia, etc.) and Jupyter (which supports many languages including Python, Julia, and R). See the documentation on [Engine Binding](https://quarto.org/docs/computations/execution-options.html#engine-binding) for additional details. +Each Quarto document can be optionally processed by a computational engine (the engine can be manually specified or automatically detected based on the code chunks within). Current engines include Knitr (which is also used by R Markdown and supports [a variety of languages](https://bookdown.org/yihui/rmarkdown-cookbook/other-languages.html) including R, Python, and Julia, etc.) and Jupyter (which supports many languages including Python, Julia, and R). See the documentation on [Engine Binding](/docs/computations/execution-options.qmd#engine-binding) for additional details. ### What human languages are supported in Quarto? -You can write your Quarto documentation in your human language of choice. The [lang](https://pandoc.org/MANUAL.html#language-variables) [document option](https://quarto.org/docs/authoring/language.html#lang-option) is used to identify the main language of the document using IETF language tags (following the [BCP 47 standard](https://tools.ietf.org/html/bcp47)), such as en or en-GB.  +You can write your Quarto documentation in your human language of choice. The [lang](https://pandoc.org/MANUAL.html#language-variables) [document option](/docs/authoring/language.qmd#lang-option) is used to identify the main language of the document using IETF language tags (following the [BCP 47 standard](https://tools.ietf.org/html/bcp47)), such as en or en-GB.  ### Can I use Quarto to develop proprietary content? @@ -48,7 +48,7 @@ It covers the styles or functionalities themselves. It does not cover your orig ### How can I share documents and have people comment on them? -You can publish Quarto content to various locations. See the user guides for [publishing](https://quarto.org/docs/publishing/) for details on using Quarto Pub, GitHub Pages, Netlify, Posit Connect, and other services with Quarto. Once documents are published you can use  [hypothes.is](https://web.hypothes.is/), [Utterances](https://utteranc.es/), or [Giscus](https://giscus.app/) for commenting. Learn more in the documentation on [commenting](https://quarto.org/docs/output-formats/html-basics.html#commenting). +You can publish Quarto content to various locations. See the user guides for [publishing](/docs/publishing/index.qmd) for details on using Quarto Pub, GitHub Pages, Netlify, Posit Connect, and other services with Quarto. Once documents are published you can use  [hypothes.is](https://web.hypothes.is/), [Utterances](https://utteranc.es/), or [Giscus](https://giscus.app/) for commenting. Learn more in the documentation on [commenting](/docs/output-formats/html-basics.qmd#commenting). ### Can I do collaborative editing with Quarto? @@ -60,11 +60,11 @@ Posit Workbench allows for [Project Sharing](https://support.rstudio.com/hc/en-u There are a wide variety of ways to publish Quarto websites. Website content is by default written to the `\_site` sub-directory (you can customize this using the output-dir option). Publishing is simply a matter of copying the output directory to a web server or web hosting service. -The [publishing documentation](https://quarto.org/docs/publishing/other.html) describes several convenient options for Quarto website deployment including Posit Connect, Netlify, GitHub Pages, Firebase, Site44, and Amazon S3. We'll mostly defer to the documentation provided by those various services, but will note any Quarto website specific configuration required. +The [publishing documentation](/docs/publishing/other.qmd) describes several convenient options for Quarto website deployment including Posit Connect, Netlify, GitHub Pages, Firebase, Site44, and Amazon S3. We'll mostly defer to the documentation provided by those various services, but will note any Quarto website specific configuration required. ### Does Posit Connect support Quarto? -Yes! You can publish Quarto content to Posit Connect v2021.08.0 or later. Quarto has to be enabled as documented in the Posit Connect [admin guide](https://docs.rstudio.com/connect/admin/appendix/configuration/#Quarto). Connect's user [documentation](https://docs.rstudio.com/connect/user/quarto/) refers to [Quarto.org docs](https://quarto.org/docs/websites/publishing-websites.html#rstudio-connect) on how to publish from the RStudio IDE. To publish Python-based Quarto content, you can use the [rsconnect-python CLI](https://docs.rstudio.com/rsconnect-python/) from various locations, including VSCode, JupyterLab or the terminal. +Yes! You can publish Quarto content to Posit Connect v2021.08.0 or later. Quarto has to be enabled as documented in the Posit Connect [admin guide](https://docs.rstudio.com/connect/admin/appendix/configuration/#Quarto). Connect's user [documentation](https://docs.rstudio.com/connect/user/quarto/) refers to [Quarto.org docs](/docs/websites/publishing-websites.qmd#rstudio-connect) on how to publish from the RStudio IDE. To publish Python-based Quarto content, you can use the [rsconnect-python CLI](https://docs.rstudio.com/rsconnect-python/) from various locations, including VSCode, JupyterLab or the terminal. ### Who are the developers of Quarto? diff --git a/docs/faq/rmarkdown.qmd b/docs/faq/rmarkdown.qmd index 502440ffee..59d4104b39 100644 --- a/docs/faq/rmarkdown.qmd +++ b/docs/faq/rmarkdown.qmd @@ -41,33 +41,33 @@ Here are the Quarto equivalents for various packages and features of the R Markd +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | Feature | R Markdown | Quarto | +=======================+==========================================================================================================+====================================================================================+ -| Basic Formats | - [html_document](https://pkgs.rstudio.com/rmarkdown/reference/html_document.html) | - [html](https://quarto.org/docs/output-formats/html-basics.html) | -| | - [pdf_document](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) | - [pdf](https://quarto.org/docs/output-formats/pdf-basics.html) | -| | - [word_document](https://pkgs.rstudio.com/rmarkdown/reference/word_document.html) | - [docx](https://quarto.org/docs/output-formats/ms-word.html) | +| Basic Formats | - [html_document](https://pkgs.rstudio.com/rmarkdown/reference/html_document.html) | - [html](/docs/output-formats/html-basics.qmd) | +| | - [pdf_document](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) | - [pdf](/docs/output-formats/pdf-basics.qmd) | +| | - [word_document](https://pkgs.rstudio.com/rmarkdown/reference/word_document.html) | - [docx](/docs/output-formats/ms-word.qmd) | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Beamer | - [beamer_presentation](https://pkgs.rstudio.com/rmarkdown/reference/beamer_presentation.html) | - [beamer](https://quarto.org/docs/presentations/beamer.html) | +| Beamer | - [beamer_presentation](https://pkgs.rstudio.com/rmarkdown/reference/beamer_presentation.html) | - [beamer](/docs/presentations/beamer.qmd) | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| PowerPoint | - [powerpoint_presentation](https://pkgs.rstudio.com/rmarkdown/reference/powerpoint_presentation.html) | - [pptx](https://quarto.org/docs/presentations/powerpoint.html) | +| PowerPoint | - [powerpoint_presentation](https://pkgs.rstudio.com/rmarkdown/reference/powerpoint_presentation.html) | - [pptx](/docs/presentations/powerpoint.qmd) | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| HTML Slides | - [xaringan](https://bookdown.org/yihui/rmarkdown/xaringan.html) | - [revealjs](https://quarto.org/docs/presentations/revealjs/) | +| HTML Slides | - [xaringan](https://bookdown.org/yihui/rmarkdown/xaringan.html) | - [revealjs](/docs/presentations/revealjs/index.qmd) | | | - [ioslides](https://bookdown.org/yihui/rmarkdown/ioslides-presentation.html) | | | | - [revealjs](https://bookdown.org/yihui/rmarkdown/revealjs.html) | | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Advanced Layout | - [tufte](https://bookdown.org/yihui/rmarkdown/tufte-handouts.html) | - [Quarto Article Layout](https://quarto.org/docs/authoring/article-layout.html) | +| Advanced Layout | - [tufte](https://bookdown.org/yihui/rmarkdown/tufte-handouts.html) | - [Quarto Article Layout](/docs/authoring/article-layout.qmd) | | | - [distill](https://rstudio.github.io/distill/figures.html) | | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Cross References | - [html_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | - [Quarto Crossrefs](https://quarto.org/docs/authoring/cross-references.html) | +| Cross References | - [html_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | - [Quarto Crossrefs](/docs/authoring/cross-references.qmd) | | | - [pdf_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | | | | - [word_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Websites & Blogs | - [blogdown](https://pkgs.rstudio.com/blogdown/) | - [Quarto Websites](https://quarto.org/docs/websites/) | -| | - [distill](https://pkgs.rstudio.com/distill/) | - [Quarto Blogs](https://quarto.org/docs/websites/website-blog.html) | +| Websites & Blogs | - [blogdown](https://pkgs.rstudio.com/blogdown/) | - [Quarto Websites](/docs/websites/index.qmd) | +| | - [distill](https://pkgs.rstudio.com/distill/) | - [Quarto Blogs](/docs/websites/website-blog.qmd) | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Books | - [bookdown](https://pkgs.rstudio.com/bookdown/) | - [Quarto Books](https://quarto.org/docs/books/) | +| Books | - [bookdown](https://pkgs.rstudio.com/bookdown/) | - [Quarto Books](/docs/books/index.qmd) | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Interactivity | [Shiny Documents](https://bookdown.org/yihui/rmarkdown/shiny-documents.html) | [Quarto Interactive Documents](https://quarto.org/docs/interactive/shiny/) | +| Interactivity | [Shiny Documents](https://bookdown.org/yihui/rmarkdown/shiny-documents.html) | [Quarto Interactive Documents](/docs/interactive/shiny/index.qmd) | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Journal Articles | [rticles](https://pkgs.rstudio.com/rticles/) | [Quarto Journal Articles](https://quarto.org/docs/journals/) | +| Journal Articles | [rticles](https://pkgs.rstudio.com/rticles/) | [Quarto Journal Articles](/docs/journals/index.qmd) | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ | Paged HTML | [pagedown](https://github.com/rstudio/pagedown) | Planned | +-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ @@ -79,23 +79,23 @@ Here are the Quarto equivalents for various packages and features of the R Markd ### Can you create custom formats for Quarto like you can for R Markdown? -Quarto offers an [Extension](https://quarto.org/docs/extensions/) mechanism to add features to a format using [Shortcodes](https://quarto.org/docs/extensions/#using-shortcodes) or [Filters](https://quarto.org/docs/extensions/#using-filters) but also create [custom formats](https://quarto.org/docs/extensions/formats.html). A major difference with custom output format in R Markdown is that Quarto Extension does not use R but Lua, for example if you need to add some logic behind custom metadata fields. See [Developing with Lua](https://quarto.org/docs/extensions/lua.html) to get started if you need use it your extension. -Some of the features from R Markdown custom formats like customizing knitting behavior can also now be done in YAML with [execution options](https://quarto.org/docs/computations/execution-options.html#knitr-options). +Quarto offers an [Extension](/docs/extensions/index.qmd) mechanism to add features to a format using [Shortcodes](/docs/extensions/#using-shortcodes) or [Filters](/docs/extensions/#using-filters) but also create [custom formats](/docs/extensions/formats.qmd). A major difference with custom output format in R Markdown is that Quarto Extension does not use R but Lua, for example if you need to add some logic behind custom metadata fields. See [Developing with Lua](/docs/extensions/lua.qmd) to get started if you need use it your extension. +Some of the features from R Markdown custom formats like customizing knitting behavior can also now be done in YAML with [execution options](/docs/computations/execution-options.qmd#knitr-options). -As example of custom formats for Quarto, [Journal Articles](https://quarto.org/docs/journals/) for Quarto are port of some custom output format inside the **rticles** R package. Extensions lives in [Quarto Journals](https://github.com/quarto-journals/) Github organization, and you can find information on how to [customize templates](https://quarto.org/docs/journals/templates.html) and [manage Authors](https://quarto.org/docs/journals/authors.html) for you format. +As example of custom formats for Quarto, [Journal Articles](/docs/journals/index.qmd) for Quarto are port of some custom output format inside the **rticles** R package. Extensions lives in [Quarto Journals](https://github.com/quarto-journals/) Github organization, and you can find information on how to [customize templates](/docs/journals/templates.qmd) and [manage Authors](/docs/journals/authors.qmd) for you format. If you are an advanced developer of R Markdown custom format, the Extension mechanism may still have limitation (like pre and post processor). The Extension feature in Quarto will be improved over time - do not hesitate to share with us your use case or wished in our [Discussion Board](https://github.com/quarto-dev/quarto-cli/discussions). ### When would be a good time to start new projects in Quarto rather than R Markdown? -Quarto v1.0 was [announced at rstudio::conf(2022)](https://www.rstudio.com/blog/announcing-quarto-a-new-scientific-and-technical-publishing-system/). This is the first stable release which is already an excellent foundation for starting new projects with Quarto or migrating existing R Markdown projects ([if you are so inclined](https://quarto.org/docs/faq/rmarkdown.html#is-r-markdown-going-away-will-my-r-markdown-documents-continue-to-work)). If you start using Quarto, please do stay updated with [latest release and changes](https://quarto.org/docs/download/) as development is very active. +Quarto v1.0 was [announced at rstudio::conf(2022)](https://www.rstudio.com/blog/announcing-quarto-a-new-scientific-and-technical-publishing-system/). This is the first stable release which is already an excellent foundation for starting new projects with Quarto or migrating existing R Markdown projects ([if you are so inclined](/docs/faq/rmarkdown.qmd#is-r-markdown-going-away-will-my-r-markdown-documents-continue-to-work)). If you start using Quarto, please do stay updated with [latest release and changes](/docs/download/index.qmd) as development is very active. ### Does the RStudio IDE support Quarto? -Yes! You need to use RStudio {{< var rstudio.min_version >}} or a later version, which includes support for [editing and preview of Quarto documents](https://quarto.org/docs/tools/rstudio.html). +Yes! You need to use RStudio {{< var rstudio.min_version >}} or a later version, which includes support for [editing and preview of Quarto documents](/docs/tools/rstudio.qmd). You can download the latest release ({{< var rstudio.current_release >}}) of RStudio from . ### Does Posit Connect support Quarto? -Yes! You can publish Quarto content to Posit Connect v2021.08.0 or later. Quarto has to be enabled as documented in the Posit Connect [admin guide](https://docs.rstudio.com/connect/admin/appendix/configuration/#Quarto). Connect's user [documentation](https://docs.rstudio.com/connect/user/quarto/) refers to [Quarto.org docs](https://quarto.org/docs/websites/publishing-websites.html#rstudio-connect) on how to publish from the RStudio IDE. To publish Python-based Quarto content, you can use the [rsconnect-python CLI](https://docs.rstudio.com/rsconnect-python/) from various locations, including VSCode, JupyterLab or the terminal. +Yes! You can publish Quarto content to Posit Connect v2021.08.0 or later. Quarto has to be enabled as documented in the Posit Connect [admin guide](https://docs.rstudio.com/connect/admin/appendix/configuration/#Quarto). Connect's user [documentation](https://docs.rstudio.com/connect/user/quarto/) refers to [Quarto.org docs](/docs/websites/publishing-websites.qmd#rstudio-connect) on how to publish from the RStudio IDE. To publish Python-based Quarto content, you can use the [rsconnect-python CLI](https://docs.rstudio.com/rsconnect-python/) from various locations, including VSCode, JupyterLab or the terminal. diff --git a/docs/get-started/authoring/_text-editor.md b/docs/get-started/authoring/_text-editor.md index 331cfe2bcd..373ad98ef4 100644 --- a/docs/get-started/authoring/_text-editor.md +++ b/docs/get-started/authoring/_text-editor.md @@ -354,8 +354,6 @@ Here is what this document looks like when rendered. ![](images/layout-render.png){.border fig-alt="Document with Quarto Layout title at the top followed by Placing Colorbars header with text below it. Next to the text is a footnote in the page margin. Below the text is a toggleable code widget to hide/reveal the code followed by four plots displayed in two rows and two columns."} -You can locate citations, footnotes, and [asides](https://quarto.org/docs/authoring/article-layout.html#asides) in the margin. You can also define custom column spans for figures, tables, or other content. See the documentation on [Article Layout](/docs/authoring/article-layout.qmd) for additional details. +You can locate citations, footnotes, and [asides](/docs/authoring/article-layout.html#asides) in the margin. You can also define custom column spans for figures, tables, or other content. See the documentation on [Article Layout](/docs/authoring/article-layout.qmd) for additional details. {{< include _footer.md >}} - - diff --git a/docs/get-started/authoring/jupyter.qmd b/docs/get-started/authoring/jupyter.qmd index c367b38233..ad45e92589 100644 --- a/docs/get-started/authoring/jupyter.qmd +++ b/docs/get-started/authoring/jupyter.qmd @@ -228,7 +228,7 @@ Equations are rendered when you run the cell. Inline equations are delimited with `$…$`. To create equations in a new line (display equation) use `$$…$$`. -See the documentation on [markdown equations](/docs/authoring/markdown-basics.html#equations) for additional details. +See the documentation on [markdown equations](/docs/authoring/markdown-basics.qmd#equations) for additional details. ## Citations @@ -430,7 +430,7 @@ Here is what this document looks like when rendered. ![](images/layout-render.png){.border fig-alt="Document with Quarto Layout title at the top followed by Placing Colorbars header with text below it. Next to the text is a footnote in the page margin. Below the text is a toggleable code widget to hide/reveal the code followed by four plots displayed in two rows and two columns."} -You can locate citations, footnotes, and [asides](https://quarto.org/docs/authoring/article-layout.html#asides,) in the margin. +You can locate citations, footnotes, and [asides](/docs/authoring/article-layout.qmd#asides,) in the margin. You can also define custom column spans for figures, tables, or other content. See the documentation on [Article Layout](/docs/authoring/article-layout.qmd) for additional details. diff --git a/docs/get-started/authoring/rstudio.qmd b/docs/get-started/authoring/rstudio.qmd index 44458bc070..e2ccfce318 100644 --- a/docs/get-started/authoring/rstudio.qmd +++ b/docs/get-started/authoring/rstudio.qmd @@ -12,7 +12,7 @@ editor_options: In this tutorial we'll show you how to author Quarto documents in RStudio. In particular, we'll discuss the various document formats you can produce with the same source code and show you how to add components like table of contents, equations, citations, etc. -The [visual markdown editor](/docs/visual-editor/) in RStudio makes many of these tasks easier so we'll highlight its use in this tutorial, but note that it's possible to accomplish these tasks in the source editor as well. +The [visual markdown editor](/docs/visual-editor/index.qmd) in RStudio makes many of these tasks easier so we'll highlight its use in this tutorial, but note that it's possible to accomplish these tasks in the source editor as well. If you would like to follow along step-by-step in your own environment, make sure that you have the [latest release](https://posit.co/download/rstudio-desktop/) of RStudio ({{< var rstudio.current_release >}}), which you can download [here](https://posit.co/download/rstudio-desktop/), installed. @@ -99,7 +99,7 @@ Otherwise render the document to see your updates reflected, including a table o An incredibly exciting format option that we won't go into too much detail in this tutorial is `revealjs`. Yes, you can make presentations with Quarto as well! In fact, Quarto supports a variety of formats for creating presentations, including `revealjs` for HTML slides, `pptx` for PowerPoint, and `beamer` for LaTeX/PDF. -The [Presentations](/docs/presentations/) article gives a thorough walk through of creating slide decks with Quarto. +The [Presentations](/docs/presentations/index.qmd) article gives a thorough walk through of creating slide decks with Quarto. ### Multiple Formats @@ -239,7 +239,7 @@ price = \hat{\beta}_0 + \hat{\beta}_1 \times area + \epsilon ``` RStudio displays a rendered version of the tutorial as you type it in the editor. -See the documentation on [markdown equations](/docs/authoring/markdown-basics.html#equations) for additional details. +See the documentation on [markdown equations](/docs/authoring/markdown-basics.qmd#equations) for additional details. ![](/docs/get-started/authoring/images/rstudio-equation-render.png){.border} @@ -422,7 +422,7 @@ quarto::quarto_publish_doc( ``` Other possible publishing options include RStudio Connect and ShinyApps as well as GitHub Pages, Netlify, etc. -The [Publishing HTML](/docs/output-formats/html-publishing.html) article gives a much more detailed overview of your publishing options. +The [Publishing HTML](/docs/output-formats/html-publishing.qmd) article gives a much more detailed overview of your publishing options. If you followed along step-by-step with this tutorial, you should now have a Quarto document that implements everything we covered. Otherwise, you can download a completed version of `computations.qmd` below. diff --git a/docs/get-started/computations/jupyter.qmd b/docs/get-started/computations/jupyter.qmd index 650d1f281c..68823a390b 100644 --- a/docs/get-started/computations/jupyter.qmd +++ b/docs/get-started/computations/jupyter.qmd @@ -154,7 +154,7 @@ Save the notebook and note that the code is now included for the NumPy cell. There a large number of other options available for cell output, for example `warning` to show/hide warnings (which can be especially helpful for package loading messages), `include` as a catch all for preventing any output (code or results) from being included in output, and `error` to prevent errors in code execution from halting the rendering of the document (and print the error in the rendered document). -See the [Jupyter Cell Options](https://quarto.org/docs/reference/cells/cells-jupyter.html) documentation for additional details. +See the [Jupyter Cell Options](/docs/reference/cells/cells-jupyter.qmd) documentation for additional details. ## Code Folding diff --git a/docs/get-started/computations/rstudio.qmd b/docs/get-started/computations/rstudio.qmd index c3f13c5829..4b16b13287 100644 --- a/docs/get-started/computations/rstudio.qmd +++ b/docs/get-started/computations/rstudio.qmd @@ -68,11 +68,11 @@ Save the document again and note that the code is now included for the `scatterp The `echo` option can be set to `true`, `false`, or `fenced`. The last one might be of special interest for writing documentation and teaching materials as it allows you to include the fenced code delimiter in your code output to emphasize that executable code requires that delimiter. -You can read more about this option in the [Fenced Echo](https://quarto.org/docs/computations/execution-options.html#fenced-echo) documentation. +You can read more about this option in the [Fenced Echo](/docs/computations/execution-options.qmd#fenced-echo) documentation. There are a large number of other options available for cell output, for example `warning` for showing/hiding warnings (which can be especially helpful for package loading messages), `include` as a catch all for preventing any output (code or results) from being included in output, and `error` to prevent errors in code execution from halting the rendering of the document (and print the error in the rendered document). -See the [Knitr Cell Options](https://quarto.org/docs/reference/cells/cells-knitr.html) documentation for additional details. +See the [Knitr Cell Options](/docs/reference/cells/cells-knitr.qmd) documentation for additional details. ## Code Folding @@ -147,7 +147,7 @@ We'll add the following chunk options. ``` Save the document to see the updated plot. -Note that we have also updated the narrative with a [cross reference](https://quarto.org/docs/authoring/cross-references.html#computations) to this figure using the following. +Note that we have also updated the narrative with a [cross reference](/docs/authoring/cross-references.qmd#computations) to this figure using the following. ``` markdown @fig-scatterplot shows a positive, strong, and linear relationship between the city and highway mileage of these cars. @@ -297,7 +297,7 @@ You can also indicate which chunks should be cached directly with using a chunk Try adding this chunk option to one of the code chunks in your document that produces a plot and save. When the document is rendered, you'll see that a new folder has been created in your working directory with the same name as your document and the suffix `_cache`. This folder contains the cached results. -You can find out more about caching in Quarto documents in the [Cache](https://quarto.org/docs/projects/code-execution.html#cache) documentation. +You can find out more about caching in Quarto documents in the [Cache](/docs/projects/code-execution.qmd#cache) documentation. If you followed along step-by-step with this tutorial, you should now have a Quarto document that implements everything we covered. Otherwise, you can download a completed version of `computations.qmd` below. diff --git a/docs/get-started/computations/text-editor.qmd b/docs/get-started/computations/text-editor.qmd index c6e91c744d..d23b3ed695 100644 --- a/docs/get-started/computations/text-editor.qmd +++ b/docs/get-started/computations/text-editor.qmd @@ -131,7 +131,7 @@ Save the file and note that the code is now included for the NumPy cell. There a large number of other options available for cell output, for example `warning` to show/hide warnings (which can be especially helpful for package loading messages), `include` as a catch all for preventing any output (code or results) from being included in output, and `error` to prevent errors in code execution from halting the rendering of the document (and print the error in the rendered document). -See the [Jupyter Cell Options](https://quarto.org/docs/reference/cells/cells-jupyter.html) documentation for additional details. +See the [Jupyter Cell Options](/docs/reference/cells/cells-jupyter.qmd) documentation for additional details. ## Code Folding diff --git a/docs/get-started/computations/vscode.qmd b/docs/get-started/computations/vscode.qmd index fdc92e5f05..a1522f4513 100644 --- a/docs/get-started/computations/vscode.qmd +++ b/docs/get-started/computations/vscode.qmd @@ -155,7 +155,7 @@ Re-render note that the code is now included for the NumPy cell. There a large number of other options available for cell output, for example `warning` to show/hide warnings (which can be especially helpful for package loading messages), `include` as a catch all for preventing any output (code or results) from being included in output, and `error` to prevent errors in code execution from halting the rendering of the document (and print the error in the rendered document). -See the [Jupyter Cell Options](https://quarto.org/docs/reference/cells/cells-jupyter.html) documentation for additional details. +See the [Jupyter Cell Options](/docs/reference/cells/cells-jupyter.qmd) documentation for additional details. ## Code Folding diff --git a/docs/get-started/hello/jupyter.qmd b/docs/get-started/hello/jupyter.qmd index 6e6e2f95b9..4b1cd2e9f6 100644 --- a/docs/get-started/hello/jupyter.qmd +++ b/docs/get-started/hello/jupyter.qmd @@ -18,7 +18,7 @@ Below is an overview of how this will look. ![](images/jupyter-quarto-preview.png){fig-alt="On the left: A Jupyter notebook titled Quarto Basics containing some text, a code cell, and the result of the code cell, which is a line plot on a polar axis. On the right: Rendered version of the same notebook."} The notebook on the left is *rendered* into the HTML version you see on the right. -This is the basic model for Quarto publishing---take a source document (in this case a notebook) and render it to a variety of [output formats](https://quarto.org/docs/output-formats/all-formats.html), including HTML, PDF, MS Word, etc. +This is the basic model for Quarto publishing---take a source document (in this case a notebook) and render it to a variety of [output formats](/docs/output-formats/all-formats.qmd), including HTML, PDF, MS Word, etc. ::: callout-note Note that while this tutorial uses Python, using Julia (via the [IJulia](https://julialang.github.io/IJulia.jl/stable/) kernel) is also well supported. diff --git a/docs/get-started/hello/neovim.qmd b/docs/get-started/hello/neovim.qmd index 9f449af7da..7320f53f0b 100644 --- a/docs/get-started/hello/neovim.qmd +++ b/docs/get-started/hello/neovim.qmd @@ -55,7 +55,7 @@ Here's what it might look like in Neovim to edit and preview a `.qmd` file: ![](./images/neovim-overview.png){.border fig-alt="Three windows arranged side by side. The window on the left is a qmd file opened in Neovim. The upper window on the right is a web browser. The contents of the qmd document are rendered by Quarto in the browser window. The third window is a rendered graph showing the output of executing a code chunk in the qmd file."} The document on the right is *rendered* into the HTML version you see on the left. -This is the basic model for Quarto publishing---take a source document and render it to a variety of [output formats](https://quarto.org/docs/output-formats/all-formats.html), including HTML, PDF, MS Word, etc. +This is the basic model for Quarto publishing---take a source document and render it to a variety of [output formats](/docs/output-formats/all-formats.qmd), including HTML, PDF, MS Word, etc. The tutorials will make use of the `matplotlib` and `plotly` Python packages---the commands you can use to install them are given in the table below. diff --git a/docs/get-started/hello/rstudio.qmd b/docs/get-started/hello/rstudio.qmd index 0449ad6407..34f02bc327 100644 --- a/docs/get-started/hello/rstudio.qmd +++ b/docs/get-started/hello/rstudio.qmd @@ -67,12 +67,12 @@ quarto::quarto_render("hello.qmd") ``` When rendering, Quarto generates a new file that contains selected text, code, and results from the .qmd file. -The new file can be an [HTML](https://quarto.org/docs/output-formats/all-formats.html), [PDF](https://quarto.org/docs/output-formats/pdf-basics.html), [MS Word](https://quarto.org/docs/output-formats/ms-word.html) document, [presentation](https://quarto.org/docs/presentations/), [website](https://quarto.org/docs/websites/), [book](https://quarto.org/docs/books/), [interactive document](https://quarto.org/docs/interactive/), or [other format](https://quarto.org/docs/output-formats/all-formats.html). +The new file can be an [HTML](/docs/output-formats/all-formats.qmd), [PDF](/docs/output-formats/pdf-basics.qmd), [MS Word](/docs/output-formats/ms-word.qmd) document, [presentation](/docs/presentations/index.qmd), [website](/docs/websites/index.qmd), [book](/docs/books/index.qmd), [interactive document](/docs/interactive/index.qmd), or [other format](/docs/output-formats/all-formats.qmd). ## Authoring In the image below, we can see the same document in the two modes of the RStudio editor: visual (on the left) and source (on the right). -RStudio's [visual editor](/docs/visual-editor/) offers an [WYSIWYM](https://en.wikipedia.org/wiki/WYSIWYM) authoring experience for markdown. +RStudio's [visual editor](/docs/visual-editor/index.qmd) offers an [WYSIWYM](https://en.wikipedia.org/wiki/WYSIWYM) authoring experience for markdown. For formatting (e.g., bolding text), you can use the toolbar, a keyboard shortcut (⌘B), or the markdown construct (`**bold**`). The plain text source code underlying the document is written for you, and you can view/edit it at any point by switching to source mode for editing. You can toggle back and forth between these two modes by clicking on **Source** and **Visual** in the editor toolbar (or using the keyboard shortcut ⌘⇧ F4). @@ -99,8 +99,8 @@ The other two YAML fields denote that the output should be in `html` `format` an The basic syntax of YAML uses key-value pairs in the format `key: value`. Other YAML fields commonly found in headers of documents include metadata like `author`, `subtitle`, `date` as well as customization options like `theme`, `fontcolor`, `fig-width`, etc. -You can find out about all available YAML fields for HTML documents [here](/docs/reference/formats/html.html). -The available YAML fields vary based on document format, e.g., see [here](/docs/reference/formats/pdf.html) for YAML fields for PDF documents and [here](/docs/reference/formats/docx.html) for MS Word. +You can find out about all available YAML fields for HTML documents [here](/docs/reference/formats/html.qmd). +The available YAML fields vary based on document format, e.g., see [here](/docs/reference/formats/pdf.qmd) for YAML fields for PDF documents and [here](/docs/reference/formats/docx.qmd) for MS Word. ### Code chunks diff --git a/docs/get-started/hello/text-editor.qmd b/docs/get-started/hello/text-editor.qmd index 7977df2fca..9653a793c2 100644 --- a/docs/get-started/hello/text-editor.qmd +++ b/docs/get-started/hello/text-editor.qmd @@ -19,7 +19,7 @@ Below is an overview of how this will look. ![](images/text-editor-quarto-preview.png){.border .column-body-outset-right fig-alt="On the left: A VS Code notebook titled Quarto Basics containing some text, a code cell, and the result of the code cell, which is a line plot on a polar axis. On the right: Rendered version of the same notebook."} The notebook on the left is *rendered* into the HTML version you see on the right. -This is the basic model for Quarto publishing---take a source document (in this case a notebook) and render it to a variety of [output formats](https://quarto.org/docs/output-formats/all-formats.html), including HTML, PDF, MS Word, etc. +This is the basic model for Quarto publishing---take a source document (in this case a notebook) and render it to a variety of [output formats](/docs/output-formats/all-formats.qmd), including HTML, PDF, MS Word, etc. The tutorials will make use of the `matplotlib` and `plotly` Python packages---the commands you can use to install them are given in the table below. diff --git a/docs/get-started/hello/vscode.qmd b/docs/get-started/hello/vscode.qmd index 6b19b4bdec..5e6983e33b 100644 --- a/docs/get-started/hello/vscode.qmd +++ b/docs/get-started/hello/vscode.qmd @@ -34,7 +34,7 @@ Here's what it might look like in VS Code to edit and preview a `.qmd` file: ![](/docs/tools/images/vscode-render.png){.border fig-alt="Two windows arranged side by side. The window on the left is a qmd file opened in VSCode. The contents of this document are the same as the first part of the Getting Started: Welcome section of this website. The contents of this document are rendered by Quarto in the window on the right."} The document on the left is *rendered* into the HTML version you see on the right. -This is the basic model for Quarto publishing---take a source document and render it to a variety of [output formats](https://quarto.org/docs/output-formats/all-formats.html), including HTML, PDF, MS Word, etc. +This is the basic model for Quarto publishing---take a source document and render it to a variety of [output formats](/docs/output-formats/all-formats.qmd), including HTML, PDF, MS Word, etc. The tutorials will make use of the `matplotlib` and `plotly` Python packages---the commands you can use to install them are given in the table below. diff --git a/docs/journals/_draft/create-extensions.qmd b/docs/journals/_draft/create-extensions.qmd index 22116cf26b..1ae561702b 100644 --- a/docs/journals/_draft/create-extensions.qmd +++ b/docs/journals/_draft/create-extensions.qmd @@ -95,7 +95,7 @@ contributes: - extension.lua ``` -For more information about authoring filters, see [Pandoc Filters](https://quarto.org/docs/authoring/filters.html#pandoc-filters). +For more information about authoring filters, see [Pandoc Filters](/docs/authoring/filters.qmd#pandoc-filters). ## Shortcode Extensions @@ -110,7 +110,7 @@ contributes: - shortcode.lua ``` -For more information about authoring shortcodes, see [Shortcodes](https://quarto.org/docs/authoring/shortcodes.html). +For more information about authoring shortcodes, see [Shortcodes](/docs/authoring/shortcodes.qmd). ## Format Extensions diff --git a/docs/manuscripts/authoring/_citations.qmd b/docs/manuscripts/authoring/_citations.qmd index b81d483019..98cac25252 100644 --- a/docs/manuscripts/authoring/_citations.qmd +++ b/docs/manuscripts/authoring/_citations.qmd @@ -53,7 +53,7 @@ This renders as: > A prior study of the magma systems feeding the volcano proposed that there are two main magma reservoirs feeding the Cumbre Vieja volcano (Marrero et al. 2019). -There are many other syntax variations to include page numbers, chapters, or exclude the author names. You can read more in the [Citations & Footnotes](/docs/authoring/footnotes-and-citations.html) documentation. +There are many other syntax variations to include page numbers, chapters, or exclude the author names. You can read more in the [Citations & Footnotes](/docs/authoring/footnotes-and-citations.qmd) documentation. ::: {.content-visible unless-meta="tool.is_jupyterlab"} diff --git a/docs/manuscripts/authoring/_cross-refs.qmd b/docs/manuscripts/authoring/_cross-refs.qmd index 3fc9a5236a..4ee7befdd1 100644 --- a/docs/manuscripts/authoring/_cross-refs.qmd +++ b/docs/manuscripts/authoring/_cross-refs.qmd @@ -49,7 +49,7 @@ Which will be rendered as: > Data and methods are discussed in Section 2. -You can read more about the types of objects that can be referenced, including code listings, and mathematical theorems, as well as some of the options to control how references appear in the Quarto [Cross References](/docs/authoring/cross-references.html) documentation. +You can read more about the types of objects that can be referenced, including code listings, and mathematical theorems, as well as some of the options to control how references appear in the Quarto [Cross References](/docs/authoring/cross-references.qmd) documentation. ::: {.content-visible unless-meta="tool.is_jupyterlab"} diff --git a/docs/manuscripts/authoring/_inline-computations.qmd b/docs/manuscripts/authoring/_inline-computations.qmd index 4ae622948a..76d37f4927 100644 --- a/docs/manuscripts/authoring/_inline-computations.qmd +++ b/docs/manuscripts/authoring/_inline-computations.qmd @@ -94,11 +94,11 @@ eruptions = [1492, 1585, 1646, 1677, 1712, 1949, 1971, 2021] The `echo` option describes whether the code is included in the rendered article. If you make this change and save `{{< meta tool.article-file >}}`, you'll see this code now appears in the article. ::: {.content-visible unless-meta="tool.is_rstudio"} -You can find a list of all the code cell options available on the [Jupyter Code Cell](/docs/reference/cells/cells-jupyter.html) reference page. +You can find a list of all the code cell options available on the [Jupyter Code Cell](/docs/reference/cells/cells-jupyter.qmd) reference page. ::: ::: {.content-visible when-meta="tool.is_rstudio"} -You can find a list of all the code cell options available on the [Knitr Code Cell](/docs/reference/cells/cells-knitr.html) reference page. +You can find a list of all the code cell options available on the [Knitr Code Cell](/docs/reference/cells/cells-knitr.qmd) reference page. ::: The next code cell creates a figure: @@ -152,7 +152,7 @@ The `label` option is used to add an identifier to code cell and its output, for The option `fig-cap` provides the caption text displayed below the figure in the manuscript, and `fig-alt` provides alt text for the figure, helping your manuscript webpage to meet accessibility guidelines. -Computations are also a good way to include tables based on data. You can read more about doing this in the Quarto documentation on [Tables from Computations](/docs/authoring/tables.html#computations). +Computations are also a good way to include tables based on data. You can read more about doing this in the Quarto documentation on [Tables from Computations](/docs/authoring/tables.qmd#computations). If you have code output you don't want to include in your article you can use `output: false`. For example, you may have a value that is helpful for writing your content, but you don't want it to appear in the article itself. The next code cell is an example: @@ -223,7 +223,7 @@ When rendered, it displays as: > Based on data up to and including 1971, eruptions on La Palma happen every 79.8 years on average. -You can read more about using code inline at [Inline Code](/docs/computations/execution-options.html#inline-code). +You can read more about using code inline at [Inline Code](/docs/computations/execution-options.qmd#inline-code). ::: Rather than including computations directly in your article you can also embed outputs from other notebooks, read more below in [Embedding Notebooks](#embed). @@ -246,4 +246,3 @@ This manuscript template uses Quarto's freeze feature, which allows us to avoid You may not have noticed, but the first time you rendered the manuscript no code was evaluated. This was because the template repo included the `_freeze/` folder, and the contents of `index.qmd` had not changed since the freeze was generated. As you change `index.qmd`, code will be re-evaluated, and the contents of `_freeze/` will be updated. Remember when you come to publish, you'll need to commit the changes in `_freeze/` as well. ::: - diff --git a/docs/manuscripts/authoring/_markdown.qmd b/docs/manuscripts/authoring/_markdown.qmd index 6baebab70b..28e0ebbc7f 100644 --- a/docs/manuscripts/authoring/_markdown.qmd +++ b/docs/manuscripts/authoring/_markdown.qmd @@ -14,4 +14,4 @@ As an example, the markdown to create the heading for the article's introduction First-level headings are reserved for the article title, so you'll use second-level and deeper headings to structure the sections in your article. -If Markdown syntax is unfamiliar, you might want to read about Quarto [Markdown Basics](/docs/authoring/markdown-basics.html). +If Markdown syntax is unfamiliar, you might want to read about Quarto [Markdown Basics](/docs/authoring/markdown-basics.qmd). diff --git a/docs/manuscripts/authoring/_overview.qmd b/docs/manuscripts/authoring/_overview.qmd index 7925c4b466..031ff6b3f8 100644 --- a/docs/manuscripts/authoring/_overview.qmd +++ b/docs/manuscripts/authoring/_overview.qmd @@ -23,7 +23,7 @@ The syntax you'll learn will apply regardless of the tool you are using to edit ## Do you mostly use `.ipynb`? -As a VS Code user, we recommend writing your article in a `.qmd` file. However, if you currently use VS Code primarily to work with `.ipynb` files, you may find the Jupyter Lab tutorial more applicable. Install the [Quarto extension for Jupyter Lab](#install-the-quarto-vs-code-extension), then pick up the Jupyter Lab tutorial at [Clone the Template Repository](jupyterlab.qmd#clone-repo). You might also like read about using [Quarto with VS Code's Notebook Editor](/docs/tools/vscode-notebook.html). +As a VS Code user, we recommend writing your article in a `.qmd` file. However, if you currently use VS Code primarily to work with `.ipynb` files, you may find the Jupyter Lab tutorial more applicable. Install the [Quarto extension for Jupyter Lab](#install-the-quarto-vs-code-extension), then pick up the Jupyter Lab tutorial at [Clone the Template Repository](jupyterlab.qmd#clone-repo). You might also like read about using [Quarto with VS Code's Notebook Editor](/docs/tools/vscode-notebook.qmd). ::: ::: diff --git a/docs/manuscripts/authoring/_tables.qmd b/docs/manuscripts/authoring/_tables.qmd index 26456d256f..08f12ecd4a 100644 --- a/docs/manuscripts/authoring/_tables.qmd +++ b/docs/manuscripts/authoring/_tables.qmd @@ -22,9 +22,9 @@ Inserting and editing tables using markdown syntax can be cumbersome. The Visual Editor provides tools for editing existing tables, and inserting new tables. Use the Table menu in the visual editor toolbar or right-click inside a table to bring up the options. ::: {.content-visible when-meta="tool.is_rstudio"} -Read more about working with tables in the RStudio Visual Editor at [Editing Tables](/docs/visual-editor/content.html#editing-tables). +Read more about working with tables in the RStudio Visual Editor at [Editing Tables](/docs/visual-editor/content.qmd#editing-tables). ::: ::: -You can learn more about tables in Quarto, including an alternative syntax known as grid tables, on the [Tables](/docs/authoring/tables.html) page in the Quarto documentation. +You can learn more about tables in Quarto, including an alternative syntax known as grid tables, on the [Tables](/docs/authoring/tables.qmd) page in the Quarto documentation. diff --git a/docs/manuscripts/authoring/_visual-editor.qmd b/docs/manuscripts/authoring/_visual-editor.qmd index 6853ff949a..25aff1be8f 100644 --- a/docs/manuscripts/authoring/_visual-editor.qmd +++ b/docs/manuscripts/authoring/_visual-editor.qmd @@ -21,7 +21,7 @@ To toggle between source and visual editor modes, toggle the "Source" and "Visua ![](images/source-visual-buttons-rstudio.png){fig-alt="Screenshot of the Source Editor pane in RStudio. The Visual button in the toolbar at the top of the Editor pane is highlighted."} -You can read more about RStudio's visual editor at [Visual Editing in RStudio](/docs/visual-editor/). +You can read more about RStudio's visual editor at [Visual Editing in RStudio](/docs/visual-editor/index.qmd). ::: ::: {.content-visible when-meta="tool.is_vscode"} @@ -29,7 +29,7 @@ To toggle between source and visual editor modes, use the Editor menu and select ![](images/source-visual-menu-vscode.png){fig-alt="Screenshot of the Editor menu in VS Code. The 'Edit in Visual Mode' item in the '...' menu is highlighted."} -There are other ways to switch modes, read about them, and other features of the visual editor at [Visual Editing in VS Code](/docs/visual-editor/vscode/). +There are other ways to switch modes, read about them, and other features of the visual editor at [Visual Editing in VS Code](/docs/visual-editor/vscode/index.qmd). ::: You can switch between the source and visual editor at any time - the location of your cursor and undo/redo history is preserved. diff --git a/docs/manuscripts/components.qmd b/docs/manuscripts/components.qmd index 24647463fe..3896cc4ae4 100644 --- a/docs/manuscripts/components.qmd +++ b/docs/manuscripts/components.qmd @@ -193,7 +193,7 @@ format: theme: solar ``` -You can read more at [HTML Theming](/docs/output-formats/html-themes.html). +You can read more at [HTML Theming](/docs/output-formats/html-themes.qmd). ### Commenting @@ -209,11 +209,11 @@ format: hypothesis: true ``` -The other two tools available are [Utterances](https://utteranc.es/) and [Giscus](https://giscus.app/). You can read about setting them up at [HTML Basics: Commenting](/docs/output-formats/html-basics.html#commenting). +The other two tools available are [Utterances](https://utteranc.es/) and [Giscus](https://giscus.app/). You can read about setting them up at [HTML Basics: Commenting](/docs/output-formats/html-basics.qmd#commenting). ## Add a Journal Template -You can find a list of available journal formats on the [Quarto Extensions: Journal Articles](/docs/extensions/listing-journals.html) page. +You can find a list of available journal formats on the [Quarto Extensions: Journal Articles](/docs/extensions/listing-journals.qmd) page. To use a journal format, e.g. the [**acs**](https://github.com/quarto-journals/acs#american-chemical-society-acs) format, you'll need to complete two steps: 1. Install the appropriate journal format. diff --git a/docs/manuscripts/next-steps.qmd b/docs/manuscripts/next-steps.qmd index 3691105118..16eea5d388 100644 --- a/docs/manuscripts/next-steps.qmd +++ b/docs/manuscripts/next-steps.qmd @@ -10,7 +10,7 @@ Alternatively, you could start from scratch. Either way, here are some resources to help you with your next steps. +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ### Basics | Head to [**Manuscript Basics**](/docs/manuscripts/components.html) to: | +| ### Basics | Head to [**Manuscript Basics**](/docs/manuscripts/components.qmd) to: | | | | | | - Learn how to turn a directory into a manuscript project by adding the `_quarto.yml` file | | | | @@ -20,11 +20,11 @@ Either way, here are some resources to help you with your next steps. | | | | | - Add an output format for a specific journal | +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ### Quarto Projects | Quarto manuscripts are a type of [**Quarto project**](/docs/projects/quarto-projects.html), so anything you can do in a Quarto project applies to a manuscript. For instance, these pages in the Project documentation might be of interest: | +| ### Quarto Projects | Quarto manuscripts are a type of [**Quarto project**](/docs/projects/quarto-projects.qmd), so anything you can do in a Quarto project applies to a manuscript. For instance, these pages in the Project documentation might be of interest: | | | | -| | - [Managing Execution](/docs/projects/code-execution.html): techniques to avoid expensive computations on every render. | +| | - [Managing Execution](/docs/projects/code-execution.qmd): techniques to avoid expensive computations on every render. | | | | -| | - [Virtual Environments](/docs/projects/virtual-environments.html): capture your computational environment to facilitate reproducing your work. | +| | - [Virtual Environments](/docs/projects/virtual-environments.qmd): capture your computational environment to facilitate reproducing your work. | +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ### Publishing | We set up the publishing workflow for the template repository, but you can publish your manuscript website any way you can [**publish a Quarto website**](https://quarto.org/docs/publishing/). For example, if you need to set up the workflow to publish to GitHub pages yourself, head to [Publishing to GitHub Pages](/docs/publishing/github-pages.html). | +| ### Publishing | We set up the publishing workflow for the template repository, but you can publish your manuscript website any way you can [**publish a Quarto website**](/docs/publishing/index.qmd). For example, if you need to set up the workflow to publish to GitHub pages yourself, head to [Publishing to GitHub Pages](/docs/publishing/github-pages.qmd). | +---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/docs/manuscripts/publishing.qmd b/docs/manuscripts/publishing.qmd index 58e3f44cc2..2c7c16bd5a 100644 --- a/docs/manuscripts/publishing.qmd +++ b/docs/manuscripts/publishing.qmd @@ -16,7 +16,7 @@ Publishing a Quarto manuscript is the process of taking the preview you've been We've set up the template manuscript to include most of the scaffolding needed to publish your manuscript to your repository's GitHub Pages site. Publishing your manuscript website is as simple as pushing your changes to your repo. -Since a Quarto manuscript is a special type of Quarto website, you can publish it any way you can publish a Quarto website. If GitHub Pages doesn't suit your needs you can learn about other options in [Publishing](/docs/publishing/). +Since a Quarto manuscript is a special type of Quarto website, you can publish it any way you can publish a Quarto website. If GitHub Pages doesn't suit your needs you can learn about other options in [Publishing](/docs/publishing/index.qmd). On this page, you'll change one setting in your GitHub repo to authorize read and write permissions for GitHub Actions, then walk through the publishing process. @@ -36,7 +36,7 @@ The GitHub Action in `.github/workflows/publish.yml` does not set up any computa Jupyter notebooks (`.ipynb`) include their output and do not need any special treatment. However, if your manuscript includes Quarto files (`.qmd`), you must first render locally to update the saved computational outputs in the `_freeze` directory. -If you instead want your GitHub Action to also evaluate code, read how to set it up in the [Executing Code section on the Publishing to GitHub page](https://quarto.org/docs/publishing/github-pages.html#executing-code). +If you instead want your GitHub Action to also evaluate code, read how to set it up in the [Executing Code section on the Publishing to GitHub page](/docs/publishing/github-pages.qmd#executing-code). ::: @@ -87,5 +87,3 @@ Your manuscript is now published! ## What Next? You've now been through the full workflow of a Quarto manuscript: authoring content, previewing the generated manuscript and publishing it to GitHub Pages. When you are ready to dive into more detail, we have some recommendations on [Next Steps](next-steps.qmd). - - diff --git a/docs/output-formats/html-basics.qmd b/docs/output-formats/html-basics.qmd index 8509dc4658..a8dec93abc 100644 --- a/docs/output-formats/html-basics.qmd +++ b/docs/output-formats/html-basics.qmd @@ -383,7 +383,7 @@ comments: hypothesis: true ``` -You can see the Hypothesis UI at the far right of the page. Rather than `true`, you can specify any of the available Hypothesis [embedding options](/docs/reference/projects/websites.html#hypothesis) as a sub-key of `hypothesis`. For example: +You can see the Hypothesis UI at the far right of the page. Rather than `true`, you can specify any of the available Hypothesis [embedding options](/docs/reference/projects/websites.qmd#hypothesis) as a sub-key of `hypothesis`. For example: ``` yaml comments: @@ -399,7 +399,7 @@ comments: repo: quarto-dev/quarto-docs ``` -You can also specify the other options [documented here](/docs/reference/projects/websites.html#utterances). +You can also specify the other options [documented here](/docs/reference/projects/websites.qmd#utterances). You may also enable [Giscus](https://giscus.app) for commenting using the `giscus` option. Giscus will store comments in the 'Discussions' of a Github repo. @@ -417,7 +417,7 @@ Like utterances, you need to specify at least the Git repo you want to use for s 3. Have discussion enabled -Review the [Giscus documentation](https://giscus.app) for instructions on setting up Giscus in your repository. Additional options are [covered here](/docs/reference/projects/websites.html#giscus). +Review the [Giscus documentation](https://giscus.app) for instructions on setting up Giscus in your repository. Additional options are [covered here](/docs/reference/projects/websites.qmd#giscus). ### Disabling Comments diff --git a/docs/output-formats/html-code.qmd b/docs/output-formats/html-code.qmd index 79a2801b40..ee8c9e6e24 100644 --- a/docs/output-formats/html-code.qmd +++ b/docs/output-formats/html-code.qmd @@ -347,7 +347,7 @@ plt.show() ## Executable Blocks -The documentation on [computations](/docs/get-started/computations/) covers how to include executable code blocks (code which is actually executed, with its output being included in the rendered document). We won't additionally cover that here, but we will talk about how to include code blocks that demonstrate executable syntax (e.g. for writing a tutorial). +The documentation on [computations](/docs/get-started/computations/index.qmd) covers how to include executable code blocks (code which is actually executed, with its output being included in the rendered document). We won't additionally cover that here, but we will talk about how to include code blocks that demonstrate executable syntax (e.g. for writing a tutorial). {{< include ../computations/_unexecuted-blocks.md >}} diff --git a/docs/output-formats/html-multi-format.qmd b/docs/output-formats/html-multi-format.qmd index 6650732a00..3ed5d16101 100644 --- a/docs/output-formats/html-multi-format.qmd +++ b/docs/output-formats/html-multi-format.qmd @@ -87,9 +87,9 @@ format-links: false ## Controlling Formats at a Project Level -In a Quarto Project, to control the formats and their behavior for a specific folder, provide the `format`{spellcheck="false"} and `format-links`{spellcheck="false"} options in a `_metadata.yml`{spellcheck="false"} file. Similarly, you can specify these options for an entire project by including them in the `_quarto.yml` project file. See [Directory Metadata](/docs/projects/quarto-projects.qmd#directory-metadata) or [Project Metadata](/docs/projects/quarto-projects.html#project-metadata) for additional details. +In a Quarto Project, to control the formats and their behavior for a specific folder, provide the `format`{spellcheck="false"} and `format-links`{spellcheck="false"} options in a `_metadata.yml`{spellcheck="false"} file. Similarly, you can specify these options for an entire project by including them in the `_quarto.yml` project file. See [Directory Metadata](/docs/projects/quarto-projects.qmd#directory-metadata) or [Project Metadata](/docs/projects/quarto-projects.qmd#project-metadata) for additional details. -The `format`{spellcheck="false"} option isn't merged like all other [metadata](https://quarto.org/docs/projects/quarto-projects.html#metadata-merging) across `_quarto.yml`{spellcheck="false"}, `_metadata.yml`{spellcheck="false"}, and the document YAML. If you have some formats specified at a project or directory level, you'll also need to explicitly list them in the document YAML. For example, suppose you have HTML options set at the project level: +The `format`{spellcheck="false"} option isn't merged like all other [metadata](/docs/projects/quarto-projects.qmd#metadata-merging) across `_quarto.yml`{spellcheck="false"}, `_metadata.yml`{spellcheck="false"}, and the document YAML. If you have some formats specified at a project or directory level, you'll also need to explicitly list them in the document YAML. For example, suppose you have HTML options set at the project level: ``` {.yaml filename="_quarto.yml"} format: diff --git a/docs/output-formats/page-layout.qmd b/docs/output-formats/page-layout.qmd index d425521eda..5a7092341e 100644 --- a/docs/output-formats/page-layout.qmd +++ b/docs/output-formats/page-layout.qmd @@ -156,7 +156,7 @@ Customizing the layout of pages that are part of a Quarto website with YAML shou ::: -Similarly, in a [custom theme `scss` file](https://quarto.org/docs/output-formats/html-themes.html#theme-options), you may set variables like: +Similarly, in a [custom theme `scss` file](/docs/output-formats/html-themes.qmd#theme-options), you may set variables like: ``` css // The left hand sidebar @@ -208,4 +208,3 @@ format: ![Wider Margin, Narrower Body](images/grid-wide-margin-narrow-body.png){fig-alt="Screenshot of a Quarto website with altered layout, devoting more space to the margin and less to the body."} ::: - diff --git a/docs/output-formats/typst-custom.qmd b/docs/output-formats/typst-custom.qmd index d854404e14..ecfd992c29 100644 --- a/docs/output-formats/typst-custom.qmd +++ b/docs/output-formats/typst-custom.qmd @@ -57,7 +57,7 @@ Additional resources you might find useful when creating custom formats include: This section covers advanced customization of Typst format output and can be safely ignored unless you have found the method of defining custom Typst formats described above too limited. ::: -Above we describe a method of creating a Typst format based on specifying two [template partials](https://quarto.org/docs/journals/templates.html#template-partials) (`typst-template.typ` and `typst-show.typ`). These partials customize components of the default Typst Pandoc template, but leave some of the core scaffolding including definitions required by Pandoc for its Typst output as well as handling of bibliographies and footnotes (this means that your own custom Typst formats do not need to explicitly handle them). +Above we describe a method of creating a Typst format based on specifying two [template partials](/docs/journals/templates.qmd#template-partials) (`typst-template.typ` and `typst-show.typ`). These partials customize components of the default Typst Pandoc template, but leave some of the core scaffolding including definitions required by Pandoc for its Typst output as well as handling of bibliographies and footnotes (this means that your own custom Typst formats do not need to explicitly handle them). If you would like to fully override the Pandoc template used for rendering Typst, use the `template` option in your custom format (rather than `template-partials`) and provide an alternate implementation of the default template. For example, your `_extensions.yml` might look like this: diff --git a/docs/output-formats/typst.qmd b/docs/output-formats/typst.qmd index 22d23b6d27..61104b6c03 100644 --- a/docs/output-formats/typst.qmd +++ b/docs/output-formats/typst.qmd @@ -50,7 +50,7 @@ Since Typst is under active development, there are still some limitations to Qua - The default size of images may not reflect the behavior you are used to in other output formats. This is a problem that Typst, pandoc and Quarto are actively working to fix. In the meantime, you can manually [specify image widths](/docs/authoring/figures.qmd#figure-sizing). -- Advanced page layout (e.g. using the `.column` classes as explained in [Article Layout](https://quarto.org/docs/authoring/article-layout.html)) is not implemented. +- Advanced page layout (e.g. using the `.column` classes as explained in [Article Layout](/docs/authoring/article-layout.qmd)) is not implemented. - Various other small things might not yet be implemented. Please [let us know](https://github.com/quarto-dev/quarto-cli/issues/new/choose) if you see things that could use improvement! @@ -157,7 +157,7 @@ bibliography: refs.bib csl: https://www.zotero.org/styles/apa-with-abstract ``` -To provide a citation style file to Pandoc's citation processing system use the `csl` option, as described in [Citation Style](https://quarto.org/docs/authoring/footnotes-and-citations.html#sec-citations-style). +To provide a citation style file to Pandoc's citation processing system use the `csl` option, as described in [Citation Style](/docs/authoring/footnotes-and-citations.qmd#sec-citations-style). ## Typst Blocks @@ -260,4 +260,3 @@ format: - text: | #show heading: set text(navy) ``` - diff --git a/docs/prerelease/1.3/_pre-release-feature.qmd b/docs/prerelease/1.3/_pre-release-feature.qmd index 3741ca3500..047a0de616 100644 --- a/docs/prerelease/1.3/_pre-release-feature.qmd +++ b/docs/prerelease/1.3/_pre-release-feature.qmd @@ -1,5 +1,5 @@ ::: {.callout-note} ## Pre-release Feature -This feature is new in the upcoming Quarto 1.3 release. To use the feature now, you'll need to [download](https://quarto.org/docs/download/prerelease) and install the Quarto pre-release. -::: \ No newline at end of file +This feature is new in the upcoming Quarto 1.3 release. To use the feature now, you'll need to [download](/docs/download/prerelease) and install the Quarto pre-release. +::: diff --git a/docs/prerelease/1.4/_highlights.qmd b/docs/prerelease/1.4/_highlights.qmd index c28f7f54d4..0648817d23 100644 --- a/docs/prerelease/1.4/_highlights.qmd +++ b/docs/prerelease/1.4/_highlights.qmd @@ -16,7 +16,7 @@ Quarto 1.4 includes the following new features: - Allows [Cross-Referencing Callouts](/docs/authoring/cross-references.qmd#callouts). - - Adds the prefixes `rem-` and `sol-` to cross-reference Remarks and Solutions in addition to the [existing theorem types](/docs/authoring/cross-references.html#theorems-and-proofs). + - Adds the prefixes `rem-` and `sol-` to cross-reference Remarks and Solutions in addition to the [existing theorem types](/docs/authoring/cross-references.qmd#theorems-and-proofs). - Makes other [behind the scenes changes](/docs/prerelease/1.4/crossref.qmd). @@ -40,4 +40,4 @@ Quarto 1.4 includes the following new features: - [Lua changes](/docs/prerelease/1.4/lua_changes.qmd)---Quarto v1.4 adds new features to writers of Lua filters. -- [AST processing changes](/docs/prerelease/1.4/ast.qmd)---Quarto v1.4 improves on the HTML table processing added in v1.3 and adds a way for LaTeX raw blocks to include Quarto-compatible markdown for processing. \ No newline at end of file +- [AST processing changes](/docs/prerelease/1.4/ast.qmd)---Quarto v1.4 improves on the HTML table processing added in v1.3 and adds a way for LaTeX raw blocks to include Quarto-compatible markdown for processing. diff --git a/docs/prerelease/1.4/_pre-release-feature.qmd b/docs/prerelease/1.4/_pre-release-feature.qmd index fec4501f31..df09158ef9 100644 --- a/docs/prerelease/1.4/_pre-release-feature.qmd +++ b/docs/prerelease/1.4/_pre-release-feature.qmd @@ -1,5 +1,5 @@ ::: {.callout-note} ## Pre-release Feature -This feature is new in the upcoming Quarto 1.4 release. To use the feature now, you'll need to [download](https://quarto.org/docs/download/prerelease) and install the Quarto pre-release. -::: \ No newline at end of file +This feature is new in the upcoming Quarto 1.4 release. To use the feature now, you'll need to [download](/docs/download/prerelease) and install the Quarto pre-release. +::: diff --git a/docs/prerelease/1.5/_pre-release-feature.qmd b/docs/prerelease/1.5/_pre-release-feature.qmd index 376460d72b..ada243990e 100644 --- a/docs/prerelease/1.5/_pre-release-feature.qmd +++ b/docs/prerelease/1.5/_pre-release-feature.qmd @@ -1,5 +1,5 @@ ::: {.callout-note} ## Pre-release Feature -This feature is new in the upcoming Quarto 1.5 release. To use the feature now, you'll need to [download](https://quarto.org/docs/download/prerelease) and install the Quarto pre-release. -::: \ No newline at end of file +This feature is new in the upcoming Quarto 1.5 release. To use the feature now, you'll need to [download](/docs/download/prerelease) and install the Quarto pre-release. +::: diff --git a/docs/presentations/revealjs/demo/index.qmd b/docs/presentations/revealjs/demo/index.qmd index c9316c5b77..2d8627f9fc 100644 --- a/docs/presentations/revealjs/demo/index.qmd +++ b/docs/presentations/revealjs/demo/index.qmd @@ -43,7 +43,7 @@ function(input, output) { ``` ::: footer -Learn more: [Syntax Highlighting](https://quarto.org/docs/output-formats/html-code.html#highlighting) +Learn more: [Syntax Highlighting](/docs/output-formats/html-code.qmd#highlighting) ::: ## Code Animations {auto-animate="true"} @@ -67,7 +67,7 @@ function(input, output) { ``` ::: footer -Learn more: [Code Animations](https://quarto.org/docs/presentations/revealjs/advanced.html#code-animations) +Learn more: [Code Animations](/docs/presentations/revealjs/advanced.qmd#code-animations) ::: ## Line Highlighting @@ -89,7 +89,7 @@ plt.show() ``` ::: footer -Learn more: [Line Highlighting](https://quarto.org/docs/presentations/revealjs/#line-highlighting) +Learn more: [Line Highlighting](/docs/presentations/revealjs/#line-highlighting) ::: ## Executable Code @@ -105,7 +105,7 @@ ggplot(mtcars, aes(hp, mpg, color = am)) + ``` ::: footer -Learn more: [Executable Code](https://quarto.org/docs/presentations/revealjs/#executable-code) +Learn more: [Executable Code](/docs/presentations/revealjs/#executable-code) ::: ## LaTeX Equations @@ -148,7 +148,7 @@ a_{21}& =b_{21}& ::: ::: footer -Learn more: [LaTeX Equations](https://quarto.org/docs/authoring/markdown-basics.html#equations) +Learn more: [LaTeX Equations](/docs/authoring/markdown-basics.qmd#equations) ::: ## Column Layout {.smaller} @@ -173,7 +173,7 @@ knitr::kable(head(mtcars)[,c("mpg", "cyl", "disp", "hp", "wt")]) ::: ::: footer -Learn more: [Multiple Columns](https://quarto.org/docs/presentations/revealjs/#multiple-columns) +Learn more: [Multiple Columns](/docs/presentations/revealjs/#multiple-columns) ::: ## Incremental Lists @@ -191,7 +191,7 @@ Lists can optionally be displayed incrementally:
Insert pauses to make other types of content display incrementally. ::: footer -Learn more: [Incremental Lists](https://quarto.org/docs/presentations/revealjs/#incremental-lists) +Learn more: [Incremental Lists](/docs/presentations/revealjs/#incremental-lists) ::: ## Fragments @@ -227,7 +227,7 @@ Highlight red ::: ::: footer -Learn more: [Fragments](https://quarto.org/docs/presentations/revealjs/advanced.html#fragments) +Learn more: [Fragments](/docs/presentations/revealjs/advanced.qmd#fragments) ::: ## Slide Backgrounds {background="#43464B"} @@ -237,7 +237,7 @@ Set the `background` attribute on a slide to change the background color (all CS Different background transitions are available via the `background-transition` option. ::: footer -Learn more: [Slide Backgrounds](https://quarto.org/docs/presentations/revealjs/#color-backgrounds) +Learn more: [Slide Backgrounds](/docs/presentations/revealjs/#color-backgrounds) ::: ## Media Backgrounds {background="#43464B" background-image="images/milky-way.jpeg"} @@ -251,7 +251,7 @@ You can also use the following as a slide background: - An iframe: `background-iframe` ::: footer -Learn more: [Media Backgrounds](https://quarto.org/docs/presentations/revealjs/#image-backgrounds) +Learn more: [Media Backgrounds](/docs/presentations/revealjs/#image-backgrounds) ::: ## Absolute Position @@ -265,7 +265,7 @@ Position images or other elements at precise locations ![](mini/images/kitten-300-200.jpeg){.absolute .fragment bottom="110" right="130" width="300"} ::: footer -Learn more: [Absolute Position](https://quarto.org/docs/presentations/revealjs/advanced.html#absolute-position) +Learn more: [Absolute Position](/docs/presentations/revealjs/advanced.qmd#absolute-position) ::: ## Auto-Animate {auto-animate="true" auto-animate-easing="ease-in-out"} @@ -284,7 +284,7 @@ Automatically animate matching elements across slides with Auto-Animate. ::: ::: footer -Learn more: [Auto-Animate](https://quarto.org/docs/presentations/revealjs/advanced.html#auto-animate) +Learn more: [Auto-Animate](/docs/presentations/revealjs/advanced.qmd#auto-animate) ::: ## Auto-Animate {auto-animate="true" auto-animate-easing="ease-in-out"} @@ -303,7 +303,7 @@ Automatically animate matching elements across slides with Auto-Animate. ::: ::: footer -Learn more: [Auto-Animate](https://quarto.org/docs/presentations/revealjs/advanced.html#auto-animate) +Learn more: [Auto-Animate](/docs/presentations/revealjs/advanced.qmd#auto-animate) ::: ## Slide Transitions {.smaller} @@ -320,7 +320,7 @@ The next few slides will transition using the `slide` transition | `zoom` | Scale the incoming slide so it grows in from the center of the screen. | ::: footer -Learn more: [Slide Transitions](https://quarto.org/docs/presentations/revealjs/advanced.html#slide-transitions) +Learn more: [Slide Transitions](/docs/presentations/revealjs/advanced.qmd#slide-transitions) ::: ## Tabsets {.smaller .scrollable transition="slide"} @@ -343,7 +343,7 @@ knitr::kable(mtcars) ::: ::: footer -Learn more: [Tabsets](https://quarto.org/docs/presentations/revealjs/#tabsets) +Learn more: [Tabsets](/docs/presentations/revealjs/#tabsets) ::: ## Interactive Slides {.smaller transition="slide"} @@ -360,7 +360,7 @@ leaflet() %>% ``` ::: footer -Learn more: [Jupyter widgets](https://quarto.org/docs/interactive/widgets/jupyter.html), [htmlwidgets](https://quarto.org/docs/interactive/widgets/htmlwidgets.html) +Learn more: [Jupyter widgets](/docs/interactive/widgets/jupyter.qmd), [htmlwidgets](/docs/interactive/widgets/htmlwidgets.qmd) ::: ## Interactive Slides {.smaller transition="slide"} @@ -388,7 +388,7 @@ plotActors(actors, talentWeight, looksWeight, minimum) ``` ::: footer -Learn more: [Observable](https://quarto.org/docs/interactive/ojs/), [Shiny](https://quarto.org/docs/interactive/shiny/), [Component Layout](https://quarto.org/docs/interactive/layout.html) +Learn more: [Observable](/docs/interactive/ojs/index.qmd), [Shiny](/docs/interactive/shiny/index.qmd), [Component Layout](/docs/interactive/layout.qmd) ::: ## Preview Links @@ -402,12 +402,12 @@ Use the `preview-links` option to open links in an iframe on top of your slides. ::: ::: footer -Learn more: [Preview Links](https://quarto.org/docs/presentations/revealjs/presenting.html#preview-links) +Learn more: [Preview Links](/docs/presentations/revealjs/presenting.qmd#preview-links) ::: ## Themes -10 Built-in Themes (or [create your own](https://quarto.org/docs/presentations/revealjs/themes.html#creating-themes)) +10 Built-in Themes (or [create your own](/docs/presentations/revealjs/themes.qmd#creating-themes)) ::: {layout-ncol="2"} ![](images/moon.png) @@ -416,7 +416,7 @@ Learn more: [Preview Links](https://quarto.org/docs/presentations/revealjs/prese ::: ::: footer -Learn more: [Themes](https://quarto.org/docs/presentations/revealjs/themes.html) +Learn more: [Themes](/docs/presentations/revealjs/themes.qmd) ::: ## Easy Navigation @@ -434,7 +434,7 @@ Toggle the slide menu with the menu button (bottom left of slide) to go to other You can also press `m` to toggle the menu open and closed. ::: footer -Learn more: [Navigation](https://quarto.org/docs/presentations/revealjs/presenting.html#navigation-menu) +Learn more: [Navigation](/docs/presentations/revealjs/presenting.qmd#navigation-menu) ::: ## Chalkboard {chalkboard-buttons="true"} @@ -458,7 +458,7 @@ Use the notes canvas button at the bottom left of the slide to toggle drawing on You can also press `b` to toggle the chalkboard or `c` to toggle the notes canvas. ::: footer -Learn more: [Chalkboard](https://quarto.org/docs/presentations/revealjs/presenting.html#chalkboard) +Learn more: [Chalkboard](/docs/presentations/revealjs/presenting.qmd#chalkboard) ::: ## Point of View @@ -470,7 +470,7 @@ Press `o` to toggle overview mode: Hold down the `Alt` key (or `Ctrl` in Linux) and click on any element to zoom towards it---try it now on this slide. ::: footer -Learn more: [Overview Mode](https://quarto.org/docs/presentations/revealjs/presenting.html#overview-mode), [Slide Zoom](https://quarto.org/docs/presentations/revealjs/presenting.html#slide-zoom) +Learn more: [Overview Mode](/docs/presentations/revealjs/presenting.qmd#overview-mode), [Slide Zoom](/docs/presentations/revealjs/presenting.qmd#slide-zoom) ::: ## Speaker View @@ -480,7 +480,7 @@ Press `s` (or use the presentation menu) to open speaker view ![](images/speaker-view.png){fig-align="center" style="border: 3px solid #dee2e6;" width="780"} ::: footer -Learn more: [Speaker View](https://quarto.org/docs/presentations/revealjs/presenting.html#speaker-view) +Learn more: [Speaker View](/docs/presentations/revealjs/presenting.qmd#speaker-view) ::: ## Authoring Tools {.smaller} @@ -498,7 +498,7 @@ Live side-by-side preview for any notebook or text editor including Jupyter and ::: ::: footer -Learn more: [Jupyter](https://quarto.org/docs/tools/jupyter-lab.html), [VS Code](https://quarto.org/docs/tools/vscode.html), [Text Editors](https://quarto.org/docs/tools/text-editors.html) +Learn more: [Jupyter](/docs/tools/jupyter-lab.qmd), [VS Code](/docs/tools/vscode.qmd), [Text Editors](/docs/tools/text-editors.qmd) ::: ## Authoring Tools {.smaller} @@ -508,16 +508,16 @@ RStudio includes an integrated presentation preview pane ![](images/rstudio.png){.border width="900"} ::: footer -Learn more: [RStudio](https://quarto.org/docs/tools/rstudio.html) +Learn more: [RStudio](/docs/tools/rstudio.qmd) ::: ## And More... -- [Touch](https://quarto.org/docs/presentations/revealjs/advanced.html#touch-navigation) optimized (presentations look great on mobile, swipe to navigate slides) -- [Footer & Logo](https://quarto.org/docs/presentations/revealjs/#footer-logo) (optionally specify custom footer per-slide) -- [Auto-Slide](https://quarto.org/docs/presentations/revealjs/presenting.html#auto-slide) (step through slides automatically, without any user input) -- [Multiplex](https://quarto.org/docs/presentations/revealjs/presenting.html#multiplex) (allows your audience to follow the slides of the presentation you are controlling on their own phone, tablet or laptop). +- [Touch](/docs/presentations/revealjs/advanced.qmd#touch-navigation) optimized (presentations look great on mobile, swipe to navigate slides) +- [Footer & Logo](/docs/presentations/revealjs/#footer-logo) (optionally specify custom footer per-slide) +- [Auto-Slide](/docs/presentations/revealjs/presenting.qmd#auto-slide) (step through slides automatically, without any user input) +- [Multiplex](/docs/presentations/revealjs/presenting.qmd#multiplex) (allows your audience to follow the slides of the presentation you are controlling on their own phone, tablet or laptop). ::: footer -Learn more: [Quarto Presentations](https://quarto.org/docs/presentations/revealjs/) +Learn more: [Quarto Presentations](/docs/presentations/revealjs/index.qmd) ::: diff --git a/docs/publishing/confluence.qmd b/docs/publishing/confluence.qmd index 8532a0e8ea..829edda034 100644 --- a/docs/publishing/confluence.qmd +++ b/docs/publishing/confluence.qmd @@ -149,7 +149,7 @@ In the sidebar navigation this page is listed at the top level under Pages becau ## Publishing Projects {#collection-of-documents} -To publish a collection of documents, organize your documents in a [Quarto project](/docs/projects/quarto-projects.html), and use the `confluence` project type. Here's a minimal `_quarto.yml` file for a Confluence project: +To publish a collection of documents, organize your documents in a [Quarto project](/docs/projects/quarto-projects.qmd), and use the `confluence` project type. Here's a minimal `_quarto.yml` file for a Confluence project: ``` {.yaml filename="_quarto.yml"} project: diff --git a/docs/reference/cells/index.qmd b/docs/reference/cells/index.qmd index 323eed11de..d810190155 100644 --- a/docs/reference/cells/index.qmd +++ b/docs/reference/cells/index.qmd @@ -8,7 +8,7 @@ listing: contents: ./reference.yml --- -The options available in an executable code cell depend on the engine used to process them. The engine is chosen automatically, as outlined in the [Guide](https://quarto.org/docs/computations/execution-options.html#engine-binding). +The options available in an executable code cell depend on the engine used to process them. The engine is chosen automatically, as outlined in the [Guide](/docs/computations/execution-options.qmd#engine-binding). ::: {#reference-links .column-screen-inset-right style="max-width: 850px;"} ::: diff --git a/docs/reference/formats/dashboards.qmd b/docs/reference/formats/dashboards.qmd index 142abb4e5a..dc8789482e 100644 --- a/docs/reference/formats/dashboards.qmd +++ b/docs/reference/formats/dashboards.qmd @@ -16,7 +16,7 @@ The following document and format options are either dashboard-specific or have | `scrolling` | Use scrolling rather than fill layout? (default: `false`) | | `expandable` | Make card content expandable (default: `true`) | | `theme` | Dashboard theme (built in or custom scss) | -| `nav-buttons` | Buttons to appear on the right side of the navigation bar. Use `linkedin`, `facebook`, `reddit`, `twitter`, `github`, or a custom [Nav Item](/docs/reference/projects/websites.html#nav-items). | +| `nav-buttons` | Buttons to appear on the right side of the navigation bar. Use `linkedin`, `facebook`, `reddit`, `twitter`, `github`, or a custom [Nav Item](/docs/reference/projects/websites.qmd#nav-items). | For example: @@ -158,4 +158,4 @@ Available themed aliases for `color` include: {{< include /docs/dashboards/_valuebox-colors.md >}} -Note that value box options can be specified either as cell options or by printing a `dict()` (for Python) or `list()` (for R) (this is helpful when options need to be dynamic). See the [Value Boxes](/docs/dashboards/data-display.qmd#value-boxes) component documentation for details. \ No newline at end of file +Note that value box options can be specified either as cell options or by printing a `dict()` (for Python) or `list()` (for R) (this is helpful when options need to be dynamic). See the [Value Boxes](/docs/dashboards/data-display.qmd#value-boxes) component documentation for details. diff --git a/docs/websites/_page-navigation.md b/docs/websites/_page-navigation.md index a2688e94b9..3f00407196 100644 --- a/docs/websites/_page-navigation.md +++ b/docs/websites/_page-navigation.md @@ -17,7 +17,7 @@ page-navigation: false --- ``` -Or to control page navigation for all pages in a directory specify `page-navigation` in [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.qmd#directory-metadata): +Or to control page navigation for all pages in a directory specify `page-navigation` in [`_metadata.yml`](/docs/projects/quarto-projects.qmd#directory-metadata): ``` {.yaml filename="_metadata.yml"} page-navigation: false diff --git a/docs/websites/website-listings-custom.qmd b/docs/websites/website-listings-custom.qmd index 2f60f7666c..50b155c7a0 100644 --- a/docs/websites/website-listings-custom.qmd +++ b/docs/websites/website-listings-custom.qmd @@ -112,7 +112,7 @@ where the contents of `items.yml` is: ### Template Examples -Portions of this website are built using custom listings. The best place to start is with [our gallery](/docs/gallery/), which is a listing built using a custom template and a metadata file. You can view the source code used to create the gallery page in our [Github repository](https://github.com/quarto-dev/quarto-web). +Portions of this website are built using custom listings. The best place to start is with [our gallery](/docs/gallery/index.qmd), which is a listing built using a custom template and a metadata file. You can view the source code used to create the gallery page in our [Github repository](https://github.com/quarto-dev/quarto-web). | File | Description | |-------------------------------------|-----------------------------------| diff --git a/index.qmd b/index.qmd index 2e63896627..5904908615 100644 --- a/index.qmd +++ b/index.qmd @@ -26,7 +26,7 @@ resources: - Author using [Jupyter](https://jupyter.org) notebooks or with plain text markdown in your favorite editor. - Create dynamic content with [Python](docs/computations/python.qmd), [R](docs/computations/r.qmd), [Julia](docs/computations/julia.qmd), and [Observable](docs/computations/ojs.qmd). - Publish reproducible, production quality articles, presentations, dashboards, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more. -- Share knowledge and insights organization-wide by publishing to [Posit Connect](https://quarto.org/docs/publishing/rstudio-connect.html), [Confluence](docs/publishing/confluence.qmd), or other publishing systems. +- Share knowledge and insights organization-wide by publishing to [Posit Connect](/docs/publishing/rstudio-connect.qmd), [Confluence](docs/publishing/confluence.qmd), or other publishing systems. - Write using [Pandoc](https://pandoc.org) markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more. ### Analyze. Share. Reproduce. You have a story to tell with data---tell it with Quarto. @@ -310,4 +310,3 @@ Publish collections of documents as a blog or full website. Create books and man ::: ::: - From f2ecffd0429d20f4fc4be6af7b14721ed585c8fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Tue, 27 Feb 2024 23:04:50 +0100 Subject: [PATCH 02/33] fix: broken link --- docs/projects/binder.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/projects/binder.qmd b/docs/projects/binder.qmd index 77a47f699a..d03e3b6fb0 100644 --- a/docs/projects/binder.qmd +++ b/docs/projects/binder.qmd @@ -50,7 +50,7 @@ The command will first detect and report the project configuration: No files which provide dependencies were discovered. If you continue, no dependencies will be restored when running this project with Binder. Learn more at: -https://www.quarto.org/docs/prerelease/1.4/binder.html#dependencies +https://www.quarto.org/docs/projects/binder.html#dependencies ? Do you want to continue? (Y/n) › ``` From 7c854a1db0329fdf68f18159b0471dac0c49d89a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Tue, 27 Feb 2024 23:05:02 +0100 Subject: [PATCH 03/33] fix: empty lines --- docs/authoring/_mermaid-examples/darkly.qmd | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/authoring/_mermaid-examples/darkly.qmd b/docs/authoring/_mermaid-examples/darkly.qmd index 307ba65537..06832f373d 100644 --- a/docs/authoring/_mermaid-examples/darkly.qmd +++ b/docs/authoring/_mermaid-examples/darkly.qmd @@ -19,5 +19,3 @@ flowchart LR ``` Read more on the [Quarto documentation site](https://quarto.org) - - From abe24313f17fd4eb36db6bab9cb5e4a92def3f5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Tue, 27 Feb 2024 23:05:19 +0100 Subject: [PATCH 04/33] style: rm unnecessary break line --- docs/faq/index.qmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/faq/index.qmd b/docs/faq/index.qmd index d8c3aa1e82..759c0f3bc5 100644 --- a/docs/faq/index.qmd +++ b/docs/faq/index.qmd @@ -6,15 +6,15 @@ If you are an R Markdown user wondering about the relationship between Quarto an ### What can I use Quarto for? -Quarto® is an open-source scientific and technical publishing system built on Pandoc. You can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books and more. \ +Quarto® is an open-source scientific and technical publishing system built on Pandoc. You can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books and more. ### How do I install Quarto? -Visit the Quarto.org [Get Started page](/docs/get-started/index.qmd), which provides installation instructions for Windows, Mac OS, and Linux. \ +Visit the Quarto.org [Get Started page](/docs/get-started/index.qmd), which provides installation instructions for Windows, Mac OS, and Linux. ### Is Quarto free to use? -Yes! Quarto is [open source](https://quarto.org/license.html). Quarto version 1.3 (and earlier) is licensed under the [GNU GPL v2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). Quarto version 1.4 is licensed under the [MIT License](https://opensource.org/license/mit/). +Yes! Quarto is [open source](/license.qmd). Quarto version 1.3 (and earlier) is licensed under the [GNU GPL v2](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html). Quarto version 1.4 is licensed under the [MIT License](https://opensource.org/license/mit/). ### What output formats can Quarto create? From d3ccc361020ea0e698106ea0ebf808451d53f6cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Tue, 27 Feb 2024 23:05:33 +0100 Subject: [PATCH 05/33] fix: internal link --- about.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/about.qmd b/about.qmd index 81bf153245..91070c3ac1 100644 --- a/about.qmd +++ b/about.qmd @@ -13,7 +13,7 @@ The overarching goal of Quarto is to make the process of creating and collaborat - Make reproducible research and publications the norm rather than the exception. Reproducibility requires that the code and data required to create a manuscript are an integrated part of it. However, this isn't often straightforward in practice---Quarto aims to make it easier to adopt a reproducible workflow than not. -Quarto is [open source software](https://quarto.org/license.html). We believe that it's better for everyone if the tools used for research and science are free and open. Reproducibility, widespread sharing of knowledge and techniques, and the leveling of the playing field by eliminating cost barriers are but a few of the shared benefits of free software in science. +Quarto is [open source software](/license.qmd). We believe that it's better for everyone if the tools used for research and science are free and open. Reproducibility, widespread sharing of knowledge and techniques, and the leveling of the playing field by eliminating cost barriers are but a few of the shared benefits of free software in science. ## Project From bc3df227ea44204c9efe41d9a6309cd0e7b201c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 28 Feb 2024 00:12:38 +0100 Subject: [PATCH 06/33] refactor: use path relative to project root This is to avoid future breakage when moving parts around --- docs/authoring/_mermaid-theming.qmd | 6 +- docs/authoring/create-citeable-articles.qmd | 2 +- docs/authoring/cross-references-divs.qmd | 2 +- docs/authoring/markdown-basics.qmd | 2 +- docs/authoring/title-blocks.qmd | 2 +- docs/authoring/variables.qmd | 2 +- .../2022-07-25-feature-extensions/index.qmd | 8 +-- .../posts/2023-04-26-1.3-release/index.qmd | 6 +- docs/books/book-basics.qmd | 30 ++++---- docs/books/book-crossrefs.qmd | 2 +- docs/books/book-output.qmd | 24 +++---- docs/books/book-structure.qmd | 2 +- docs/computations/julia.qmd | 4 +- docs/computations/python.qmd | 7 +- docs/computations/r.qmd | 12 ++-- .../interactivity/shiny-python/index.qmd | 4 +- docs/extensions/_formats-common.qmd | 2 +- docs/extensions/creating.qmd | 2 +- docs/extensions/formats.qmd | 2 +- docs/extensions/project-types.qmd | 4 +- docs/extensions/revealjs.qmd | 2 +- docs/extensions/shortcodes.qmd | 14 ++-- docs/extensions/starter-templates.qmd | 7 +- docs/get-started/authoring/rstudio.qmd | 2 +- docs/get-started/computations/rstudio.qmd | 4 +- docs/get-started/hello/neovim.qmd | 4 +- docs/guide/index.qmd | 2 +- docs/interactive/layout.qmd | 2 +- docs/interactive/ojs/code-reuse.qmd | 2 +- docs/interactive/ojs/ojs-cells.qmd | 6 +- docs/interactive/shiny/running.qmd | 4 +- docs/interactive/widgets/htmlwidgets.qmd | 2 +- docs/manuscripts/authoring/_footer.qmd | 2 +- docs/manuscripts/authoring/_setup.qmd | 2 +- docs/output-formats/all-formats.qmd | 72 +++++++++---------- docs/output-formats/gfm.qmd | 4 +- docs/output-formats/html-basics.qmd | 4 +- docs/output-formats/html-publishing.qmd | 16 ++--- docs/output-formats/hugo.qmd | 4 +- docs/output-formats/ms-word-templates.qmd | 2 +- docs/output-formats/ms-word.qmd | 3 +- docs/output-formats/page-layout.qmd | 2 +- docs/output-formats/pdf-basics.qmd | 4 +- docs/presentations/beamer.qmd | 2 +- docs/presentations/powerpoint.qmd | 2 +- docs/presentations/revealjs/index.qmd | 8 +-- docs/presentations/revealjs/presenting.qmd | 2 +- docs/presentations/revealjs/themes.qmd | 2 +- docs/publishing/ci.qmd | 6 +- docs/publishing/posit-cloud.qmd | 4 +- docs/publishing/rstudio-connect.qmd | 6 +- docs/reference/cells/cells-jupyter.qmd | 2 +- docs/reference/cells/cells-knitr.qmd | 2 +- docs/reference/cells/cells-ojs.qmd | 2 +- docs/reference/formats/docx.qmd | 2 +- docs/reference/formats/html.qmd | 2 +- docs/reference/formats/markdown/gfm.qmd | 2 +- docs/reference/formats/pdf.qmd | 2 +- .../formats/presentations/beamer.qmd | 2 +- docs/reference/formats/presentations/pptx.qmd | 2 +- .../formats/presentations/revealjs.qmd | 2 +- docs/reference/formats/typst.qmd | 2 +- docs/reference/index.qmd | 2 +- docs/reference/projects/books.qmd | 3 +- docs/reference/projects/manuscripts.qmd | 4 +- docs/reference/projects/websites.qmd | 3 +- docs/tools/jupyter-lab.qmd | 8 +-- docs/tools/rstudio.qmd | 2 +- docs/tools/text-editors.qmd | 2 +- docs/tools/vscode-notebook.qmd | 6 +- docs/tools/vscode.qmd | 2 +- docs/visual-editor/content.qmd | 2 +- docs/visual-editor/markdown.qmd | 2 +- docs/visual-editor/technical.qmd | 6 +- docs/visual-editor/vscode/index.qmd | 4 +- docs/websites/website-basics.qmd | 12 ++-- docs/websites/website-blog.qmd | 18 ++--- docs/websites/website-tools.qmd | 4 +- 78 files changed, 207 insertions(+), 218 deletions(-) diff --git a/docs/authoring/_mermaid-theming.qmd b/docs/authoring/_mermaid-theming.qmd index 0dbd05e5a0..ddcc43c1ff 100644 --- a/docs/authoring/_mermaid-theming.qmd +++ b/docs/authoring/_mermaid-theming.qmd @@ -8,7 +8,7 @@ The following sections describe the ways in which you can control the color them ### Default Colors for Mermaid Diagrams -If you use Quarto's [bootswatch built-in themes](../output-formats/html-themes.qmd), including the default theme, or a custom theme that uses the same SCSS variables, your Mermaid diagrams will automatically follow your theme. +If you use Quarto's [bootswatch built-in themes](/docs/output-formats/html-themes.qmd), including the default theme, or a custom theme that uses the same SCSS variables, your Mermaid diagrams will automatically follow your theme. The following examples demonstrate this with a few of Quarto's built-in bootswatch themes. @@ -100,7 +100,7 @@ Their CSS variable counterparts are: } ``` -For example, to provide a custom color for the background of the nodes you could [add a custom CSS stylesheet](../../output-formats/html-basics.html#css-styles) containing: +For example, to provide a custom color for the background of the nodes you could [add a custom CSS stylesheet](/docs/output-formats/html-basics.html#css-styles) containing: ```css :root { @@ -108,4 +108,4 @@ For example, to provide a custom color for the background of the nodes you could } ``` -You can find the correspondence between Quarto's variables and Mermaid's native CSS classes in Quarto's source code in the file [embed-mermaid.css](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/html/mermaid/embed-mermaid.css). \ No newline at end of file +You can find the correspondence between Quarto's variables and Mermaid's native CSS classes in Quarto's source code in the file [embed-mermaid.css](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/formats/html/mermaid/embed-mermaid.css). diff --git a/docs/authoring/create-citeable-articles.qmd b/docs/authoring/create-citeable-articles.qmd index c57b9eae5e..be8e707158 100644 --- a/docs/authoring/create-citeable-articles.qmd +++ b/docs/authoring/create-citeable-articles.qmd @@ -162,7 +162,7 @@ Quarto's approach to emitting scholarly metadata is to take the standard CSL fie | Document `date` will be used if not provided. | | +-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ | `url`\ | `citation_fulltext_html_url` | -| `url` will be synthesized for current document if a [`site-url`](../websites/website-tools.qmd#preview-images) has been specified. | | +| `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` | +-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ diff --git a/docs/authoring/cross-references-divs.qmd b/docs/authoring/cross-references-divs.qmd index 5b3b71dbfa..441f7dbcb1 100644 --- a/docs/authoring/cross-references-divs.qmd +++ b/docs/authoring/cross-references-divs.qmd @@ -340,7 +340,7 @@ This renders as: ## Computed Captions -If you want to include computed values in a caption, use the cross-reference div syntax, along with an [inline code expression](../computations/execution-options.html#inline-code). For example: +If you want to include computed values in a caption, use the cross-reference div syntax, along with an [inline code expression](/docs/computations/execution-options.html#inline-code). For example: :::: {.panel-tabset} diff --git a/docs/authoring/markdown-basics.qmd b/docs/authoring/markdown-basics.qmd index 6453d5deaa..46f5d1d602 100644 --- a/docs/authoring/markdown-basics.qmd +++ b/docs/authoring/markdown-basics.qmd @@ -206,7 +206,7 @@ code ``` ```` -If you are creating HTML output there is a wide variety of options available for code block output. See the article on [HTML Code](../output-formats/html-code.qmd) for additional details. +If you are creating HTML output there is a wide variety of options available for code block output. See the article on [HTML Code](/docs/output-formats/html-code.qmd) for additional details. ## Equations diff --git a/docs/authoring/title-blocks.qmd b/docs/authoring/title-blocks.qmd index bdc1b72fa9..d6ac4727e1 100644 --- a/docs/authoring/title-blocks.qmd +++ b/docs/authoring/title-blocks.qmd @@ -93,4 +93,4 @@ The labels for the metadata included in the title block have default values that ## Custom Title Pages -To learn more about providing a complete custom title block, see the [documentation on template partials](../journals/templates.qmd#template-partials). +To learn more about providing a complete custom title block, see the [documentation on template partials](/docs/journals/templates.qmd#template-partials). diff --git a/docs/authoring/variables.qmd b/docs/authoring/variables.qmd index 312405a57b..2494246772 100644 --- a/docs/authoring/variables.qmd +++ b/docs/authoring/variables.qmd @@ -12,7 +12,7 @@ For example, the following prints the `title` from document metadata: {{< meta title >}} ``` -The `{{{< meta >}}}` syntax used here is an example of a [shortcode](../extensions/shortcodes.qmd). Quarto supports the following shortcodes for dynamic variables: +The `{{{< meta >}}}` syntax used here is an example of a [shortcode](/docs/extensions/shortcodes.qmd). Quarto supports the following shortcodes for dynamic variables: | Shortcode | Description | |---------------|--------------------------------------| diff --git a/docs/blog/posts/2022-07-25-feature-extensions/index.qmd b/docs/blog/posts/2022-07-25-feature-extensions/index.qmd index 0c0e603ac2..049c32be22 100644 --- a/docs/blog/posts/2022-07-25-feature-extensions/index.qmd +++ b/docs/blog/posts/2022-07-25-feature-extensions/index.qmd @@ -14,11 +14,11 @@ image-alt: "The main page for the quarto-ext GitHub organization which lists ext Quarto Extensions are a powerful way to modify or extend the behavior of Quarto, and can be created and distributed by anyone. There are three types of extensions available: -- [Shortcodes](../../../extensions/shortcodes.qmd) are special markdown directives that generate various types of content. For example, you could create shortcodes to embed tweets or videos in a document. +- [Shortcodes](/docs/extensions/shortcodes.qmd) are special markdown directives that generate various types of content. For example, you could create shortcodes to embed tweets or videos in a document. -- [Filters](../../../extensions/filters.qmd) are a flexible and powerful tool for introducing new global behaviors and/or new markdown rendering behaviors. For example, you could create filters to implement output folding, an image carousel, or just about anything you can imagine! +- [Filters](/docs/extensions/filters.qmd) are a flexible and powerful tool for introducing new global behaviors and/or new markdown rendering behaviors. For example, you could create filters to implement output folding, an image carousel, or just about anything you can imagine! -- [Formats](../../../extensions/formats.qmd) enable you to create new output formats by bundling together document options, templates, stylesheets, and other content. +- [Formats](/docs/extensions/formats.qmd) enable you to create new output formats by bundling together document options, templates, stylesheets, and other content. Here are some examples of extensions developed and maintained by the core Quarto team: @@ -31,4 +31,4 @@ Here are some examples of extensions developed and maintained by the core Quarto : {tbl-colwidths="\[30,70\]"} -To learn more about using extensions, see the [Extensions](../../../extensions/index.qmd) documentation on the Quarto website. If you want to dive in to creating your own extensions check out the articles on [Creating Shortcodes](../../../extensions/shortcodes.qmd), [Creating Filters](../../../extensions/filters.qmd), and [Creating Formats](../../../extensions/formats.qmd). +To learn more about using extensions, see the [Extensions](/docs/extensions/index.qmd) documentation on the Quarto website. If you want to dive in to creating your own extensions check out the articles on [Creating Shortcodes](/docs/extensions/shortcodes.qmd), [Creating Filters](/docs/extensions/filters.qmd), and [Creating Formats](/docs/extensions/formats.qmd). diff --git a/docs/blog/posts/2023-04-26-1.3-release/index.qmd b/docs/blog/posts/2023-04-26-1.3-release/index.qmd index 7cd41dbdac..6213691b50 100644 --- a/docs/blog/posts/2023-04-26-1.3-release/index.qmd +++ b/docs/blog/posts/2023-04-26-1.3-release/index.qmd @@ -46,7 +46,7 @@ format: Results in an HTML page that includes a link to the additional notebook format in the right margin below the table of contents: -![An HTML document with a link to another format](../../../output-formats/images/other-format.png){.border fig-alt="Screenshot of an HTML page that includes a link to the Jupyter format below the table of contents under the heading Other Formats."} +![An HTML document with a link to another format](/docs/output-formats/images/other-format.png){.border fig-alt="Screenshot of an HTML page that includes a link to the Jupyter format below the table of contents under the heading Other Formats."} Find out more in the documentation on [Including Other Formats](/docs/output-formats/html-multi-format.qmd). @@ -63,9 +63,9 @@ Learn more about the embed shortcode in [Embedding Jupyter Notebook Cells](/docs [Atlassian Confluence](https://www.atlassian.com/software/confluence) is a publishing platform for supporting team collaboration. Quarto now provides support for publishing individual documents, as well as projects composed of multiple documents, into [Confluence Spaces](https://support.atlassian.com/confluence-cloud/docs/use-spaces-to-organize-your-work/). ::: {layout="[800,969]"} -![A Quarto Project](../../../publishing/images/confluence-project.png){fig-alt="A screenshot of a Quarto project in VS Code. On the left in the Explorer, the project folder is called 'Guide-site', and contains folders 'authoring', and 'computation', along with some other files. A document from the folder 'python' inside the folder 'computations' with the title 'Using Python - site' is open in the Source Pane. "} +![A Quarto Project](/docs/publishing/images/confluence-project.png){fig-alt="A screenshot of a Quarto project in VS Code. On the left in the Explorer, the project folder is called 'Guide-site', and contains folders 'authoring', and 'computation', along with some other files. A document from the folder 'python' inside the folder 'computations' with the title 'Using Python - site' is open in the Source Pane. "} -![Published to Confluence](../../../publishing/images/confluence-site.png){fig-alt="A screenshot of Space in Confluence. On the left in the Sdiebar under Pages is a page called 'Guide-site'. Nested under this page are pages called 'authoring', and 'computation', along with some other pages. The 'computation' page item is expanded and shows a page called 'Using Python - site', nested under a page called 'python'. A page is displayed on the right with the title 'Using Python - site'"} +![Published to Confluence](/docs/publishing/images/confluence-site.png){fig-alt="A screenshot of Space in Confluence. On the left in the Sdiebar under Pages is a page called 'Guide-site'. Nested under this page are pages called 'authoring', and 'computation', along with some other pages. The 'computation' page item is expanded and shows a page called 'Using Python - site', nested under a page called 'python'. A page is displayed on the right with the title 'Using Python - site'"} ::: To learn more, head to the documentation on [Confluence Publishing](/docs/publishing/confluence.qmd). diff --git a/docs/books/book-basics.qmd b/docs/books/book-basics.qmd index 687fe42725..d42b70a9d5 100644 --- a/docs/books/book-basics.qmd +++ b/docs/books/book-basics.qmd @@ -15,7 +15,7 @@ Quarto Books are combinations of multiple documents (chapters) into a single man - EPUB - AsciiDoc -HTML books are actually just a special type of [Quarto Website](../websites/website-basics.qmd) and consequently support all of the same features as websites including full-text search. The most important difference is that HTML books use chapter numbers and therefore support [Cross References](../authoring/cross-references.qmd) between different chapters. +HTML books are actually just a special type of [Quarto Website](/docs/websites/website-basics.qmd) and consequently support all of the same features as websites including full-text search. The most important difference is that HTML books use chapter numbers and therefore support [Cross References](/docs/authoring/cross-references.qmd) between different chapters. Here are some examples of books created with Quarto: @@ -25,7 +25,7 @@ Here are some examples of books created with Quarto: | [Python for Data Analysis](https://wesmckinney.com/book/) | [Code](https://github.com/wesm/pydata-book/tree/3rd-edition) | | [Visualization Curriculum](https://jjallaire.github.io/visualization-curriculum) | [Code](https://github.com/jjallaire/visualization-curriculum) | -Quarto books can be published to a wide variety of destinations including GitHub Pages, Netlify, RStudio Connect, or any other static hosting service or intranet web server. See the documentation on [Publishing Websites](../publishing/index.qmd) for additional details. +Quarto books can be published to a wide variety of destinations including GitHub Pages, Netlify, RStudio Connect, or any other static hosting service or intranet web server. See the documentation on [Publishing Websites](/docs/publishing/index.qmd) for additional details. ## Quick Start @@ -38,19 +38,19 @@ Follow the Quick Start for your tool of choice to get a simple book up and runni To create a new book project within VS Code, execute the **Quarto: Create Project** command from the command-palette: -![](../websites/images/vscode-create-project-command.png) +![](/docs/websites/images/vscode-create-project-command.png) Then, select **Book Project**: -![](../websites/images/vscode-create-project-book.png){.border} +![](/docs/websites/images/vscode-create-project-book.png){.border} You'll be prompted to select a parent directory to create the project within. Then, you'll be asked to name the directory for your book project: -![](../websites/images/vscode-create-project-directory.png){.border} +![](/docs/websites/images/vscode-create-project-directory.png){.border} The new book project will be created and opened within VS Code. Click the **Render** button to preview the book: -![](../websites/images/vscode-create-project-render-book.png) +![](/docs/websites/images/vscode-create-project-render-book.png) The preview will show to the right of the source file. As you re-render `index.qmd` or render other files like `intro.qmd`, the preview is automatically updated. @@ -61,18 +61,18 @@ To create a new book project within RStudio, use the **New Project** command and :::{layout-ncol="2"} -![](../websites/images/rstudio-project-new-directory.png){.border} +![](/docs/websites/images/rstudio-project-new-directory.png){.border} -![](../websites/images/rstudio-project-book.png){.border} +![](/docs/websites/images/rstudio-project-book.png){.border} ::: Then, provide a directory name and other relevant options for the book: -![](../websites/images/rstudio-project-book-options.png){.border} +![](/docs/websites/images/rstudio-project-book-options.png){.border} Click the **Render** button to preview the book: -![](../websites/images/rstudio-project-book-preview.png) +![](/docs/websites/images/rstudio-project-book-preview.png) The preview will show to the right of the source file. As you re-render `index.qmd` or render other files like `intro.qmd`, the preview is automatically updated. @@ -131,7 +131,7 @@ format: -See the [Project Basics](../projects/quarto-projects.qmd) article to learn more about working with projects, including how to add custom pre and post render scripts to your book. +See the [Project Basics](/docs/projects/quarto-projects.qmd) article to learn more about working with projects, including how to add custom pre and post render scripts to your book. ### Book Preview @@ -178,7 +178,7 @@ mybook/ mybook.epub ``` -See the documentation on [Publishing Websites](../publishing/index.qmd) for details on how to publish books to GitHub Pages, Netlify, and other services. Note that in that documentation the `output-dir` may be referred to as `_site`: for publishing books you should use `_book` rather than `_site`. +See the documentation on [Publishing Websites](/docs/publishing/index.qmd) for details on how to publish books to GitHub Pages, Netlify, and other services. Note that in that documentation the `output-dir` may be referred to as `_site`: for publishing books you should use `_book` rather than `_site`. ### AsciiDoc Books {#asciidoc-books} @@ -222,8 +222,8 @@ Once you've got the basic book template up and running check out these articles - [Book Output](book-output.qmd) covers customizing the style and appearance of your book in the various output format as well as how to provide navigation and other tools for readers. -- [Book Options](../reference/projects/books.qmd) provides a comprehensive reference to all of the available book options. +- [Book Options](/docs/reference/projects/books.qmd) provides a comprehensive reference to all of the available book options. -- [Code Execution](../projects/code-execution.qmd) provides tips for optimizing the rendering of books with large numbers of documents or expensive computations. +- [Code Execution](/docs/projects/code-execution.qmd) provides tips for optimizing the rendering of books with large numbers of documents or expensive computations. -- [Publishing Websites](../publishing/index.qmd) enumerates the various options for publishing your book as a website including GitHub Pages, Netlify, and RStudio Connect. +- [Publishing Websites](/docs/publishing/index.qmd) enumerates the various options for publishing your book as a website including GitHub Pages, Netlify, and RStudio Connect. diff --git a/docs/books/book-crossrefs.qmd b/docs/books/book-crossrefs.qmd index 76c5beff0d..360052c6a4 100644 --- a/docs/books/book-crossrefs.qmd +++ b/docs/books/book-crossrefs.qmd @@ -10,7 +10,7 @@ To create books that are consumable in all of these mediums, special care should Quarto cross references provide automatic numbering and reference creation for figures, tables, equations, sections, listings, theorems, and proofs. In books, cross references work the same way except they can reach across chapters. -If you aren't already familiar with using crossrefs you may want to read the documentation on [cross references](../authoring/cross-references.qmd) before reading on about how they work with books. +If you aren't already familiar with using crossrefs you may want to read the documentation on [cross references](/docs/authoring/cross-references.qmd) before reading on about how they work with books. ## Creating References diff --git a/docs/books/book-output.qmd b/docs/books/book-output.qmd index 7408d6259f..606ced0ff0 100644 --- a/docs/books/book-output.qmd +++ b/docs/books/book-output.qmd @@ -31,14 +31,14 @@ Note that in the above configuration the `highlight-style` option applies to all ### Website Tools -HTML books are at their core [Quarto Websites](../websites/website-basics.qmd) with some special navigational behavior built in. This means that all of the features described for enhancing websites are also available for books, including: +HTML books are at their core [Quarto Websites](/docs/websites/website-basics.qmd) with some special navigational behavior built in. This means that all of the features described for enhancing websites are also available for books, including: -- [Navbars](../websites/website-navigation.html#top-navigation) -- [Social Metadata](../websites/website-tools.qmd#social-metadata) -- [Full Text Search](../websites/website-search.html) -- [Google Analytics](../websites/website-tools.html#google-analytics) -- [Headers and Footers](../websites/website-tools.html#headers-footers) -- [Dark Mode](../websites/website-tools.html#dark-mode) +- [Navbars](/docs/websites/website-navigation.html#top-navigation) +- [Social Metadata](/docs/websites/website-tools.qmd#social-metadata) +- [Full Text Search](/docs/websites/website-search.html) +- [Google Analytics](/docs/websites/website-tools.html#google-analytics) +- [Headers and Footers](/docs/websites/website-tools.html#headers-footers) +- [Dark Mode](/docs/websites/website-tools.html#dark-mode) {{< include _book-vs-website-key.qmd >}} @@ -70,13 +70,13 @@ Note the various tools that now appear: - The buttons immediately below the book title in the sidebar provide a link to the GitHub repo for the book, downloads for PDF and ePub versions of the book, and links for sharing the book on Twitter and Facebook. -- Immediately below the table of contents on the right there is an "Edit this page" link that takes the reader to the edit interface on GitHub for the current chapter. Note that in this example we specify `repo-actions: [edit]`. You can optionally also add `issue` and `source` actions (e.g. `repo-actions: [edit, issue, source]`). There are additional options available (`repo-subdir` and `repo-branch`) for [customizing repository links](../websites/website-navigation.qmd#github-links). +- Immediately below the table of contents on the right there is an "Edit this page" link that takes the reader to the edit interface on GitHub for the current chapter. Note that in this example we specify `repo-actions: [edit]`. You can optionally also add `issue` and `source` actions (e.g. `repo-actions: [edit, issue, source]`). There are additional options available (`repo-subdir` and `repo-branch`) for [customizing repository links](/docs/websites/website-navigation.qmd#github-links). -- The [Hypothesis](https://web.hypothes.is/) commenting bar appears on the far right of the page. Note that [commenting](../output-formats/html-basics.qmd#commenting) is a feature available for all Quarto HTML output so appears in its own YAML key. +- The [Hypothesis](https://web.hypothes.is/) commenting bar appears on the far right of the page. Note that [commenting](/docs/output-formats/html-basics.qmd#commenting) is a feature available for all Quarto HTML output so appears in its own YAML key. #### Sidebar Options -Note that books utilize the standard sidebar component from [Quarto Websites](../websites/website-basics.qmd). This means that you can use any of the available [sidebar options](../websites/website-navigation.qmd#side-navigation) within your `book` configuration. For example, here we specify a docked sidebar with a light background: +Note that books utilize the standard sidebar component from [Quarto Websites](/docs/websites/website-basics.qmd). This means that you can use any of the available [sidebar options](/docs/websites/website-navigation.qmd#side-navigation) within your `book` configuration. For example, here we specify a docked sidebar with a light background: ``` yaml book: @@ -165,7 +165,7 @@ format: theme: [cosmo, theme.scss] ``` -You can learn more about creating theme files in the documentation on [HTML Themes](../output-formats/html-themes.qmd). +You can learn more about creating theme files in the documentation on [HTML Themes](/docs/output-formats/html-themes.qmd). You can also just use plain CSS. For example: @@ -214,4 +214,4 @@ format: reference-doc: custom-reference.docx ``` -Learn more about creating and customizing a reference document in the documentation on [Word templates](../output-formats/ms-word-templates.qmd). +Learn more about creating and customizing a reference document in the documentation on [Word templates](/docs/output-formats/ms-word-templates.qmd). diff --git a/docs/books/book-structure.qmd b/docs/books/book-structure.qmd index 0b7593859f..45a5f02d99 100644 --- a/docs/books/book-structure.qmd +++ b/docs/books/book-structure.qmd @@ -52,7 +52,7 @@ All chapters are numbered by default. If you want a chapter to be unnumbered sim # Resources {.unnumbered} ``` -You can mix together numbered and unnumbered chapters. Note however that while you can link to unnumbered chapters, you can't [cross reference](../authoring/cross-references.qmd) figures, tables, etc. within them. Unnumbered chapters are therefore mostly useful for prefatory content or references at the end of your book. +You can mix together numbered and unnumbered chapters. Note however that while you can link to unnumbered chapters, you can't [cross reference](/docs/authoring/cross-references.qmd) figures, tables, etc. within them. Unnumbered chapters are therefore mostly useful for prefatory content or references at the end of your book. ## Section Numbers diff --git a/docs/computations/julia.qmd b/docs/computations/julia.qmd index d1b6c6f0ae..064858ad1c 100644 --- a/docs/computations/julia.qmd +++ b/docs/computations/julia.qmd @@ -47,11 +47,11 @@ plot(sin, ``` ```` -You'll note that there are some special comments at the top of the code block. These are cell level options that make the figure [cross-referenceable](../authoring/cross-references.qmd). +You'll note that there are some special comments at the top of the code block. These are cell level options that make the figure [cross-referenceable](/docs/authoring/cross-references.qmd). This document would result in the following rendered output: -![](../../images/hello-julia.png){.border fig-alt="Example Plots Demo output with title, author, date published and main section on Parametric plots which contains text, a toggleable code field, and the output of the plot, with the caption Figure 1 Parametric Plots."} +![](/images/hello-julia.png){.border fig-alt="Example Plots Demo output with title, author, date published and main section on Parametric plots which contains text, a toggleable code field, and the output of the plot, with the caption Figure 1 Parametric Plots."} You can produce a wide variety of output types from executable code blocks, including plots, tabular output from data frames, and plain text output (e.g. printing the results of statistical summaries). diff --git a/docs/computations/python.qmd b/docs/computations/python.qmd index 2676744e08..a8c94c06a3 100644 --- a/docs/computations/python.qmd +++ b/docs/computations/python.qmd @@ -1,7 +1,7 @@ --- title: "Using Python" jupyter-language: "Python" -jupyter-screenshot: "![](../get-started/hello/images/jupyter-basics.png){.border fig-alt='A Jupyter notebook titled Quarto Basics containing some text, a code cell, and the result of the code cell, which is a line plot on a polar axis.'}" +jupyter-screenshot: "![](/docs/get-started/hello/images/jupyter-basics.png){.border fig-alt='A Jupyter notebook titled Quarto Basics containing some text, a code cell, and the result of the code cell, which is a line plot on a polar axis.'}" vscode-extension: "[Python Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)" vscode-screenshot: "![](images/python-vscode){.border fig-alt='Screen shot of VS Code editor with three vertical sections. The leftmost includes the file explorer, and quarto help. The second pane is the source code for a quarto file with python code. The third is interactive with Python running and output of the code cells shown.'}" --- @@ -46,11 +46,11 @@ plt.show() ``` ```` -You'll note that there are some special comments at the top of the code block. These are cell level options that make the figure [cross-referenceable](../authoring/cross-references.qmd). +You'll note that there are some special comments at the top of the code block. These are cell level options that make the figure [cross-referenceable](/docs/authoring/cross-references.qmd). This document would result in the following rendered output: -![](../../images/hello-jupyter.png){.border fig-alt="Example output where header reads: matplotlib demo, the body reads: For a demonstration of a line plot on a polar axis, see Figure 1. Below the body text is a toggleable field to reveal the code, and the Figure 1 image with a caption that reads: Figure 1: A line plot on a polar axis."} +![](/images/hello-jupyter.png){.border fig-alt="Example output where header reads: matplotlib demo, the body reads: For a demonstration of a line plot on a polar axis, see Figure 1. Below the body text is a toggleable field to reveal the code, and the Figure 1 image with a caption that reads: Figure 1: A line plot on a polar axis."} You can produce a wide variety of output types from executable code blocks, including plots, tabular output from data frames, and plain text output (e.g. printing the results of statistical summaries). @@ -110,4 +110,3 @@ Note that this step is not required if you are merely using conda with Quarto. I ::: {{< include _jupyter-daemon.md >}} - diff --git a/docs/computations/r.qmd b/docs/computations/r.qmd index db04d75a64..f45f5b6ae7 100644 --- a/docs/computations/r.qmd +++ b/docs/computations/r.qmd @@ -39,11 +39,11 @@ ggplot(airquality, aes(Temp, Ozone)) + ``` ```` -You'll note that there are some special comments at the top of the code block. These are cell level options that make the figure [cross-referenceable](../authoring/cross-references.qmd). +You'll note that there are some special comments at the top of the code block. These are cell level options that make the figure [cross-referenceable](/docs/authoring/cross-references.qmd). This document results in the following rendered output: -![](../../images/hello-knitr.png){.border fig-alt="Example output with title (ggplot2 demo), author (Norah Jones), and date (5/22/2021). Below is a header reading Air Quality followed by body text (Figure 1 further explores the impact of temperature on ozone level.) with a toggleable code field, and figure with caption that reads Figure 1 Temperature and ozone level."} +![](/images/hello-knitr.png){.border fig-alt="Example output with title (ggplot2 demo), author (Norah Jones), and date (5/22/2021). Below is a header reading Air Quality followed by body text (Figure 1 further explores the impact of temperature on ozone level.) with a toggleable code field, and figure with caption that reads Figure 1 Temperature and ozone level."} You can produce a wide variety of output types from executable code blocks, including plots, tabular output from data frames, and plain text output (e.g. printing the results of statistical summaries). @@ -104,7 +104,7 @@ Quarto will select a version of R by looking on the system `PATH`. In addition, ## VS Code -The [Quarto Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) for VS Code provides a variety of tools for working with `.qmd` files in VS Code. The extension integrates directly with the [R Extension](https://marketplace.visualstudio.com/items?itemName=Ikuyadeu.r) to provide the following R-specific capabilities: +The [Quarto Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) for VS Code provides a variety of tools for working with `.qmd` files in VS Code. The extension integrates directly with the [R Extension](https://marketplace.visualstudio.com/items?itemName=REditorSupport.r) to provide the following R-specific capabilities: 1) Code completion 2) Cell execution @@ -152,7 +152,7 @@ Unless you want to specify a cross-reference avoid using the [reserved cross-ref ## Output Formats {#output-formats} -Another difference between R Markdown and Quarto is related to output formats. Quarto includes many more built in output formats (and many more options for customizing each format). Quarto also has native features for special project types like [Websites](../websites/), [Books](../books/), and [Blogs](../websites/website-blog.qmd) (rather than relying on external packages). +Another difference between R Markdown and Quarto is related to output formats. Quarto includes many more built in output formats (and many more options for customizing each format). Quarto also has native features for special project types like [Websites](/docs/websites/), [Books](/docs/books/), and [Blogs](/docs/websites/website-blog.qmd) (rather than relying on external packages). To use a format in Quarto you use the `format` key rather than the `output` key as you did in R Markdown. Here's a comparison of equivalent format specifications: @@ -182,9 +182,9 @@ format: One source of the difference in syntax is that Quarto is more closely aligned with [Pandoc](https://pandoc.org) format names and options (thus the use of `-` as a word separator rather than `_`). -See the listing of all [supported formats](../output-formats/all-formats.qmd) along with their user guides and reference pages for more details. +See the listing of all [supported formats](/docs/output-formats/all-formats.qmd) along with their user guides and reference pages for more details. -See the articles on creating [Websites](../websites/), [Books](../books/), and [Blogs](../websites/website-blog.qmd) for additional details on more advanced output formats. +See the articles on creating [Websites](/docs/websites/), [Books](/docs/books/), and [Blogs](/docs/websites/website-blog.qmd) for additional details on more advanced output formats. ## Data Frames diff --git a/docs/dashboards/interactivity/shiny-python/index.qmd b/docs/dashboards/interactivity/shiny-python/index.qmd index dac29143f3..90852d7f67 100644 --- a/docs/dashboards/interactivity/shiny-python/index.qmd +++ b/docs/dashboards/interactivity/shiny-python/index.qmd @@ -119,7 +119,7 @@ Similarly, Shiny will only automatically re-run functions that are reactivity-aw Next, we'll explore a more in-depth example that covers more features, including factoring out setup code, reactive calculations, and more advanced layout constructs like pages. Here is the interactive document we'll be building: -![](../../images/penguins-shiny.png){.border fig-alt="Screenshot of a Palmer Penguins dashboard. Navigation bar shows two pages: Plots and Data. On the left is a sidebar with an image of penguins followed by four inputs: a set of checkboxes for Species; a set of checkboxes for Islands; and dropdown for Distribution; and a checkbox to show rug marks. On the right the page is divided into two rows each showing a density plot: the top row of bill_depth_mm; the bottom row of bill_length_mm"} +![](/images/penguins-shiny.png){.border fig-alt="Screenshot of a Palmer Penguins dashboard. Navigation bar shows two pages: Plots and Data. On the left is a sidebar with an image of penguins followed by four inputs: a set of checkboxes for Species; a set of checkboxes for Islands; and dropdown for Distribution; and a checkbox to show rug marks. On the right the page is divided into two rows each showing a density plot: the top row of bill_depth_mm; the bottom row of bill_length_mm"} Here is the source code for this dashboard. You can click on the numbers on the far right for additional explanation of syntax and mechanics, and we'll also explain in more detail below. @@ -220,4 +220,4 @@ To learn more about Shiny for Python interactive documents see the following art [Execution Contexts](execution.qmd) goes in depth on when different code cells run (e.g. rendering vs. serving). -[Shiny for Python](https://shiny.posit.co/py/) provides in-depth documentation on all of the available UI and ouput widgets, as well as conceptual discussions on how things work. \ No newline at end of file +[Shiny for Python](https://shiny.posit.co/py/) provides in-depth documentation on all of the available UI and ouput widgets, as well as conceptual discussions on how things work. diff --git a/docs/extensions/_formats-common.qmd b/docs/extensions/_formats-common.qmd index 9759cfbb06..62632be966 100644 --- a/docs/extensions/_formats-common.qmd +++ b/docs/extensions/_formats-common.qmd @@ -18,7 +18,7 @@ This is often the preferred way to get started with a format as it provides the quarto add {{< meta example-org >}}/{{< meta example-format >}} ``` -Note that it is possible to bundle and distribute extensions as simple gzip archives (as opposed to using a GitHub repository as described above). See the article on [Distributing Extensions](../extensions/distributing.qmd) for additional details. +Note that it is possible to bundle and distribute extensions as simple gzip archives (as opposed to using a GitHub repository as described above). See the article on [Distributing Extensions](/docs/extensions/distributing.qmd) for additional details. ## Multiple Formats diff --git a/docs/extensions/creating.qmd b/docs/extensions/creating.qmd index dae06b673b..981d352457 100644 --- a/docs/extensions/creating.qmd +++ b/docs/extensions/creating.qmd @@ -12,7 +12,7 @@ Quarto Extensions are a powerful way to modify or extend the behavior of Quarto, |----------------------------------|-----------------------------------------------------------------------------------| | [Shortcodes](shortcodes.qmd) | Special markdown directives that generate various types of content. For example, you could create shortcodes to embed tweets or videos in a document. | | [Filters](filters.qmd) | A flexible and powerful tool for introducing new global behaviors and/or new markdown rendering behaviors. For example, you could create filters to implement output folding, an image carousel, or just about anything you can imagine! | -| [Journal Articles](../journals/formats.qmd) | Enable authoring of professional Journal articles using markdown, and produce both LaTeX (PDF) and HTML versions of the articles. | +| [Journal Articles](/docs/journals/formats.qmd) | Enable authoring of professional Journal articles using markdown, and produce both LaTeX (PDF) and HTML versions of the articles. | | [Custom Formats](formats.qmd) | Create new output formats by bundling together document options, templates, style sheets, and other content. | | [Revealjs Plugins](revealjs.qmd) | Extend the capabilities of HTML presentations created with Revealjs. | | [Project Types](project-types.qmd) | Create new project project types that bundle together standard content and options, or make it easy to create a website for a custom HTML format. | diff --git a/docs/extensions/formats.qmd b/docs/extensions/formats.qmd index f2a10754f0..b84bcd5539 100644 --- a/docs/extensions/formats.qmd +++ b/docs/extensions/formats.qmd @@ -42,7 +42,7 @@ Custom formats can also be used with the `--to` argument to `quarto render`. For quarto render document.qmd --to acm-html ``` - Note that if you are specifically interested in using or creating custom formats for journals and manuscripts, you may want to proceed instead to the documentation on [Journal Articles](../journals/index.qmd). + Note that if you are specifically interested in using or creating custom formats for journals and manuscripts, you may want to proceed instead to the documentation on [Journal Articles](/docs/journals/index.qmd). ## Quick Start diff --git a/docs/extensions/project-types.qmd b/docs/extensions/project-types.qmd index b69aec0711..cc2de81038 100644 --- a/docs/extensions/project-types.qmd +++ b/docs/extensions/project-types.qmd @@ -104,7 +104,7 @@ You'll also note that we additionally define a `lexdocs-html` [Custom Format](fo There are three additional files referenced in the custom `project` definition in `_extension.yml`. We won't show their source code, but here's a rundown on the role they play: - `lexcorp.png` is a logo added to the `sidebar`. -- `theme.scss` provides a [custom theme](../output-formats/html-themes.qmd) for HTML output. +- `theme.scss` provides a [custom theme](/docs/output-formats/html-themes.qmd) for HTML output. - `filter.lua` provides some additional transformations required by the format. ### Starter Template @@ -133,7 +133,7 @@ Users of the template will natually change the default `title`, and can add what If you are using Quarto to produce markdown for another publishing system, you can use a project type extension to tailor the markdown output created by Quarto, as well as integrate with the native preview capabilities of the other system. -Quarto includes a couple of built-in project-types for integrating with the [Hugo](../output-formats/hugo.qmd) and [Docusaurus](../output-formats/docusaurus.qmd) publishing systems. You can see the source code for these project types here: +Quarto includes a couple of built-in project-types for integrating with the [Hugo](/docs/output-formats/hugo.qmd) and [Docusaurus](/docs/output-formats/docusaurus.qmd) publishing systems. You can see the source code for these project types here: - [`hugo`](https://github.com/quarto-dev/quarto-cli/blob/main/src/resources/extensions/quarto/hugo/_extension.yml) project type diff --git a/docs/extensions/revealjs.qmd b/docs/extensions/revealjs.qmd index 5c7f4c059c..56f0cf66f9 100644 --- a/docs/extensions/revealjs.qmd +++ b/docs/extensions/revealjs.qmd @@ -6,7 +6,7 @@ title: "Revealjs Plugins" ## Overview -Revealjs plugins enable you to extend the capabilities of HTML presentations created with [Revealjs](../presentations/revealjs/). The Reveal Plugin API is very rich, and many of the built-in capabilities of Quarto Revealjs presentations are implemented as plugins, including [Menu](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/revealjs/plugins/menu), [Chalkboard](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/revealjs/plugins/chalkboard), and [PDF Export](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/revealjs/plugins/pdfexport). +Revealjs plugins enable you to extend the capabilities of HTML presentations created with [Revealjs](/docs/presentations/revealjs/). The Reveal Plugin API is very rich, and many of the built-in capabilities of Quarto Revealjs presentations are implemented as plugins, including [Menu](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/revealjs/plugins/menu), [Chalkboard](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/revealjs/plugins/chalkboard), and [PDF Export](https://github.com/quarto-dev/quarto-cli/tree/main/src/resources/formats/revealjs/plugins/pdfexport). Here are some examples of Revealjs plugins packaged as Quarto extensions: diff --git a/docs/extensions/shortcodes.qmd b/docs/extensions/shortcodes.qmd index 7d2c42015c..2b80632f08 100644 --- a/docs/extensions/shortcodes.qmd +++ b/docs/extensions/shortcodes.qmd @@ -20,14 +20,14 @@ Quarto supports several shortcodes natively: | Shortcode | Description | |-------------------------------------|-----------------------------------| -| [var](../authoring/variables.qmd#var) | Print value from `_variables.yml` file | -| [meta](../authoring/variables.qmd#meta) | Print value from document metadata | -| [env](../authoring/variables.qmd#url) | Print system environment variable | -| [pagebreak](../authoring/markdown-basics.qmd#page-breaks) | Insert a native page-break | -| [kbd](../authoring/markdown-basics.qmd#keyboard-shortcuts) | Describe keyboard shortcuts | +| [var](/docs/authoring/variables.qmd#var) | Print value from `_variables.yml` file | +| [meta](/docs/authoring/variables.qmd#meta) | Print value from document metadata | +| [env](/docs/authoring/variables.qmd#url) | Print system environment variable | +| [pagebreak](/docs/authoring/markdown-basics.qmd#page-breaks) | Insert a native page-break | +| [kbd](/docs/authoring/markdown-basics.qmd#keyboard-shortcuts) | Describe keyboard shortcuts | | [video](/docs/authoring/videos.qmd) | Embed a video in a document | -| [include](../authoring/includes.qmd) | Include contents of another qmd | -| [embed](../authoring/notebook-embed.qmd) | Embed cells from a Jupyter Notebook | +| [include](/docs/authoring/includes.qmd) | Include contents of another qmd | +| [embed](/docs/authoring/notebook-embed.qmd) | Embed cells from a Jupyter Notebook | This article describes how to create your own shortcodes. diff --git a/docs/extensions/starter-templates.qmd b/docs/extensions/starter-templates.qmd index 11a04044c3..bd889a380d 100644 --- a/docs/extensions/starter-templates.qmd +++ b/docs/extensions/starter-templates.qmd @@ -9,7 +9,7 @@ title: "Starter Templates" Starter templates provide a straightforward way for users to get started with new Quarto projects by providing example content and options. You might use starter templates to: -1. Create a working initial document for [Journal Articles](../journals/index.qmd) or [Custom Formats](formats.qmd). +1. Create a working initial document for [Journal Articles](/docs/journals/index.qmd) or [Custom Formats](formats.qmd). 2. Provide the initial content for a custom [Project Type](project-types.qmd). @@ -51,7 +51,7 @@ If the command is run in an empty directory, the user will be prompted whether t ## Extensions & Templates -When creating [Journal Articles](../journals/index.qmd), [Custom Formats](formats.qmd), or [Project Type](project-types.qmd) extensions, we recommend that you additionally provide a starter template to make it easy for users to get started. +When creating [Journal Articles](/docs/journals/index.qmd), [Custom Formats](formats.qmd), or [Project Type](project-types.qmd) extensions, we recommend that you additionally provide a starter template to make it easy for users to get started. This is generally as easy as adding a `template.qmd` file to your extension that demonstrates its use. With this configuration, users can either begin using your extension via the template or by a conventional `quarto install` of the extension. @@ -66,6 +66,3 @@ Alternatively, you can add the format (without the template) into an existing pr ```{.bash filename="Terminal"} quarto add quarto-journals/acm ``` - - - diff --git a/docs/get-started/authoring/rstudio.qmd b/docs/get-started/authoring/rstudio.qmd index e2ccfce318..66a3b487da 100644 --- a/docs/get-started/authoring/rstudio.qmd +++ b/docs/get-started/authoring/rstudio.qmd @@ -68,7 +68,7 @@ We recommend the use of TinyTeX (which is based on TexLive), which you can insta quarto install tinytex ``` -See the article on [PDF Engines](../../output-formats/pdf-engine.qmd) for details on using other LaTeX distributions and PDF compilation engines. +See the article on [PDF Engines](/docs/output-formats/pdf-engine.qmd) for details on using other LaTeX distributions and PDF compilation engines. Once you have LaTeX setup, click on ![](images/rstudio-render-button.png){width="25" height="20"} **Render** (or use the keyboard shortcut ⇧⌘K). We recommend also checking the box for **Render on Save** for a live preview of your changes. diff --git a/docs/get-started/computations/rstudio.qmd b/docs/get-started/computations/rstudio.qmd index 4b16b13287..f7b2dd8140 100644 --- a/docs/get-started/computations/rstudio.qmd +++ b/docs/get-started/computations/rstudio.qmd @@ -214,7 +214,7 @@ We also added an option to control how multiple figures are laid out---in this c ``` If you have 3, 4, or more figures in a panel there are many options available for customizing their layout. -See the article [Figure Layout](../../authoring/figures.qmd#figure-panels) for details. +See the article [Figure Layout](/docs/authoring/figures.qmd#figure-panels) for details. Finally, we added an option to control the span of the page that our figures occupy. @@ -223,7 +223,7 @@ Finally, we added an option to control the span of the page that our figures occ ``` This allows our figure display to span out beyond the normal body text column. -See the documentation on [Article Layout](../../authoring/article-layout.qmd) to learn about all of the available layout options. +See the documentation on [Article Layout](/docs/authoring/article-layout.qmd) to learn about all of the available layout options. ## Data Frames diff --git a/docs/get-started/hello/neovim.qmd b/docs/get-started/hello/neovim.qmd index 7320f53f0b..444fd11897 100644 --- a/docs/get-started/hello/neovim.qmd +++ b/docs/get-started/hello/neovim.qmd @@ -222,8 +222,8 @@ See Amy Cesal's article on [Writing Alt Text for Data Visualization](https://med You now know the basics of creating and authoring Quarto documents. The following tutorials explore Quarto in more depth: -- [Tutorial: Computations](../computations/) --- Learn how to tailor the behavior and output of executable code blocks. +- [Tutorial: Computations](/docs/computations/) --- Learn how to tailor the behavior and output of executable code blocks. -- [Tutorial: Authoring](../authoring/) --- Learn more about output formats and technical writing features like citations, crossrefs, and advanced layout. +- [Tutorial: Authoring](/docs/authoring/) --- Learn more about output formats and technical writing features like citations, crossrefs, and advanced layout. See the article on [Using Neovim with Quarto](/docs/tools/neovim.qmd) to learn more about installing, using, and customizing Neovim for Quarto. diff --git a/docs/guide/index.qmd b/docs/guide/index.qmd index 1111ff5890..1c91f192ee 100644 --- a/docs/guide/index.qmd +++ b/docs/guide/index.qmd @@ -1,6 +1,6 @@ --- title: "Guide" -subtitle: Comprehensive guide to using Quarto. If you are just starting out, you may want to explore the [tutorials](../get-started/index.qmd) to learn the basics. +subtitle: Comprehensive guide to using Quarto. If you are just starting out, you may want to explore the [tutorials](/docs/get-started/index.qmd) to learn the basics. page-layout: article anchor-sections: false search: false diff --git a/docs/interactive/layout.qmd b/docs/interactive/layout.qmd index ef2fb7bc6a..505461ac15 100644 --- a/docs/interactive/layout.qmd +++ b/docs/interactive/layout.qmd @@ -225,7 +225,7 @@ You can arrange multiple interactive components into a panel using the `layout` ![](images/application-panel-layout.png){.border} -As described in the article on [Figures](../authoring/figures.qmd#complex-layouts), you can arrange panels of figures in very flexible fashion using the `layout` attribute. For the example above we enclosed the three visualizations in the following div: +As described in the article on [Figures](/docs/authoring/figures.qmd#complex-layouts), you can arrange panels of figures in very flexible fashion using the `layout` attribute. For the example above we enclosed the three visualizations in the following div: ``` default ::: {layout="[ [1], [1,1] ]"} diff --git a/docs/interactive/ojs/code-reuse.qmd b/docs/interactive/ojs/code-reuse.qmd index b86000368b..67ee9cff1c 100644 --- a/docs/interactive/ojs/code-reuse.qmd +++ b/docs/interactive/ojs/code-reuse.qmd @@ -2,7 +2,7 @@ title: "Code Reuse" --- -As you build larger Quarto projects (like [websites](../../websites/) and [books](../../books/)) that incorporate OJS, you'll likely want to re-use code, data, and output across different pages. +As you build larger Quarto projects (like [websites](/docs/websites/) and [books](/docs/books/)) that incorporate OJS, you'll likely want to re-use code, data, and output across different pages. ## Modules diff --git a/docs/interactive/ojs/ojs-cells.qmd b/docs/interactive/ojs/ojs-cells.qmd index 97f3fad687..f2d33722a2 100644 --- a/docs/interactive/ojs/ojs-cells.qmd +++ b/docs/interactive/ojs/ojs-cells.qmd @@ -77,7 +77,7 @@ If you click the inspector you'll see it expand to reveal the data as JSON. We talked about showing and hiding source code above, but what about controlling exactly how it's displayed? -There are options available for customizing the appearance of code blocks (highlighting, background, border, etc.) as well as how horizontal overflow is handled. See the article on [HTML Code Blocks](../../output-formats/html-code.qmd) for all of the details. +There are options available for customizing the appearance of code blocks (highlighting, background, border, etc.) as well as how horizontal overflow is handled. See the article on [HTML Code Blocks](/docs/output-formats/html-code.qmd) for all of the details. One option we wanted to specifically highlight here is code folding, which enables you to collapse code but still provide an option for users to view it. This is especially handy for custom JavaScript visualizations as they often span dozens of lines of code. @@ -234,7 +234,7 @@ Learn more in the article on [Layout](../layout.qmd) for interactive documents. ## Cell Figures -OJS cells can also be rendered as numbered, [cross-referenceable](../../authoring/cross-references.qmd) figures. To do this, add the `label` and `fig-cap` options to the cell. For example: +OJS cells can also be rendered as numbered, [cross-referenceable](/docs/authoring/cross-references.qmd) figures. To do this, add the `label` and `fig-cap` options to the cell. For example: ```{ojs} //| echo: fenced @@ -261,7 +261,7 @@ Plot.rectY(filtered, See @fig-penguin-body-mass for further illustration. -To reference the figure use its label in a markdown [cross reference](../../authoring/cross-references.qmd): +To reference the figure use its label in a markdown [cross reference](/docs/authoring/cross-references.qmd): ``` markdown See @fig-penguin-body-mass for further illustration. diff --git a/docs/interactive/shiny/running.qmd b/docs/interactive/shiny/running.qmd index d8bde5d8f9..1148628bb2 100644 --- a/docs/interactive/shiny/running.qmd +++ b/docs/interactive/shiny/running.qmd @@ -71,7 +71,7 @@ library(quarto) quarto_publish_app(server = "shinyapps.io") ``` -If you are using RStudio you can also use the **Publish** button ![](../../output-formats/images/publish-button.png){width="21"} available when working with an interactive document: +If you are using RStudio you can also use the **Publish** button ![](/docs/output-formats/images/publish-button.png){width="21"} available when working with an interactive document: ![](images/rstudio-ide-publish.png){.border width="587"} @@ -99,7 +99,7 @@ library(quarto) quarto_publish_app(server = "rsc.example.com") ``` -If you are using RStudio you can also use the **Publish** button ![](../../output-formats/images/publish-button.png){width="21"} as described above in the ShinyApps documentation: +If you are using RStudio you can also use the **Publish** button ![](/docs/output-formats/images/publish-button.png){width="21"} as described above in the ShinyApps documentation: ![](images/rstudio-ide-rsc-publish.png){.border width="573"} diff --git a/docs/interactive/widgets/htmlwidgets.qmd b/docs/interactive/widgets/htmlwidgets.qmd index 02d1a151c7..4e5a64c026 100644 --- a/docs/interactive/widgets/htmlwidgets.qmd +++ b/docs/interactive/widgets/htmlwidgets.qmd @@ -50,6 +50,6 @@ dygraph(mdeaths, "Male Deaths") dygraph(ldeaths, "All Deaths") ``` -See the article on [Figures](../../authoring/figures.qmd#complex-layouts) for additional documentation on custom layouts. +See the article on [Figures](/docs/authoring/figures.qmd#complex-layouts) for additional documentation on custom layouts. To learn about available htmlwidgets see the [showcase page](http://www.htmlwidgets.org/showcase_leaflet.html) and the [htmlwidget gallery](http://gallery.htmlwidgets.org/). diff --git a/docs/manuscripts/authoring/_footer.qmd b/docs/manuscripts/authoring/_footer.qmd index 36ab2c0641..0a51012e22 100644 --- a/docs/manuscripts/authoring/_footer.qmd +++ b/docs/manuscripts/authoring/_footer.qmd @@ -2,4 +2,4 @@ You've now covered the main features of Quarto for authoring a manuscript. You'v Once, you are happy with the changes you've made, you'll need update your public manuscript webpage. -Head on to [Publishing](../publishing.qmd) to learn how to publish and share your manuscript with the world. +Head on to [Publishing](/docs/publishing.qmd) to learn how to publish and share your manuscript with the world. diff --git a/docs/manuscripts/authoring/_setup.qmd b/docs/manuscripts/authoring/_setup.qmd index dc7ff19ad0..65aee26873 100644 --- a/docs/manuscripts/authoring/_setup.qmd +++ b/docs/manuscripts/authoring/_setup.qmd @@ -13,7 +13,7 @@ To follow along, you'll need to install the VS Code Quarto extension, install so ::: callout-important ## Install Quarto First -If you haven't already, make sure you've installed the latest release version of Quarto, as described in the [Manuscript Overview](../index.qmd#install). +If you haven't already, make sure you've installed the latest release version of Quarto, as described in the [Manuscript Overview](/docs/manuscripts/index.qmd#install). ::: ::: {.content-visible when-meta="tool.is_jupyterlab"} diff --git a/docs/output-formats/all-formats.qmd b/docs/output-formats/all-formats.qmd index fb9af7973b..5f758fe571 100644 --- a/docs/output-formats/all-formats.qmd +++ b/docs/output-formats/all-formats.qmd @@ -32,62 +32,62 @@ See below for a list of all output formats by type along with links to their ref | | | |--------------------------|----------------------------------------------| -| [HTML](../reference/formats/html.qmd) | HTML is a markup language used for structuring and presenting content on the web. | -| [PDF](../reference/formats/pdf.qmd) | PDF is a file format for creating print-ready paged documents. | -| [MS Word](../reference/formats/docx.qmd) | MS Word is the word processor included with Microsoft Office. | -| [OpenOffice](../reference/formats/odt.qmd) | OpenDocument is an open standard file format for word processing documents. | -| [ePub](../reference/formats/epub.qmd) | ePub is an e-book file format that is supported by many e-readers. | +| [HTML](/docs/reference/formats/html.qmd) | HTML is a markup language used for structuring and presenting content on the web. | +| [PDF](/docs/reference/formats/pdf.qmd) | PDF is a file format for creating print-ready paged documents. | +| [MS Word](/docs/reference/formats/docx.qmd) | MS Word is the word processor included with Microsoft Office. | +| [OpenOffice](/docs/reference/formats/odt.qmd) | OpenDocument is an open standard file format for word processing documents. | +| [ePub](/docs/reference/formats/epub.qmd) | ePub is an e-book file format that is supported by many e-readers. | ## Presentations | | | |-------------------------------|-----------------------------------------| -| [Revealjs](../reference/formats/presentations/revealjs.qmd) | Revealjs is an open source HTML presentation framework. | -| [PowerPoint](../reference/formats/presentations/pptx.qmd) | PowerPoint is the presentation editing software included with Microsoft Office. | -| [Beamer](../reference/formats/presentations/beamer.qmd) | Beamer is a LaTeX class for producing presentations and slides. | +| [Revealjs](/docs/reference/formats/presentations/revealjs.qmd) | Revealjs is an open source HTML presentation framework. | +| [PowerPoint](/docs/reference/formats/presentations/pptx.qmd) | PowerPoint is the presentation editing software included with Microsoft Office. | +| [Beamer](/docs/reference/formats/presentations/beamer.qmd) | Beamer is a LaTeX class for producing presentations and slides. | ## Markdown | | | |--------------------------|----------------------------------------------| -| [GitHub](../reference/formats/markdown/gfm.qmd) | GitHub Flavored Markdown (GFM) is the dialect of Markdown that is currently supported for user content on GitHub. | -| [CommonMark](../reference/formats/markdown/commonmark.qmd) | CommonMark is a strongly defined, highly compatible specification of Markdown. | -| [Hugo](../output-formats/hugo.qmd) | Hugo is an open-source static website generator. | -| [Docusaurus](../output-formats/docusaurus.qmd) | Docusaurus is an open-source markdown documentation system. | -| [Markua](../reference/formats/markdown/markua.qmd) | Markua is a markdown variant used by Leanpub. | +| [GitHub](/docs/reference/formats/markdown/gfm.qmd) | GitHub Flavored Markdown (GFM) is the dialect of Markdown that is currently supported for user content on GitHub. | +| [CommonMark](/docs/reference/formats/markdown/commonmark.qmd) | CommonMark is a strongly defined, highly compatible specification of Markdown. | +| [Hugo](/docs/output-formats/hugo.qmd) | Hugo is an open-source static website generator. | +| [Docusaurus](/docs/output-formats/docusaurus.qmd) | Docusaurus is an open-source markdown documentation system. | +| [Markua](/docs/reference/formats/markdown/markua.qmd) | Markua is a markdown variant used by Leanpub. | ## Wikis | | | |-------------------------|------------------------------------------------| -| [MediaWiki](../reference/formats/wiki/mediawiki.qmd) | MediaWiki is the native document format of Wikipedia. | -| [DokuWiki](../reference/formats/wiki/dokuwiki.qmd) | DokuWiki is a simple to use and highly versatile open source wiki software that doesn't require a database. | -| [ZimWiki](../reference/formats/wiki/zimwiki.qmd) | Zim is a graphical text editor used to maintain a collection of wiki pages. | -| [Jira Wiki](../reference/formats/wiki/jira.qmd) | Jira Wiki is the native document format for the Jira issue tracking and project management system from Atlassian. | -| [XWiki](../reference/formats/wiki/xwiki.qmd) | XWiki is an open-source enterprise wiki system. | +| [MediaWiki](/docs/reference/formats/wiki/mediawiki.qmd) | MediaWiki is the native document format of Wikipedia. | +| [DokuWiki](/docs/reference/formats/wiki/dokuwiki.qmd) | DokuWiki is a simple to use and highly versatile open source wiki software that doesn't require a database. | +| [ZimWiki](/docs/reference/formats/wiki/zimwiki.qmd) | Zim is a graphical text editor used to maintain a collection of wiki pages. | +| [Jira Wiki](/docs/reference/formats/wiki/jira.qmd) | Jira Wiki is the native document format for the Jira issue tracking and project management system from Atlassian. | +| [XWiki](/docs/reference/formats/wiki/xwiki.qmd) | XWiki is an open-source enterprise wiki system. | ## More Formats | | | |-------------------|-----------------------------------------------------| -| [JATS](../reference/formats/jats.qmd) | JATS (Journal Article Tag Suite) is an XML format for marking up and exchanging journal content. | -| [Jupyter](../reference/formats/ipynb.qmd) | Jupyter Notebooks combine software code, computational output, explanatory text and multimedia resources in a single document. | -| [ConTeXt](../reference/formats/context.qmd) | ConTeXt is a system for typesetting documents based on TEX and METAPOST. | -| [RTF](../reference/formats/rtf.qmd) | The Rich Text Format (RTF) is a file format for for cross-platform document interchange. | -| [reST](../reference/formats/rst.qmd) | reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. | -| [AsciiDoc](../reference/formats/asciidoc.qmd) | AsciiDoc is a text document format for writing documentation, articles, and books, ebooks, slideshows, web pages, man pages and blogs. | -| [Org-Mode](../reference/formats/org.qmd) | Org-Mode is an Emacs major mode for keeping notes, authoring documents, creating computational notebooks, and more. | -| [Muse](../reference/formats/muse.qmd) | Emacs Muse is an authoring and publishing environment for Emacs. | -| [GNU Texinfo](../reference/formats/texinfo.qmd) | Texinfo is the official documentation format of the GNU project. | -| [Groff Man Page](../reference/formats/man.qmd) | The Groff (GNU troff) man page document formats consists of plain text mixed with formatting commands that produce ASCII/UTF8 for display at the terminal. | -| [Groff Manuscript](../reference/formats/ms.qmd) | The Groff (GNU troff) manuscript format consists of plain text mixed with formatting commands that produces PostScript, PDF, or HTML. | -| [Haddock markup](../reference/formats/haddock.qmd) | Haddock is a tool for automatically generating documentation from annotated Haskell source code. | -| [OPML](../reference/formats/opml.qmd) | OPML (Outline Processor Markup Language) is an XML format for outlines. | -| [Textile](../reference/formats/textile.qmd) | Textile is a simple text markup language that makes it easy to structure content for blogs, wikis, and documentation. | -| [DocBook](../reference/formats/docbook.qmd) | DocBook is an XML schema particularly well suited to books and papers about computer hardware and software. | -| [InDesign](../reference/formats/icml.qmd) | ICML is an XML representation of an Adobe InDesign document. | -| [TEI Simple](../reference/formats/tei.qmd) | TEI Simple aims to define a new *highly-constrained* and *prescriptive* subset of the Text Encoding Initiative (TEI) Guidelines suited to the representation of early modern and modern books. | -| [FictionBook](../reference/formats/fb2.qmd) | FictionBook is an open XML-based e-book format. | +| [JATS](/docs/reference/formats/jats.qmd) | JATS (Journal Article Tag Suite) is an XML format for marking up and exchanging journal content. | +| [Jupyter](/docs/reference/formats/ipynb.qmd) | Jupyter Notebooks combine software code, computational output, explanatory text and multimedia resources in a single document. | +| [ConTeXt](/docs/reference/formats/context.qmd) | ConTeXt is a system for typesetting documents based on TEX and METAPOST. | +| [RTF](/docs/reference/formats/rtf.qmd) | The Rich Text Format (RTF) is a file format for for cross-platform document interchange. | +| [reST](/docs/reference/formats/rst.qmd) | reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. | +| [AsciiDoc](/docs/reference/formats/asciidoc.qmd) | AsciiDoc is a text document format for writing documentation, articles, and books, ebooks, slideshows, web pages, man pages and blogs. | +| [Org-Mode](/docs/reference/formats/org.qmd) | Org-Mode is an Emacs major mode for keeping notes, authoring documents, creating computational notebooks, and more. | +| [Muse](/docs/reference/formats/muse.qmd) | Emacs Muse is an authoring and publishing environment for Emacs. | +| [GNU Texinfo](/docs/reference/formats/texinfo.qmd) | Texinfo is the official documentation format of the GNU project. | +| [Groff Man Page](/docs/reference/formats/man.qmd) | The Groff (GNU troff) man page document formats consists of plain text mixed with formatting commands that produce ASCII/UTF8 for display at the terminal. | +| [Groff Manuscript](/docs/reference/formats/ms.qmd) | The Groff (GNU troff) manuscript format consists of plain text mixed with formatting commands that produces PostScript, PDF, or HTML. | +| [Haddock markup](/docs/reference/formats/haddock.qmd) | Haddock is a tool for automatically generating documentation from annotated Haskell source code. | +| [OPML](/docs/reference/formats/opml.qmd) | OPML (Outline Processor Markup Language) is an XML format for outlines. | +| [Textile](/docs/reference/formats/textile.qmd) | Textile is a simple text markup language that makes it easy to structure content for blogs, wikis, and documentation. | +| [DocBook](/docs/reference/formats/docbook.qmd) | DocBook is an XML schema particularly well suited to books and papers about computer hardware and software. | +| [InDesign](/docs/reference/formats/icml.qmd) | ICML is an XML representation of an Adobe InDesign document. | +| [TEI Simple](/docs/reference/formats/tei.qmd) | TEI Simple aims to define a new *highly-constrained* and *prescriptive* subset of the Text Encoding Initiative (TEI) Guidelines suited to the representation of early modern and modern books. | +| [FictionBook](/docs/reference/formats/fb2.qmd) | FictionBook is an open XML-based e-book format. | ```{=html} ``` -You can find release notes and installers for all platforms at +You can find release notes and installers for all platforms in the [download page](/docs/download/prerelease.qmd). ### Step 2: Learn the Basics @@ -156,4 +156,3 @@ Once you've mastered the basics, check out these additional articles to learn mo [Deployment](deployment.qmd) covers how to deploy both static dashboards (which require only a web host, but not a server) and Shiny dashboards (which require a Shiny Server). [Interactivity](interactivity/index.qmd) explores the various ways to create interactive dashboards that enable more flexible data exploration. - diff --git a/docs/manuscripts/index.qmd b/docs/manuscripts/index.qmd index 76cab5e67e..b47d49efcc 100644 --- a/docs/manuscripts/index.qmd +++ b/docs/manuscripts/index.qmd @@ -69,7 +69,7 @@ Manuscripts are a feature in the 1.4 release of Quarto. Before you get started, ``` -You can find release notes and installers for all platforms at +You can find release notes and installers for all platforms in the [download page](/docs/download/prerelease.qmd). ### Choose Your Tool {#choose} diff --git a/docs/prerelease/1.3/_pre-release-feature.qmd b/docs/prerelease/1.3/_pre-release-feature.qmd index 047a0de616..233ea1a591 100644 --- a/docs/prerelease/1.3/_pre-release-feature.qmd +++ b/docs/prerelease/1.3/_pre-release-feature.qmd @@ -1,5 +1,5 @@ ::: {.callout-note} ## Pre-release Feature -This feature is new in the upcoming Quarto 1.3 release. To use the feature now, you'll need to [download](/docs/download/prerelease) and install the Quarto pre-release. +This feature is new in the upcoming Quarto 1.3 release. To use the feature now, you'll need to [download](/docs/download/prerelease.qmd) and install the Quarto pre-release. ::: diff --git a/docs/prerelease/1.3/index.qmd b/docs/prerelease/1.3/index.qmd index c0d15cb0bb..a2c6b06716 100644 --- a/docs/prerelease/1.3/index.qmd +++ b/docs/prerelease/1.3/index.qmd @@ -7,7 +7,7 @@ search: false {{< include _highlights.qmd >}} -See the [Pre-Release Download Page](/docs/download/prerelease) for a complete list of all the changes and bug fixes. +See the [Pre-Release Download Page](/docs/download/prerelease.qmd) for a complete list of all the changes and bug fixes. docx ``` -Read more on the [Quarto documentation site](/index.qmd) +Read more on the [Quarto documentation site](https://quarto.org) + + diff --git a/docs/authoring/_mermaid-examples/sandstone.qmd b/docs/authoring/_mermaid-examples/sandstone.qmd index 23a5816e4b..110fea49dc 100644 --- a/docs/authoring/_mermaid-examples/sandstone.qmd +++ b/docs/authoring/_mermaid-examples/sandstone.qmd @@ -18,4 +18,4 @@ flowchart LR P --> docx ``` -Read more on the [Quarto documentation site](/index.qmd) +Read more on the [Quarto documentation site](https://quarto.org) diff --git a/docs/authoring/_mermaid-examples/solar.qmd b/docs/authoring/_mermaid-examples/solar.qmd index ca6387fc99..7a5777947b 100644 --- a/docs/authoring/_mermaid-examples/solar.qmd +++ b/docs/authoring/_mermaid-examples/solar.qmd @@ -18,4 +18,6 @@ flowchart LR P --> docx ``` -Read more on the [Quarto documentation site](/index.qmd) +Read more on the [Quarto documentation site](https://quarto.org) + + diff --git a/docs/authoring/_mermaid-examples/vapor.qmd b/docs/authoring/_mermaid-examples/vapor.qmd index 8855bef7ae..afd1936eda 100644 --- a/docs/authoring/_mermaid-examples/vapor.qmd +++ b/docs/authoring/_mermaid-examples/vapor.qmd @@ -18,4 +18,6 @@ flowchart LR P --> docx ``` -Read more on the [Quarto documentation site](/index.qmd) +Read more on the [Quarto documentation site](https://quarto.org) + + From a385c9bd8019971c79900b9e07f9bdb1bd178af1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 13 Mar 2024 13:13:44 +0100 Subject: [PATCH 26/33] revert: keep apex in codeblock --- docs/extensions/formats.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extensions/formats.qmd b/docs/extensions/formats.qmd index 7930becc2e..ee1da0539c 100644 --- a/docs/extensions/formats.qmd +++ b/docs/extensions/formats.qmd @@ -97,7 +97,7 @@ The custom HTML format defined here is very simple. It takes the base `html` for /*-- scss:defaults --*/ /* TODO: Customize appearance with SCSS variables */ -/* See [HTML theme](/docs/output-formats/html-themes.html#theme-options) */ +/* See [HTML theme](https://quarto.org/docs/output-formats/html-themes.html#theme-options) */ /*-- scss:rules --*/ From 2a6a651f4282e9aaa86de59df879ca53de651690 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 13 Mar 2024 13:15:50 +0100 Subject: [PATCH 27/33] fix: right hand side of table miss aligned --- docs/faq/rmarkdown.qmd | 74 +++++++++++++++++++++--------------------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/docs/faq/rmarkdown.qmd b/docs/faq/rmarkdown.qmd index 75d83b00c3..1dd13a1bce 100644 --- a/docs/faq/rmarkdown.qmd +++ b/docs/faq/rmarkdown.qmd @@ -38,43 +38,43 @@ We should emphasize that switching is not imperative. While we don't plan on maj Here are the Quarto equivalents for various packages and features of the R Markdown ecosystem (in some cases Quarto equivalents are not yet available but will be later this year): ::: comparison -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Feature | R Markdown | Quarto | -+=======================+==========================================================================================================+====================================================================================+ -| Basic Formats | - [html_document](https://pkgs.rstudio.com/rmarkdown/reference/html_document.html) | - [html](/docs/output-formats/html-basics.qmd) | -| | - [pdf_document](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) | - [pdf](/docs/output-formats/pdf-basics.qmd) | -| | - [word_document](https://pkgs.rstudio.com/rmarkdown/reference/word_document.html) | - [docx](/docs/output-formats/ms-word.qmd) | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Beamer | - [beamer_presentation](https://pkgs.rstudio.com/rmarkdown/reference/beamer_presentation.html) | - [beamer](/docs/presentations/beamer.qmd) | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| PowerPoint | - [powerpoint_presentation](https://pkgs.rstudio.com/rmarkdown/reference/powerpoint_presentation.html) | - [pptx](/docs/presentations/powerpoint.qmd) | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| HTML Slides | - [xaringan](https://bookdown.org/yihui/rmarkdown/xaringan.html) | - [revealjs](/docs/presentations/revealjs/index.qmd) | -| | - [ioslides](https://bookdown.org/yihui/rmarkdown/ioslides-presentation.html) | | -| | - [revealjs](https://bookdown.org/yihui/rmarkdown/revealjs.html) | | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Advanced Layout | - [tufte](https://bookdown.org/yihui/rmarkdown/tufte-handouts.html) | - [Quarto Article Layout](/docs/authoring/article-layout.qmd) | -| | - [distill](https://rstudio.github.io/distill/figures.html) | | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Cross References | - [html_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | - [Quarto Crossrefs](/docs/authoring/cross-references.qmd) | -| | - [pdf_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | | -| | - [word_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Websites & Blogs | - [blogdown](https://pkgs.rstudio.com/blogdown/) | - [Quarto Websites](/docs/websites/website-basics.qmd) | -| | - [distill](https://pkgs.rstudio.com/distill/) | - [Quarto Blogs](/docs/websites/website-blog.qmd) | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Books | - [bookdown](https://pkgs.rstudio.com/bookdown/) | - [Quarto Books](/docs/books/book-basics.qmd) | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Interactivity | [Shiny Documents](https://bookdown.org/yihui/rmarkdown/shiny-documents.html) | [Quarto Interactive Documents](/docs/interactive/shiny/index.qmd) | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Journal Articles | [rticles](https://pkgs.rstudio.com/rticles/) | [Quarto Journal Articles](/docs/journals/index.qmd) | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Paged HTML | [pagedown](https://github.com/rstudio/pagedown) | Planned | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Dashboards | [flexdashboard](https://pkgs.rstudio.com/flexdashboard/) | Planned | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Interactive Tutorials | [learnr](https://pkgs.rstudio.com/learnr/) | No equivalent planned | -+-----------------------+----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------+ ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Feature | R Markdown | Quarto | ++=======================+==========================================================================================================+===================================================================+ +| Basic Formats | - [html_document](https://pkgs.rstudio.com/rmarkdown/reference/html_document.html) | - [html](/docs/output-formats/html-basics.qmd) | +| | - [pdf_document](https://pkgs.rstudio.com/rmarkdown/reference/pdf_document.html) | - [pdf](/docs/output-formats/pdf-basics.qmd) | +| | - [word_document](https://pkgs.rstudio.com/rmarkdown/reference/word_document.html) | - [docx](/docs/output-formats/ms-word.qmd) | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Beamer | - [beamer_presentation](https://pkgs.rstudio.com/rmarkdown/reference/beamer_presentation.html) | - [beamer](/docs/presentations/beamer.qmd) | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| PowerPoint | - [powerpoint_presentation](https://pkgs.rstudio.com/rmarkdown/reference/powerpoint_presentation.html) | - [pptx](/docs/presentations/powerpoint.qmd) | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| HTML Slides | - [xaringan](https://bookdown.org/yihui/rmarkdown/xaringan.html) | - [revealjs](/docs/presentations/revealjs/index.qmd) | +| | - [ioslides](https://bookdown.org/yihui/rmarkdown/ioslides-presentation.html) | | +| | - [revealjs](https://bookdown.org/yihui/rmarkdown/revealjs.html) | | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Advanced Layout | - [tufte](https://bookdown.org/yihui/rmarkdown/tufte-handouts.html) | - [Quarto Article Layout](/docs/authoring/article-layout.qmd) | +| | - [distill](https://rstudio.github.io/distill/figures.html) | | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Cross References | - [html_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | - [Quarto Crossrefs](/docs/authoring/cross-references.qmd) | +| | - [pdf_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | | +| | - [word_document2](https://bookdown.org/yihui/bookdown/a-single-document.html) | | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Websites & Blogs | - [blogdown](https://pkgs.rstudio.com/blogdown/) | - [Quarto Websites](/docs/websites/website-basics.qmd) | +| | - [distill](https://pkgs.rstudio.com/distill/) | - [Quarto Blogs](/docs/websites/website-blog.qmd) | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Books | - [bookdown](https://pkgs.rstudio.com/bookdown/) | - [Quarto Books](/docs/books/book-basics.qmd) | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Interactivity | [Shiny Documents](https://bookdown.org/yihui/rmarkdown/shiny-documents.html) | [Quarto Interactive Documents](/docs/interactive/shiny/index.qmd) | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Journal Articles | [rticles](https://pkgs.rstudio.com/rticles/) | [Quarto Journal Articles](/docs/journals/index.qmd) | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Paged HTML | [pagedown](https://github.com/rstudio/pagedown) | Planned | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Dashboards | [flexdashboard](https://pkgs.rstudio.com/flexdashboard/) | Planned | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ +| Interactive Tutorials | [learnr](https://pkgs.rstudio.com/learnr/) | No equivalent planned | ++-----------------------+----------------------------------------------------------------------------------------------------------+-------------------------------------------------------------------+ ::: ### Can you create custom formats for Quarto like you can for R Markdown? From e5338f6c6c715ff20ed7e240b8463ffea7de09b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 13 Mar 2024 13:17:26 +0100 Subject: [PATCH 28/33] fix: right hand side of wide table --- docs/reference/formats/dashboards.qmd | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/reference/formats/dashboards.qmd b/docs/reference/formats/dashboards.qmd index dc8789482e..90d47c19a8 100644 --- a/docs/reference/formats/dashboards.qmd +++ b/docs/reference/formats/dashboards.qmd @@ -7,15 +7,15 @@ tbl-colwidths: [25,75] The following document and format options are either dashboard-specific or have special behavior within dashboards (note that in addition to these options all standard [HTML Format](/docs/reference/formats/html.qmd) options are available): -| Option | Description | -|--------------------------|----------------------------------------------| -| `title` | Title (displayed in top left of navigation bar) | -| `author` | Author (displayed alongside title in smaller font) | -| `logo` | Logo (displayed left of the title in the navigation bar) | -| `orientation` | `rows` or `columns` (default: `rows`) | -| `scrolling` | Use scrolling rather than fill layout? (default: `false`) | -| `expandable` | Make card content expandable (default: `true`) | -| `theme` | Dashboard theme (built in or custom scss) | +| Option | Description | +|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `title` | Title (displayed in top left of navigation bar) | +| `author` | Author (displayed alongside title in smaller font) | +| `logo` | Logo (displayed left of the title in the navigation bar) | +| `orientation` | `rows` or `columns` (default: `rows`) | +| `scrolling` | Use scrolling rather than fill layout? (default: `false`) | +| `expandable` | Make card content expandable (default: `true`) | +| `theme` | Dashboard theme (built in or custom scss) | | `nav-buttons` | Buttons to appear on the right side of the navigation bar. Use `linkedin`, `facebook`, `reddit`, `twitter`, `github`, or a custom [Nav Item](/docs/reference/projects/websites.qmd#nav-items). | For example: From 3e88b5ec7b8243bfe2cde349c83a6f8696de0635 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 13 Mar 2024 13:22:17 +0100 Subject: [PATCH 29/33] fix: message link from CLI, table alignment and type --- docs/projects/binder.qmd | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/projects/binder.qmd b/docs/projects/binder.qmd index 89b7da05b2..e7cce88fe8 100644 --- a/docs/projects/binder.qmd +++ b/docs/projects/binder.qmd @@ -49,7 +49,8 @@ The command will first detect and report the project configuration: No files which provide dependencies were discovered. If you continue, no dependencies will be restored when running this project with Binder. -Learn more about [Binder dependencies](/docs/projects/binder.qmd#dependencies). +Learn more at: +https://www.quarto.org/docs/prerelease/1.4/binder.html#dependencies ? Do you want to continue? (Y/n) › ``` @@ -99,13 +100,13 @@ Most projects will have additional dependencies such as R, Python or Julia packa When your project is restored to a new computational environment using Binder, any dependencies that the project has must also be restored. The `quarto use binder` command won't detect computational dependencies from within your Quarto documents, but it will detect the files commonly used to describe them. The most common ways to describe them for the each environment are as follows: -| Language | Environment | File | -|----------------|----------------------------------------|----------------| -| R | [renv](https://rstudio.github.io/renv/index.html) | `renv.lock` | -| R | [Binder R Config](https://mybinder.readthedocs.io/en/latest/using/config_files.html#install-r-install-an-r-rstudio-environment) | `install.R` | -| Python | [Conda](https://docs.conda.io/projects/conda/en/stable/) | `environment.yml` | -| Python | [Pip](https://pip.pypa.io/en/stable/user_guide/#requirements-files) | `requirements.txt` | -| Julia | [Pkg](https://pkgdocs.julialang.org/v1/toml-files/) | `project.toml` | +| Language | Environment | File | +|----------|---------------------------------------------------------------------------------------------------------------------------------|--------------------| +| R | [renv](https://rstudio.github.io/renv/index.html) | `renv.lock` | +| R | [Binder R Config](https://mybinder.readthedocs.io/en/latest/using/config_files.html#install-r-install-an-r-rstudio-environment) | `install.R` | +| Python | [Conda](https://docs.conda.io/projects/conda/en/stable/) | `environment.yml` | +| Python | [Pip](https://pip.pypa.io/en/stable/user_guide/#requirements-files) | `requirements.txt` | +| Julia | [Pkg](https://pkgdocs.julialang.org/v1/toml-files/) | `project.toml` | Often these files are created as the result of using a virtual environment. See [Virtual Environments](/docs/projects/virtual-environments.qmd) for more about using Quarto with virtual environments. @@ -123,7 +124,7 @@ The following files may be generated by the `quarto use binder` command. Note th `runtime.txt` -: For R projects, this file will be generated with the appropriate R version, which is used to ensure that the same R version is present in the computational environment. This also will result in RStudio being configured and available when the computational evironment is restored by a user. +: For R projects, this file will be generated with the appropriate R version, which is used to ensure that the same R version is present in the computational environment. This also will result in RStudio being configured and available when the computational environment is restored by a user. `install.R` From c45cdf7147ad5d984dd5a66803a204bb9716eec5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 13 Mar 2024 13:25:29 +0100 Subject: [PATCH 30/33] revert: changes made to demo file --- docs/presentations/revealjs/demo/index.qmd | 62 +++++++++++----------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/docs/presentations/revealjs/demo/index.qmd b/docs/presentations/revealjs/demo/index.qmd index 2d8627f9fc..c9316c5b77 100644 --- a/docs/presentations/revealjs/demo/index.qmd +++ b/docs/presentations/revealjs/demo/index.qmd @@ -43,7 +43,7 @@ function(input, output) { ``` ::: footer -Learn more: [Syntax Highlighting](/docs/output-formats/html-code.qmd#highlighting) +Learn more: [Syntax Highlighting](https://quarto.org/docs/output-formats/html-code.html#highlighting) ::: ## Code Animations {auto-animate="true"} @@ -67,7 +67,7 @@ function(input, output) { ``` ::: footer -Learn more: [Code Animations](/docs/presentations/revealjs/advanced.qmd#code-animations) +Learn more: [Code Animations](https://quarto.org/docs/presentations/revealjs/advanced.html#code-animations) ::: ## Line Highlighting @@ -89,7 +89,7 @@ plt.show() ``` ::: footer -Learn more: [Line Highlighting](/docs/presentations/revealjs/#line-highlighting) +Learn more: [Line Highlighting](https://quarto.org/docs/presentations/revealjs/#line-highlighting) ::: ## Executable Code @@ -105,7 +105,7 @@ ggplot(mtcars, aes(hp, mpg, color = am)) + ``` ::: footer -Learn more: [Executable Code](/docs/presentations/revealjs/#executable-code) +Learn more: [Executable Code](https://quarto.org/docs/presentations/revealjs/#executable-code) ::: ## LaTeX Equations @@ -148,7 +148,7 @@ a_{21}& =b_{21}& ::: ::: footer -Learn more: [LaTeX Equations](/docs/authoring/markdown-basics.qmd#equations) +Learn more: [LaTeX Equations](https://quarto.org/docs/authoring/markdown-basics.html#equations) ::: ## Column Layout {.smaller} @@ -173,7 +173,7 @@ knitr::kable(head(mtcars)[,c("mpg", "cyl", "disp", "hp", "wt")]) ::: ::: footer -Learn more: [Multiple Columns](/docs/presentations/revealjs/#multiple-columns) +Learn more: [Multiple Columns](https://quarto.org/docs/presentations/revealjs/#multiple-columns) ::: ## Incremental Lists @@ -191,7 +191,7 @@ Lists can optionally be displayed incrementally:
Insert pauses to make other types of content display incrementally. ::: footer -Learn more: [Incremental Lists](/docs/presentations/revealjs/#incremental-lists) +Learn more: [Incremental Lists](https://quarto.org/docs/presentations/revealjs/#incremental-lists) ::: ## Fragments @@ -227,7 +227,7 @@ Highlight red ::: ::: footer -Learn more: [Fragments](/docs/presentations/revealjs/advanced.qmd#fragments) +Learn more: [Fragments](https://quarto.org/docs/presentations/revealjs/advanced.html#fragments) ::: ## Slide Backgrounds {background="#43464B"} @@ -237,7 +237,7 @@ Set the `background` attribute on a slide to change the background color (all CS Different background transitions are available via the `background-transition` option. ::: footer -Learn more: [Slide Backgrounds](/docs/presentations/revealjs/#color-backgrounds) +Learn more: [Slide Backgrounds](https://quarto.org/docs/presentations/revealjs/#color-backgrounds) ::: ## Media Backgrounds {background="#43464B" background-image="images/milky-way.jpeg"} @@ -251,7 +251,7 @@ You can also use the following as a slide background: - An iframe: `background-iframe` ::: footer -Learn more: [Media Backgrounds](/docs/presentations/revealjs/#image-backgrounds) +Learn more: [Media Backgrounds](https://quarto.org/docs/presentations/revealjs/#image-backgrounds) ::: ## Absolute Position @@ -265,7 +265,7 @@ Position images or other elements at precise locations ![](mini/images/kitten-300-200.jpeg){.absolute .fragment bottom="110" right="130" width="300"} ::: footer -Learn more: [Absolute Position](/docs/presentations/revealjs/advanced.qmd#absolute-position) +Learn more: [Absolute Position](https://quarto.org/docs/presentations/revealjs/advanced.html#absolute-position) ::: ## Auto-Animate {auto-animate="true" auto-animate-easing="ease-in-out"} @@ -284,7 +284,7 @@ Automatically animate matching elements across slides with Auto-Animate. ::: ::: footer -Learn more: [Auto-Animate](/docs/presentations/revealjs/advanced.qmd#auto-animate) +Learn more: [Auto-Animate](https://quarto.org/docs/presentations/revealjs/advanced.html#auto-animate) ::: ## Auto-Animate {auto-animate="true" auto-animate-easing="ease-in-out"} @@ -303,7 +303,7 @@ Automatically animate matching elements across slides with Auto-Animate. ::: ::: footer -Learn more: [Auto-Animate](/docs/presentations/revealjs/advanced.qmd#auto-animate) +Learn more: [Auto-Animate](https://quarto.org/docs/presentations/revealjs/advanced.html#auto-animate) ::: ## Slide Transitions {.smaller} @@ -320,7 +320,7 @@ The next few slides will transition using the `slide` transition | `zoom` | Scale the incoming slide so it grows in from the center of the screen. | ::: footer -Learn more: [Slide Transitions](/docs/presentations/revealjs/advanced.qmd#slide-transitions) +Learn more: [Slide Transitions](https://quarto.org/docs/presentations/revealjs/advanced.html#slide-transitions) ::: ## Tabsets {.smaller .scrollable transition="slide"} @@ -343,7 +343,7 @@ knitr::kable(mtcars) ::: ::: footer -Learn more: [Tabsets](/docs/presentations/revealjs/#tabsets) +Learn more: [Tabsets](https://quarto.org/docs/presentations/revealjs/#tabsets) ::: ## Interactive Slides {.smaller transition="slide"} @@ -360,7 +360,7 @@ leaflet() %>% ``` ::: footer -Learn more: [Jupyter widgets](/docs/interactive/widgets/jupyter.qmd), [htmlwidgets](/docs/interactive/widgets/htmlwidgets.qmd) +Learn more: [Jupyter widgets](https://quarto.org/docs/interactive/widgets/jupyter.html), [htmlwidgets](https://quarto.org/docs/interactive/widgets/htmlwidgets.html) ::: ## Interactive Slides {.smaller transition="slide"} @@ -388,7 +388,7 @@ plotActors(actors, talentWeight, looksWeight, minimum) ``` ::: footer -Learn more: [Observable](/docs/interactive/ojs/index.qmd), [Shiny](/docs/interactive/shiny/index.qmd), [Component Layout](/docs/interactive/layout.qmd) +Learn more: [Observable](https://quarto.org/docs/interactive/ojs/), [Shiny](https://quarto.org/docs/interactive/shiny/), [Component Layout](https://quarto.org/docs/interactive/layout.html) ::: ## Preview Links @@ -402,12 +402,12 @@ Use the `preview-links` option to open links in an iframe on top of your slides. ::: ::: footer -Learn more: [Preview Links](/docs/presentations/revealjs/presenting.qmd#preview-links) +Learn more: [Preview Links](https://quarto.org/docs/presentations/revealjs/presenting.html#preview-links) ::: ## Themes -10 Built-in Themes (or [create your own](/docs/presentations/revealjs/themes.qmd#creating-themes)) +10 Built-in Themes (or [create your own](https://quarto.org/docs/presentations/revealjs/themes.html#creating-themes)) ::: {layout-ncol="2"} ![](images/moon.png) @@ -416,7 +416,7 @@ Learn more: [Preview Links](/docs/presentations/revealjs/presenting.qmd#preview- ::: ::: footer -Learn more: [Themes](/docs/presentations/revealjs/themes.qmd) +Learn more: [Themes](https://quarto.org/docs/presentations/revealjs/themes.html) ::: ## Easy Navigation @@ -434,7 +434,7 @@ Toggle the slide menu with the menu button (bottom left of slide) to go to other You can also press `m` to toggle the menu open and closed. ::: footer -Learn more: [Navigation](/docs/presentations/revealjs/presenting.qmd#navigation-menu) +Learn more: [Navigation](https://quarto.org/docs/presentations/revealjs/presenting.html#navigation-menu) ::: ## Chalkboard {chalkboard-buttons="true"} @@ -458,7 +458,7 @@ Use the notes canvas button at the bottom left of the slide to toggle drawing on You can also press `b` to toggle the chalkboard or `c` to toggle the notes canvas. ::: footer -Learn more: [Chalkboard](/docs/presentations/revealjs/presenting.qmd#chalkboard) +Learn more: [Chalkboard](https://quarto.org/docs/presentations/revealjs/presenting.html#chalkboard) ::: ## Point of View @@ -470,7 +470,7 @@ Press `o` to toggle overview mode: Hold down the `Alt` key (or `Ctrl` in Linux) and click on any element to zoom towards it---try it now on this slide. ::: footer -Learn more: [Overview Mode](/docs/presentations/revealjs/presenting.qmd#overview-mode), [Slide Zoom](/docs/presentations/revealjs/presenting.qmd#slide-zoom) +Learn more: [Overview Mode](https://quarto.org/docs/presentations/revealjs/presenting.html#overview-mode), [Slide Zoom](https://quarto.org/docs/presentations/revealjs/presenting.html#slide-zoom) ::: ## Speaker View @@ -480,7 +480,7 @@ Press `s` (or use the presentation menu) to open speaker view ![](images/speaker-view.png){fig-align="center" style="border: 3px solid #dee2e6;" width="780"} ::: footer -Learn more: [Speaker View](/docs/presentations/revealjs/presenting.qmd#speaker-view) +Learn more: [Speaker View](https://quarto.org/docs/presentations/revealjs/presenting.html#speaker-view) ::: ## Authoring Tools {.smaller} @@ -498,7 +498,7 @@ Live side-by-side preview for any notebook or text editor including Jupyter and ::: ::: footer -Learn more: [Jupyter](/docs/tools/jupyter-lab.qmd), [VS Code](/docs/tools/vscode.qmd), [Text Editors](/docs/tools/text-editors.qmd) +Learn more: [Jupyter](https://quarto.org/docs/tools/jupyter-lab.html), [VS Code](https://quarto.org/docs/tools/vscode.html), [Text Editors](https://quarto.org/docs/tools/text-editors.html) ::: ## Authoring Tools {.smaller} @@ -508,16 +508,16 @@ RStudio includes an integrated presentation preview pane ![](images/rstudio.png){.border width="900"} ::: footer -Learn more: [RStudio](/docs/tools/rstudio.qmd) +Learn more: [RStudio](https://quarto.org/docs/tools/rstudio.html) ::: ## And More... -- [Touch](/docs/presentations/revealjs/advanced.qmd#touch-navigation) optimized (presentations look great on mobile, swipe to navigate slides) -- [Footer & Logo](/docs/presentations/revealjs/#footer-logo) (optionally specify custom footer per-slide) -- [Auto-Slide](/docs/presentations/revealjs/presenting.qmd#auto-slide) (step through slides automatically, without any user input) -- [Multiplex](/docs/presentations/revealjs/presenting.qmd#multiplex) (allows your audience to follow the slides of the presentation you are controlling on their own phone, tablet or laptop). +- [Touch](https://quarto.org/docs/presentations/revealjs/advanced.html#touch-navigation) optimized (presentations look great on mobile, swipe to navigate slides) +- [Footer & Logo](https://quarto.org/docs/presentations/revealjs/#footer-logo) (optionally specify custom footer per-slide) +- [Auto-Slide](https://quarto.org/docs/presentations/revealjs/presenting.html#auto-slide) (step through slides automatically, without any user input) +- [Multiplex](https://quarto.org/docs/presentations/revealjs/presenting.html#multiplex) (allows your audience to follow the slides of the presentation you are controlling on their own phone, tablet or laptop). ::: footer -Learn more: [Quarto Presentations](/docs/presentations/revealjs/index.qmd) +Learn more: [Quarto Presentations](https://quarto.org/docs/presentations/revealjs/) ::: From 71a25fd57998ede091971c2688a6f6a3730a51f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 13 Mar 2024 13:30:35 +0100 Subject: [PATCH 31/33] fix: target for Posit Connect from RStudio --- docs/faq/rmarkdown.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq/rmarkdown.qmd b/docs/faq/rmarkdown.qmd index 1dd13a1bce..fd966e1185 100644 --- a/docs/faq/rmarkdown.qmd +++ b/docs/faq/rmarkdown.qmd @@ -98,4 +98,4 @@ You can download the latest release ({{< var rstudio.current_release >}}) of RSt ### Does Posit Connect support Quarto? -Yes! You can publish Quarto content to Posit Connect v2021.08.0 or later. Quarto has to be enabled as documented in the Posit Connect [admin guide](https://docs.rstudio.com/connect/admin/appendix/configuration/#Quarto). Connect's user [documentation](https://docs.rstudio.com/connect/user/quarto/) refers to [Quarto.org docs](/docs/publishing/index.qmd#rstudio-connect) on how to publish from the RStudio IDE. To publish Python-based Quarto content, you can use the [rsconnect-python CLI](https://docs.rstudio.com/rsconnect-python/) from various locations, including VSCode, JupyterLab or the terminal. +Yes! You can publish Quarto content to Posit Connect v2021.08.0 or later. Quarto has to be enabled as documented in the Posit Connect [admin guide](https://docs.rstudio.com/connect/admin/appendix/configuration/#Quarto). Connect's user [documentation](https://docs.rstudio.com/connect/user/quarto/) refers to [Quarto.org docs](/docs/publishing/rstudio-connect.qmd#rstudio-ide) on how to publish from the RStudio IDE. To publish Python-based Quarto content, you can use the [rsconnect-python CLI](https://docs.rstudio.com/rsconnect-python/) from various locations, including VSCode, JupyterLab or the terminal. From b326e01fdff6f9d75639691b43ef0674ecc309f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20Canouil?= <8896044+mcanouil@users.noreply.github.com> Date: Wed, 13 Mar 2024 13:32:24 +0100 Subject: [PATCH 32/33] fix: right hand side of the table not aligned --- docs/manuscripts/next-steps.qmd | 36 ++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/manuscripts/next-steps.qmd b/docs/manuscripts/next-steps.qmd index 16eea5d388..3609053936 100644 --- a/docs/manuscripts/next-steps.qmd +++ b/docs/manuscripts/next-steps.qmd @@ -9,22 +9,22 @@ One way to start your own manuscript is to alter the contents of this template. Alternatively, you could start from scratch. Either way, here are some resources to help you with your next steps. -+---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ### Basics | Head to [**Manuscript Basics**](/docs/manuscripts/components.qmd) to: | -| | | -| | - Learn how to turn a directory into a manuscript project by adding the `_quarto.yml` file | -| | | -| | - Start a new project with a minimal template using the `quarto create` command | -| | | -| | - Controlling manuscript settings in `_quarto.yml` | -| | | -| | - Add an output format for a specific journal | -+---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ### Quarto Projects | Quarto manuscripts are a type of [**Quarto project**](/docs/projects/quarto-projects.qmd), so anything you can do in a Quarto project applies to a manuscript. For instance, these pages in the Project documentation might be of interest: | -| | | -| | - [Managing Execution](/docs/projects/code-execution.qmd): techniques to avoid expensive computations on every render. | -| | | -| | - [Virtual Environments](/docs/projects/virtual-environments.qmd): capture your computational environment to facilitate reproducing your work. | -+---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ### Basics | Head to [**Manuscript Basics**](/docs/manuscripts/components.qmd) to: | +| | | +| | - Learn how to turn a directory into a manuscript project by adding the `_quarto.yml` file | +| | | +| | - Start a new project with a minimal template using the `quarto create` command | +| | | +| | - Controlling manuscript settings in `_quarto.yml` | +| | | +| | - Add an output format for a specific journal | ++---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| ### Quarto Projects | Quarto manuscripts are a type of [**Quarto project**](/docs/projects/quarto-projects.qmd), so anything you can do in a Quarto project applies to a manuscript. For instance, these pages in the Project documentation might be of interest: | +| | | +| | - [Managing Execution](/docs/projects/code-execution.qmd): techniques to avoid expensive computations on every render. | +| | | +| | - [Virtual Environments](/docs/projects/virtual-environments.qmd): capture your computational environment to facilitate reproducing your work. | ++---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ### Publishing | We set up the publishing workflow for the template repository, but you can publish your manuscript website any way you can [**publish a Quarto website**](/docs/publishing/index.qmd). For example, if you need to set up the workflow to publish to GitHub pages yourself, head to [Publishing to GitHub Pages](/docs/publishing/github-pages.qmd). | -+---------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++---------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ From 2085e9b1cfa25553eacc43a67a3c0f9454c04658 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Fri, 15 Mar 2024 15:10:36 +0100 Subject: [PATCH 33/33] Update freeze state --- _freeze/docs/authoring/tables/execute-results/html.json | 4 ++-- .../computations/execution-options/execute-results/html.json | 4 ++-- .../docs/output-formats/html-code/execute-results/html.json | 5 +++-- _freeze/site_libs/quarto-listing/list.min.js | 2 +- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/_freeze/docs/authoring/tables/execute-results/html.json b/_freeze/docs/authoring/tables/execute-results/html.json index d16a31db88..3d29627ef0 100644 --- a/_freeze/docs/authoring/tables/execute-results/html.json +++ b/_freeze/docs/authoring/tables/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "4fdbfaec54c087b4c0b117e4af067e72", + "hash": "2793b4a36f4351bbf9d5dc8c35df0206", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Tables\nengine: jupyter\n---\n\n## Overview\n\nQuarto includes a number of features aimed at making it easy to to author and customize markdown table output, including:\n\n- Specifying column alignment and widths.\n- Providing captions, subcaptions, and cross-references.\n- Generating tables dynamically from executable code cells.\n\nThis article covers using these features in-depth.\n\n## Markdown Tables\n\nThe most commonly used markdown table is known as a pipe table. Pipe tables support specifying per column alignment as well as captions. For example:\n\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n```\n\n::::\n\n:::: {}\n\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n\n::::\n\n:::\n\nThe beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. The header cannot be omitted, however you can simulate a headerless table by including a header with blank cells.\n\nSince the pipes indicate column boundaries, columns need not be vertically aligned, as they are in the above example. So, this is a perfectly legal (though ugly) pipe table:\n\n``` markdown\nfruit| price\n-----|-----:\napple|2.05\npear|1.37\norange|3.09\n```\n\nThe cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. If a pipe table contains a row whose markdown content is wider than the column width (see `columns` option), then the table will take up the full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body.\n\nFor example `---|-` would make the first column 3/4 and the second column 1/4 of the full text width. On the other hand, if no lines are wider than column width, then cell contents will not be wrapped, and the cells will be sized to their contents.\n\n### Using Bootstrap classes\n\nBootstrap table classes given as attributes next to a table caption are inserted into the `` element.\nThe classes permitted are those that apply expressly to the entire table, and these are:\n`\"primary\"`, `\"secondary\"`, `\"success\"`, `\"danger\"`, `\"warning\"`, `\"info\"`, `\"light\"`, `\"dark\"`, `\"striped\"`, `\"hover\"`, `\"active\"`, `\"bordered\"`, `\"borderless\"`, `\"sm\"`, `\"responsive\"`, `\"responsive-sm\"`, `\"responsive-md\"`, `\"responsive-lg\"`, `\"responsive-xl\"`, `\"responsive-xxl\"`.\nFor example, the following Markdown table will be rendered with row stripes and the rows will also be highlighted on hover:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n\n::::\n\n:::\n\n### Authoring\n\nFor simple tables with only a few cells it's straightforward to create them directly in markdown. As tables get larger, it makes sense to use an authoring tool. Some table authoring tools to consider include:\n\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [TablesGenerator](https://tablesgenerator.com/markdown_tables) | Online tool for generating markdown tables |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Emacs TableMode](https://www.emacswiki.org/emacs/TableMode) | Text based table creation and editing capabilities for Emacs. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Quarto Visual Editor](/docs/visual-editor/content.qmd#editing-tables) | Visual editor for `.qmd` files with table editing support. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n\n: {tbl-colwidths=\"\\[35,65\\]\"}\n\n## Column Widths\n\nAbove we describe a means of specifying column widths using the relative number of dashes in each column header (_e.g._, `---|-` to get a 75% / 25% split for a two-column table).\n\nYou can also explicitly specify columns widths using the `tbl-colwidths` attribute or document-level option. For an individual markdown table, add the attribute after the caption. For example:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nIf your table doesn't have a caption, then you can still specify only `tbl-colwidths`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nColumn widths can also be specified at the document level (_e.g._, to have uniform widths across a set of tables):\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\ntbl-colwidths: [75,25]\n---\n```\n\n## Cross References\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable.\nFor example:\n\n::: {#tbl-planets .cell tbl-cap='Astronomical object' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\n\n\nFor markdown tables, add a caption below the table, then include a `#tbl-` label in braces at the end of the caption. For example:\n\n``` markdown\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: My Caption {#tbl-letters}\n\nSee @tbl-letters.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](images/crossref-table.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\n\n\n\nSee the article on [Cross References](cross-references.qmd) for additional details.\n\n### Subtables\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## Caption Location\n\nBy default, table captions are positioned above tables. You can modify this behavior using the `tbl-cap-location` option. For example:\n\n``` yaml\n---\ntbl-cap-location: top\n---\n```\n\nNote that this option is specified at the top level so that it can be shared by both PDF and HTML formats. If you are only targeting a single format you can place it alongside other `format` specific options.\n\nValid values for the caption location include:\n\n| Value | Description |\n|----------|---------------------------------------|\n| `top` | Position the caption above the table. |\n| `bottom` | Position the caption below the table. |\n| `margin` | Position the caption in the margin. |\n\nSee the article on [Article Layout](article-layout.qmd#margin-captions) for additional details on placing captions in the margin.\n\n## Computations\n\nAll of the options described above work for tables produced by executable code cells. For example, here we use the Python [tabulate](https://pypi.org/project/tabulate/) package along with the `Markdown()` function from the IPython [display](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#) module to print a markdown table:\n\n::: {#tbl-planet-measures .cell tbl-cap='Astronomical object' execution_count=2}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planet-measures\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=2}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\nHere we apply the `tbl-cap` and `tbl-colwidths` options to a code cell that uses the knitr `kable()` function to write a markdown table:\n\n```{{r}}\n#| label: tbl-cars\n#| tbl-cap: \"Cars\"\n#| tbl-colwidths: [60,40]\n\nkable(head(cars))\n```\n\nIf your code cell produces multiple tables, you can also specify subcaptions and layout using cell options:\n\n::: {.panel-tabset group=\"language\"}\n\n## Python\n\n````python\n```{{python}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"MPG\"\n#| - \"Taxis\"\n#| layout-ncol: 2\n\nimport seaborn as sns\nfrom IPython.display import Markdown, display\nmpg = sns.load_dataset(\"mpg\").head(10)\ntaxis = sns.load_dataset(\"taxis\").head(10)\n\ndisplay(Markdown(mpg.to_markdown(index = False)))\ndisplay(Markdown(taxis.to_markdown(index = False)))\n```\n````\n\nNote that we use the [`display()`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display) function imported from `IPython` so that we can render multiple outputs from a single cell (by default cells only output their last expression).\n\n## R\n\n````python\n```{{r}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n````\n\n\n:::\n\n## Grid Tables\n\nGrid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). For example:\n\n\n``` markdown\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n```\n\nWhich looks like this when rendered to HTML:\n\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n\n\nThe row of `=`s separates the header from the table body, and can be omitted for a headerless table. Cells that span multiple columns or rows are not supported.\n\nAlignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:\n\n\n``` markdown\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n```\nWhich looks like this when rendered to HTML:\n\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n\n\nFor headerless tables, the colons go on the top line instead:\n\n``` markdown\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n```\n\nWhich looks like this when rendered to HTML:\n\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n\n\nNote that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). Here are some tools that can assist with creating grid tables:\n\n- Emacs' [table-mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Based-Tables.html) (`M-x table-insert`)\n- Quarto [Visual Editor](https://quarto.org/docs/visual-editor/content.html#editing-tables)\n- Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled\n\n## HTML Tables\n\nQuarto can process HTML tables in `html` `RawBlock` nodes (_i.e._, `{=html}`) and convert them to Markdown tables, regardless of the output format (intentionally including non-HTML formats).\nAs a result, you can use HTML table syntax in your documents and it will be converted to Markdown syntax for all formats.\nAdditionally, libraries that emit computational tables in HTML format can work in other output formats.\n\nFor example, consider the following raw HTML block:\n\n````markdown\n```{=html}\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n````\n\nWhen rendered, this results in the following output for HTML and PDF formats:\n\n::: {layout-ncol=2}\n\n:::: {}\n### HTML Output\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n\n::::\n\n:::: {}\n### PDF Output\n\n![](images/raw-table-pdf.png){.border fig-alt=\"Screenshot of PDF output showing a table with a caption and two columns. The column headers are Header 1 and Header 2, and the cell contents are an image of an elephant and text that reads Regular Output.\"}\n::::\n\n:::\n\nIn addition, Quarto supports the specification of embedded Markdown content in tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese nodes can appear anywhere that such content is allowed: table headers, footers, cells, captions, _etc._ \n\nFor example, the following table includes a cross reference, markdown formatting and a shortcode:\n\n:::: {layout-nrow=\"2\"}\n\n::: {}\n\n```` markdown\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}}\">Regular output
\n```\n````\n\n:::\n\n::: {}\n\nWhich renders as follows:\n\n## HTML Tables Example {#sec-html-tables}\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}\">Regular output
\n```\n\n\n:::\n\n::::\n\n\n## Disabling Quarto Table Processing\n\nIt's possible that Quarto's processing of HTML tables may interfere with the HTML produced computationally with table packages in R and Python (or other supported languages).\n\nYou can disable Quarto's HTML table processing at a document level or project level with the option `html-table-processing`:\n\n```{.yaml}\n---\nformat:\n html:\n html-table-processing: none\n---\n```\n\nThis option is also available as a code cell option for Knitr and Jupyter, e.g. \n\n\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\n````\n\n\nTo disable Quarto's HTML table processing for parts of a document use a div with the attribute `html-table-processing=\"none\"`:\n\n````{.markdown}\n::: {html-table-processing=\"none\"}\n\nContent with HTML tables you don't want processed.\n\n:::\n````\n\n### Library authors\n\nIf you are the author of a library that emits HTML tables you might like to disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing=\"true\"` to the `` element. For example:\n\n```html\n
\n ...\n
\n```\n\n", + "markdown": "---\ntitle: Tables\nengine: jupyter\n---\n\n## Overview\n\nQuarto includes a number of features aimed at making it easy to to author and customize markdown table output, including:\n\n- Specifying column alignment and widths.\n- Providing captions, subcaptions, and cross-references.\n- Generating tables dynamically from executable code cells.\n\nThis article covers using these features in-depth.\n\n## Markdown Tables\n\nThe most commonly used markdown table is known as a pipe table. Pipe tables support specifying per column alignment as well as captions. For example:\n\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n```\n\n::::\n\n:::: {}\n\n| Default | Left | Right | Center |\n|---------|:-----|------:|:------:|\n| 12 | 12 | 12 | 12 |\n| 123 | 123 | 123 | 123 |\n| 1 | 1 | 1 | 1 |\n\n: Demonstration of pipe table syntax\n\n::::\n\n:::\n\nThe beginning and ending pipe characters are optional, but pipes are required between all columns. The colons indicate column alignment as shown. The header cannot be omitted, however you can simulate a headerless table by including a header with blank cells.\n\nSince the pipes indicate column boundaries, columns need not be vertically aligned, as they are in the above example. So, this is a perfectly legal (though ugly) pipe table:\n\n``` markdown\nfruit| price\n-----|-----:\napple|2.05\npear|1.37\norange|3.09\n```\n\nThe cells of pipe tables cannot contain block elements like paragraphs and lists, and cannot span multiple lines. If a pipe table contains a row whose markdown content is wider than the column width (see `columns` option), then the table will take up the full text width and the cell contents will wrap, with the relative cell widths determined by the number of dashes in the line separating the table header from the table body.\n\nFor example `---|-` would make the first column 3/4 and the second column 1/4 of the full text width. On the other hand, if no lines are wider than column width, then cell contents will not be wrapped, and the cells will be sized to their contents.\n\n### Using Bootstrap classes\n\nBootstrap table classes given as attributes next to a table caption are inserted into the `` element.\nThe classes permitted are those that apply expressly to the entire table, and these are:\n`\"primary\"`, `\"secondary\"`, `\"success\"`, `\"danger\"`, `\"warning\"`, `\"info\"`, `\"light\"`, `\"dark\"`, `\"striped\"`, `\"hover\"`, `\"active\"`, `\"bordered\"`, `\"borderless\"`, `\"sm\"`, `\"responsive\"`, `\"responsive-sm\"`, `\"responsive-md\"`, `\"responsive-lg\"`, `\"responsive-xl\"`, `\"responsive-xxl\"`.\nFor example, the following Markdown table will be rendered with row stripes and the rows will also be highlighted on hover:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {.striped .hover}\n\n::::\n\n:::\n\n### Authoring\n\nFor simple tables with only a few cells it's straightforward to create them directly in markdown. As tables get larger, it makes sense to use an authoring tool. Some table authoring tools to consider include:\n\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [TablesGenerator](https://tablesgenerator.com/markdown_tables) | Online tool for generating markdown tables |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Emacs TableMode](https://www.emacswiki.org/emacs/TableMode) | Text based table creation and editing capabilities for Emacs. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n| [Quarto Visual Editor](/docs/visual-editor/content.qmd#editing-tables) | Visual editor for `.qmd` files with table editing support. |\n+------------------------------------------------------------------------+---------------------------------------------------------------+\n\n: {tbl-colwidths=\"\\[35,65\\]\"}\n\n## Column Widths\n\nAbove we describe a means of specifying column widths using the relative number of dashes in each column header (_e.g._, `---|-` to get a 75% / 25% split for a two-column table).\n\nYou can also explicitly specify columns widths using the `tbl-colwidths` attribute or document-level option. For an individual markdown table, add the attribute after the caption. For example:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: Fruit prices {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nIf your table doesn't have a caption, then you can still specify only `tbl-colwidths`:\n\n::: {layout-ncol=\"2\"}\n\n:::: {}\n\n``` markdown\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n```\n\n::::\n\n:::: {}\n\n| fruit | price |\n|--------|--------|\n| apple | 2.05 |\n| pear | 1.37 |\n| orange | 3.09 |\n\n: {tbl-colwidths=\"[75,25]\"}\n\n::::\n\n:::\n\nColumn widths can also be specified at the document level (_e.g._, to have uniform widths across a set of tables):\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\ntbl-colwidths: [75,25]\n---\n```\n\n## Cross References\n\nFor tables produced by executable code cells, include a label with a `tbl-` prefix to make them cross-referenceable.\nFor example:\n\n::: {#tbl-planets .cell tbl-cap='Astronomical object' execution_count=1}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planets\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=1}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\n::: callout-important\n## Label Prefix\n\nIn order for a table to be cross-referenceable, its label must start with the `tbl-` prefix.\n:::\n\n\n\n\nFor markdown tables, add a caption below the table, then include a `#tbl-` label in braces at the end of the caption. For example:\n\n``` markdown\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: My Caption {#tbl-letters}\n\nSee @tbl-letters.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](images/crossref-table.png){fig-alt=\"A table with 3 columns and four rows. The text 'Table 1: My Caption' is above the header column. The text 'See tbl. 1' is aligned to the left underneath the last column.\" width=\"500\"}\n\n\n\nSee the article on [Cross References](cross-references.qmd) for additional details.\n\n### Subtables\n\n\nYou may want to create a composition of several sub-tables. To do this, create a div with a main identifier, then apply sub-identifiers (and optional caption text) to the contained tables. For example:\n\n``` markdown\n::: {#tbl-panel layout-ncol=2}\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: First Table {#tbl-first}\n\n| Col1 | Col2 | Col3 |\n|------|------|------|\n| A | B | C |\n| E | F | G |\n| A | G | G |\n\n: Second Table {#tbl-second}\n\nMain Caption\n:::\n\nSee @tbl-panel for details, especially @tbl-second.\n```\n\nWhich looks like this when rendered to HTML:\n\n![](/docs/authoring/images/crossref-subtable.png){fig-alt=\"Two tables side-by-side. Both tables have 3 columns and 4 rows. The table on the left is titled '(a) First table'. The table on the right is titled '(b) Second Table'. Centered underneath both tables is the text 'Table 1: Main Caption'. The text 'See tbl. 2 for details, especially tbl. 2 (b)' is aligned to the left underneath that.\"}\n\nNote that the \"Main Caption\" for the table is provided as the last block within the containing div.\n\n\n\n## Caption Location\n\nBy default, table captions are positioned above tables. You can modify this behavior using the `tbl-cap-location` option. For example:\n\n``` yaml\n---\ntbl-cap-location: top\n---\n```\n\nNote that this option is specified at the top level so that it can be shared by both PDF and HTML formats. If you are only targeting a single format you can place it alongside other `format` specific options.\n\nValid values for the caption location include:\n\n| Value | Description |\n|----------|---------------------------------------|\n| `top` | Position the caption above the table. |\n| `bottom` | Position the caption below the table. |\n| `margin` | Position the caption in the margin. |\n\nSee the article on [Article Layout](article-layout.qmd#margin-captions) for additional details on placing captions in the margin.\n\n## Computations\n\nAll of the options described above work for tables produced by executable code cells. For example, here we use the Python [tabulate](https://pypi.org/project/tabulate/) package along with the `Markdown()` function from the IPython [display](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#) module to print a markdown table:\n\n::: {#tbl-planet-measures .cell tbl-cap='Astronomical object' execution_count=2}\n```` { .cell-code}\n```{{python}}\n#| label: tbl-planet-measures\n#| tbl-cap: Astronomical object\n\nfrom IPython.display import Markdown\nfrom tabulate import tabulate\ntable = [[\"Sun\",\"696,000\",1.989e30],\n [\"Earth\",\"6,371\",5.972e24],\n [\"Moon\",\"1,737\",7.34e22],\n [\"Mars\",\"3,390\",6.39e23]]\nMarkdown(tabulate(\n table, \n headers=[\"Astronomical object\",\"R (km)\", \"mass (kg)\"]\n))\n```\n\n````\n\n::: {.cell-output .cell-output-display .cell-output-markdown execution_count=2}\nAstronomical object R (km) mass (kg)\n--------------------- -------- -----------\nSun 696,000 1.989e+30\nEarth 6,371 5.972e+24\nMoon 1,737 7.34e+22\nMars 3,390 6.39e+23\n:::\n:::\n\n\nHere we apply the `tbl-cap` and `tbl-colwidths` options to a code cell that uses the knitr `kable()` function to write a markdown table:\n\n```{{r}}\n#| label: tbl-cars\n#| tbl-cap: \"Cars\"\n#| tbl-colwidths: [60,40]\n\nkable(head(cars))\n```\n\nIf your code cell produces multiple tables, you can also specify subcaptions and layout using cell options:\n\n::: {.panel-tabset group=\"language\"}\n\n## Python\n\n````python\n```{{python}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"MPG\"\n#| - \"Taxis\"\n#| layout-ncol: 2\n\nimport seaborn as sns\nfrom IPython.display import Markdown, display\nmpg = sns.load_dataset(\"mpg\").head(10)\ntaxis = sns.load_dataset(\"taxis\").head(10)\n\ndisplay(Markdown(mpg.to_markdown(index = False)))\ndisplay(Markdown(taxis.to_markdown(index = False)))\n```\n````\n\nNote that we use the [`display()`](https://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html#IPython.display.display) function imported from `IPython` so that we can render multiple outputs from a single cell (by default cells only output their last expression).\n\n## R\n\n````python\n```{{r}}\n#| label: tbl-example\n#| tbl-cap: \"Example\"\n#| tbl-subcap: \n#| - \"Cars\"\n#| - \"Pressure\"\n#| layout-ncol: 2\n\nlibrary(knitr)\nkable(head(cars))\nkable(head(pressure))\n```\n````\n\n\n:::\n\n## Grid Tables\n\nGrid tables are a more advanced type of markdown tables that allow arbitrary block elements (multiple paragraphs, code blocks, lists, etc.). For example:\n\n\n``` markdown\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n```\n\nWhich looks like this when rendered to HTML:\n\n+-----------+-----------+--------------------+\n| Fruit | Price | Advantages |\n+===========+===========+====================+\n| Bananas | $1.34 | - built-in wrapper |\n| | | - bright color |\n+-----------+-----------+--------------------+\n| Oranges | $2.10 | - cures scurvy |\n| | | - tasty |\n+-----------+-----------+--------------------+\n\n: Sample grid table.\n\n\nThe row of `=`s separates the header from the table body, and can be omitted for a headerless table. Cells that span multiple columns or rows are not supported.\n\nAlignments can be specified as with pipe tables, by putting colons at the boundaries of the separator line after the header:\n\n\n``` markdown\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n```\nWhich looks like this when rendered to HTML:\n\n+---------+--------+------------------+\n| Right | Left | Centered |\n+========:+:=======+:================:+\n| Bananas | $1.34 | built-in wrapper |\n+---------+--------+------------------+\n\n\nFor headerless tables, the colons go on the top line instead:\n\n``` markdown\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n```\n\nWhich looks like this when rendered to HTML:\n\n+----------:+:----------+:--------:+\n| Right | Left | Centered |\n+-----------+-----------+----------+\n\n\nNote that grid tables are quite awkward to write with a plain text editor (because unlike pipe tables, the column indicators must align). Here are some tools that can assist with creating grid tables:\n\n- Emacs' [table-mode](https://www.gnu.org/software/emacs/manual/html_node/emacs/Text-Based-Tables.html) (`M-x table-insert`)\n- Quarto [Visual Editor](/docs/visual-editor/content.qmd#editing-tables)\n- Tables Generator's [Plain Text mode](https://www.tablesgenerator.com/text_tables) with `Use reStructuredText syntax` enabled\n\n## HTML Tables\n\nQuarto can process HTML tables in `html` `RawBlock` nodes (_i.e._, `{=html}`) and convert them to Markdown tables, regardless of the output format (intentionally including non-HTML formats).\nAs a result, you can use HTML table syntax in your documents and it will be converted to Markdown syntax for all formats.\nAdditionally, libraries that emit computational tables in HTML format can work in other output formats.\n\nFor example, consider the following raw HTML block:\n\n````markdown\n```{=html}\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n````\n\nWhen rendered, this results in the following output for HTML and PDF formats:\n\n::: {layout-ncol=2}\n\n:::: {}\n### HTML Output\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
As described in the section above, Quarto tables are great.
Header 1Header 2
\"AfricanRegular output
\n```\n\n::::\n\n:::: {}\n### PDF Output\n\n![](images/raw-table-pdf.png){.border fig-alt=\"Screenshot of PDF output showing a table with a caption and two columns. The column headers are Header 1 and Header 2, and the cell contents are an image of an elephant and text that reads Regular Output.\"}\n::::\n\n:::\n\nIn addition, Quarto supports the specification of embedded Markdown content in tables.\nThis is done by providing a data attribute `qmd` or `qmd-base64` in an embedded `span` or `div` node.\nThese nodes can appear anywhere that such content is allowed: table headers, footers, cells, captions, _etc._ \n\nFor example, the following table includes a cross reference, markdown formatting and a shortcode:\n\n:::: {layout-nrow=\"2\"}\n\n::: {}\n\n```` markdown\n## HTML Tables Example {#sec-html-tables}\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}}\">Regular output
\n```\n````\n\n:::\n\n::: {}\n\nWhich renders as follows:\n\n## HTML Tables Example {#sec-html-tables}\n\n\n```{=html}\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n
}}\">Regular output
\n```\n\n\n:::\n\n::::\n\n\n## Disabling Quarto Table Processing\n\nIt's possible that Quarto's processing of HTML tables may interfere with the HTML produced computationally with table packages in R and Python (or other supported languages).\n\nYou can disable Quarto's HTML table processing at a document level or project level with the option `html-table-processing`:\n\n```{.yaml}\n---\nformat:\n html:\n html-table-processing: none\n---\n```\n\nThis option is also available as a code cell option for Knitr and Jupyter, e.g. \n\n\n````{markdown}\n```{{r}}\n#| html-table-processing: none\n\n# R Code that generates an HTML table\n```\n````\n\n\nTo disable Quarto's HTML table processing for parts of a document use a div with the attribute `html-table-processing=\"none\"`:\n\n````{.markdown}\n::: {html-table-processing=\"none\"}\n\nContent with HTML tables you don't want processed.\n\n:::\n````\n\n### Library authors\n\nIf you are the author of a library that emits HTML tables you might like to disable Quarto's processing of HTML tables by adding the attribute `data-quarto-disable-processing=\"true\"` to the `` element. For example:\n\n```html\n
\n ...\n
\n```\n\n", "supporting": [ "tables_files" ], diff --git a/_freeze/docs/computations/execution-options/execute-results/html.json b/_freeze/docs/computations/execution-options/execute-results/html.json index 4404df286c..5ac304342a 100644 --- a/_freeze/docs/computations/execution-options/execute-results/html.json +++ b/_freeze/docs/computations/execution-options/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "307951cb3cfda279dd5e9a3f361c5b82", + "hash": "f39244a08bb2056e19c116ca7ba841c9", "result": { "engine": "jupyter", - "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+===========+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `output` | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\n::: callout-tip\nWhen using the Knitr engine, you can also use any of the available native options (e.g. `collapse`, `tidy`, `comment`, etc.). See the [Knitr options documentation](https://yihui.org/knitr/options/) for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the `{r}` as shown in the Knitr documentation.\n:::\n\n::: callout-tip\nThe Knitr engine can also *conditionally* evaluate a code chunk using objects or expressions. See [Using R: Knitr Options](r.qmd#chunk-options).\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Knitr engine, `fig-width` and `fig-height` are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). See [Inline Code](inline-code.qmd) for details.\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n\n## Jupyter Options\n\n### Expression Printing\n\nWhen multiple expressions are present in a code cell, by default, only the last top-level expression is captured in the rendered output. For example, consider the code cell:\n\n::: {layout-ncol=\"2\"}\n```` markdown\n```{{python}}\n\"first\"\n\"last\"\n```\n````\n:::\n\nWhen rendered to HTML the output generated is:\n\n``` markdown\n'last'\n```\n\nThis behavior corresponds to the `last_expr` setting for [Jupyter shell interactivity](https://ipython.readthedocs.io/en/stable/config/options/terminal.html#configtrait-InteractiveShell.ast_node_interactivity).\n\nYou can control this behavior with the `ipynb-shell-interactivity` option. For example, to capture all top-level expressions set it to `all`:\n\n``` yaml\n---\ntitle: All expressions\nformat: html\nipynb-shell-interactivity: all\n---\n```\n\nNow the above code cell results in the output:\n\n``` markdown\n'first'\n\n'last'\n```\n\n::: callout-note\n## All Expressions are Printed in Dashboards\n\nFor [dashboards](/docs/dashboards/) the default setting of `ipynb-shell-interactivity` is `all.`\n:::\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#d9b2e5a8 .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#521ace61 .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", + "markdown": "---\ntitle: Execution Options\nformat: html\n---\n\n## Output Options\n\nThere are a wide variety of options available for customizing output from executed code. All of these options can be specified either globally (in the document front-matter) or per code-block. For example, here's a modification of the Python example to specify that we don't want to \"echo\" the code into the output document:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\nOptions available for customizing output include:\n\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Option | Description |\n+===========+===================================================================================================================================================================================================+\n| `eval` | Evaluate the code chunk (if `false`, just echos the code into the output). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `echo` | Include the source code in output |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `output` | Include the results of executing the code in the output (`true`, `false`, or `asis` to indicate that the output is raw markdown and should not have any of Quarto's standard enclosing markdown). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `warning` | Include warnings in the output. |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `error` | Include errors in the output (note that this implies that errors executing code will not halt processing of the document). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `include` | Catch all for preventing any output (code or results) from being included (e.g. `include: false` suppresses all output from the code block). |\n+-----------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nHere's a Knitr example with some of these additional options included:\n\n```` \n---\ntitle: \"Knitr Document\"\nexecute:\n echo: false\n---\n\n```{{r}}\n#| warning: false\n\nlibrary(ggplot2)\nggplot(airquality, aes(Temp, Ozone)) + \n geom_point() + \n geom_smooth(method = \"loess\", se = FALSE)\n```\n\n```{{r}}\nsummary(airquality)\n```\n````\n\n::: callout-tip\nWhen using the Knitr engine, you can also use any of the available native options (e.g. `collapse`, `tidy`, `comment`, etc.). See the [Knitr options documentation](https://yihui.org/knitr/options/) for additional details. You can include these native options in option comment blocks as shown above, or on the same line as the `{r}` as shown in the Knitr documentation.\n:::\n\n::: callout-tip\nThe Knitr engine can also *conditionally* evaluate a code chunk using objects or expressions. See [Using R: Knitr Options](r.qmd#chunk-options).\n:::\n\n## Figure Options\n\nThere are a number of ways to control the default width and height of figures generated from code. First, it's important to know that Quarto sets a default width and height for figures appropriate to the target output format. Here are the defaults (expressed in inches):\n\n| Format | Default |\n|-------------------------|-----------|\n| Default | 7 x 5 |\n| HTML Slides | 9.5 x 6.5 |\n| HTML Slides (reveal.js) | 9 x 5 |\n| PDF | 5.5 x 3.5 |\n| PDF Slides (Beamer) | 10 x 7 |\n| PowerPoint | 7.5 x 5.5 |\n| MS Word, ODT, RTF | 5 x 4 |\n| EPUB | 5 x 4 |\n| Hugo | 8 x 5 |\n\nThese defaults were chosen to provide attractive well proportioned figures, but feel free to experiment to see whether you prefer another default size. You can change the default sizes using the `fig-width` and `fig-height` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: \n html:\n fig-width: 8\n fig-height: 6\n pdf:\n fig-width: 7\n fig-height: 5\n---\n```\n\nHow do these sizes make their way into the engine-level defaults for generating figures? This differs by engine:\n\n- For the Knitr engine, these values become the default values for the `fig.width` and `fig.height` chunk options. You can override these default values via chunk level options.\n\n- For Python, these values are used to set the [Matplotlib](https://matplotlib.org/stable/tutorials/introductory/customizing.html) `figure.figsize` rcParam (you can of course manually override these defaults for any given plot).\n\n- For Julia, these values are used to initialize the default figure size for the [Plots.jl](https://docs.juliaplots.org/stable/) GR backend.\n\n If you are using another graphics library with Jupyter and want to utilize these values, you can read them from `QUARTO_FIG_WIDTH` and `QUARTO_FIG_HEIGHT` environment variables.\n\n::: callout-caution\nWhen using the Knitr engine, `fig-width` and `fig-height` are supported on a per-cell basis. But when using the Jupyter engine, these options only have an effect if specified at the document- or project-level metadata.\n:::\n\n### Caption and Alt Text\n\nYou can specify the caption and alt text for figures generated from code using the `fig-cap` and `fig-alt` options. For example, here we add these options to a Python code cell that creates a plot:\n\n```{{python}}\n#| fig-cap: \"Polar axis plot\"\n#| fig-alt: \"A line plot on a polar axis\"\n\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nr = np.arange(0, 2, 0.01)\ntheta = 2 * np.pi * r\nfig, ax = plt.subplots(subplot_kw={'projection': 'polar'})\nax.plot(theta, r)\nax.set_rticks([0.5, 1, 1.5, 2])\nax.grid(True)\nplt.show()\n```\n\n## Inline Code\n\nJupyter, Knitr and OJS all support executing inline code within markdown (e.g. to allow narrative to automatically use the most up to date computations). See [Inline Code](inline-code.qmd) for details.\n\n## Raw Output\n\nThe `output: asis` option enables you to generate raw markdown output. When `output: asis` is specified none of Quarto's standard enclosing divs will be included. For example, here we specify `output: asis` in order to generate a pair of headings:\n\n::: panel-tabset\n## Jupyter\n\n```{{python}}\n#| echo: false\n#| output: asis\n\nprint(\"# Heading 1\\n\")\nprint(\"## Heading 2\\n\")\n```\n\n## Knitr\n\n```{{r}}\n#| echo: false\n#| output: asis\n\ncat(\"# Heading 1\\n\")\ncat(\"## Heading 2\\n\")\n```\n:::\n\nWhich generates the following output:\n\n``` default\n# Heading 1\n\n## Heading 2\n```\n\nNote that we also include the `echo: false` option to ensure that the code used to generate markdown isn't included in the final output.\n\nIf we had not specified `output: asis` the output, as seen in the intermediate markdown, would have included Quarto's `.cell-output` div:\n\n```` default\n::: {.cell-output-stdout}\n```\n# Heading 1\n\n## Heading 2\n \n```\n:::\n````\n\nFor the Jupyter engine, you can also create raw markdown output using the functions in `IPython.display`. For example:\n\n```{{python}}\n#| echo: false\nradius = 10\nfrom IPython.display import Markdown\nMarkdown(f\"The _radius_ of the circle is **{radius}**.\")\n```\n\n\n## Knitr Options\n\nIf you are using the Knitr cell execution engine, you can specify default document-level [Knitr chunk options](https://yihui.org/knitr/options/) in YAML. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nknitr:\n opts_chunk: \n collapse: true\n comment: \"#>\" \n R.options:\n knitr.graphics.auto_pdf: true\n---\n```\n\nYou can additionally specify global Knitr options using `opts_knit`.\n\nThe `R.options` chunk option is a convenient way to define R options that are set temporarily via [`options()`](https://rdrr.io/r/base/options.html) before the code chunk execution, and immediately restored afterwards.\n\nIn the example above, we establish default Knitr chunk options for a single document. You can also add shared `knitr` options to a project-wide `_quarto.yml` file or a project-directory scoped `_metadata.yml` file.\n\n\n\n## Jupyter Options\n\n### Expression Printing\n\nWhen multiple expressions are present in a code cell, by default, only the last top-level expression is captured in the rendered output. For example, consider the code cell:\n\n::: {layout-ncol=\"2\"}\n```` markdown\n```{{python}}\n\"first\"\n\"last\"\n```\n````\n:::\n\nWhen rendered to HTML the output generated is:\n\n``` markdown\n'last'\n```\n\nThis behavior corresponds to the `last_expr` setting for [Jupyter shell interactivity](https://ipython.readthedocs.io/en/stable/config/options/terminal.html#configtrait-InteractiveShell.ast_node_interactivity).\n\nYou can control this behavior with the `ipynb-shell-interactivity` option. For example, to capture all top-level expressions set it to `all`:\n\n``` yaml\n---\ntitle: All expressions\nformat: html\nipynb-shell-interactivity: all\n---\n```\n\nNow the above code cell results in the output:\n\n``` markdown\n'first'\n\n'last'\n```\n\n::: callout-note\n## All Expressions are Printed in Dashboards\n\nFor [dashboards](/docs/dashboards/index.qmd) the default setting of `ipynb-shell-interactivity` is `all.`\n:::\n\n## Intermediates\n\nOn the way from markdown input to final output, there are some intermediate files that are created and automatically deleted at the end of rendering. You can use the following options to keep these intermediate files:\n\n+--------------+------------------------------------------------------------------------------------------------+\n| Option | Description |\n+==============+================================================================================================+\n| `keep-md` | Keep the markdown file generated by executing code. |\n+--------------+------------------------------------------------------------------------------------------------+\n| `keep-ipynb` | Keep the notebook file generated from executing code (applicable only to markdown input files) |\n+--------------+------------------------------------------------------------------------------------------------+\n\nFor example, here we specify that we want to keep the jupyter intermediate file after rendering:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n keep-ipynb: true\njupyter: python3\n---\n```\n\n## Fenced Echo\n\nIf you are writing a tutorial or documentation on using Quarto code blocks, you'll likely want to include the fenced code delimiter (e.g. ```` ```{python} ````) in your code output to emphasize that executable code requires that delimiter. You can do this using the `echo: fenced` option. For example, the following code block:\n\n```{{python}}\n#| echo: fenced\n1 + 1\n```\n\nWill be rendered as:\n\n::: {#f3ae4c60 .cell execution_count=1}\n```` { .cell-code}\n```{{python}}\n1 + 1\n```\n\n````\n\n::: {.cell-output .cell-output-display execution_count=1}\n```\n2\n```\n:::\n:::\n\n\nThis is especially useful when you want to demonstrate the use of cell options. For example, here we demonstrate the use of the `output` and `code-overflow` options:\n\n```{{python}}\n#| echo: fenced\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\nThis code block appears in the rendered document as:\n\n::: {#0d066063 .cell execution_count=2}\n```` { .cell-code .code-overflow-wrap}\n```{{python}}\n#| output: false\n#| code-overflow: wrap\n1 + 1\n```\n\n````\n:::\n\n\nNote that all YAML options will be included in the fenced code output *except for* `echo: fenced` (as that might be confusing to readers).\n\nThis behavior can also be specified at the document level if you want all of your executable code blocks to include the fenced delimiter and YAML options:\n\n``` yaml\n---\ntitle: \"My Document\"\nformat: html\nexecute:\n echo: fenced\n---\n```\n\n#### Unexecuted Blocks\n\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Engine Binding\n\nEarlier we said that the engine used for computations was determined automatically. You may want to customize this---for example you may want to use the Jupyter [R kernel](https://github.com/IRkernel/IRkernel) rather than Knitr, or you may want to use Knitr with Python code (via [reticulate](https://rstudio.github.io/reticulate/)).\n\nHere are the basic rules for automatic binding:\n\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Extension | Engine Binding |\n+===========+========================================================================================================================================================================================================================================+\n| .qmd | Use Knitr engine if an `{r}` code block is discovered within the file |\n| | |\n| | Use Jupyter engine if *any other* executable code block (e.g. `{python}`, `{julia}`, `{bash}`, etc.) is discovered within the file. The kernel used is determined based on the language of the first executable code block discovered. |\n| | |\n| | Use no engine if no executable code blocks are discovered. |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .ipynb | Jupyter engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .Rmd | Knitr engine |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| .md | No engine (note that if an `md` document does contain executable code blocks then an error will occur) |\n+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nFor `.qmd` files in particular, you can override the engine used via the `engine` option. For example:\n\n``` markdown\nengine: jupyter\n```\n\n``` markdown\nengine: knitr\n```\n\nYou can also specify that no execution engine should be used via `engine: markdown`.\n\nThe presence of the `knitr` or `jupyter` option will also override the default engine:\n\n``` markdown\nknitr: true\n```\n\n``` markdown\njupyter: python3\n```\n\nVariations with additional engine-specific options also work to override the default engine:\n\n``` markdown\nknitr:\n opts_knit:\n verbose: true\n```\n\n``` markdown\njupyter:\n kernelspec:\n display_name: Python 3\n language: python\n name: python3\n```\n\n## Shell Commands\n\nUsing shell commands (from Bash, Zsh, etc.) within Quarto computational documents differs by engine. If you are using the Jupyter engine you can use [Jupyter shell magics](https://jakevdp.github.io/PythonDataScienceHandbook/01.05-ipython-and-shell-commands.html). For example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: jupyter\n---\n\n```{{python}}\n!echo \"foo\"\n```\n````\n\nNote that `!` preceding `echo` is what enables a Python cell to be able to execute a shell command.\n\nIf you are using the Knitr engine you can use ```` ```{bash} ```` cells, for example:\n\n```` markdown\n---\ntitle: \"Using Bash\"\nengine: knitr\n---\n\n```{{bash}}\necho \"foo\" \n```\n````\n\nNote that the Knitr engine also supports ```` ```{python} ```` cells, enabling the combination of R, Python, and Bash in the same document\n\n", "supporting": [ "execution-options_files" ], diff --git a/_freeze/docs/output-formats/html-code/execute-results/html.json b/_freeze/docs/output-formats/html-code/execute-results/html.json index e725adaf7a..6bdc8d6955 100644 --- a/_freeze/docs/output-formats/html-code/execute-results/html.json +++ b/_freeze/docs/output-formats/html-code/execute-results/html.json @@ -1,7 +1,8 @@ { - "hash": "40fe1a80fe5c6d1ac8a8c9bedbc419ba", + "hash": "aa242198e1887f90d19d599694fe46e3", "result": { - "markdown": "---\ntitle: \"HTML Code Blocks\"\nformat: \n html:\n code-tools: true\nexecute:\n warning: false\n---\n\n\n## Overview\n\nThere are wide variety of options available to customize the display of source code within HTML documents, including:\n\n1. Hiding some or all code that was executed by [Knitr](https://yihui.name/knitr) or [Jupyter](https://jupyter.org).\n2. Code folding for executed code (hidden by default and expandable by readers).\n3. Handling code that overflows the available horizontal display space.\n4. View the source code of the markdown file used to generate the document.\n5. Syntax highlighting themes and other options to control the appearance of code.\n6. Copy to clipboard button for code blocks.\n7. Generating hyperlinks to online documentation for functions used within code blocks via the [downlit](https://downlit.r-lib.org/) package (note that this option currently only works when using the Knitr engine).\n\nDetails on using all of these options are provided below.\n\n## Hiding Code\n\nFor many documents you may want to hide all of the executable source code used to produce dynamic outputs. You can do this by specifying `echo: false` in the document `execute` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\n## Folding Code\n\nUse the `code-fold` option to include code but have it hidden by default using the HTML `
` tag. For example, click the **Code** button to see the code that produced this plot.\n\n\n::: {.cell}\n\n```{.r .cell-code code-fold=\"true\"}\nlibrary(ggplot2)\ndat <- data.frame(cond = rep(c(\"A\", \"B\"), each=10),\n xvar = 1:20 + rnorm(20,sd=3),\n yvar = 1:20 + rnorm(20,sd=3))\n\nggplot(dat, aes(x=xvar, y=yvar)) +\n geom_point(shape=1) + \n geom_smooth() \n```\n\n::: {.cell-output-display}\n![](html-code_files/figure-html/unnamed-chunk-1-1.png){width=672}\n:::\n:::\n\n\nHere we specify both `code-fold: true` as well as custom summary text (the default is just \"Code\" as shown above):\n\n``` yaml\nformat:\n html:\n code-fold: true\n code-summary: \"Show the code\"\n```\n\nValid values for `code-fold` include:\n\n| Value | Behavior |\n|---------|------------------------------|\n| `false` | No folding (default) |\n| `true` | Fold code (initially hidden) |\n| `show` | Fold code (initially shown) |\n\nUse the `code-fold` and `code-summary` chunk attributes to control this on a chunk-by-chunk basis:\n\n```{{r}}\n#| code-fold: true\n#| code-summary: \"Show the code\"\n```\n\n## Code Overflow\n\nIn some cases the width of source code will overflow the available horizontal display space. By default, this will result in a horizontal scroll bar for the code block. However if you prefer not to have scrollbars you can have the longer lines wrap instead.\n\nTo set the global default behavior use the `code-overflow` option. For example:\n\n``` yaml\nformat:\n html:\n code-overflow: wrap\n```\n\nValid values for `code-overflow` are:\n\n| Option | Description |\n|------------------|------------------------------------------------------|\n| `scroll` | Scroll code blocks that exceed available width (default, corresponds to `white-space: pre`). |\n| `wrap` | Wrap lines of code that exceed available width (corresponds to `white-space: pre-wrap`). |\n\nYou can also override the global default on a per-code-block basis. For computational cells you do this with the `code-overflow` cell option:\n\n```{{python}}\n#| code-overflow: wrap\n\n# very long line of code....\n```\n\nFor a static code block, add the `.code-overflow-scroll` or `.code-overflow-wrap` CSS class:\n\n```` python\n```{.python .code-overflow-wrap}\n# very long line of code....\n```\n````\n\nNote that irrespective of these options, code will always wrap within printed HTML output (as it would otherwise be clipped off the edge of the page).\n\n## Code Tools\n\nYou can include a **Code** menu in the header of your document that provides various tools for readers to interact with the source code. Specify `code-tools: true` to activate these tools:\n\n``` yaml\nformat:\n html:\n code-fold: true\n code-tools: true\n```\n\nIf you have a document that includes folded code blocks then the **Code** menu will present options to show and hide the folded code as well as view the full source code of the document:\n\n![](images/code-tools-01.png){.border fig-alt=\"A screen shot of the header of a rendered Quarto document showing the result of setting both the code-fold and code-tools option to true. There is a drop-down menu labeled 'Code' to the right of the page title with a triangle pointing down. The menu is open and there are three options listed vertically beneath it: 'Hide All Code,' 'Show All Code,' and 'View Source.'\"}\n\nThis document specifies `code-tools: true` in its options so you should see the **Code** menu above next to the main header.\n\nYou can control which of these options are made available as well as the \"Code\" caption text using sub-options of `code-tools`. For example, here we specify that we want only \"View Source\" (no toggling of code visibility) and no caption on the code menu:\n\n``` yaml\nformat:\n html: \n code-tools:\n source: true\n toggle: false\n caption: none\n```\n\nBy default, the source code is embedded in the document and shown in a popup window like this:\n\n![](images/code-tools-source.png){fig-alt=\"A screenshot of this webpage with a pop-up window labeled 'Source Code' over it. This 'Source Code' window contains the raw markdown and R code used to write this page. There is an 'X' on the upper right corner of the 'Source Code' pop up to close it.\"}\n\nYou can alternatively specify a URL for the value of `source`:\n\n``` yaml\nformat:\n html: \n code-tools:\n source: https://github.com/quarto-dev/quarto-web/blob/main/index.md\n```\n\nIf you are within a project and have specified a `repo-url` option then you can just use `repo` and the correct link to your source file will be generated:\n\n``` yaml\nformat:\n html: \n code-tools:\n source: repo\n```\n\nNote that the `code-tools` option is not available when you disable the standard HTML theme (e.g. if you specify the `theme: none` option).\n\n## Appearance\n\nBy default code blocks are rendered with a left border whose color is derived from the current theme. You can customize code chunk appearance with some simple options that control the background color and left border. Options can either be booleans to enable or disable the treatment or can be legal CSS color strings (or they could even be SASS variable names!).\n\nHere is the default appearance for code blocks (`code-block-background: true`):\n\n![](images/code-bg.png){fig-alt=\"A block of code with a gray background.\"}\n\nYou can instead use a left border treatment using the `code-block-border-left` option:\n\n``` yaml\ncode-block-border-left: true\n```\n\n![](images/code-default.png){fig-alt=\"A block of code with a gray vertical stripe running along its left border. This code block has no background.\"}\n\nYou can combine a background and border treatment as well as customize the left border color:\n\n``` yaml\ncode-block-bg: true\ncode-block-border-left: \"#31BAE9\"\n```\n\n![](images/code-custom.png){fig-alt=\"A block of code with a gray background and a blue vertical stripe running along its left border.\"}\n\n## Code Filename\n\nUse the `filename` attribute on code blocks If you are documenting the contents of a file and want to be especially clear about the name of the file the code is associated with.\n\nFor example, the following code:\n\n```` markdown\n```{.python filename=\"matplotlib.py\"}\nimport matplotlib.pyplot as plt\nplt.plot([1,23,2,4])\nplt.show()\n```\n````\n\nResults in this HTML output:\n\n![](images/code-filename.png)\n\nNon-HTML formats will still have the filename, but it will simply be shown in bold above the code block.\n\n## Highlighting\n\nPandoc will automatically highlight syntax in [fenced code blocks](https://pandoc.org/MANUAL.html#fenced-code-blocks) that are marked with a language name. For example:\n\n ```python\n 1 + 1\n ```\n\nPandoc can provide syntax highlighting for over 140 different languages (see the output of `quarto pandoc --list-highlight-languages` for a list of all of them). If you want to provide the appearance of a highlighted code block for a language not supported, just use `default` as the language name.\n\nYou can specify the code highlighting style using `highlight-style` and specifying one of the supported themes. These themes are \"adaptive\", which means they will automatically switch between a dark and light mode based upon the theme of the website. These are designed to work well with sites that include a dark and light mode.\n\n- a11y\n- arrow\n- atom-one\n- ayu\n- breeze\n- github\n- gruvbox\n\nAll of the standard Pandoc themes are also available:\n\n- pygments\n- tango\n- espresso\n- zenburn\n- kate\n- monochrome\n- breezedark\n- haddock\n\nAs well as an additional set of extended themes, including:\n\n- dracula\n- monokai\n- nord\n- oblivion\n- printing\n- radical\n- solarized\n- vim-dark\n\nThe `highlight-style` option determines which theme is used. For example:\n\n``` yaml\nhighlight-style: github\n```\n\nHighlighting themes can provide either a single highlighting definition or two definitions, one optimized for a light colored background and another optimized for a dark color background. When available, Quarto will automatically select the appropriate style based upon the code chunk background color's darkness. Users may always opt to specify the full name (e.g. `atom-one-dark`) to by pass this automatic behavior.\n\nBy default, code is highlighted using the `arrow` theme, which is optimized for accessibility. We've additionally introduced the `arrow-dark` theme which is designed to provide accessible highlighting against dark backgrounds.\n\nExamples of the light and dark themes:\n\n#### Arrow (light)\n\n![](images/arrow.png){fig.alt=\"A block of code showcasing the Arrow (light) theme.\"}\n\n#### Arrow (dark)\n\n![](images/arrow-dark.png){fig.alt=\"A block of code showcasing the Arrow (dark) theme.\"}\n\n#### Ayu (light)\n\n![](images/ayu.png){fig.alt=\"A block of code showcasing the Ayu (light) theme.\"}\n\n#### Ayu (dark)\n\n![](images/ayu-dark.png){.preview-image fig.alt=\"A block of code showcasing the Ayu (dark) theme.\"}\n\n### Custom Highlighting\n\nIn addition to the built in themes available for syntax highlighting, you can also specify your own syntax highlighting by providing the path to a valid theme file (which is based upon the KDE XML syntax highlighting descriptions). Highlighting is implemented using [skylighting](https://github.com/jgm/skylighting).\n\nFor example:\n\n``` yaml\n---\nhighlight-style: custom.theme\n---\n```\n\nIn addition, if you'd like to provide adaptive themes, you may also pass both a light and dark theme file:\n\n``` yaml\n---\nhighlight-style:\n light: custom-light.theme\n dark: custom-dark.theme\n---\n```\n\nNote that as with adaptive text higlighting themes, when you provide a dark and light `highlight-style`, background colors specified in the themes will be ignored in favor of the overall theme specified background colors.\n\n## Code Annotation\n\nYou can add annotations to lines of code in code blocks and executable code cells. See [Code Annotation](/docs/authoring/code-annotation.qmd) for full details.\n\n\n\n## Line Numbers\n\nIf you want to display line numbers alongside the code block, add the `code-line-numbers` option. For example:\n\n``` yaml\nformat:\n html:\n code-line-numbers: true\n```\n\nHere's how a code block with line numbers would display:\n\n``` {.python code-line-numbers=\"true\"}\nimport matplotlib.pyplot as plt\nplt.plot([1,23,2,4])\nplt.show()\n```\n\nYou can also enable line numbers for an individual code block using the `code-line-numbers` attribute. For example:\n\n```` python\n``` {.python code-line-numbers=\"true\"}\nimport matplotlib.pyplot as plt\nplt.plot([1,23,2,4])\nplt.show()\n```\n````\n\n## Executable Blocks\n\nThe documentation on [computations](/docs/get-started/computations/) covers how to include executable code blocks (code which is actually executed, with its output being included in the rendered document). We won't additionally cover that here, but we will talk about how to include code blocks that demonstrate executable syntax (e.g. for writing a tutorial).\n\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Copy Button\n\nHover over the code block below and you will see a copy icon in the top-right corner:\n\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(dygraphs)\ndygraph(nhtemp, main = \"New Haven Temperatures\") %>% \n dyRangeSelector(dateWindow = c(\"1920-01-01\", \"1960-01-01\"))\n```\n:::\n\n\nThis behavior is enabled by default but you configure it using the `code-copy` option:\n\n``` yaml\nformat:\n html:\n code-copy: false\n```\n\nValid values for `code-copy` include:\n\n| | |\n|---------|--------------------------------|\n| `hover` | Show button on hover (default) |\n| `true` | Always show code copy button |\n| `false` | Never show code copy button |\n\n## Code Linking\n\nThe `code-link` option enables hyper-linking of functions within code blocks to their online documentation:\n\n``` yaml\nformat:\n html:\n code-link: true\n```\n\nCode linking is currently implemented only for the knitr engine (via the [downlit](https://downlit.r-lib.org) package).\nA limitation of downlit currently prevents code linking if `code-line-numbers` and/or `code-annotations` are also `true`.\n", + "engine": "knitr", + "markdown": "---\ntitle: \"HTML Code Blocks\"\nformat: \n html:\n code-tools: true\nexecute:\n warning: false\n---\n\n\n\n## Overview\n\nThere are wide variety of options available to customize the display of source code within HTML documents, including:\n\n1. Hiding some or all code that was executed by [Knitr](https://yihui.name/knitr) or [Jupyter](https://jupyter.org).\n2. Code folding for executed code (hidden by default and expandable by readers).\n3. Handling code that overflows the available horizontal display space.\n4. View the source code of the markdown file used to generate the document.\n5. Syntax highlighting themes and other options to control the appearance of code.\n6. Copy to clipboard button for code blocks.\n7. Generating hyperlinks to online documentation for functions used within code blocks via the [downlit](https://downlit.r-lib.org/) package (note that this option currently only works when using the Knitr engine).\n\nDetails on using all of these options are provided below.\n\n## Hiding Code\n\nFor many documents you may want to hide all of the executable source code used to produce dynamic outputs. You can do this by specifying `echo: false` in the document `execute` options. For example:\n\n``` yaml\n---\ntitle: \"My Document\"\nexecute:\n echo: false\njupyter: python3\n---\n```\n\nNote that we can override this option on a per code-block basis. For example:\n\n```{{python}}\n#| echo: true\n\nimport matplotlib.pyplot as plt\nplt.plot([1,2,3,4])\nplt.show()\n```\n\nCode block options are included in a special comment at the top of the block (lines at the top prefaced with `#|` are considered options).\n\n## Folding Code\n\nUse the `code-fold` option to include code but have it hidden by default using the HTML `
` tag. For example, click the **Code** button to see the code that produced this plot.\n\n\n\n::: {.cell}\n\n```{.r .cell-code code-fold=\"true\"}\nlibrary(ggplot2)\ndat <- data.frame(cond = rep(c(\"A\", \"B\"), each=10),\n xvar = 1:20 + rnorm(20,sd=3),\n yvar = 1:20 + rnorm(20,sd=3))\n\nggplot(dat, aes(x=xvar, y=yvar)) +\n geom_point(shape=1) + \n geom_smooth() \n```\n\n::: {.cell-output-display}\n![](html-code_files/figure-html/unnamed-chunk-1-1.png){width=672}\n:::\n:::\n\n\n\nHere we specify both `code-fold: true` as well as custom summary text (the default is just \"Code\" as shown above):\n\n``` yaml\nformat:\n html:\n code-fold: true\n code-summary: \"Show the code\"\n```\n\nValid values for `code-fold` include:\n\n| Value | Behavior |\n|---------|------------------------------|\n| `false` | No folding (default) |\n| `true` | Fold code (initially hidden) |\n| `show` | Fold code (initially shown) |\n\nUse the `code-fold` and `code-summary` chunk attributes to control this on a chunk-by-chunk basis:\n\n```{{r}}\n#| code-fold: true\n#| code-summary: \"Show the code\"\n```\n\n## Code Overflow\n\nIn some cases the width of source code will overflow the available horizontal display space. By default, this will result in a horizontal scroll bar for the code block. However if you prefer not to have scrollbars you can have the longer lines wrap instead.\n\nTo set the global default behavior use the `code-overflow` option. For example:\n\n``` yaml\nformat:\n html:\n code-overflow: wrap\n```\n\nValid values for `code-overflow` are:\n\n| Option | Description |\n|------------------|------------------------------------------------------|\n| `scroll` | Scroll code blocks that exceed available width (default, corresponds to `white-space: pre`). |\n| `wrap` | Wrap lines of code that exceed available width (corresponds to `white-space: pre-wrap`). |\n\nYou can also override the global default on a per-code-block basis. For computational cells you do this with the `code-overflow` cell option:\n\n```{{python}}\n#| code-overflow: wrap\n\n# very long line of code....\n```\n\nFor a static code block, add the `.code-overflow-scroll` or `.code-overflow-wrap` CSS class:\n\n```` python\n```{.python .code-overflow-wrap}\n# very long line of code....\n```\n````\n\nNote that irrespective of these options, code will always wrap within printed HTML output (as it would otherwise be clipped off the edge of the page).\n\n## Code Tools\n\nYou can include a **Code** menu in the header of your document that provides various tools for readers to interact with the source code. Specify `code-tools: true` to activate these tools:\n\n``` yaml\nformat:\n html:\n code-fold: true\n code-tools: true\n```\n\nIf you have a document that includes folded code blocks then the **Code** menu will present options to show and hide the folded code as well as view the full source code of the document:\n\n![](images/code-tools-01.png){.border fig-alt=\"A screen shot of the header of a rendered Quarto document showing the result of setting both the code-fold and code-tools option to true. There is a drop-down menu labeled 'Code' to the right of the page title with a triangle pointing down. The menu is open and there are three options listed vertically beneath it: 'Hide All Code,' 'Show All Code,' and 'View Source.'\"}\n\nThis document specifies `code-tools: true` in its options so you should see the **Code** menu above next to the main header.\n\nYou can control which of these options are made available as well as the \"Code\" caption text using sub-options of `code-tools`. For example, here we specify that we want only \"View Source\" (no toggling of code visibility) and no caption on the code menu:\n\n``` yaml\nformat:\n html: \n code-tools:\n source: true\n toggle: false\n caption: none\n```\n\nBy default, the source code is embedded in the document and shown in a popup window like this:\n\n![](images/code-tools-source.png){fig-alt=\"A screenshot of this webpage with a pop-up window labeled 'Source Code' over it. This 'Source Code' window contains the raw markdown and R code used to write this page. There is an 'X' on the upper right corner of the 'Source Code' pop up to close it.\"}\n\nYou can alternatively specify a URL for the value of `source`:\n\n``` yaml\nformat:\n html: \n code-tools:\n source: https://github.com/quarto-dev/quarto-web/blob/main/index.md\n```\n\nIf you are within a project and have specified a `repo-url` option then you can just use `repo` and the correct link to your source file will be generated:\n\n``` yaml\nformat:\n html: \n code-tools:\n source: repo\n```\n\nNote that the `code-tools` option is not available when you disable the standard HTML theme (e.g. if you specify the `theme: none` option).\n\n## Appearance\n\nBy default code blocks are rendered with a left border whose color is derived from the current theme. You can customize code chunk appearance with some simple options that control the background color and left border. Options can either be booleans to enable or disable the treatment or can be legal CSS color strings (or they could even be SASS variable names!).\n\nHere is the default appearance for code blocks (`code-block-background: true`):\n\n![](images/code-bg.png){fig-alt=\"A block of code with a gray background.\"}\n\nYou can instead use a left border treatment using the `code-block-border-left` option:\n\n``` yaml\ncode-block-border-left: true\n```\n\n![](images/code-default.png){fig-alt=\"A block of code with a gray vertical stripe running along its left border. This code block has no background.\"}\n\nYou can combine a background and border treatment as well as customize the left border color:\n\n``` yaml\ncode-block-bg: true\ncode-block-border-left: \"#31BAE9\"\n```\n\n![](images/code-custom.png){fig-alt=\"A block of code with a gray background and a blue vertical stripe running along its left border.\"}\n\n## Code Filename\n\nUse the `filename` attribute on code blocks If you are documenting the contents of a file and want to be especially clear about the name of the file the code is associated with.\n\nFor example, the following code:\n\n```` markdown\n```{.python filename=\"matplotlib.py\"}\nimport matplotlib.pyplot as plt\nplt.plot([1,23,2,4])\nplt.show()\n```\n````\n\nResults in this HTML output:\n\n![](images/code-filename.png)\n\nNon-HTML formats will still have the filename, but it will simply be shown in bold above the code block.\n\n## Highlighting\n\nPandoc will automatically highlight syntax in [fenced code blocks](https://pandoc.org/MANUAL.html#fenced-code-blocks) that are marked with a language name. For example:\n\n ```python\n 1 + 1\n ```\n\nPandoc can provide syntax highlighting for over 140 different languages (see the output of `quarto pandoc --list-highlight-languages` for a list of all of them). If you want to provide the appearance of a highlighted code block for a language not supported, just use `default` as the language name.\n\nYou can specify the code highlighting style using `highlight-style` and specifying one of the supported themes. These themes are \"adaptive\", which means they will automatically switch between a dark and light mode based upon the theme of the website. These are designed to work well with sites that include a dark and light mode.\n\n- a11y\n- arrow\n- atom-one\n- ayu\n- breeze\n- github\n- gruvbox\n\nAll of the standard Pandoc themes are also available:\n\n- pygments\n- tango\n- espresso\n- zenburn\n- kate\n- monochrome\n- breezedark\n- haddock\n\nAs well as an additional set of extended themes, including:\n\n- dracula\n- monokai\n- nord\n- oblivion\n- printing\n- radical\n- solarized\n- vim-dark\n\nThe `highlight-style` option determines which theme is used. For example:\n\n``` yaml\nhighlight-style: github\n```\n\nHighlighting themes can provide either a single highlighting definition or two definitions, one optimized for a light colored background and another optimized for a dark color background. When available, Quarto will automatically select the appropriate style based upon the code chunk background color's darkness. Users may always opt to specify the full name (e.g. `atom-one-dark`) to by pass this automatic behavior.\n\nBy default, code is highlighted using the `arrow` theme, which is optimized for accessibility. We've additionally introduced the `arrow-dark` theme which is designed to provide accessible highlighting against dark backgrounds.\n\nExamples of the light and dark themes:\n\n#### Arrow (light)\n\n![](images/arrow.png){fig.alt=\"A block of code showcasing the Arrow (light) theme.\"}\n\n#### Arrow (dark)\n\n![](images/arrow-dark.png){fig.alt=\"A block of code showcasing the Arrow (dark) theme.\"}\n\n#### Ayu (light)\n\n![](images/ayu.png){fig.alt=\"A block of code showcasing the Ayu (light) theme.\"}\n\n#### Ayu (dark)\n\n![](images/ayu-dark.png){.preview-image fig.alt=\"A block of code showcasing the Ayu (dark) theme.\"}\n\n### Custom Highlighting\n\nIn addition to the built in themes available for syntax highlighting, you can also specify your own syntax highlighting by providing the path to a valid theme file (which is based upon the KDE XML syntax highlighting descriptions). Highlighting is implemented using [skylighting](https://github.com/jgm/skylighting).\n\nFor example:\n\n``` yaml\n---\nhighlight-style: custom.theme\n---\n```\n\nIn addition, if you'd like to provide adaptive themes, you may also pass both a light and dark theme file:\n\n``` yaml\n---\nhighlight-style:\n light: custom-light.theme\n dark: custom-dark.theme\n---\n```\n\nNote that as with adaptive text higlighting themes, when you provide a dark and light `highlight-style`, background colors specified in the themes will be ignored in favor of the overall theme specified background colors.\n\n\n## Code Annotation\n\nYou can add annotations to lines of code in code blocks and executable code cells. See [Code Annotation](/docs/authoring/code-annotation.qmd) for full details.\n\n\n\n## Line Numbers\n\nIf you want to display line numbers alongside the code block, add the `code-line-numbers` option. For example:\n\n``` yaml\nformat:\n html:\n code-line-numbers: true\n```\n\nHere's how a code block with line numbers would display:\n\n``` {.python code-line-numbers=\"true\"}\nimport matplotlib.pyplot as plt\nplt.plot([1,23,2,4])\nplt.show()\n```\n\nYou can also enable line numbers for an individual code block using the `code-line-numbers` attribute. For example:\n\n```` python\n``` {.python code-line-numbers=\"true\"}\nimport matplotlib.pyplot as plt\nplt.plot([1,23,2,4])\nplt.show()\n```\n````\n\n## Executable Blocks\n\nThe documentation on [computations](/docs/get-started/computations/index.qmd) covers how to include executable code blocks (code which is actually executed, with its output being included in the rendered document). We won't additionally cover that here, but we will talk about how to include code blocks that demonstrate executable syntax (e.g. for writing a tutorial).\n\n\n\n\n\nOften you'll want to include a fenced code block purely as documentation (not executable). You can do this by using two curly braces around the language (e.g. `python`, `r`, etc.) rather than one. For example:\n\n```{{{python}}}\n1 + 1\n```\n\nWill be output into the document as:\n\n```{{python}}\n1 + 1\n```\n\nIf you want to show an example with multiple code blocks and other markdown, just enclose the entire example in 4 backticks (e.g. ````` ```` `````) and use the two curly brace syntax for code blocks within. For example:\n\n ````\n ---\n title: \"My document\"\n ---\n\n Some markdown content.\n\n ```{{{python}}}\n 1 + 1\n ```\n\n Some additional markdown content.\n\n ````\n\n\n\n## Copy Button\n\nHover over the code block below and you will see a copy icon in the top-right corner:\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nlibrary(dygraphs)\ndygraph(nhtemp, main = \"New Haven Temperatures\") %>% \n dyRangeSelector(dateWindow = c(\"1920-01-01\", \"1960-01-01\"))\n```\n:::\n\n\n\nThis behavior is enabled by default but you configure it using the `code-copy` option:\n\n``` yaml\nformat:\n html:\n code-copy: false\n```\n\nValid values for `code-copy` include:\n\n| | |\n|---------|--------------------------------|\n| `hover` | Show button on hover (default) |\n| `true` | Always show code copy button |\n| `false` | Never show code copy button |\n\n## Code Linking\n\nThe `code-link` option enables hyper-linking of functions within code blocks to their online documentation:\n\n``` yaml\nformat:\n html:\n code-link: true\n```\n\nCode linking is currently implemented only for the knitr engine (via the [downlit](https://downlit.r-lib.org) package).\nA limitation of downlit currently prevents code linking if `code-line-numbers` and/or `code-annotations` are also `true`.\n", "supporting": [ "html-code_files" ], diff --git a/_freeze/site_libs/quarto-listing/list.min.js b/_freeze/site_libs/quarto-listing/list.min.js index 81318815c9..511346fc10 100644 --- a/_freeze/site_libs/quarto-listing/list.min.js +++ b/_freeze/site_libs/quarto-listing/list.min.js @@ -1,2 +1,2 @@ -var List;List=function(){var t={"./src/add-async.js":function(t){t.exports=function(t){return function e(r,n,s){var i=r.splice(0,50);s=(s=s||[]).concat(t.add(i)),r.length>0?setTimeout((function(){e(r,n,s)}),1):(t.update(),n(s))}}},"./src/filter.js":function(t){t.exports=function(t){return t.handlers.filterStart=t.handlers.filterStart||[],t.handlers.filterComplete=t.handlers.filterComplete||[],function(e){if(t.trigger("filterStart"),t.i=1,t.reset.filter(),void 0===e)t.filtered=!1;else{t.filtered=!0;for(var r=t.items,n=0,s=r.length;nv.page,a=new g(t[s],void 0,n),v.items.push(a),r.push(a)}return v.update(),r}m(t.slice(0),e)}},this.show=function(t,e){return this.i=t,this.page=e,v.update(),v},this.remove=function(t,e,r){for(var n=0,s=0,i=v.items.length;s-1&&r.splice(n,1),v},this.trigger=function(t){for(var e=v.handlers[t].length;e--;)v.handlers[t][e](v);return v},this.reset={filter:function(){for(var t=v.items,e=t.length;e--;)t[e].filtered=!1;return v},search:function(){for(var t=v.items,e=t.length;e--;)t[e].found=!1;return v}},this.update=function(){var t=v.items,e=t.length;v.visibleItems=[],v.matchingItems=[],v.templater.clear();for(var r=0;r=v.i&&v.visibleItems.lengthe},innerWindow:function(t,e,r){return t>=e-r&&t<=e+r},dotted:function(t,e,r,n,s,i,a){return this.dottedLeft(t,e,r,n,s,i)||this.dottedRight(t,e,r,n,s,i,a)},dottedLeft:function(t,e,r,n,s,i){return e==r+1&&!this.innerWindow(e,s,i)&&!this.right(e,n)},dottedRight:function(t,e,r,n,s,i,a){return!t.items[a-1].values().dotted&&(e==n&&!this.innerWindow(e,s,i)&&!this.right(e,n))}};return function(e){var n=new i(t.listContainer.id,{listClass:e.paginationClass||"pagination",item:e.item||"
    • ",valueNames:["page","dotted"],searchClass:"pagination-search-that-is-not-supposed-to-exist",sortClass:"pagination-sort-that-is-not-supposed-to-exist"});s.bind(n.listContainer,"click",(function(e){var r=e.target||e.srcElement,n=t.utils.getAttribute(r,"data-page"),s=t.utils.getAttribute(r,"data-i");s&&t.show((s-1)*n+1,n)})),t.on("updated",(function(){r(n,e)})),r(n,e)}}},"./src/parse.js":function(t,e,r){t.exports=function(t){var e=r("./src/item.js")(t),n=function(r,n){for(var s=0,i=r.length;s0?setTimeout((function(){e(r,s)}),1):(t.update(),t.trigger("parseComplete"))};return t.handlers.parseComplete=t.handlers.parseComplete||[],function(){var e=function(t){for(var e=t.childNodes,r=[],n=0,s=e.length;n]/g.exec(t)){var e=document.createElement("tbody");return e.innerHTML=t,e.firstElementChild}if(-1!==t.indexOf("<")){var r=document.createElement("div");return r.innerHTML=t,r.firstElementChild}}},a=function(e,r,n){var s=void 0,i=function(e){for(var r=0,n=t.valueNames.length;r=1;)t.list.removeChild(t.list.firstChild)},function(){var r;if("function"!=typeof t.item){if(!(r="string"==typeof t.item?-1===t.item.indexOf("<")?document.getElementById(t.item):i(t.item):s()))throw new Error("The list needs to have at least one item on init otherwise you'll have to add a template.");r=n(r,t.valueNames),e=function(){return r.cloneNode(!0)}}else e=function(e){var r=t.item(e);return i(r)}}()};t.exports=function(t){return new e(t)}},"./src/utils/classes.js":function(t,e,r){var n=r("./src/utils/index-of.js"),s=/\s+/;Object.prototype.toString;function i(t){if(!t||!t.nodeType)throw new Error("A DOM element reference is required");this.el=t,this.list=t.classList}t.exports=function(t){return new i(t)},i.prototype.add=function(t){if(this.list)return this.list.add(t),this;var e=this.array();return~n(e,t)||e.push(t),this.el.className=e.join(" "),this},i.prototype.remove=function(t){if(this.list)return this.list.remove(t),this;var e=this.array(),r=n(e,t);return~r&&e.splice(r,1),this.el.className=e.join(" "),this},i.prototype.toggle=function(t,e){return this.list?(void 0!==e?e!==this.list.toggle(t,e)&&this.list.toggle(t):this.list.toggle(t),this):(void 0!==e?e?this.add(t):this.remove(t):this.has(t)?this.remove(t):this.add(t),this)},i.prototype.array=function(){var t=(this.el.getAttribute("class")||"").replace(/^\s+|\s+$/g,"").split(s);return""===t[0]&&t.shift(),t},i.prototype.has=i.prototype.contains=function(t){return this.list?this.list.contains(t):!!~n(this.array(),t)}},"./src/utils/events.js":function(t,e,r){var n=window.addEventListener?"addEventListener":"attachEvent",s=window.removeEventListener?"removeEventListener":"detachEvent",i="addEventListener"!==n?"on":"",a=r("./src/utils/to-array.js");e.bind=function(t,e,r,s){for(var o=0,l=(t=a(t)).length;o32)return!1;var a=n,o=function(){var t,r={};for(t=0;t=p;b--){var j=o[t.charAt(b-1)];if(C[b]=0===m?(C[b+1]<<1|1)&j:(C[b+1]<<1|1)&j|(v[b+1]|v[b])<<1|1|v[b+1],C[b]&d){var x=l(m,b-1);if(x<=u){if(u=x,!((c=b-1)>a))break;p=Math.max(1,2*a-c)}}}if(l(m+1,a)>u)break;v=C}return!(c<0)}},"./src/utils/get-attribute.js":function(t){t.exports=function(t,e){var r=t.getAttribute&&t.getAttribute(e)||null;if(!r)for(var n=t.attributes,s=n.length,i=0;i=48&&t<=57}function i(t,e){for(var i=(t+="").length,a=(e+="").length,o=0,l=0;o=i&&l=a?-1:l>=a&&o=i?1:i-a}i.caseInsensitive=i.i=function(t,e){return i((""+t).toLowerCase(),(""+e).toLowerCase())},Object.defineProperties(i,{alphabet:{get:function(){return e},set:function(t){r=[];var s=0;if(e=t)for(;s0?setTimeout((function(){e(r,n,s)}),1):(t.update(),n(s))}}},"./src/filter.js":function(t){t.exports=function(t){return t.handlers.filterStart=t.handlers.filterStart||[],t.handlers.filterComplete=t.handlers.filterComplete||[],function(e){if(t.trigger("filterStart"),t.i=1,t.reset.filter(),void 0===e)t.filtered=!1;else{t.filtered=!0;for(var r=t.items,n=0,s=r.length;nv.page,a=new g(t[s],void 0,n),v.items.push(a),r.push(a)}return v.update(),r}m(t.slice(0),e)}},this.show=function(t,e){return this.i=t,this.page=e,v.update(),v},this.remove=function(t,e,r){for(var n=0,s=0,i=v.items.length;s-1&&r.splice(n,1),v},this.trigger=function(t){for(var e=v.handlers[t].length;e--;)v.handlers[t][e](v);return v},this.reset={filter:function(){for(var t=v.items,e=t.length;e--;)t[e].filtered=!1;return v},search:function(){for(var t=v.items,e=t.length;e--;)t[e].found=!1;return v}},this.update=function(){var t=v.items,e=t.length;v.visibleItems=[],v.matchingItems=[],v.templater.clear();for(var r=0;r=v.i&&v.visibleItems.lengthe},innerWindow:function(t,e,r){return t>=e-r&&t<=e+r},dotted:function(t,e,r,n,s,i,a){return this.dottedLeft(t,e,r,n,s,i)||this.dottedRight(t,e,r,n,s,i,a)},dottedLeft:function(t,e,r,n,s,i){return e==r+1&&!this.innerWindow(e,s,i)&&!this.right(e,n)},dottedRight:function(t,e,r,n,s,i,a){return!t.items[a-1].values().dotted&&(e==n&&!this.innerWindow(e,s,i)&&!this.right(e,n))}};return function(e){var n=new i(t.listContainer.id,{listClass:e.paginationClass||"pagination",item:e.item||"
    • ",valueNames:["page","dotted"],searchClass:"pagination-search-that-is-not-supposed-to-exist",sortClass:"pagination-sort-that-is-not-supposed-to-exist"});s.bind(n.listContainer,"click",(function(e){var r=e.target||e.srcElement,n=t.utils.getAttribute(r,"data-page"),s=t.utils.getAttribute(r,"data-i");s&&t.show((s-1)*n+1,n)})),t.on("updated",(function(){r(n,e)})),r(n,e)}}},"./src/parse.js":function(t,e,r){t.exports=function(t){var e=r("./src/item.js")(t),n=function(r,n){for(var s=0,i=r.length;s0?setTimeout((function(){e(r,s)}),1):(t.update(),t.trigger("parseComplete"))};return t.handlers.parseComplete=t.handlers.parseComplete||[],function(){var e=function(t){for(var e=t.childNodes,r=[],n=0,s=e.length;n]/g.exec(t)){var e=document.createElement("tbody");return e.innerHTML=t,e.firstElementChild}if(-1!==t.indexOf("<")){var r=document.createElement("div");return r.innerHTML=t,r.firstElementChild}}},a=function(e,r,n){var s=void 0,i=function(e){for(var r=0,n=t.valueNames.length;r=1;)t.list.removeChild(t.list.firstChild)},function(){var r;if("function"!=typeof t.item){if(!(r="string"==typeof t.item?-1===t.item.indexOf("<")?document.getElementById(t.item):i(t.item):s()))throw new Error("The list needs to have at least one item on init otherwise you'll have to add a template.");r=n(r,t.valueNames),e=function(){return r.cloneNode(!0)}}else e=function(e){var r=t.item(e);return i(r)}}()};t.exports=function(t){return new e(t)}},"./src/utils/classes.js":function(t,e,r){var n=r("./src/utils/index-of.js"),s=/\s+/;Object.prototype.toString;function i(t){if(!t||!t.nodeType)throw new Error("A DOM element reference is required");this.el=t,this.list=t.classList}t.exports=function(t){return new i(t)},i.prototype.add=function(t){if(this.list)return this.list.add(t),this;var e=this.array();return~n(e,t)||e.push(t),this.el.className=e.join(" "),this},i.prototype.remove=function(t){if(this.list)return this.list.remove(t),this;var e=this.array(),r=n(e,t);return~r&&e.splice(r,1),this.el.className=e.join(" "),this},i.prototype.toggle=function(t,e){return this.list?(void 0!==e?e!==this.list.toggle(t,e)&&this.list.toggle(t):this.list.toggle(t),this):(void 0!==e?e?this.add(t):this.remove(t):this.has(t)?this.remove(t):this.add(t),this)},i.prototype.array=function(){var t=(this.el.getAttribute("class")||"").replace(/^\s+|\s+$/g,"").split(s);return""===t[0]&&t.shift(),t},i.prototype.has=i.prototype.contains=function(t){return this.list?this.list.contains(t):!!~n(this.array(),t)}},"./src/utils/events.js":function(t,e,r){var n=window.addEventListener?"addEventListener":"attachEvent",s=window.removeEventListener?"removeEventListener":"detachEvent",i="addEventListener"!==n?"on":"",a=r("./src/utils/to-array.js");e.bind=function(t,e,r,s){for(var o=0,l=(t=a(t)).length;o32)return!1;var a=n,o=function(){var t,r={};for(t=0;t=p;b--){var j=o[t.charAt(b-1)];if(C[b]=0===m?(C[b+1]<<1|1)&j:(C[b+1]<<1|1)&j|(v[b+1]|v[b])<<1|1|v[b+1],C[b]&d){var x=l(m,b-1);if(x<=u){if(u=x,!((c=b-1)>a))break;p=Math.max(1,2*a-c)}}}if(l(m+1,a)>u)break;v=C}return!(c<0)}},"./src/utils/get-attribute.js":function(t){t.exports=function(t,e){var r=t.getAttribute&&t.getAttribute(e)||null;if(!r)for(var n=t.attributes,s=n.length,i=0;i=48&&t<=57}function i(t,e){for(var i=(t+="").length,a=(e+="").length,o=0,l=0;o=i&&l=a?-1:l>=a&&o=i?1:i-a}i.caseInsensitive=i.i=function(t,e){return i((""+t).toLowerCase(),(""+e).toLowerCase())},Object.defineProperties(i,{alphabet:{get:function(){return e},set:function(t){r=[];var s=0;if(e=t)for(;s