Interactive Components in Markdown

Recently I implemented a Calendar and it turned out so well I wanted to document the approach and share it with the wider audience. And I really wanted to have an actual testable result of my work right there in the article.

I've been tweaking my website for a while now and this idea kick started the next iteration. And ultimately led to yet another full rebuild, but this story is not about my battle with perfectionism. It's about turning this:

HTML comes with a lot of ready to use and flexible elements, but date selector
has a handful of limitations and the need to write your own calendar / date
input emerges sooner rather than later. In this tutorial I'll walk you through
implementing a calendar view and show how you can extend its functionality to fit
your booking widget or dashboard filter.

Here's how the final result might look like:

<!--render:custom-calendar-component/CalendarExample.ssi.tsx-->

Into this:

Setup

My website is running on Deno and uses Hono and Hono/JSX since recently, but the approach works with any JS-based runtime and JSX.

Blog posts, as you've already noticed, are markdown files with attributes which are converted to static HTML on build using Marked and Front Matter.

After a bit of back and forth I've settled on this workflow:

• I write article in markdown
• I create a JSX component in the same folder as the article
• I "import" the component in markdown using HTML comment
• It magically works

The comment would need some sort of prefix, e.g. render and basically just a path to this component:

<!--render:custom-calendar-component/CalendarExample.ssi.tsx-->

One could also add props after path, but for my use case it wasn't needed so I skipped that part.

Rendering HTML

Before we can hydrate anything on the browser we need to render HTML from JSX component. To do so I we "just" need to override HTML rendering logic using custom Renderer:

export default class Renderer extends Marked.Renderer {
  constructor(private baseUrl: string, options?: Marked.marked.MarkedOptions) {
    super(options);
  }

  override html(html: string): string {
    const ssiMatch = /<!--render:(.+)-->/.exec(html);
    if (ssiMatch?.length) {
      const filename = ssiMatch[1];
      const ssi = SSIComponents.get(filename);
      if (!ssi) return html;
      const content = render(createElement(ssi.Component, {}));
      return [
        content,
        `<script type="module" src="${ssi.script}"></script>`,
      ].join("");
    }
    return html;
  }
}

Logic is quite straightforward: check if html string matches /<!--render:(.+)-->/ and then render JSX. Easy-peasy, if you have the component at hand that is.

Compiling components

My blog content is statically generated so naturally I've went for the same approach:

• Scan the content folder for *.ssi.tsx components (hence the suffix)
• Create a file that would import them and add to a Map so that I can easily retrieve them by th path

Here's how my build script looks like:

const rawContent = await readDir("./content");
const content: Record<string, Article> = {};
const ssi: Array<string> = [];

for (const pathname in rawContent) {
  if (pathname.endsWith(".ssi.tsx")) {
    ssi.push(pathname);
    continue;
  }
}

const scripts = await compileSSI(ssi.map((name) => `./content/${name}`));

const ssiContents = `
import type { FC } from 'hono/jsx';
const SSIComponents = new Map<string,{ Component: FC, script: string }>();
${
  scripts
    ? ssi
        .map(
          (pathname, i) =>
            `SSIComponents.set("${pathname}", { Component: (await import("./${pathname}")).default, script: "${scripts[i]}" })`
        )
        .join("\n")
    : ""
}
export default SSIComponents;
`;

await Deno.writeFile("./content/ssi.ts", new TextEncoder().encode(ssiContents));

Don't get too attached to Deno specific functions, it can be easily rewritten with node or anything else.

The magic is in writing a text file that resembles JavaScript code.

This script:

const ssiContents = `
import type { FC } from 'hono/jsx';
const SSIComponents = new Map<string,{ Component: FC, script: string }>();
${
  scripts
    ? ssi
        .map(
          (pathname, i) =>
            `SSIComponents.set("${pathname}", { Component: (await import("./${pathname}")).default, script: "${scripts[i]}" })`
        )
        .join("\n")
    : ""
}
export default SSIComponents;
`;

Returns a string like this:

import type { FC } from 'hono/jsx';
const SSIComponents = new Map<string,{ Component: FC, script: string }>();
SSIComponents.set("custom-calendar-component/CalendarExample.ssi.tsx", { Component: (await import("./custom-calendar-component/CalendarExample.ssi.tsx")).default, script: "/content/custom-calendar-component/CalendarExample.ssi.js" })
export default SSIComponents;

Which then can be imported and used in the Renderer :)

Code that writes the code! Magic! And no AI have been hurt in process: just your old school metaprogramming.

And finally, the last piece of the puzzle is hydrating the component on the frontend. I used esbuild for it, but personally I'm planning to switch it to Vite or anything else that comes with HMR.

Nonetheless, here's how it looks like:

import * as esbuild from "esbuild";
import { denoPlugins } from "jsr:@luca/esbuild-deno-loader";

export default async function compileSSI(
  filenames: string[]
): Promise<string[] | undefined> {
  await esbuild.build({
    plugins: [...denoPlugins()],
    entryPoints: ["./features/example.ssi.ts", ...filenames],
    bundle: true,
    write: true,
    outdir: "./static",
    minify: true,
    format: "esm",
    tsconfig: "./ssi-tsconfig.json",
    sourcemap: "external",
  });

  return filenames.map((name) => name.slice(1).replace(/\.tsx$/, ".js"));
}

You can notice a dummy entry point which has zero value, but forces esbuild to create files in their own folders and have predictable paths.

And ssi-tsconfig.json is pretty generic:

{
  "compilerOptions": {
    "target": "es2020",
    "module": "ES6",
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx"
  }
}

As of actual frontend hydration I chose the easy way and just added this at the bottom of my .ssi.tsx file:

if (typeof document !== "undefined") {
  render(<CalendarExample />, document.getElementById("calendar")!);
}

I'm sure the reader would find a more elegant way to do it, but that's pretty much it!

Feel free to tune the code (link to the repo is below), add your own flair and share your thoughts!

ValeriaVG / valeriavg.dev