@mostajs/markdown-html 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# @mostajs/markdown-html
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com> · AGPL-3.0-or-later · **zéro dépendance** · ESM, sans build
+
+Rendu **Markdown → HTML** pour servir un `README.md` comme page d'aide dans une app.
+
+```js
+import { markdownPage, mdToHtml, MD_CSS } from '@mostajs/markdown-html';
+
+const html = markdownPage(await readFile('README.md', 'utf8'), { title: 'Aide' });
+```
+
+## Périmètre (assumé)
+
+Titres (+ ancres, table des matières), paragraphes, **gras**/*italique*/`code`/~~barré~~, listes à puces, numérotées et **cases à cocher**, blocs de code, **tableaux** (avec défilement horizontal), citations, règles, liens. Pas un moteur CommonMark complet : un rendu de doc interne, pas un CMS.
+
+## Sécurité
+
+- **Le HTML d'un `.md` n'est jamais interprété** : tout est échappé. Un `<script>` collé dans un document **s'affiche**, il ne s'exécute pas. Un README vient d'un dépôt, d'un import ou d'un collègue — on ne lui fait pas confiance.
+- **Un lien `javascript:` n'est pas rendu cliquable** (seuls `http(s)`, `mailto:` et les chemins relatifs le sont).
+
+## Thème
+
+`MD_CSS` s'appuie sur les **tokens** de l'app s'ils existent (`var(--brand)`, `var(--text)`, `var(--focus-ring)`, `var(--radius-lg)`…), avec des replis sobres sinon. Propriétés **logiques** (`padding-inline-start`, `border-inline-start`) : compatible **RTL**.
+
+## API
+
+| Export | Rôle |
+|---|---|
+| `mdToHtml(md)` | `{ html, toc }` — le rendu + la table des matières (titres de niveau 2) |
+| `markdownPage(md, { title, head, toc, lang, dir })` | document HTML complet |
+| `inline(text)` | fragments en ligne seuls |
+| `MD_CSS` · `esc(s)` | feuille de style · échappement |
+
+**14 tests verts** (`@mostajs/mjs-unit`) : `npm test`.

package/llms.txt

