Composants interactifs dans Markdown

Récemment, j'ai mis en place un calendrier et cela s'est si bien passé que j'ai voulu documenter l'approche et la partager avec un public plus large. Et je voulais vraiment avoir un résultat testable de mon travail directement dans l'article.

Je peaufine mon site Web depuis un moment maintenant et cette idée a lancé la prochaine itération. Et a finalement conduit à une autre reconstruction complète, mais cette histoire ne parle pas de mon combat contre le perfectionnisme. Il s'agit de transformer ceci :

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-->

Dans ceci :

Installation

Mon site Web fonctionne sur Deno et utilise Hono et Hono/JSX depuis récemment, mais l'approche fonctionne avec n'importe quel runtime basé sur JS et JSX.

Les articles de blog, comme vous l'avez déjà remarqué, sont des fichiers markdown avec des attributs qui sont convertis en HTML statique lors de la construction à l'aide de Marked et Front Matter.

Après quelques allers-retours, j'ai opté pour ce workflow :

• J'écris un article en markdown
• Je crée un composant JSX dans le même dossier que l'article
• J'"importe" le composant en markdown en utilisant le commentaire HTML
• Ça fonctionne comme par magie

Le commentaire aurait besoin d'une sorte de préfixe, par ex. rendu et fondamentalement juste un chemin vers ce composant :

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

On pourrait également ajouter des accessoires après le chemin, mais pour mon cas d'utilisation, ce n'était pas nécessaire, j'ai donc sauté cette partie.

Rendu HTML

Avant de pouvoir hydrater quoi que ce soit sur le navigateur, nous devons restituer le HTML à partir du composant JSX. Pour ce faire, nous devons "juste" remplacer la logique de rendu HTML à l'aide d'un moteur de rendu personnalisé :

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;
  }
}

La logique est assez simple : vérifiez si la chaîne html correspond à // puis effectuez le rendu JSX. C’est facile, si vous avez le composant sous la main.

Compilation de composants

Le contenu de mon blog est généré de manière statique, j'ai donc naturellement opté pour la même approche :

• Scannez le dossier de contenu pour les composants *.ssi.tsx (d'où le suffixe)
• Créer un fichier qui les importerait et l'ajouterait à une carte afin que je puisse les récupérer facilement par le chemin

Voici à quoi ressemble mon script de build :

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));

Ne vous attachez pas trop aux fonctions spécifiques à Deno, cela peut être facilement réécrit avec node ou autre chose.

La magie réside dans l'écriture d'un fichier texte qui ressemble à du code JavaScript.

Ce 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;
`;

Renvoie une chaîne comme celle-ci :

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;

Qui peut ensuite être importé et utilisé dans le moteur de rendu :)

Code qui écrit le code ! Magie! Et aucune IA n'a été blessée au cours du processus : juste votre métaprogrammation à l'ancienne.

Et enfin, la dernière pièce du puzzle consiste à hydrater le composant sur le frontend. J'ai utilisé esbuild pour cela, mais personnellement, je prévois de le passer à Vite ou à tout autre élément fourni avec HMR.

Néanmoins, voici à quoi cela ressemble :

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-->

Vous pouvez remarquer un point d'entrée factice qui a une valeur nulle, mais oblige esbuild à créer des fichiers dans leurs propres dossiers et à avoir des chemins prévisibles.

Et ssi-tsconfig.json est assez générique :

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

En ce qui concerne l'hydratation réelle du frontend, j'ai choisi la méthode la plus simple et j'ai simplement ajouté ceci au bas de mon fichier .ssi.tsx :

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;
  }
}

Je suis sûr que le lecteur trouverait une façon plus élégante de le faire, mais c'est à peu près tout !

N'hésitez pas à modifier le code (le lien vers le dépôt est ci-dessous), à ajouter votre propre touche et à partager vos réflexions !

ValériaVG / valériavg.dev

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!