Aside component / multi-column content

[brianjenkins94]

The ability to augment the main body of content with aside content in an adjacent column. Ideally with some way to write this (in markdown or similar) so that the aside content could live in the same file and section as the body content.

Examples:

• https://stripe.com/docs/api/balance/balance_retrieve
• https://ricostacruz.com/flatdoc/#customizing-basic

---

I'd be willing to attempt to contribute this but I'm stuck on a few things:

• What should it look like to author this content? Would it be better to do it footnote-style so you can read/write/edit the main body content without the aside content disrupting it? Some sort of custom markdown syntax to provide both?

  Something like this would be cool:

  >>>
  
  Aside content here
  
  >>>

• How should it behave on a narrow screen? It should probably have the option to either collapse into the main column or hide.

• Is there a way to have it so it doesn't have to be locked to a section header or paragraph start and instead have it vertically centered and off to the side of where its associated key word or phrase lands in the text flow? But then it would also need to shift down so it didn't overlap earlier asides... nevermind, too complicated.

TL;DR: Feature Request^(?): Stripe-style API docs.

[shuding]

This is a good idea, I'm wondering if there's a proposal for this in the Markdown/MDX ecosystem for a new syntax like you mentioned. Otherwise, I'd stick with custom React component for this.

Another thing is it currently conflicts with the floating ToC design.

[brianjenkins94]

You can extend markdown syntax by way of Remark plugins, or so I've been told.

Looks like MDX offers some advice on this as well: https://mdxjs.com/docs/extending-mdx/

[shuding]

Yes, Nextra is already doing that. What I'm wondering is if there's any standard syntax, or a proposal for this use case, instead of inventing a new one.

[brianjenkins94]

Research:

In Markua, A> is used to represent an aside, with other letters combined with > representing different types of asides (e.g B> for blurb, W> for warning)."

• https://talk.commonmark.org/t/pipe-character-for-aside/2227/2

They discuss the fence syntax I suggested further down, noting it would conflict with triply nested blockquotes.

---

Here's another syntax:

The quick brown fox ^[Aside content here]

• https://community.rstudio.com/t/writing-a-side-note-on-r-markdown-html/43518/2

And that's actually all I could find.