@@ -0,0 +1,16 @@
+# @mostajs/markdown-html (0.1.0) — Markdown → HTML, zéro dépendance, sans build
+
+QUOI : rendre un .md en HTML (README servi comme page d'aide dans une app).
+API : mdToHtml(md)→{html,toc} · markdownPage(md,{title,head,toc,lang,dir})→document · inline(text) · MD_CSS · esc(s).
+COUVRE : titres+ancres+TOC(h2), listes (puces/numérotées/cases à cocher), code (inline + blocs ```lang),
+tableaux (+wrapper scrollable), citations, règles, liens, gras/italique/barré, paragraphes recollés.
+PAS un CommonMark complet — périmètre assumé : doc interne.
+
+SÉCURITÉ (testée) : tout est ÉCHAPPÉ — le HTML d'un .md n'est PAS interprété (<script> s'affiche, ne s'exécute pas) ;
+les liens javascript: ne sont PAS rendus cliquables (seuls http(s)/mailto/relatifs le sont).
+
+THÈME : MD_CSS consomme les tokens (var(--brand), var(--text), var(--focus-ring), var(--radius-lg)…) avec replis.
+Propriétés logiques → compatible RTL.
+
+CONSOMMATEUR : Palette Studio (palette.amia.fr/aide sert son propre README).
+TESTS : 14 verts (mjs-unit).

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mostajs/markdown-html",
+  "version": "0.1.0",
+  "description": "Rendu Markdown → HTML zéro dépendance, sans build : titres, listes, tableaux, code, citations, liens, cases à cocher + table des matières. Tout est échappé (le HTML d'un .md n'est PAS interprété). Pour servir un README comme page d'aide.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "llms.txt"
+  ],
+  "keywords": [
+    "markdown",
+    "html",
+    "no-build",
+    "zero-dependency",
+    "readme",
+    "docs",
+    "mostajs"
+  ],
+  "scripts": {
+    "test": "node test-scripts/unit/markdown-html.test.mjs"
+  }
+}

package/src/index.js

@@ -0,0 +1,162 @@
+// @mostajs/markdown-html — rendu Markdown → HTML, zéro dépendance, sans build.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+//
+// Périmètre ASSUMÉ : le Markdown des README et docs de l'écosystème (titres, listes, tableaux,
+// code, citations, liens, emphase, règles, cases à cocher). Ce n'est pas un moteur CommonMark
+// complet — et ça n'a pas à l'être : un rendu de doc interne, pas un CMS.
+//
+// SÉCURITÉ : tout est ÉCHAPPÉ avant d'être rendu. Le HTML brut d'un document Markdown n'est PAS
+// interprété — un `<script>` collé dans un .md s'affiche, il ne s'exécute pas. Ces documents
+// peuvent venir d'un dépôt, d'un collègue ou d'un import : on ne leur fait pas confiance.
+
+export const esc = (s = '') => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+/** Fragments en ligne : `code`, **gras**, *italique*, [lien](url), ~~barré~~. */
+export function inline(text = '') {
+  let out = esc(text);
+  out = out.replace(/`([^`]+)`/g, (_, c) => `<code>${c}</code>`);
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  out = out.replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<em>$2</em>');
+  out = out.replace(/~~([^~]+)~~/g, '<del>$1</del>');
+  // Liens : seuls http(s), mailto et les chemins relatifs sont rendus cliquables (pas de javascript:)
+  out = out.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (m, label, href) =>
+    (/^(https?:\/\/|mailto:|[./#])/i.test(href) ? `<a href="${href}">${label}</a>` : label));
+  return out;
+}
+
+const slug = (s) => s.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '')
+  .replace(/[^a-z0-9\s-]/g, '').trim().replace(/\s+/g, '-');
+
+/** Markdown → HTML. Retourne { html, toc } (la table des matières : les titres de niveau 2). */
+export function mdToHtml(md = '') {
+  const lines = String(md).replace(/\r\n/g, '\n').split('\n');
+  const out = []; const toc = [];
+  let i = 0;
+  const closeList = (state) => { if (state.ul) { out.push('</ul>'); state.ul = false; } if (state.ol) { out.push('</ol>'); state.ol = false; } };
+  const state = { ul: false, ol: false };
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    // Bloc de code ```lang
+    if (/^\s*```/.test(line)) {
+      closeList(state);
+      const lang = line.replace(/^\s*```/, '').trim();
+      const buf = [];
+      i++;
+      while (i < lines.length && !/^\s*```/.test(lines[i])) buf.push(lines[i++]);
+      i++;   // ferme la clôture
+      out.push(`<pre class="md-code"${lang ? ` data-lang="${esc(lang)}"` : ''}><code>${esc(buf.join('\n'))}</code></pre>`);
+      continue;
+    }
+
+    // Tableau | a | b |
+    if (/^\s*\|/.test(line) && /^\s*\|?[\s:-]+\|/.test(lines[i + 1] || '')) {
+      closeList(state);
+      const cells = (l) => l.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+      const head = cells(line);
+      i += 2;
+      const rows = [];
+      while (i < lines.length && /^\s*\|/.test(lines[i])) rows.push(cells(lines[i++]));
+      out.push(`<div class="md-tablewrap"><table class="md-table"><thead><tr>${head.map((h) => `<th>${inline(h)}</th>`).join('')}</tr></thead>`
+        + `<tbody>${rows.map((r) => `<tr>${r.map((c) => `<td>${inline(c)}</td>`).join('')}</tr>`).join('')}</tbody></table></div>`);
+      continue;
+    }
+
+    // Titres
+    const h = line.match(/^(#{1,6})\s+(.*)$/);
+    if (h) {
+      closeList(state);
+      const lvl = h[1].length; const txt = h[2].replace(/\s*#+\s*$/, '');
+      const id = slug(txt);
+      if (lvl === 2) toc.push({ id, text: txt.replace(/[*`]/g, '') });
+      out.push(`<h${lvl} id="${id}">${inline(txt)}</h${lvl}>`);
+      i++; continue;
+    }
+
+    // Règle horizontale
+    if (/^\s*(-{3,}|\*{3,}|_{3,})\s*$/.test(line)) { closeList(state); out.push('<hr>'); i++; continue; }
+
+    // Citation
+    if (/^\s*>\s?/.test(line)) {
+      closeList(state);
+      const buf = [];
+      while (i < lines.length && /^\s*>\s?/.test(lines[i])) buf.push(lines[i++].replace(/^\s*>\s?/, ''));
+      out.push(`<blockquote>${inline(buf.join(' '))}</blockquote>`);
+      continue;
+    }
+
+    // Listes (à puces, numérotées, cases à cocher)
+    const ul = line.match(/^\s*[-*+]\s+(.*)$/);
+    const ol = line.match(/^\s*\d+[.)]\s+(.*)$/);
+    if (ul || ol) {
+      if (ul && !state.ul) { closeList(state); out.push('<ul>'); state.ul = true; }
+      if (ol && !state.ol) { closeList(state); out.push('<ol>'); state.ol = true; }
+      let item = (ul || ol)[1];
+      const box = item.match(/^\[([ xX])\]\s+(.*)$/);
+      if (box) item = `<input type="checkbox" disabled${/[xX]/.test(box[1]) ? ' checked' : ''}> ${box[2]}`;
+      out.push(`<li>${box ? item.replace(/^(<input[^>]*>)\s*/, '$1 ') && item.replace(/^(<input[^>]*> )(.*)$/, (m, a, b) => a + inline(b)) : inline(item)}</li>`);
+      i++; continue;
+    }
+
+    // Ligne vide → ferme les listes
+    if (!line.trim()) { closeList(state); i++; continue; }
+
+    // Paragraphe (les lignes suivantes sont recollées)
+    closeList(state);
+    const buf = [line];
+    i++;
+    while (i < lines.length && lines[i].trim() && !/^\s*([-*+]\s|\d+[.)]\s|#{1,6}\s|>|\||```)/.test(lines[i])) buf.push(lines[i++]);
+    out.push(`<p>${inline(buf.join(' '))}</p>`);
+  }
+  closeList(state);
+  return { html: out.join('\n'), toc };
+}
+
+/** Feuille de style du rendu — s'appuie sur les tokens s'ils existent, sinon des replis sobres. */
+export const MD_CSS = `
+.md{max-width:80ch;margin:0 auto;padding:24px;color:var(--text,#0F172A);
+  font-family:var(--font-family,system-ui,sans-serif);line-height:1.65}
+.md h1{font-size:var(--font-h1-size,32px);line-height:1.2;margin:0 0 8px}
+.md h2{font-size:var(--font-h2-size,24px);margin:34px 0 10px;padding-bottom:6px;border-bottom:1px solid var(--line,#e2e8f0)}
+.md h3{font-size:var(--font-h3-size,20px);margin:24px 0 8px}
+.md h4{font-size:var(--font-bodyLg-size,16px);margin:18px 0 6px}
+.md p{margin:0 0 12px}
+.md a{color:var(--link,#2563EB)}
+.md a:focus-visible,.md summary:focus-visible{outline:2px solid var(--focus-ring,#bc8b29);outline-offset:2px}
+.md code{background:var(--surface-alt,#f1f5f9);border:1px solid var(--line,#e2e8f0);border-radius:5px;
+  padding:1px 5px;font-family:ui-monospace,monospace;font-size:.9em}
+.md pre.md-code{background:var(--brand,#0F172A);color:#E2E8F0;border-radius:var(--radius-lg,12px);
+  padding:14px 16px;overflow-x:auto;margin:0 0 14px}
+.md pre.md-code code{background:none;border:0;color:inherit;padding:0;font-size:13px;line-height:1.6}
+.md blockquote{margin:0 0 14px;padding:10px 14px;border-inline-start:3px solid var(--accent,#C9952C);
+  background:var(--surface-alt,#f8fafc);border-radius:0 var(--radius-md,8px) var(--radius-md,8px) 0}
+.md blockquote p{margin:0}
+.md ul,.md ol{margin:0 0 12px;padding-inline-start:22px}
+.md li{margin:4px 0}
+.md hr{border:0;border-top:1px solid var(--line,#e2e8f0);margin:28px 0}
+.md .md-tablewrap{overflow-x:auto;margin:0 0 16px}
+.md table.md-table{width:100%;border-collapse:collapse;font-size:14px;background:var(--surface,#fff);
+  border:1px solid var(--line,#e2e8f0);border-radius:var(--radius-md,8px)}
+.md table.md-table th{text-align:start;padding:8px 10px;background:var(--surface-alt,#f8fafc);
+  border-bottom:1px solid var(--line,#e2e8f0);font-weight:600;color:var(--text-muted,#64748b);font-size:12px}
+.md table.md-table td{padding:8px 10px;border-bottom:1px solid var(--line,#e2e8f0);vertical-align:top}
+.md .md-toc{background:var(--surface-alt,#f8fafc);border:1px solid var(--line,#e2e8f0);
+  border-radius:var(--radius-lg,12px);padding:12px 16px;margin:0 0 24px}
+.md .md-toc ol{margin:0;padding-inline-start:20px}
+.md .md-toc a{text-decoration:none}
+.md .md-toc a:hover{text-decoration:underline}
+`;
+
+/** Document complet : le Markdown rendu, avec sa table des matières. */
+export function markdownPage(md = '', { title = 'Aide', head = '', toc = true, lang = 'fr', dir = 'ltr' } = {}) {
+  const r = mdToHtml(md);
+  const nav = toc && r.toc.length
+    ? `<nav class="md-toc"><ol>${r.toc.map((t) => `<li><a href="#${t.id}">${esc(t.text)}</a></li>`).join('')}</ol></nav>`
+    : '';
+  return `<!doctype html><html lang="${esc(lang)}" dir="${esc(dir)}"><head><meta charset="utf-8">`
+    + `<meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title>`
+    + `${head}<style>${MD_CSS}</style></head><body><article class="md">${nav}${r.html}</article></body></html>`;
+}
+
+export const moduleInfo = { name: '@mostajs/markdown-html', version: '0.1.0' };