Document conventions for internal links in `quarto-web`

[cwickham]

@mcanouil did some great work improving the consistency of our internal links on quarto.org (fixing some broken ones in the process).

Below you'll find some draft recommendations for the conventions followed for these links. We need to:

1. Discuss and agree on these recommendations
2. Document them (I propose in the quarto-web README for now)

Link Recommendations

• Use relative paths for child or sibling documents. E.g. images/fig-1.png, pdf-basics.qmd
• Prefer absolute paths from the root of the project over relative paths involving ../. E.g. use /docs/output-formats/html-themes.qmd, not ../output-formats/html-themes.qmd.
  • Possible exception: documents in a subfolder of a section that link to the section root, e.g. you may use ../index.qmd to refer to docs/manuscripts/index.qmd from docs/manuscripts/authoring/index.qmd.
• Use .qmd instead of .html. E.g. use content.qmd#editing-tables, not content.html#editing-tables
  • Possible exception: links in blog posts

[mcanouil]

Some rational:

• html to qmd: long run change to allow in the future to have Quarto documentation as a PDF (feature request by many users). Having qmd reference, will avoid issues.
  • Since the blog posts won't be part of the "manual" and because of the "pre-release" content, using html links makes sense (with aliases later on), thus a possible exception.
• Avoid the use of https://quarto.org/ for any links: in Netlify preview, the links won't target the preview, but will target the original website. Domain/Apex is set in site-url, so there is no reason to add it in internal links.