chunk option to include link to src for ojs imports

[zac-garland]

is there a way to include the ojs src link post-import?

//| include_source: true
//| source_caption: 'caption'
import {ToolsImage} from "@observablehq/state-of-dataviz-2021"
ToolsImage

resulting in something like

//| quasi-engine: pug
.code-src
   a(href='obs/...') caption

[jjallaire]

@cscheid Is this something that's possible?

[cscheid]

We have full control over the generated content, so I'm pretty sure we could do "it". Except that I don't quite understand what @zac-garland wants 😬 Zac, can you please post a minimal .qmd file that shows what you're looking to do? I'll be happy to work with you on something, assuming @jjallaire is ok with the feature.

[zac-garland]

@cscheid of course! I'm open on how this might look for multiple imports or references, but the basic idea is something similar to the below.

Where you'd have the chunk option to include the source in the markup

//| include_ojs_source: true
import {ToolsImage} from "@observablehq/state-of-dataviz-2021"
ToolsImage

An example src link format:

// example format function for sources

ojsSourceLink = function (ojsName, ojsLink, ojsCaption) {
  return html`
    <span>
      <code>${ojsName}</code> imported from
      <a href="https://observablehq.com/${ojsLink}" target="_blank"
        >${typeof ojsCaption === "undefined" || ojsCaption === null
          ? ojsLink
          : ojsCaption}
      </a>
    </span>
  `;
};

Where the below chunk would be run automatically (based on chunk options specified)

ojsSourceLink("ToolsImage", "@observablehq/state-of-dataviz-2021");

If we expanded the idea to code references as a whole, (quarto, r, julia, etc.) it might be a cool way to delineate between code sources vs. research citations, though I realize the addition of multiple languages would make the inclusion logic more complex.

Does the above make sense or are there alternative ways to think about it?

[cscheid]

Thanks, I think I get it now. You're looking for an automatic way to add attribution back to the observablehq source - is that right?

If so, we should definitely be able to come up with something.

Just to set expectations here: I want to make sure this plays nicely with the rest of Quarto and how references are handled, so it's not going to be a one-afternoon feature.

I think something like this is a little closer to our style:

//| ojs-citation:
//|   source: @observablehq/state-of-dataviz-2021
//|   variable: ToolsImage

@jjallaire I imagine the schema for this would be a maybeArrayOf, so people can give either a single citation or multiples.

The next question, then, is how we should actually render this. @jjallaire I think Charles is the one who knows the most about our content generation for this stuff. I'll ask him about this at some point this week.

[zac-garland]

Thanks, I think I get it now. You're looking for an automatic way to add attribution back to the observablehq source - is that right?

Exactly! Automatic attribution that's based on existing quarto reference handling.

[jjallaire]

I think we'd probably want to treat this like a figure caption where the caption text is automatically generated by the import.

[cscheid]

That seems sensible. I'll add to my list and will report back here.

[cscheid]

Unfortunately, I now don't think we want to implement this directly, because it turns out to be trickier than it looks.

Consider the following ojs block, with the syntax I think we would want:

```{ojs}
//| echo: false
//| ojs-cite-imports: true
import { hanon01 } from "@cscheid/hanon-01-diagrams-for-chapman-stick";

{
    const result = hanon01;
    result.style.maxWidth = "100%";
    return result;
}
```

This would synthesize a caption that said "hanon01 imported from @cscheid/...".

The problem with a smart API: multiple cells and multiple captions

The problem arises from the way that observablehq's runtime handles imports and how we handle multiple-statement blocks. To observable's runtime, there are two cells, one with the import statement and one with the tweaking of the style. The problem is where and how to synthesize the caption. We believe that OJS, for the most part, will be rendered with echo: false (like you did above).

As a result, the import cell is invisible. So we need to attach a caption to the cell that uses the import, not the cell with the import statement, otherwise the caption ends up in a weird spot. But in order to know which of the variables uses an observable import, we'd have to do a global static analysis pass over the ojs source, since the use is usually indirect.

A simpler API is not worth the notational weight

We could do it with a simpler API:

```{ojs}
//| echo: false
import { hanon01 } from "@cscheid/hanon-01-diagrams-for-chapman-stick";
```

```{ojs}
//| echo: false
//| ojs-import-variable: hanon01
//| ojs-import-notebook: @cscheid/hanon-01-diagrams-for-chapman-stick
{
    const result = hanon01;
    result.style.maxWidth = "100%";
    return result;
}
```

In this API, we just use ojs-import-variable and ojs-import-notebook to synthesize the caption. But I think this is not worth it, because the non-API alternative is

```{ojs}
//| echo: false
import { hanon01 } from "@cscheid/hanon-01-diagrams-for-chapman-stick";
```

```{ojs}
//| echo: false
//| fig-cap: `hanon01` imported from [@cscheid/hanon-01-diagrams-for-chapman-stick](https://observablehq.com/@cscheid/hanon-01-diagrams-for-chapman-stick)
{
    const result = hanon01;
    result.style.maxWidth = "100%";
    return result;
}
```

This is wordy, but it's not that much worse than the simple API, and it's much clearer what's going on, and it's easier to create more complicated captions.

New proposal: create a citation

I think something like this is workable:

```{ojs}
//| ojs-import-citation: auto
import { hanon01 } from "@cscheid/hanon-01-diagrams-for-chapman-stick";
```

This tells our engine to analyze those cells for import statements explicitly, and then to create an actual pandoc citation (in this case with id @cscheid/hanon-01-diagrams-for-chapman-stick, since we said auto). This is a local, much simpler analysis. At render time, we go to observablehq and grab author metadata, etc.

After that is defined, you can use the citation id in markdown, in captions, or wherever you want, as a typical Quarto doc. I think this plays better with the rest of the quarto tooling, so that's what we're going to implement.

[cscheid]

Tracking this on https://github.com/quarto-dev/quarto-cli/tree/feature/observable-citation.

Merging this will have to wait for the design of our "citation synthesis" API, so it's unlikely to land before 1.0