Unclear where options stated succinctly in the documentation should actually go in YAML

[gavinsimpson]

What would you like to do?

Give feedback or suggest an improvement

Description

Consider this subsection https://quarto.org/docs/authoring/article-layout.html#margin-references in the documentation. It has the YAML required to turn on marginal footnotes and citations respectively.

---
reference-location: margin
citation-location: margin
---

Great! I found this pretty easily! However, it is not immediately clear where this has to actually go in the YAML. I use Quarto a lot (for a casual user with an academic day job) for a range of different document types, but not enough to know that in this case these are format options. After a process of trial and error I figure out where these should go, but, like a USB A cable, I never get it right first time, and that's because the option is given out of context. This is frustrating and confusing for the casual user encountering an option for the first time.

I don't know what the ideal solution to this is in general; you could include a little more context in the YAML snippets shown but there has to be a limit to what you can show otherwise the snippets will get overly long and the forest missed due to the trees. In this case, mentioning that this is a format option would have triggered my brain into knowing to try the correct (as it turns out) place the first time. Or it could have been

---
format:
  html:
    reference-location: margin
    citation-location: margin
---

for example.

I (personally) encounter this issue often with the otherwise excellent quarto documentation. As I said, I usually get there in the end. But, a little more context in the snippets would be very helpful throughout the documentation. Arguably, the snippet will never occur as it is shown in the documentation (I think this is true) because in any real document it would be indented at least 4(?) spaces because it would under a format option plus the specific document-format heading.

[cderv]

I will try to clarify the situation to be sure your feedback is context-aware of this.

Take this example

---
title: Margin Citations and References Demo
format: 
  html: default
  pdf: default
reference-location: margin
citation-location: margin
references:
- type: article-journal
  id: smith2020
  author:
  - family: Smith
    given: John
  - family: Johnson
    given: Mary
  issued:
    date-parts:
    - - 2020
      - 6
      - 15
  title: 'Data Analysis Methods in Modern Research'
  container-title: Journal of Data Science
  volume: 15
  issue: 3
  page: 123-145
  DOI: 10.1234/jds.2020.15.3.123
---

This document shows how `reference-location: margin` and `citation-location: margin` work in Quarto.

## Citation Location in Margins

When you set `citation-location: margin`, citations move to the margin. This research [@smith2020] demonstrates the concept clearly.

## Reference Location in Margins

The `reference-location: margin` option moves footnotes to the margin. Here's a footnote^[This footnote appears in the margin instead of at the bottom.] showing this feature.

## Combined Features

Academic writing benefits from both citations [@smith2020] and footnotes^[This note explains why margin layout improves readability.] in the margins for clean text flow.

If you render to HTML and PDF, in both cases, references and sitations will be in the margins. This is because

reference-location: margin
citation-location: margin

It is set globally at the top level. So it will be reused in both formats.

Now use this instead in the YAML

format: 
  html: 
    reference-location: margin
    citation-location: margin
  pdf: default

This will only use the margin for HTML output and not PDF. this is because the option is set only under one of the format.

Document code

---
title: Margin Citations and References Demo
format: 
  html: 
    reference-location: margin
    citation-location: margin
  pdf: default
references:
- type: article-journal
  id: smith2020
  author:
  - family: Smith
    given: John
  - family: Johnson
    given: Mary
  issued:
    date-parts:
    - - 2020
      - 6
      - 15
  title: 'Data Analysis Methods in Modern Research'
  container-title: Journal of Data Science
  volume: 15
  issue: 3
  page: 123-145
  DOI: 10.1234/jds.2020.15.3.123
---

This document shows how `reference-location: margin` and `citation-location: margin` work in Quarto.

## Citation Location in Margins

When you set `citation-location: margin`, citations move to the margin. This research [@smith2020] demonstrates the concept clearly.

## Reference Location in Margins

The `reference-location: margin` option moves footnotes to the margin. Here's a footnote^[This footnote appears in the margin instead of at the bottom.] showing this feature.

## Combined Features

Academic writing benefits from both citations [@smith2020] and footnotes^[This note explains why margin layout improves readability.] in the margins for clean text flow.

So in conclusion, options can be set

• Under format to apply on a specific format only
• Globally so that they apply on all formats.

Does it helps understand ?

[gavinsimpson]

Thanks for resplying @cderv

I should have perhaps then given more context myself (!); this is in a quarto book. Am I misunderstanding that I can't put reference-location: margin in my top level _quarto.yml. I'm getting a compilation error if I place this there:

project:
  type: book

book:
  title: "book title"
  author: "Gavin L. Simpson"
  date: last-modified
  chapters:
    - index.qmd
    - introduction.qmd
    - chapter1.qmd
    - references.qmd

execute:
  freeze: auto

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrbook

knitr:
  opts_chunk: 
    collapse: true
    comment: "#>"

reference-location: margin

[gavinsimpson]

Hmm, OK, something screwy was going on (perhaps the auto-rebuild on file change was too quick?), but if I do place this as per my example above, then the document does actually render properly, Apologies for the noise.

I've held off making this general comment partly because I've usually had a time crunch when I came across these things before in different areas of the documentation while prepping materials for class. Guess I picked the wrong one to finally have time to make the comment.