Use <code> blocks instead of interpolated strings in Markdown backing files

[dleeftink]

Currently, fenced codeblocks and HTML can be mixed. However, rendering these markdown 'backing files' produces inconsistent results. For instance, see https://github.com/dleeftink/observable-codespace/blob/main/basic-template/docs/example-dashboard.md for how these backing files render on GitHub.

To streamline how code blocks are rendered in markdown backing files, I propose one of the following:

1 : HTML <code> blocks

First, users can write fenced codeblocks of scripts they might need:

```js 
const launches = FileAttachment("data/launches.csv").csv({typed: true});
```

```js
const color = Plot.scale({
  color: {
    type: "categorical",
    domain: d3.groupSort(launches, (D) => -D.length, (d) => d.state).filter((d) => d !== "Other"),
    unknown: "var(--theme-foreground-muted)"
  }
});
```

Here, the top-level variable becomes the code blocks name (current functionality). However, unnamed/downstream reactive <code> blocks may be written like so:

<div class="grid grid-cols-4">
  <div class="card">
    <h2>🇺🇸</h2>
    <span class="big">
      <code>launches.filter((d) => d.stateId ==="US").length.toLocaleString("en-US")</code>
    </span>
  </div>
  <div class="card">
    <h2>🇷🇺</h2>
    <span class="big">
      <code>launches.filter((d) => d.stateId === "SU" || d.stateId ==="RU").length.toLocaleString("en-US")</code>
    </span>
  </div>
</div>

Rendering like so:

🇺🇸

launches.filter((d) => d.stateId ==="US").length.toLocaleString("en-US")

🇷🇺

launches.filter((d) => d.stateId === "SU" || d.stateId ==="RU").length.toLocaleString("en-US")

2 : Overloading Markdown tables

Another approach would be using a markdown table with references to named codeblocks:

``` js
const us_card = launches.filter((d) => d.stateId === "US").length.toLocaleString("en-US")
```

``` js
const ru_card = launches.filter((d) => d.stateId === "SU" || d.stateId === "RU").length.toLocaleString("en-US")
```

And defining columnar layouts like so:

|   col_1   |   col_2   |
|-----------|-----------|
| `us_card` | `ru_card` |

Rendering as follows:

col_1	col_2
us_card	ru_card

This table would then get replaced in the static pages with a div based layout. Additional HTML might be added in a similar fashion, or wrapping the inline code blocks.

3 : Multi-column markdown

I will not copy the spec here, as the Obsidian Plugin page does a good job at explaining it. Similar to solution 2, this involves naming codeblocks and ordering your references into a desired layout. However, this format is not widely supported outside of Obsidian.

Summary

Proposal 1 and 2 allow for better rendering of markdown backing files in places like Obisidian and GitHub, making it easier to distinguish code and prose while keeping to 'the spirit' of the spec. I welcome any other suggestions on how to improve legibility of markdown backing files.

[mbostock]

Thanks for the feedback, @dleeftink.

We don’t have any current plans to change the spec, with one exception: we will likely switch to {{…}} for interpolation from ${…} as described in #597 (mainly for better syntax highlighting in VS Code because {{…}} is a more popular convention). We also considered Quarto-like inline code syntax but I find the `{js} …` syntax to be more awkward than {{…}}, and we have no plans to support inline code expressions in any language other than JavaScript so typing {js} to denote live code felt burdensome. Though maybe if we have server-side rendering that could change…

In particular I would be opposed to changing the meaning of HTML tags to be reactive. I consider HTML a lower-level representation than Markdown, so while I’m comfortable overloading the meaning of fenced code blocks to be reactive (which you can opt-out of with run=false), I wouldn’t want us to ever change the meaning of HTML.

It’s already the case that you can interpolate inline expressions into Markdown tables (though there are limitations, like you can interpolate into a table cell, but you can’t interpolate an entire table row), like so:

| one              | two      |
|------------------|----------|
| ${Math.random()} | ${1 + 2} |

Which looks like this:

So, you can declare a chart top-level variable and then interpolate it into a Markdown table, for example. If you want to avoid complex inline code expressions you could use that technique to improve the readability of your pages in generic Markdown renderers.

I’m going to close this issue because we won’t be implementing your proposed changes, but I appreciate you taking the time to write it up and share your suggestions! 🙏 Please continue to share your thoughts.