lamenting the things we can't echo

[declann]

Hi!

Observable Framework is an awesome tool. I already think I'll be using it a lot to develop with calculang: for which local tools are better (& thanks for the file-over-app pointer!) and fast reactive and visual patterns are an important sidekick in the development/exploratory process. Maybe a show and tell about that soon.

I like a lot the self-documenting power of Notebooks. Framework is a different thing, but echo seems like a helpful nod to that.

I filed #833 for collapsible echos that I like to pair with my main outputs (I often publish with Quarto which has this well covered - if not Observable Notebooks where it's a non-issue).

However, I realise echo won't actually work in many places: when outputs are interpolated into Markdown, or where laid out across HTML divs to make a dashboard. But I think echo (collapsible) for dashboard cards and for Markdown text can be very useful.

It might be that a few details make wider echo tricky. The html block separation rule (entirely implicit?) might point to one issue. Markdown interpolation opens a question about what exactly to echo, and it may also look like a different thing for a user to interpret.

Of course it's possible to simply publish a complete file(!), and I haven't tried it but I guess that echo for data processing steps is covered already.

So I wonder will there be an interest or a plan to add wider echoing - or if this type of documenting completeness will remain for the Notebook world?

Cheers!
Declan

[Fil]

By "simply publish a complete file" do you mean sharing the actual .md source? If so it's currently possible in many ways, for example simply by creating a <a href="page.md" download>view source</a> button, or a system that loads the page as a FileAttachment and passes it to highlight.js. But in most cases I think that the best way to make a project "transparent" will be a link to a repo.

example code using highlight.js to display a code dependency (components/marimekko.js):

```js
import  hljs from "npm:highlight.js";
```

```js
const code = await FileAttachment("components/marimekko.js").text();
const div = display(document.createElement("pre"));
div.innerHTML = hljs.highlight(code, {language: "js"}).value;
```

[declann]

Thanks for the hljs tip! Developing a custom workaround is also an option for what I'd like to provide; I may use that.
I think expanded echo can add to Framework generally though.

Yes, we have flexibility to publish the entire file and I'm all in favor of features like view source buttons and repo links (I think the link in your comment is broken though?).

Notebooks let you see the code in-context behind any cell, and the granularity and context is also useful.

echo only works for fenced code blocks in Framework. It isn't an option for code in dashboard cards and in interpolated markdown. Perhaps I'll file an enhancement Issue?

Fwiw, Quarto provides options for source code into HTML documents and also folding (collapsing) so that it appears discrete almost like a notebook.

[Fil]

the link in your comment is broken

ha, it was meant to be escaped, sorry.

[Fil]

here's what I'm using currently:

function showCode(file, language = file.name.match(/\.(\w+)$/)?.[1]) {
  const div = document.createElement("details");
  div.innerHTML = `
    <summary>code</summary>
    <div class="observablehq-pre-container" data-language=${language}>
      <pre>loading ${file.name}…</pre>
    </div>`;
  file.text().then((code) => (div.querySelector("pre").innerHTML = hljs.highlight(code, {language}).value));
  return div;
}

display(showCode(FileAttachment("myfile.ts")));

[mbostock]

Maybe a technique would be to pull your HTML up to top-level variables inside blocks that can be echoed, but interpolate them elsewhere. As a trivial example:

```js echo
const hello = html`<b>Hello, world!</b>`;
```

And now I would like to say, ${hello}

So, the hello is initially declared detached inside an echo code block so the implementation is visible. But then you can insert it anywhere into the page using ${hello}.

[declann]

Hi guys,

Thanks for the suggestions!

Here's a sample page I'm working on now:

https://declann.observablehq.cloud/calculang-dx-pattern-exampling/graphing-calcs/tixy-land

It's a dashboard with formulas on the left and visuals which interact with the formulas on the right. I want to also show the code for the visuals which interact with the formulas.

I'm showing that at the bottom - like suggested by Mike, labeled "appendix" which is workable for now - but I think a little disjointed and would be much neater and clearer collapsed into html details blocks beside the individual visuals.

I'm probably moving the gallery at calculang.dev over to this, and then this will be important to me so I'll generate or move blocks like @Fil suggests using JS or else do pre-processing of .md files: hacks that are fine for this usecase.

But I think this is a generally useful presentation to make available for dashboards.

So perhaps I'll make a feature request after I have some experience doing this. The core ability to surface code using echo is there and workable per Mike and per link - so it's not a critical thing, but maybe nice to have.

However, there are definitely Framework-specific things like how to infer the connection between code blocks and placement in dashboard which might be hard to address in a general way.

[declann]

We can't echo inline JS but we can echo JS blocks, and we can put them anywhere now thanks to CommonMark compatibility in 1.1.

So this "lament" was short-lived!

My workaround for collapsible code blocks then becomes simple (just wrap observablehq-pre-container class elements in a details tag) and works as a proof of concept here.

gif of collapsible code blocks attached to content (sorry for no cursor).

I'll post collapsible details to #833