@vyriy/ssg 0.8.7

package/AGENTS.md

@@ -0,0 +1,102 @@
+# Project Agent Guide
+
+This repository follows a calm engineering style: changes should be explicit, reusable, typed, documented, tested, and easy to reason about.
+
+Use this guide as the default behavior for AI agents and contributors working in this repository. Prefer local package conventions when they are more specific than this document.
+
+## Core Principles
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package and project boundaries explicit.
+- Avoid project-specific coupling in reusable code.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths when working with frontend or shared code.
+- Keep integrations replaceable and avoid hard coupling to a CMS, framework, vendor, or runtime host.
+- Prefer infrastructure assumptions that are easy to deploy, observe, and replace.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
+
+## File Shape
+
+- Prefer one exported runtime method, component, helper, or class per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use relative import and export specifiers that match the package module style.
+- Use `.js` relative specifiers in TypeScript source for ESM/NodeNext packages.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export must be re-exported from the package or module public entry point.
+- Add or update public-surface tests when exports change.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Avoid exporting internal helpers only to make tests easier.
+- Do not hand-maintain package `exports` maps unless the project has a real custom publishing need.
+
+## Tests
+
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- Keep tests deterministic.
+- Avoid real network, filesystem, timers, browser, or cloud dependencies unless the behavior specifically requires them.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing behavior.
+
+Example validation commands:
+
+```bash
+yarn test
+```
+
+For workspaces, prefer the project convention, for example:
+
+```bash
+yarn workspace <package-name> test
+```
+
+For Jest-based packages, focused validation may look like:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# <package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Update docs when public behavior changes.
+- Keep generated docs wrappers, such as `doc.mdx`, aligned with the README when the project uses them.
+- For component packages, include visual documentation or stories for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React components with TypeScript when working in React packages.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and predictable ergonomics.
+- Put each public component in its own file with a matching test.
+- Add stories or examples when a component has visual states, variants, or interaction states.
+- Keep styling explicit and reusable. Avoid hidden theme assumptions unless they are part of the package contract.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, docs, examples, and public re-exports together.
+- Do not introduce new dependencies unless they clearly reduce complexity or are already part of the project direction.
+- Prefer small, reviewable changes over broad rewrites.
+- Preserve existing conventions unless there is a clear reason to change them.
+
+## Before Finishing
+
+Check that the change is complete:
+
+- Public exports are updated.
+- Public-surface tests are updated when exports change.
+- Matching unit tests exist for new behavior.
+- README examples still match the real API.
+- Visual docs, stories, or examples are updated for visible component behavior.
+- TypeScript imports follow the package module style.
+- No unrelated files, formatting churn, or generated artifacts were changed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyriy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @vyriy/ssg
+
+Part of [Vyriy](https://vyriy.dev) - a calm architecture toolkit for TypeScript, React, SSR, SSG, APIs, and cloud-ready apps.
+
+Full documentation: https://vyriy.dev/docs/ssg/
+
+Static Markdown site generator for Vyriy-style content sites.
+
+## Purpose
+
+This package builds a static site from Markdown `README.md` files. It is intended for content-first sites that need HTML pages, section catalogs, MiniSearch data, featured home content, related links, sitemap, robots, and copied public assets without adopting a full framework.
+
+Markdown rendering uses `react-markdown` with GitHub-flavored Markdown and `rehype-highlight`, so content supports tables, task lists, autolinks, and highlighted fenced code blocks.
+
+## CLI
+
+Build a site from `site` into `dist`:
+
+```bash
+vyriy-ssg site --output dist
+```
+
+The package also exposes the short `ssg` command:
+
+```bash
+ssg site -o dist
+```
+
+Useful options:
+
+- `--site-url <url>` sets canonical URLs and sitemap locations.
+- `--site-name <name>` sets the built-in theme name.
+- `--stylesheet <href>` links a stylesheet instead of using the built-in CSS.
+- `--stylesheet-file <path>` inlines a stylesheet file.
+- `--ga <id>` adds a Google Analytics measurement ID.
+
+## Content
+
+By default, the generator expects this shape:
+
+```txt
+site/
+  home/README.md
+  consulting/README.md
+  docs/README.md
+  blog/<slug>/README.md
+  docs/<slug>/README.md
+  examples/<slug>/README.md
+  public/
+```
+
+Markdown files can include simple frontmatter:
+
+```md
+---
+title: Calm deployment
+description: Deployment notes for calm static sites.
+date: 2026-06-16
+published: true
+homePage: true
+tags:
+  - ssg
+  - deployment
+---
+
+# Calm deployment
+
+Page content.
+```
+
+## API
+
+```ts
+import { buildStaticSite } from '@vyriy/ssg';
+
+await buildStaticSite({
+  contentPath: 'site',
+  outputPath: 'dist',
+  siteUrl: 'https://vyriy.dev',
+});
+```
+
+Custom sections are supported:
+
+```ts
+await buildStaticSite({
+  sections: [
+    {
+      path: 'articles',
+      title: 'Articles',
+    },
+  ],
+});
+```
+
+Set `index: false` when a section should generate individual pages and search data without its own paginated catalog.
+
+## Exports
+
+- `buildStaticSite(options)` builds the static site.
+- `runSsgCli(args)` runs the CLI programmatically.
+- `parsePage(markdown)` parses page frontmatter and fallback metadata.
+- `renderMarkdown(markdown)` renders Markdown through `react-markdown`, `remark-gfm`, and `rehype-highlight`.
+- `renderSitemap(urls, siteUrl)` renders sitemap XML.
+- `renderRobotsTxt(siteUrl)` renders robots.txt.

package/bin/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runSsgCli } from '../index.js';
+await runSsgCli(process.argv.slice(2));

