Asides don't work in all the column widths?

[dense-set]

Description

Consider an aside in a .qmd file as follows:

First paragraph

...ending of second paragraph.[This is an aside.]{.aside}

Another paragraph begins...

I notice the following behaviours when the above (all three paragraphs) are enclosed as follows:

1. Within {.column-body-outset}, {.column-body-outset-left}, {.column-body-outset-right}: No change.

2. Within {.column-page}: The second paragraph "escapes" the {.column-page} whereas the rest is as expected.

Why these different behaviours?

[mcanouil]

Could you share a small self-contained "working" (reproducible) example to work with, i.e., a complete Quarto document or a Git repository? Thanks.

You can share a Quarto document using the following syntax, i.e., using more backticks than you have in your document (usually four ````).

````qmd
---
title: "Reproducible Quarto Document"
format: html
---

This is a reproducible Quarto document using `format: html`.
It is written in Markdown and contains embedded R code.
When you run the code, it will produce a plot.

```{r}
plot(cars)
```

The end.
````

[dense-set]

Psst! I just discovered that the autogenerated quarto.js in libs/quarto-html/ contains the following code that might be relevant to this (I don't know java, otherwise would've figured out myself):

// Find the first element that uses formatting in special columns
  const conflictingEls = window.document.body.querySelectorAll(
    '[class^="column-"], [class*=" column-"], aside, [class*="margin-caption"], [class*=" margin-caption"], [class*="margin-ref"], [class*=" margin-ref"]'
  );

  // Filter all the possibly conflicting elements into ones
  // the do conflict on the left or ride side
  const arrConflictingEls = Array.from(conflictingEls);
  const leftSideConflictEls = arrConflictingEls.filter((el) => {
    if (el.tagName === "ASIDE") {
      return false;
    }
    return Array.from(el.classList).find((className) => {
      return (
        className !== "column-body" &&
        className.startsWith("column-") &&
        !className.endsWith("right") &&
        !className.endsWith("container") &&
        className !== "column-margin"
      );
    });
  });
  const rightSideConflictEls = arrConflictingEls.filter((el) => {
    if (el.tagName === "ASIDE") {
      return true;
    }

    const hasMarginCaption = Array.from(el.classList).find((className) => {
      return className == "margin-caption";
    });
    if (hasMarginCaption) {
      return true;
    }

    return Array.from(el.classList).find((className) => {
      return (
        className !== "column-body" &&
        !className.endsWith("container") &&
        className.startsWith("column-") &&
        !className.endsWith("left")
      );
    });
  });

[mcanouil]

I now believe it's not a bug.
Where should the sidebar "aside" be if your content occupies 100% of the space?

If you simply want to increase body part and change the sidebar width, see https://quarto.org/docs/output-formats/page-layout.html#grid-customization.

[dense-set]

Fair enough.

A few things before I close this discussion:

1. Question: asides is a "Quarto-specific" class, not covered in Pandoc's markdown (even via extensions), correct?

2. A suggestion/request: Can the options above like aside (if any) that Quarto introduces out of the scope of Pandoc's markdown (and its extensions), be indicated in the Refrence? This raises in turn the last question below.

3. Question: Does the Reference in fact document all the such options?

[mcanouil]

1. Far as I know, yes.
2. "reference" pages are for options. aside is not a YAML option. It's for layout and is documented in https://quarto.org/docs/authoring/article-layout.html#asides
3. as for 2., "reference" pages are for options. aside is not an option. Also, references pages are not exhaustive, especially because other options are available through the engine, for example with knitr.

[dense-set]

So, the Reference pages contain exclusively (a subset of) YAML options, and nothing else, right?

[mcanouil]

For short, yes.

Long answer:
You don't have all the options from knitr.
Additionally, "every" options from Pandoc (YAML or CLI) can be passed within Quarto.
Quarto can't list/document all third parties/dependencies options.

[dense-set]

Got it. (I understand it'd be not possible to list all the options, but maybe referencing them would be very helpful to those looking for more control.)

[mcanouil]

Referencing all possible options from third parties/dependencies would mean to "watch" those, it's not something that is usually worth it (e.g. rmarkdown does not do that either, but it is also based on Pandoc).
In some aspects, it would be like asking if knitr documentation could list all R base functions.
Another example, Quarto uses Bootstrap, but does not list everything that is pretty well described in https://getbootstrap.com/.

Most users do not need that because it will clutter the documentation and make it really hard to see Quarto's feature.
Advanced users are aware that Quarto is based on Pandoc, thus tend to go to Pandoc documentation, etc.