requesting help to use/understand HTL + Markdown template literal (porting a notebook)

[aaronkyle]

I am trying porting @mootari 's Signature toolkit into Observable Framework (Markdown + HTL). The notebook relies heavily on the html and md template literals, which operates differently in Framework. I haven't found a way to get everything working and would appreciate any help and guidance to better understand and overcome the issues.

Here's a re-cap of things I've been learning and trying:

• Dynamic tag names not supported in HTL.

The original notebook uses constructs like:

const tag = open == null ? "div" : "details";
return html`<${tag}>${body}</${tag}>`;

In Framework this throws Error: invalid binding because HTL disallows interpolating tag names.

• Template literal escaping (md).

In Framework, the the (unsafe)^{[ref1],[ref2]} md template literal is interpreting fenced code. I changed the md helper to use strings.raw so that `${...}` survives literally, which seems to fix the Markdown/code fence issue.

• Function signature parsing (defaultSignatureParser).

The notebook extracts function signatures using:

const [prefix, mAsync, mFunc, mGen] =
  sig.match(/^(async\s*)?(function\s*)?(\*)?/);

In Framework, this returns TypeError: can't access property 0, r is undefined

I tried this by optional-chaining the regex match (const m = sig.match(...)). I also replaced suffix[0] with suffix.startsWith("(") to avoid indexing into an empty string. Still I am getting errors.

---

If you're interested, I can share my various hacks on the original notebook that reflect these changes... but I expect that they're not useful and that there's a more simple, elegant solution out there. Instead, here's a link to a more-or-less direct porting attempt that leaves off where I start experiencing issues.

Here's a copy on GitHub: https://github.com/aaronkyle/categorise/blob/master/src/signature.md?plain=1

And here's a (temporary) link to the deployed notebook: https://categorise.observablehq.cloud/categorise/signature

Can anyone help me to identify how best to get this notebook working in Framework? Any guidance or working examples would be hugely appreciated. 🙏

[mbostock]

To answer your first question, you could use this technique:

return open == null ? html`<div>${body}</div>` : html`<details>${body}</details>`;

On your defaultSignatureParser question, I don’t see why that wouldn’t work as-is in any vanilla JavaScript environment. It seems to work fine in Notebooks 2.0. Perhaps the error is somewhere else.

[aaronkyle]

Thank you. That seems to have done the trick. I was indeed chasing down solutions to errors that I wouldn't have encountered had I started looking in the correct place.

I revised this:

function defaultFormatter({signature, description, examples, testList}, {name, open, scope, css}) {
  return html`<${open == null ? 'div' : `details ${open ? 'open' : ''}`} class="${scope}">${[
    !css ? '' : scope == null ? css : scopedStyle('.' + scope, css),
    html`<${open == null ? 'div' : 'summary'} class=signature>${signature}${
!name || !name.length ? '' : html`<a class=link href="#${name}">`
}`,
    description == null ? '' : html`<div class=description>${description}`,
    !examples.length ? '' : html`<div class=examples>${[
      examples.length < 2 ? md`Example:` : md`Examples:`,
      ...examples
    ]}`,
    testList || '',
  ]}`;
}

To this:

function defaultFormatter({signature, description, examples, testList}, {name, open, scope, css}) {
  const header =
    open == null
      ? html`<div class=signature>${signature}${!name || !name.length ? '' : html`<a class=link href="#${name}">`}`
      : html`<summary class=signature>${signature}${!name || !name.length ? '' : html`<a class=link href="#${name}">`}`;

  const body = [
    !css ? '' : scope == null ? css : scopedStyle('.' + scope, css),
    header,
    description == null ? '' : html`<div class=description>${description}`,
    !examples.length ? '' : html`<div class=examples>${[
      examples.length < 2 ? md`Example:` : md`Examples:`,
      ...examples
    ]}`,
    testList || '',
  ];

  return open == null
    ? html`<div class="${scope}">${body}`
    : html`<details class="${scope}" ?open=${open}>${body}`;
}

Which appears to have done the trick. The working version is deployed to the same links as above. I welcome any and all further suggestions for improvement! 🙏

Thank you for helping me out! ❤️

[mootari]

@aaronkyle I'm happy to hear that you find Signature useful, but please don't republish copied or ported code without including attribution.

[aaronkyle]

Hi @mootari - I apologize and thank you for reminding me. I will take better care in the future. Here's a link to demonstrate corrections.

[mootari]

Thank you. I've also republished the notebook under the ISC license to make redistribution easier, because technically Observable's implicit proprietary license under which it was published doesn't allow you to share the code outside of observablehq.com.

[aaronkyle]

Yikes! Thank you for pointing this out. I will reach out to Tom about his and check others!

…

On Sun, Sep 14, 2025, 1:24 PM Fabian Iwand ***@***.***> wrote: Thank you. I've also republished the notebook under the ISC license to make redistribution easier, because technically Observable's implicit proprietary license that it was published under doesn't allow you to share the code outside of observablehq.com. — Reply to this email directly, view it on GitHub <#2026 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARR56UTMONUHEC7WIVPUIL3SWQDJAVCNFSM6AAAAACGJIKUQ2VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTIMZZG42DCMI> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>