package/cli.d.ts

@@ -0,0 +1,7 @@
+import type { BuildStaticSiteOptions } from './types.js';
+type CliOptions = BuildStaticSiteOptions & {
+    readonly help?: boolean;
+};
+export declare const parseSsgCliArgs: (args: readonly string[]) => Promise<CliOptions>;
+export declare const runSsgCli: (args?: readonly string[]) => Promise<void>;
+export {};

package/cli.js

@@ -0,0 +1,84 @@
+import { readFile } from 'node:fs/promises';
+import { buildStaticSite } from './ssg.js';
+const helpText = `Usage:
+  ssg <content> [options]
+  vyriy-ssg <content> [options]
+
+Options:
+  -o, --output <path>       Output directory. Defaults to dist.
+  --site-url <url>          Absolute site URL for canonical links and sitemap.
+  --site-name <name>        Site name used by the default theme.
+  --stylesheet <href>       Stylesheet URL. Omit to use the built-in CSS.
+  --stylesheet-file <path>  Inline CSS from a local file.
+  --ga <id>                 Google Analytics measurement ID.
+  -h, --help                Show this help.
+`;
+const readValue = (args, index, flag) => {
+    const value = args[index + 1];
+    if (!value || value.startsWith('-')) {
+        throw new Error(`Missing value for ${flag}.`);
+    }
+    return value;
+};
+const optionHandlers = {
+    '--ga': (args, index, options, arg) => {
+        options.googleAnalyticsMeasurementId = readValue(args, index, arg);
+    },
+    '--output': (args, index, options, arg) => {
+        options.outputPath = readValue(args, index, arg);
+    },
+    '--site-name': (args, index, options, arg) => {
+        options.siteName = readValue(args, index, arg);
+    },
+    '--site-url': (args, index, options, arg) => {
+        options.siteUrl = readValue(args, index, arg);
+    },
+    '--stylesheet': (args, index, options, arg) => {
+        options.stylesheetHref = readValue(args, index, arg);
+    },
+    '--stylesheet-file': async (args, index, options, arg) => {
+        options.stylesheetContent = await readFile(readValue(args, index, arg), 'utf8');
+    },
+    '-o': (args, index, options, arg) => {
+        options.outputPath = readValue(args, index, arg);
+    },
+};
+export const parseSsgCliArgs = async (args) => {
+    const options = {};
+    let contentPath;
+    let index = 0;
+    while (index < args.length) {
+        const arg = args[index] ?? '';
+        if (arg === '-h' || arg === '--help') {
+            return {
+                help: true,
+            };
+        }
+        const optionHandler = optionHandlers[arg];
+        if (optionHandler) {
+            await optionHandler(args, index, options, arg);
+            index += 2;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        if (contentPath) {
+            throw new Error(`Unexpected argument: ${arg}`);
+        }
+        contentPath = arg;
+        index += 1;
+    }
+    return {
+        ...options,
+        ...(contentPath ? { contentPath } : {}),
+    };
+};
+export const runSsgCli = async (args = process.argv.slice(2)) => {
+    const options = await parseSsgCliArgs(args);
+    if (options.help) {
+        process.stdout.write(helpText);
+        return;
+    }
+    await buildStaticSite(options);
+};

package/content.d.ts

@@ -0,0 +1,43 @@
+import type { BuildStaticSiteOptions, ContentEntry, ContentSectionBuildResult, HomePageFeaturedContentItem, RelatedDocumentsMap, SearchDocument, StaticSiteSection } from './types.js';
+type ContentDataSection = {
+    readonly entries: readonly ContentEntry[];
+    readonly section: string;
+};
+type RenderOptions = Required<Pick<BuildStaticSiteOptions, 'defaultTitle' | 'footerText' | 'siteName'>> & Pick<BuildStaticSiteOptions, 'googleAnalyticsMeasurementId' | 'siteUrl' | 'stylesheetContent' | 'stylesheetHref'>;
+export declare const contentSearchOptions: {
+    boost: {
+        content: number;
+        description: number;
+        tags: number;
+        title: number;
+    };
+    fuzzy: number;
+    prefix: boolean;
+};
+export declare const contentMiniSearchOptions: {
+    fields: string[];
+    storeFields: string[];
+    searchOptions: {
+        boost: {
+            content: number;
+            description: number;
+            tags: number;
+            title: number;
+        };
+        fuzzy: number;
+        prefix: boolean;
+    };
+};
+export declare const findReadmePaths: (directory: string) => Promise<readonly string[]>;
+export declare const buildContentEntries: (section: StaticSiteSection, contentPath: string, defaultTitle?: string) => Promise<ContentEntry[]>;
+export declare const buildContentSection: (section: StaticSiteSection, contentPath: string, outputDirectory: string, renderOptions: RenderOptions) => Promise<ContentSectionBuildResult>;
+export declare const writeContentEntryDocuments: (section: StaticSiteSection, entries: readonly ContentEntry[], outputDirectory: string, renderOptions: RenderOptions & {
+    readonly relatedDocuments?: RelatedDocumentsMap;
+}) => Promise<void>;
+export declare const getSearchDocuments: (section: string, entries: readonly ContentEntry[]) => readonly SearchDocument[];
+export declare const getSiteSearchDocuments: (sections: readonly ContentDataSection[]) => readonly SearchDocument[];
+export declare const getMiniSearchIndexJson: (documents: readonly SearchDocument[]) => unknown;
+export declare const getRelatedDocumentsMap: (documents: readonly SearchDocument[]) => RelatedDocumentsMap;
+export declare const getHomePageFeaturedContent: (sections: readonly ContentDataSection[]) => readonly HomePageFeaturedContentItem[];
+export declare const writeContentData: (sections: readonly ContentDataSection[], outputDirectory: string) => Promise<void>;
+export {};

package/content.js

@@ -0,0 +1,237 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+import MiniSearch from 'minisearch';
+import { renderContentIndex, renderPage } from './html.js';
+import { getPlainTextFromMarkdown } from './markdown.js';
+import { parsePage } from './parse-page.js';
+const relatedDocumentCount = 4;
+const homePageFeaturedContentCount = 4;
+const minimumRelatedScore = 10;
+export const contentSearchOptions = {
+    boost: {
+        content: 1,
+        description: 2,
+        tags: 3,
+        title: 4,
+    },
+    fuzzy: 0.2,
+    prefix: true,
+};
+export const contentMiniSearchOptions = {
+    fields: [
+        'title',
+        'description',
+        'tags',
+        'content',
+    ],
+    storeFields: [
+        'title',
+        'description',
+        'section',
+        'slug',
+        'url',
+        'tags',
+        'date',
+    ],
+    searchOptions: contentSearchOptions,
+};
+const isNodeError = (error) => {
+    return typeof error === 'object' && error !== null && 'code' in error;
+};
+export const findReadmePaths = async (directory) => {
+    let entries;
+    try {
+        entries = await readdir(directory, {
+            withFileTypes: true,
+        });
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    const paths = await Promise.all(entries.map(async (entry) => {
+        const entryPath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            return findReadmePaths(entryPath);
+        }
+        return entry.name === 'README.md' ? [entryPath] : [];
+    }));
+    return paths.flat();
+};
+const getSlug = (sectionDirectory, readmePath) => {
+    return dirname(relative(sectionDirectory, readmePath))
+        .split(sep)
+        .filter((segment) => segment && segment !== '.')
+        .join('/');
+};
+const writeDocument = async (outputPath, document) => {
+    await mkdir(dirname(outputPath), {
+        recursive: true,
+    });
+    await writeFile(outputPath, document);
+};
+const getContentIndexHref = (sectionPath, page) => {
+    return page <= 1 ? `/${sectionPath}/` : `/${sectionPath}/${page}/`;
+};
+const getContentIndexOutputPath = (outputDirectory, sectionPath, page) => {
+    return page <= 1
+        ? join(outputDirectory, sectionPath, 'index.html')
+        : join(outputDirectory, sectionPath, String(page), 'index.html');
+};
+export const buildContentEntries = async (section, contentPath, defaultTitle = 'Vyriy') => {
+    const sectionDirectory = join(contentPath, section.path);
+    const readmePaths = await findReadmePaths(sectionDirectory);
+    const entries = (await Promise.all(readmePaths.map(async (readmePath) => {
+        const slug = getSlug(sectionDirectory, readmePath);
+        const page = parsePage(await readFile(readmePath, 'utf8'), defaultTitle);
+        if (!slug || !page.published) {
+            return undefined;
+        }
+        return {
+            ...page,
+            href: `/${section.path}/${slug}/`,
+            section: section.path,
+            slug,
+        };
+    })))
+        .filter((entry) => Boolean(entry))
+        .sort((left, right) => right.date.localeCompare(left.date) || left.title.localeCompare(right.title));
+    return entries;
+};
+export const buildContentSection = async (section, contentPath, outputDirectory, renderOptions) => {
+    const entries = await buildContentEntries(section, contentPath, renderOptions.defaultTitle);
+    const pageSize = section.pageSize ?? 10;
+    const pages = Math.max(1, Math.ceil(entries.length / pageSize));
+    const indexPaths = Array.from({ length: pages }, (_value, index) => getContentIndexHref(section.path, index + 1));
+    await Promise.all(indexPaths.map((_path, index) => {
+        const page = index + 1;
+        const pageEntries = entries.slice(index * pageSize, page * pageSize);
+        return writeDocument(getContentIndexOutputPath(outputDirectory, section.path, page), renderContentIndex(pageEntries, {
+            ...renderOptions,
+            page,
+            pages,
+            sectionPath: section.path,
+            sectionTitle: section.title,
+        }));
+    }));
+    return {
+        entries,
+        indexPaths,
+    };
+};
+export const writeContentEntryDocuments = async (section, entries, outputDirectory, renderOptions) => {
+    await Promise.all(entries.map((entry) => writeDocument(join(outputDirectory, section.path, entry.slug, 'index.html'), renderPage(entry, {
+        ...renderOptions,
+        canonicalPath: entry.href,
+        related: renderOptions.relatedDocuments?.[`${section.path}:${entry.slug}`] ?? [],
+        showTags: true,
+    }))));
+};
+const getOptionalDate = (date) => date || undefined;
+export const getSearchDocuments = (section, entries) => {
+    return entries.map((entry) => ({
+        content: getPlainTextFromMarkdown(entry.content),
+        date: getOptionalDate(entry.date),
+        description: entry.description,
+        id: `${section}:${entry.slug}`,
+        section,
+        slug: entry.slug,
+        tags: entry.tags,
+        title: entry.title,
+        updatedAt: entry.updatedAt,
+        url: entry.href,
+    }));
+};
+export const getSiteSearchDocuments = (sections) => {
+    return sections.flatMap((section) => getSearchDocuments(section.section, section.entries));
+};
+export const getMiniSearchIndexJson = (documents) => {
+    const miniSearch = new MiniSearch(contentMiniSearchOptions);
+    miniSearch.addAll([...documents]);
+    return miniSearch.toJSON();
+};
+const wordPattern = /[\p{L}\p{N}]+/gu;
+const getKeywords = (text) => {
+    return new Set((text.toLowerCase().match(wordPattern) ?? []).map((word) => word.trim()).filter((word) => word.length >= 4));
+};
+const countKeywordMatches = (keywords, text) => {
+    const targetKeywords = getKeywords(text);
+    let matches = 0;
+    for (const keyword of keywords) {
+        if (targetKeywords.has(keyword)) {
+            matches += 1;
+        }
+    }
+    return matches;
+};
+const getSharedTagCount = (leftTags, rightTags) => {
+    const rightTagSet = new Set(rightTags.map((tag) => tag.toLowerCase()));
+    return leftTags.filter((tag) => rightTagSet.has(tag.toLowerCase())).length;
+};
+const getRelatedScore = (document, candidate) => {
+    const keywords = getKeywords(`${document.title} ${document.description}`);
+    return (getSharedTagCount(document.tags, candidate.tags) * 10 +
+        countKeywordMatches(keywords, candidate.title) * 4 +
+        countKeywordMatches(keywords, candidate.description) * 2 +
+        countKeywordMatches(keywords, candidate.content));
+};
+export const getRelatedDocumentsMap = (documents) => {
+    return Object.fromEntries(documents.map((document) => [
+        document.id,
+        documents
+            .filter((candidate) => candidate.id !== document.id)
+            .map((candidate) => ({
+            description: candidate.description,
+            score: getRelatedScore(document, candidate),
+            section: candidate.section,
+            slug: candidate.slug,
+            tags: candidate.tags,
+            title: candidate.title,
+            url: candidate.url,
+        }))
+            .filter((candidate) => candidate.score >= minimumRelatedScore)
+            .sort((left, right) => right.score - left.score || left.title.localeCompare(right.title))
+            .slice(0, relatedDocumentCount),
+    ]));
+};
+export const getHomePageFeaturedContent = (sections) => {
+    return sections
+        .flatMap((section) => section.entries
+        .filter((entry) => entry.homePage)
+        .map((entry) => ({
+        entry,
+        section: section.section,
+    })))
+        .sort((left, right) => (left.entry.homePageOrder ?? Number.MAX_SAFE_INTEGER) -
+        (right.entry.homePageOrder ?? Number.MAX_SAFE_INTEGER) ||
+        right.entry.date.localeCompare(left.entry.date) ||
+        left.entry.title.localeCompare(right.entry.title))
+        .map(({ entry, section }) => ({
+        date: getOptionalDate(entry.date),
+        description: entry.description,
+        homePageOrder: entry.homePageOrder,
+        section,
+        slug: entry.slug,
+        tags: entry.tags,
+        title: entry.title,
+        url: entry.href,
+    }))
+        .slice(0, homePageFeaturedContentCount);
+};
+const writeJson = async (path, value) => {
+    await mkdir(dirname(path), {
+        recursive: true,
+    });
+    await writeFile(path, `${JSON.stringify(value, undefined, 2)}\n`);
+};
+export const writeContentData = async (sections, outputDirectory) => {
+    const documents = getSiteSearchDocuments(sections);
+    await Promise.all([
+        writeJson(join(outputDirectory, 'search/documents.json'), documents),
+        writeJson(join(outputDirectory, 'search/minisearch-index.json'), getMiniSearchIndexJson(documents)),
+        writeJson(join(outputDirectory, 'search/related.json'), getRelatedDocumentsMap(documents)),
+        writeJson(join(outputDirectory, 'home-featured.json'), getHomePageFeaturedContent(sections)),
+    ]);
+};

package/html.d.ts

@@ -0,0 +1,29 @@
+import type { ContentEntry, HomePageFeaturedContentItem, PageData, RelatedDocument } from './types.js';
+type RenderDocumentOptions = {
+    readonly canonicalPath?: string;
+    readonly footerText: string;
+    readonly googleAnalyticsMeasurementId?: string;
+    readonly robotsDirective?: string;
+    readonly siteName: string;
+    readonly siteUrl?: string;
+    readonly stylesheetContent?: string;
+    readonly stylesheetHref?: string;
+};
+type RenderPageOptions = RenderDocumentOptions & {
+    readonly featured?: readonly HomePageFeaturedContentItem[];
+    readonly related?: readonly RelatedDocument[];
+    readonly showTags?: boolean;
+};
+type RenderContentIndexOptions = RenderDocumentOptions & {
+    readonly page?: number;
+    readonly pages?: number;
+    readonly sectionPath: string;
+    readonly sectionTitle: string;
+};
+export declare const defaultStylesheet: string;
+export declare const renderPage: (page: PageData, options: RenderPageOptions) => string;
+export declare const renderContentIndex: (entries: readonly ContentEntry[], { page, pages, sectionPath, sectionTitle, ...documentOptions }: RenderContentIndexOptions) => string;
+export declare const renderNotFoundPage: (options: RenderDocumentOptions) => string;
+export declare const searchScript: string;
+export declare const renderSearchPage: (options: RenderDocumentOptions) => string;
+export {};