hyogen.md (@b4moss/hyogen-md)

Extended Markdown template engine for TypeScript / JavaScript.

Control flow and templating live in HTML comments (@hg … @endhg or @@ … @@), so source files stay preview-friendly. The library outputs Markdown only (HTML is left to the consumer).

• Package name: @b4moss/hyogen-md
• Product name: hyogen.md（表現.md）
• License: MIT
• Japanese README: README_ja.md
• Changelog: user-docs/changelog.md
• Documentation: https://hyogenmd.oss.b4m.jp (Nuxt Content; not in npm)
• Playground: https://hyogenmd.oss.b4m.jp/playground (same site; not in npm)
• Specs (Japanese, maintainers): docs/

Homepage: https://github.com/b4m-oss/hyogen-md

This file is kept in sync at the repository root and at app/README.md (npm package root).

Install

npm install @b4moss/hyogen-md

Requires Node.js >= 24.

Quick start

Client / CSR (@b4moss/hyogen-md/client)

import { renderClient } from "@b4moss/hyogen-md/client";

const result = await renderClient(
  { path: "/src/index.md" },
  { siteName: "Demo" },
  {
    loader: async (path) => {
      // resolve path → file contents (virtual FS, fetch, etc.)
      return await readSomewhere(path);
    },
  },
);

console.log(result.markdown);
console.log(result.warnings);

Server / SSR (@b4moss/hyogen-md)

import { renderServer, createNodeLoader } from "@b4moss/hyogen-md";

const result = await renderServer(
  { path: "./pages/index.md" },
  { title: "Hello" },
  {
    loader: createNodeLoader(),
    // serverContext: { apiKey: "…" }, // server-only; not available on renderClient
  },
);

SSG batch (build)

import { build } from "@b4moss/hyogen-md";

const { files, warnings } = await build({
  input: "./src/**/*.md",
  outDir: "./out",
  context: { siteName: "Demo" },
});

API details: docs/specs/api.md.

Repository layout

| Path | Role | |------|------| | app/ | Library published to npm (files: dist, plus README / LICENSE) | | docs-site/ | Documentation site + Playground on GitHub Pages (not in npm) | | user-docs/ | User-facing docs (e.g. changelog) | | docs/ | Specs and roadmap (Japanese, maintainers) |

Documentation & Playground

Site: https://hyogenmd.oss.b4m.jp (GitHub Pages; /ja, /en, /playground).
Playground: https://hyogenmd.oss.b4m.jp/playground

Local:

make install-docs
make dev-docs

Open http://localhost:3000 (docs) and /playground. Uses ../app via Vite alias. Virtual FS + localStorage only.

Status

This is 0.x. APIs and output may change until 1.0.0.
Published: @b4moss/[email protected] (git tag v0.10.0).

Playground UX is part of the v0.10.0 product milestone but is not included in the npm tarball.

The coverage badge reflects approximate statement coverage for app/ (library) from Vitest (~84%). Initial release goal is ≥50%. Coverage is uploaded to Codecov from .github/workflows/quality.yml on pushes to main.

Changelog

See user-docs/changelog.md (Japanese: changelog_ja.md).

License

MIT © Kohki SHIKATA