Merge pull request #1031 from mcanouil/fix/internal-ref-qmd

refactor: harmonise and fix broken internal links
quarto-dev · Mar 15, 2024 · ae8c4ff · ae8c4ff
2 parents 112bb82 + 2085e9b
commit ae8c4ff
Show file tree

Hide file tree

Showing 155 changed files with 469 additions and 504 deletions.
diff --git a/_freeze/docs/authoring/tables/execute-results/html.json b/_freeze/docs/authoring/tables/execute-results/html.json
diff --git a/_freeze/docs/computations/execution-options/execute-results/html.json b/_freeze/docs/computations/execution-options/execute-results/html.json
diff --git a/_freeze/docs/output-formats/html-code/execute-results/html.json b/_freeze/docs/output-formats/html-code/execute-results/html.json
diff --git a/_freeze/site_libs/quarto-listing/list.min.js b/_freeze/site_libs/quarto-listing/list.min.js
diff --git 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
 
@@ -23,7 +23,7 @@ At the core of Quarto is [Pandoc](https://pandoc.org), a powerful and flexible d
 
 2.  A variety of extensions to Pandoc markdown useful for technical writing including cross-references, sub-figures, layout panels, hoverable citations and footnotes, callouts, and more.
 
-3.  A project system for rendering groups of documents at once, sharing options across documents, and producing aggregate output like [websites](docs/websites/website-basics.qmd) and [books](docs/books/book-basics.qmd).
+3.  A project system for rendering groups of documents at once, sharing options across documents, and producing aggregate output like [websites](/docs/websites/website-basics.qmd) and [books](/docs/books/book-basics.qmd).
 
 Development of Quarto is sponsored by [Posit, PBC](https://www.posit.co), where we previously created a similar system ([R Markdown](https://rmarkdown.rstudio.com/)) that shared the same goals, but was targeted principally at users of the R language. The same core team works on both Quarto and R Markdown:
 

diff --git a/docs/_require-1.4.qmd b/docs/_require-1.4.qmd
@@ -1,5 +1,5 @@
 ::: {.callout-note}
 ## Quarto 1.4 Feature
 
-This feature is new in Quarto 1.4. Download the latest version of Quarto at <https://quarto.org/docs/download/>.
-:::
+This feature is new in Quarto 1.4. Download the latest version of Quarto at the [download page](/docs/download/index.qmd)
+:::
diff --git 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,12 +100,12 @@ 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.qmd#css-styles) containing:
 
 ```css
 :root {
   --mermaid-node-bg-color: #375a7f;
 }
 ```
 
-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).
+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/callouts.qmd b/docs/authoring/callouts.qmd
@@ -164,4 +164,4 @@ When the target format doesn't support callouts, they are rendered as a simple b
 
 {{< include _cross-references-callouts.qmd >}}
 
-Cross-referencing callouts is currently only supported for HTML, PDF and MS Word.
+Cross-referencing callouts is currently only supported for HTML, PDF and MS Word.
diff --git 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
 | <sub>Document `date` will be used if not provided.</sub>                                                                                      |                                                                                         |
 +-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 | `url`\                                                                                                                                        | `citation_fulltext_html_url`                                                            |
-| <sub>`url` will be synthesized for current document if a [`site-url`](../websites/website-tools.qmd#preview-images) has been specified.</sub> |                                                                                         |
+| <sub>`url` will be synthesized for current document if a [`site-url`](/docs/websites/website-tools.qmd#preview-images) has been specified.</sub> |                                                                                         |
 +-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+
 | `pdf-url`                                                                                                                                     | `citation_pdf_url`                                                                      |
 +-----------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+

diff --git 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.
+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
@@ -238,7 +238,7 @@ When the output is a figure or table, you can reference the code and the output
 
 ::: callout-note
 
-When your sub-content is either all figures or all tables there is abbreviated syntax, see the Cross References page for [Subfigures](cross-references.html#subfigures) and [Subtables](cross-references.html#subtables) for details.
+When your sub-content is either all figures or all tables there is abbreviated syntax, see the Cross References page for [Subfigures](cross-references.qmd#subfigures) and [Subtables](cross-references.qmd#subtables) for details.
 
 :::
 
@@ -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.qmd#inline-code). For example:
 
 :::: {.panel-tabset}
 
@@ -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
@@ -22,7 +22,7 @@ This results in the following treatment for various output types:
 |---------------------------|-----------------------|-----------------------|
 | ![](images/html-figure.png){fig-alt="A line drawing of an elephant." width="340"} | ![](images/pdf-figure.png){fig-alt="A line drawing of an elephant."} | ![](images/word-figure.png){fig-alt="A line drawing of an elephant."} |
 
-Note that for LaTeX / PDF output figures are automatically numbered (you can arrange for figures to be numbered in other formats using [Cross References](cross-references.html)).
+Note that for LaTeX / PDF output figures are automatically numbered (you can arrange for figures to be numbered in other formats using [Cross References](cross-references.qmd)).
 
 ### Figure Sizing
 
@@ -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
@@ -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/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/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
 <table data-quarto-disable-processing="true">
   ...
 </table>
-```
+```
diff --git 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
@@ -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
@@ -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/2022-10-25-shinylive-extension/index.qmd b/docs/blog/posts/2022-10-25-shinylive-extension/index.qmd
@@ -12,10 +12,9 @@ image: shinylive-embedded-app.png
 image-alt: "Screenshot of a Quarto document with an embedded Shinylive application."
 ---
 
-
 The new [Shinylive Quarto extension](https://github.com/quarto-ext/shinylive) makes it easy to embed Shiny for Python applications in your Quarto documents. This makes it possible to add interactivity to your documents with just Python code. For example, you can include an interactive Shiny application like this, directly inside your Quarto document.
 
-[![](shinylive-embedded-app.png){.preview-image fig-align="center" fig-alt="Shinylive appplication embedded in a Quarto document."}](https://quarto-ext.github.io/shinylive/sine.html)
+[![](shinylive-embedded-app.png){.preview-image fig-align="center" fig-alt="Shinylive application embedded in a Quarto document."}](https://quarto-ext.github.io/shinylive/sine.html)
 
 In case you're not already familiar with Shiny, here's some background: [Shiny](https://shiny.rstudio.com/) is a framework for creating web applications. Shiny was originally just for R, but we've recently released an alpha version of [Shiny for Python](https://shiny.rstudio.com/py/).
 
@@ -26,6 +25,3 @@ The Shiny for Python [website](https://shiny.rstudio.com/py/) contains many inte
 Bear in mind that not all Shiny applications can be deployed with Shinylive, in part because not all Python packages can run in WebAssembly -- but for those that can, this extension makes it possible to deploy the Quarto document with the embedded application on any web hosting service. To learn more about Shinylive, see [this page](https://shiny.rstudio.com/py/docs/shinylive.html).
 
 The new Shinylive Quarto extension makes it easy to embed Shiny for Python applications in Quarto documents. This is a great way of adding interactive components to your Quarto document. And, once again, you don't need a server running Python to share these Quarto documents -- just deploy the generated files as you would for any other Quarto website.
-
-
-
diff --git 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/authoring/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
@@ -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/output-formats/html-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
@@ -35,4 +35,4 @@ Managing Confluence content with Quarto allows you to author content in Markdown
 
 <!-- Quick overview of key features: new format and project type, local preview, `quarto publish confluence`. -->
 
-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/publishing/confluence.qmd) of the pre-release highlights to learn more.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -164,4 +164,4 @@ When the target format doesn't support callouts, they are rendered as a simple b

		{{< include _cross-references-callouts.qmd >}}

		Cross-referencing callouts is currently only supported for HTML, PDF and MS Word.
		Cross-referencing callouts is currently only supported for HTML, PDF and MS Word.
-Original file line number
+Diff line change
@@ Expand Up / @@ -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
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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/output-formats/html-multi-format.qmd) of the pre-release highlights.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -35,4 +35,4 @@ Managing Confluence content with Quarto allows you to author content in Markdown

		<!-- Quick overview of key features: new format and project type, local preview, `quarto publish confluence`. -->

		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/publishing/confluence.qmd) of the pre-release highlights to learn more.