@md-plugins/vite-ssg-plugin 0.1.0-beta.23

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 md-plugins
+
+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,185 @@
+# @md-plugins/vite-ssg-plugin
+
+Static-site-generation infrastructure for Q-Press and md-plugins documentation sites.
+
+This package currently focuses on route inventory and static route output:
+
+- Normalize static route declarations.
+- Discover Q-Press Markdown routes from a `src/markdown` folder.
+- Generate a route manifest during Vite builds.
+- Expose the same manifest through a virtual module.
+- Emit route-specific HTML files from the built app shell so static hosts can serve deep
+  links without relying on a SPA fallback rewrite.
+- Accept a custom per-route renderer when a project is ready to generate fully prerendered
+  route HTML.
+
+By default, generated route HTML uses the built `index.html` app shell. That makes the output
+usable on Netlify or other static hosts today. Q-Press projects can use `qpress-ssg` for
+first-class Vue/Quasar build-time prerendering without enabling Quasar SSR mode.
+
+## Why SSG?
+
+SSG turns known routes into static HTML at build time. A direct visit or browser refresh can receive
+the route's own `index.html` file, then the Vue/Quasar client bundle hydrates the page and normal
+SPA navigation takes over.
+
+That gives docs sites a useful middle ground: static hosting without a runtime SSR server, but with
+route-specific HTML, meta tags, headings, and body content in the first response. This can help SEO,
+indexing crawlers, and social link previews because they no longer need to depend entirely on
+client-side JavaScript rendering. SSG does not guarantee search ranking improvements by itself; it
+simply makes the route content easier to read earlier and more reliably.
+
+## Usage
+
+```ts
+import { viteSsgPlugin } from '@md-plugins/vite-ssg-plugin'
+
+export default {
+  plugins: [
+    viteSsgPlugin({
+      routes: ['/', '/getting-started/introduction', '/other/releases'],
+    }),
+  ],
+}
+```
+
+For Q-Press-style Markdown docs:
+
+```ts
+import { viteSsgPlugin } from '@md-plugins/vite-ssg-plugin'
+
+export default {
+  plugins: [
+    viteSsgPlugin({
+      markdown: {
+        root: './src/markdown',
+      },
+    }),
+  ],
+}
+```
+
+The plugin emits `q-press-ssg-routes.json` by default:
+
+```json
+{
+  "base": "/",
+  "routes": [
+    {
+      "path": "/",
+      "htmlFile": "index.html",
+      "id": "root",
+      "meta": {},
+      "params": {}
+    }
+  ]
+}
+```
+
+Route `meta`, `params`, and `data` values should stay JSON-safe because they are written
+directly into the emitted manifest and the virtual module.
+
+## Route HTML
+
+When Vite emits `index.html`, this plugin creates matching route HTML files such as:
+
+```txt
+index.html
+getting-started/introduction/index.html
+other/releases/index.html
+q-press-ssg-routes.json
+```
+
+Each generated page receives a small JSON payload:
+
+```html
+<script type="application/json" id="md-plugins-ssg-route">
+  ...
+</script>
+```
+
+That payload helps future hydration or diagnostics know which static route was generated.
+
+Projects that need fully prerendered content can provide `renderRoute`:
+
+```ts
+viteSsgPlugin({
+  routes: ['/', '/guide'],
+  async renderRoute(route, { appHtml }) {
+    return appHtml.replace('<div id="q-app"></div>', `<div id="q-app">${route.path}</div>`)
+  },
+})
+```
+
+## Post-Build Prerendering
+
+When a project has a renderer available outside the Vite build, use `prerenderSsgRoutes`.
+This is the intended bridge for SSR-quality output:
+
+```ts
+import { prerenderSsgRoutes } from '@md-plugins/vite-ssg-plugin'
+
+await prerenderSsgRoutes({
+  outDir: 'dist/spa',
+  async renderRoute(route, { appHtml }) {
+    const renderedAppHtml = await renderMyAppAt(route.path)
+
+    return appHtml.replace('<div id="q-app"></div>', `<div id="q-app">${renderedAppHtml}</div>`)
+  },
+})
+```
+
+The helper reads `q-press-ssg-routes.json`, renders every route, and writes each route's
+`index.html` file. The renderer can be a Vue SSR renderer, a Quasar SSR adapter, or any
+project-specific static renderer.
+
+## Vue / Quasar Build-Time Rendering
+
+For Q-Press apps, run the generated Q-Press command after a normal SPA build:
+
+```bash
+pnpm build:ssg
+```
+
+Projects that already have a Quasar SSR bundle can opt into that renderer with
+`qpress-ssg --renderer quasar-ssr`, but it is not required for the default Q-Press SSG flow.
+
+For lower-level Vue or Quasar apps, `createVueSsgRouteRenderer` adapts a per-route SSR app factory
+into the generic `renderRoute` hook. This uses Vue's server renderer at build time only; the
+published output can still be deployed as static files on Netlify or any other static host.
+
+```ts
+import { prerenderVueSsgRoutes } from '@md-plugins/vite-ssg-plugin'
+import { createQPressSsgApp } from './src/.q-press/ssg/create-app'
+
+await prerenderVueSsgRoutes({
+  outDir: 'dist/spa',
+  createApp: createQPressSsgApp,
+})
+```
+
+Q-Press generates `src/.q-press/ssg/create-app` and `src/.q-press/ssg/prerender`, and the `qpress-ssg` binary uses that app factory for the common docs-site flow. Non-Q-Press projects can still provide their own app factory. Vue SSR dependencies are optional until this adapter is used. Projects that already build a Quasar SSR bundle can opt into that path with `qpress-ssg --renderer quasar-ssr`.
+
+## Local SSR / SSG Proving
+
+It is reasonable to create a local branch or throwaway script that boots a Quasar/Vue SSR app and
+feeds it into `prerenderVueSsgRoutes()` while the workflow is still being proven.
+
+That scratch harness should not be committed as finalized docs-site code. Commit the reusable
+plugin behavior, the documented options, the generated Q-Press app-factory template, and reusable
+runner behavior such as `qpress-ssg`; leave one-off local test wiring out unless it belongs in the
+shared tooling.
+
+## Virtual Module
+
+Client or build tooling can import the generated manifest:
+
+```ts
+import ssgRouteManifest, { ssgRoutes } from 'virtual:md-plugins/ssg-routes'
+```
+
+## Next Steps
+
+- Add dynamic-route parameter expansion.
+- Define lazy client hydration behavior for examples and browser-only components.
+- Define how browser-only examples opt out of prerendering.

package/dist/index.d.mts

@@ -0,0 +1,224 @@
+import { Plugin } from 'vite';
+
+type MaybePromise<T> = T | Promise<T>;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type SsgRouteParams = Record<string, JsonPrimitive | undefined>;
+type SsgRouteMeta = Record<string, JsonValue | undefined>;
+interface SsgRouteObject {
+    path: string;
+    meta?: SsgRouteMeta;
+    params?: SsgRouteParams;
+    data?: JsonValue;
+}
+type SsgRouteInput = string | SsgRouteObject;
+interface SsgRoute {
+    path: string;
+    htmlFile: string;
+    id: string;
+    meta: SsgRouteMeta;
+    params: SsgRouteParams;
+    data?: JsonValue;
+}
+interface SsgRouteManifest {
+    base: string;
+    routes: SsgRoute[];
+}
+type SsgRouteSource = SsgRouteInput[] | (() => MaybePromise<SsgRouteInput[]>);
+interface MarkdownSsgRoutesOptions {
+    /**
+     * Directory containing Markdown pages.
+     */
+    root: string;
+    /**
+     * Glob pattern or patterns to include.
+     */
+    include?: string | string[];
+    /**
+     * Glob pattern or patterns to exclude.
+     */
+    exclude?: string | string[];
+    /**
+     * Markdown file that should map to the site root.
+     */
+    landingPage?: string;
+}
+interface SsgRouteRenderContext {
+    appHtml: string;
+    manifest: SsgRouteManifest;
+    routeIndex: number;
+}
+type SsgRouteRenderer = (route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string | undefined>;
+type SsgRouteHtmlTransformer = (html: string, route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string>;
+interface SsgRouteHtmlOptions {
+    /**
+     * Optional per-route HTML renderer. Returning undefined falls back to the app shell.
+     */
+    renderRoute?: SsgRouteRenderer;
+    /**
+     * Optional per-route HTML transform after rendering or app-shell fallback.
+     */
+    transformHtml?: SsgRouteHtmlTransformer;
+    /**
+     * Injects a JSON payload for the current SSG route into generated HTML.
+     */
+    injectRoutePayload?: boolean;
+}
+interface PrerenderSsgRoutesOptions extends SsgRouteHtmlOptions {
+    /**
+     * Built output directory containing the app shell and route manifest.
+     */
+    outDir: string;
+    /**
+     * Built HTML file used as the app shell. Defaults to index.html.
+     */
+    appHtmlFile?: string;
+    /**
+     * Build asset path for the generated route manifest.
+     */
+    manifestFile?: string;
+    /**
+     * Manifest to use instead of reading one from disk.
+     */
+    manifest?: SsgRouteManifest;
+}
+interface PrerenderedSsgRoute {
+    path: string;
+    htmlFile: string;
+    bytes: number;
+}
+interface PrerenderSsgRoutesResult {
+    manifest: SsgRouteManifest;
+    outDir: string;
+    routes: PrerenderedSsgRoute[];
+}
+interface VueSsgRouterAdapter {
+    push?: (location: unknown) => MaybePromise<unknown>;
+    replace?: (location: unknown) => MaybePromise<unknown>;
+    isReady?: () => MaybePromise<unknown>;
+}
+interface VueSsgAppFactoryResult {
+    app: unknown;
+    router?: VueSsgRouterAdapter;
+    ssrContext?: Record<string, unknown>;
+    routeLocation?: unknown;
+    onRendered?: () => MaybePromise<void>;
+}
+type VueSsgAppFactory = (route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<VueSsgAppFactoryResult | unknown>;
+type VueSsgRenderToString = (app: unknown, ssrContext?: Record<string, unknown>) => MaybePromise<string>;
+type VueSsgRouteLocationResolver = (route: SsgRoute, context: SsgRouteRenderContext) => unknown;
+type VueSsgAppHtmlReplacer = (appHtml: string, renderedAppHtml: string, route: SsgRoute, context: SsgRouteRenderContext) => string;
+type VueSsgRenderedAppHtmlTransformer = (renderedAppHtml: string, route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string>;
+interface VueSsgRouteRendererOptions {
+    /**
+     * Creates a fresh Vue/Quasar SSR app instance for each route.
+     */
+    createApp: VueSsgAppFactory;
+    /**
+     * Optional renderer. Defaults to lazy-loading @vue/server-renderer when used.
+     */
+    renderToString?: VueSsgRenderToString;
+    /**
+     * DOM id for the app mount element in the built shell. Defaults to q-app.
+     */
+    appMountId?: string;
+    /**
+     * Route location pushed into the returned router before rendering.
+     */
+    routeLocation?: VueSsgRouteLocationResolver;
+    /**
+     * Use router.replace instead of router.push when both are available.
+     */
+    useRouterReplace?: boolean;
+    /**
+     * Optional transform for the SSR-rendered app fragment before shell insertion.
+     */
+    transformRenderedAppHtml?: VueSsgRenderedAppHtmlTransformer;
+    /**
+     * Optional full shell replacer for projects with a custom app placeholder.
+     */
+    replaceAppHtml?: VueSsgAppHtmlReplacer;
+}
+interface PrerenderVueSsgRoutesOptions extends Omit<PrerenderSsgRoutesOptions, 'renderRoute'>, VueSsgRouteRendererOptions {
+}
+interface ViteSsgPluginOptions {
+    /**
+     * Enables manifest emission. The virtual module remains available either way.
+     */
+    enabled?: boolean;
+    /**
+     * Static route declarations or a function that resolves them.
+     */
+    routes?: SsgRouteSource;
+    /**
+     * Optional Markdown route discovery. This can be combined with explicit routes.
+     */
+    markdown?: MarkdownSsgRoutesOptions;
+    /**
+     * Base path used by the generated route manifest.
+     * Falls back to Vite's resolved base.
+     */
+    base?: string;
+    /**
+     * Emits static HTML files for each route. Defaults to true.
+     */
+    emitHtml?: boolean;
+    /**
+     * Built HTML file used as the app shell. Defaults to index.html.
+     */
+    appHtmlFile?: string;
+    /**
+     * Optional per-route HTML renderer/transform behavior.
+     */
+    renderRoute?: SsgRouteHtmlOptions['renderRoute'];
+    transformHtml?: SsgRouteHtmlOptions['transformHtml'];
+    injectRoutePayload?: SsgRouteHtmlOptions['injectRoutePayload'];
+    /**
+     * Build asset path for the generated route manifest.
+     */
+    manifestFile?: string;
+    /**
+     * Virtual module id used to import the generated route manifest.
+     */
+    virtualModuleId?: string;
+}
+
+declare function escapeJsonForHtml(json: string): string;
+declare function createSsgRoutePayloadScript(route: SsgRoute): string;
+declare function injectSsgRoutePayload(html: string, route: SsgRoute): string;
+declare function createSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, { injectRoutePayload }?: {
+    injectRoutePayload?: boolean;
+}): string;
+declare function renderSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, options?: SsgRouteHtmlOptions): Promise<string>;
+
+declare function markdownFileToRoutePath(markdownFile: string, { landingPage }?: Pick<MarkdownSsgRoutesOptions, 'landingPage'>): string;
+declare function discoverMarkdownSsgRoutes({ root, include, exclude, landingPage, }: MarkdownSsgRoutesOptions): SsgRouteInput[];
+
+declare function prerenderSsgRoutes({ outDir, appHtmlFile, manifestFile, manifest, renderRoute, transformHtml, injectRoutePayload, }: PrerenderSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
+
+declare const defaultSsgManifestFile = "q-press-ssg-routes.json";
+declare const defaultSsgVirtualModuleId = "virtual:md-plugins/ssg-routes";
+declare function normalizeSsgBase(base?: string): string;
+declare function normalizeSsgRoutePath(path: string): string;
+declare function routePathToHtmlFile(routePath: string): string;
+declare function routePathToId(routePath: string): string;
+declare function normalizeSsgRoute(input: SsgRouteInput): SsgRoute;
+declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base }?: {
+    base?: string;
+}): SsgRouteManifest;
+
+/**
+ * Creates a route renderer that turns a fresh Vue/Quasar SSR app into static HTML.
+ */
+declare function createVueSsgRouteRenderer(options: VueSsgRouteRendererOptions): SsgRouteRenderer;
+/**
+ * Convenience wrapper for projects that prerender after a normal Vite/Quasar build.
+ */
+declare function prerenderVueSsgRoutes(options: PrerenderVueSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
+
+declare function viteSsgPlugin(options?: ViteSsgPluginOptions): Plugin;
+
+export { createSsgRouteHtml, createSsgRouteManifest, createSsgRoutePayloadScript, createVueSsgRouteRenderer, defaultSsgManifestFile, defaultSsgVirtualModuleId, discoverMarkdownSsgRoutes, escapeJsonForHtml, injectSsgRoutePayload, markdownFileToRoutePath, normalizeSsgBase, normalizeSsgRoute, normalizeSsgRoutePath, prerenderSsgRoutes, prerenderVueSsgRoutes, renderSsgRouteHtml, routePathToHtmlFile, routePathToId, viteSsgPlugin };
+export type { JsonPrimitive, JsonValue, MarkdownSsgRoutesOptions, MaybePromise, PrerenderSsgRoutesOptions, PrerenderSsgRoutesResult, PrerenderVueSsgRoutesOptions, PrerenderedSsgRoute, SsgRoute, SsgRouteHtmlOptions, SsgRouteHtmlTransformer, SsgRouteInput, SsgRouteManifest, SsgRouteMeta, SsgRouteObject, SsgRouteParams, SsgRouteRenderContext, SsgRouteRenderer, SsgRouteSource, ViteSsgPluginOptions, VueSsgAppFactory, VueSsgAppFactoryResult, VueSsgAppHtmlReplacer, VueSsgRenderToString, VueSsgRenderedAppHtmlTransformer, VueSsgRouteLocationResolver, VueSsgRouteRendererOptions, VueSsgRouterAdapter };

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+import { Plugin } from 'vite';
+
+type MaybePromise<T> = T | Promise<T>;
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type SsgRouteParams = Record<string, JsonPrimitive | undefined>;
+type SsgRouteMeta = Record<string, JsonValue | undefined>;
+interface SsgRouteObject {
+    path: string;
+    meta?: SsgRouteMeta;
+    params?: SsgRouteParams;
+    data?: JsonValue;
+}
+type SsgRouteInput = string | SsgRouteObject;
+interface SsgRoute {
+    path: string;
+    htmlFile: string;
+    id: string;
+    meta: SsgRouteMeta;
+    params: SsgRouteParams;
+    data?: JsonValue;
+}
+interface SsgRouteManifest {
+    base: string;
+    routes: SsgRoute[];
+}
+type SsgRouteSource = SsgRouteInput[] | (() => MaybePromise<SsgRouteInput[]>);
+interface MarkdownSsgRoutesOptions {
+    /**
+     * Directory containing Markdown pages.
+     */
+    root: string;
+    /**
+     * Glob pattern or patterns to include.
+     */
+    include?: string | string[];
+    /**
+     * Glob pattern or patterns to exclude.
+     */
+    exclude?: string | string[];
+    /**
+     * Markdown file that should map to the site root.
+     */
+    landingPage?: string;
+}
+interface SsgRouteRenderContext {
+    appHtml: string;
+    manifest: SsgRouteManifest;
+    routeIndex: number;
+}
+type SsgRouteRenderer = (route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string | undefined>;
+type SsgRouteHtmlTransformer = (html: string, route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string>;
+interface SsgRouteHtmlOptions {
+    /**
+     * Optional per-route HTML renderer. Returning undefined falls back to the app shell.
+     */
+    renderRoute?: SsgRouteRenderer;
+    /**
+     * Optional per-route HTML transform after rendering or app-shell fallback.
+     */
+    transformHtml?: SsgRouteHtmlTransformer;
+    /**
+     * Injects a JSON payload for the current SSG route into generated HTML.
+     */
+    injectRoutePayload?: boolean;
+}
+interface PrerenderSsgRoutesOptions extends SsgRouteHtmlOptions {
+    /**
+     * Built output directory containing the app shell and route manifest.
+     */
+    outDir: string;
+    /**
+     * Built HTML file used as the app shell. Defaults to index.html.
+     */
+    appHtmlFile?: string;
+    /**
+     * Build asset path for the generated route manifest.
+     */
+    manifestFile?: string;
+    /**
+     * Manifest to use instead of reading one from disk.
+     */
+    manifest?: SsgRouteManifest;
+}
+interface PrerenderedSsgRoute {
+    path: string;
+    htmlFile: string;
+    bytes: number;
+}
+interface PrerenderSsgRoutesResult {
+    manifest: SsgRouteManifest;
+    outDir: string;
+    routes: PrerenderedSsgRoute[];
+}
+interface VueSsgRouterAdapter {
+    push?: (location: unknown) => MaybePromise<unknown>;
+    replace?: (location: unknown) => MaybePromise<unknown>;
+    isReady?: () => MaybePromise<unknown>;
+}
+interface VueSsgAppFactoryResult {
+    app: unknown;
+    router?: VueSsgRouterAdapter;
+    ssrContext?: Record<string, unknown>;
+    routeLocation?: unknown;
+    onRendered?: () => MaybePromise<void>;
+}
+type VueSsgAppFactory = (route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<VueSsgAppFactoryResult | unknown>;
+type VueSsgRenderToString = (app: unknown, ssrContext?: Record<string, unknown>) => MaybePromise<string>;
+type VueSsgRouteLocationResolver = (route: SsgRoute, context: SsgRouteRenderContext) => unknown;
+type VueSsgAppHtmlReplacer = (appHtml: string, renderedAppHtml: string, route: SsgRoute, context: SsgRouteRenderContext) => string;
+type VueSsgRenderedAppHtmlTransformer = (renderedAppHtml: string, route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string>;
+interface VueSsgRouteRendererOptions {
+    /**
+     * Creates a fresh Vue/Quasar SSR app instance for each route.
+     */
+    createApp: VueSsgAppFactory;
+    /**
+     * Optional renderer. Defaults to lazy-loading @vue/server-renderer when used.
+     */
+    renderToString?: VueSsgRenderToString;
+    /**
+     * DOM id for the app mount element in the built shell. Defaults to q-app.
+     */
+    appMountId?: string;
+    /**
+     * Route location pushed into the returned router before rendering.
+     */
+    routeLocation?: VueSsgRouteLocationResolver;
+    /**
+     * Use router.replace instead of router.push when both are available.
+     */
+    useRouterReplace?: boolean;
+    /**
+     * Optional transform for the SSR-rendered app fragment before shell insertion.
+     */
+    transformRenderedAppHtml?: VueSsgRenderedAppHtmlTransformer;
+    /**
+     * Optional full shell replacer for projects with a custom app placeholder.
+     */
+    replaceAppHtml?: VueSsgAppHtmlReplacer;
+}
+interface PrerenderVueSsgRoutesOptions extends Omit<PrerenderSsgRoutesOptions, 'renderRoute'>, VueSsgRouteRendererOptions {
+}
+interface ViteSsgPluginOptions {
+    /**
+     * Enables manifest emission. The virtual module remains available either way.
+     */
+    enabled?: boolean;
+    /**
+     * Static route declarations or a function that resolves them.
+     */
+    routes?: SsgRouteSource;
+    /**
+     * Optional Markdown route discovery. This can be combined with explicit routes.
+     */
+    markdown?: MarkdownSsgRoutesOptions;
+    /**
+     * Base path used by the generated route manifest.
+     * Falls back to Vite's resolved base.
+     */
+    base?: string;
+    /**
+     * Emits static HTML files for each route. Defaults to true.
+     */
+    emitHtml?: boolean;
+    /**
+     * Built HTML file used as the app shell. Defaults to index.html.
+     */
+    appHtmlFile?: string;
+    /**
+     * Optional per-route HTML renderer/transform behavior.
+     */
+    renderRoute?: SsgRouteHtmlOptions['renderRoute'];
+    transformHtml?: SsgRouteHtmlOptions['transformHtml'];
+    injectRoutePayload?: SsgRouteHtmlOptions['injectRoutePayload'];
+    /**
+     * Build asset path for the generated route manifest.
+     */
+    manifestFile?: string;
+    /**
+     * Virtual module id used to import the generated route manifest.
+     */
+    virtualModuleId?: string;
+}
+
+declare function escapeJsonForHtml(json: string): string;
+declare function createSsgRoutePayloadScript(route: SsgRoute): string;
+declare function injectSsgRoutePayload(html: string, route: SsgRoute): string;
+declare function createSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, { injectRoutePayload }?: {
+    injectRoutePayload?: boolean;
+}): string;
+declare function renderSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, options?: SsgRouteHtmlOptions): Promise<string>;
+
+declare function markdownFileToRoutePath(markdownFile: string, { landingPage }?: Pick<MarkdownSsgRoutesOptions, 'landingPage'>): string;
+declare function discoverMarkdownSsgRoutes({ root, include, exclude, landingPage, }: MarkdownSsgRoutesOptions): SsgRouteInput[];
+
+declare function prerenderSsgRoutes({ outDir, appHtmlFile, manifestFile, manifest, renderRoute, transformHtml, injectRoutePayload, }: PrerenderSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
+
+declare const defaultSsgManifestFile = "q-press-ssg-routes.json";
+declare const defaultSsgVirtualModuleId = "virtual:md-plugins/ssg-routes";
+declare function normalizeSsgBase(base?: string): string;
+declare function normalizeSsgRoutePath(path: string): string;
+declare function routePathToHtmlFile(routePath: string): string;
+declare function routePathToId(routePath: string): string;
+declare function normalizeSsgRoute(input: SsgRouteInput): SsgRoute;
+declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base }?: {
+    base?: string;
+}): SsgRouteManifest;
+
+/**
+ * Creates a route renderer that turns a fresh Vue/Quasar SSR app into static HTML.
+ */
+declare function createVueSsgRouteRenderer(options: VueSsgRouteRendererOptions): SsgRouteRenderer;
+/**
+ * Convenience wrapper for projects that prerender after a normal Vite/Quasar build.
+ */
+declare function prerenderVueSsgRoutes(options: PrerenderVueSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
+
+declare function viteSsgPlugin(options?: ViteSsgPluginOptions): Plugin;
+
+export { createSsgRouteHtml, createSsgRouteManifest, createSsgRoutePayloadScript, createVueSsgRouteRenderer, defaultSsgManifestFile, defaultSsgVirtualModuleId, discoverMarkdownSsgRoutes, escapeJsonForHtml, injectSsgRoutePayload, markdownFileToRoutePath, normalizeSsgBase, normalizeSsgRoute, normalizeSsgRoutePath, prerenderSsgRoutes, prerenderVueSsgRoutes, renderSsgRouteHtml, routePathToHtmlFile, routePathToId, viteSsgPlugin };
+export type { JsonPrimitive, JsonValue, MarkdownSsgRoutesOptions, MaybePromise, PrerenderSsgRoutesOptions, PrerenderSsgRoutesResult, PrerenderVueSsgRoutesOptions, PrerenderedSsgRoute, SsgRoute, SsgRouteHtmlOptions, SsgRouteHtmlTransformer, SsgRouteInput, SsgRouteManifest, SsgRouteMeta, SsgRouteObject, SsgRouteParams, SsgRouteRenderContext, SsgRouteRenderer, SsgRouteSource, ViteSsgPluginOptions, VueSsgAppFactory, VueSsgAppFactoryResult, VueSsgAppHtmlReplacer, VueSsgRenderToString, VueSsgRenderedAppHtmlTransformer, VueSsgRouteLocationResolver, VueSsgRouteRendererOptions, VueSsgRouterAdapter };

package/dist/index.mjs

@@ -0,0 +1,405 @@
+import { globSync } from 'tinyglobby';
+import { Buffer } from 'node:buffer';
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { resolve, join, dirname } from 'node:path';
+
+function escapeJsonForHtml(json) {
+  return json.replace(/</g, "\\u003C").replace(/>/g, "\\u003E").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function createSsgRoutePayloadScript(route) {
+  const payload = escapeJsonForHtml(JSON.stringify(route));
+  return `<script type="application/json" id="md-plugins-ssg-route">${payload}<\/script>`;
+}
+function injectSsgRoutePayload(html, route) {
+  const script = createSsgRoutePayloadScript(route);
+  if (html.includes('id="md-plugins-ssg-route"')) {
+    return html;
+  }
+  if (html.includes("</head>")) {
+    return html.replace("</head>", `${script}
+</head>`);
+  }
+  return `${script}
+${html}`;
+}
+function createSsgRouteHtml(route, context, { injectRoutePayload = true } = {}) {
+  if (injectRoutePayload === false) {
+    return context.appHtml;
+  }
+  return injectSsgRoutePayload(context.appHtml, route);
+}
+async function renderSsgRouteHtml(route, context, options = {}) {
+  const renderedHtml = await options.renderRoute?.(route, context);
+  const routeHtml = renderedHtml ?? createSsgRouteHtml(route, context, {
+    injectRoutePayload: options.injectRoutePayload
+  });
+  const html = renderedHtml && options.injectRoutePayload !== false ? injectSsgRoutePayload(routeHtml, route) : routeHtml;
+  return await options.transformHtml?.(html, route, context) ?? html;
+}
+
+const markdownExtensionRE = /\.md$/i;
+function normalizePatterns(patterns, fallback) {
+  if (patterns === void 0) {
+    return fallback;
+  }
+  return Array.isArray(patterns) ? patterns : [patterns];
+}
+function markdownFileToRoutePath(markdownFile, { landingPage = "landing-page.md" } = {}) {
+  const normalizedFile = markdownFile.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (normalizedFile === landingPage.replace(/\\/g, "/").replace(/^\.\//, "")) {
+    return "/";
+  }
+  const routeParts = normalizedFile.replace(markdownExtensionRE, "").split("/");
+  const lastPart = routeParts.at(-1);
+  const parentPart = routeParts.at(-2);
+  if (routeParts.length > 1 && lastPart === parentPart) {
+    routeParts.pop();
+  }
+  return `/${routeParts.join("/")}`;
+}
+function discoverMarkdownSsgRoutes({
+  root,
+  include,
+  exclude,
+  landingPage
+}) {
+  const files = globSync(normalizePatterns(include, ["**/*.md"]), {
+    cwd: root,
+    ignore: normalizePatterns(exclude, [])
+  }).sort();
+  return files.map((file) => ({
+    path: markdownFileToRoutePath(file, { landingPage }),
+    meta: {
+      source: "markdown",
+      file
+    }
+  }));
+}
+
+const defaultSsgManifestFile = "q-press-ssg-routes.json";
+const defaultSsgVirtualModuleId = "virtual:md-plugins/ssg-routes";
+function normalizeSsgBase(base = "/") {
+  const trimmed = base.trim();
+  if (trimmed === "" || trimmed === "/") {
+    return "/";
+  }
+  if (trimmed === "." || trimmed === "./") {
+    return "./";
+  }
+  if (/^[a-z]+:\/\//i.test(trimmed)) {
+    return trimmed.replace(/\/+$/, "");
+  }
+  const withLeadingSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  const withoutTrailingSlash = withLeadingSlash.replace(/\/+$/, "");
+  return withoutTrailingSlash || "/";
+}
+function normalizeSsgRoutePath(path) {
+  const trimmed = path.trim();
+  if (!trimmed) {
+    throw new Error("SSG route path cannot be empty");
+  }
+  const withoutHash = trimmed.split("#")[0] ?? "";
+  const withoutQuery = withoutHash.split("?")[0] ?? "";
+  const withLeadingSlash = withoutQuery.startsWith("/") ? withoutQuery : `/${withoutQuery}`;
+  const compacted = withLeadingSlash.replace(/\/{2,}/g, "/");
+  if (compacted === "/") {
+    return "/";
+  }
+  return compacted.replace(/\/+$/, "");
+}
+function routePathToHtmlFile(routePath) {
+  const normalized = normalizeSsgRoutePath(routePath);
+  if (normalized === "/") {
+    return "index.html";
+  }
+  return `${normalized.slice(1)}/index.html`;
+}
+function routePathToId(routePath) {
+  const normalized = normalizeSsgRoutePath(routePath);
+  if (normalized === "/") {
+    return "root";
+  }
+  return normalized.slice(1).replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function normalizeSsgRoute(input) {
+  const route = typeof input === "string" ? {
+    path: input,
+    meta: {},
+    params: {}
+  } : input;
+  const path = normalizeSsgRoutePath(route.path);
+  const meta = route.meta ?? {};
+  const params = route.params ?? {};
+  return {
+    path,
+    htmlFile: routePathToHtmlFile(path),
+    id: routePathToId(path),
+    meta,
+    params,
+    ...Object.hasOwn(route, "data") ? { data: route.data } : {}
+  };
+}
+function createSsgRouteManifest(routeInputs, { base = "/" } = {}) {
+  const routes = routeInputs.map(normalizeSsgRoute);
+  const routePaths = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    if (routePaths.has(route.path)) {
+      throw new Error(`Duplicate SSG route path: ${route.path}`);
+    }
+    routePaths.add(route.path);
+  }
+  return {
+    base: normalizeSsgBase(base),
+    routes
+  };
+}
+
+async function readSsgRouteManifest(outDir, manifestFile) {
+  const manifestJson = await readFile(join(outDir, manifestFile), "utf8");
+  return JSON.parse(manifestJson);
+}
+async function prerenderSsgRoutes({
+  outDir,
+  appHtmlFile = "index.html",
+  manifestFile = defaultSsgManifestFile,
+  manifest,
+  renderRoute,
+  transformHtml,
+  injectRoutePayload
+}) {
+  const resolvedOutDir = resolve(outDir);
+  const resolvedManifest = manifest ?? await readSsgRouteManifest(resolvedOutDir, manifestFile);
+  const appHtml = await readFile(join(resolvedOutDir, appHtmlFile), "utf8");
+  const routes = [];
+  for (const [routeIndex, route] of resolvedManifest.routes.entries()) {
+    const html = await renderSsgRouteHtml(
+      route,
+      {
+        appHtml,
+        manifest: resolvedManifest,
+        routeIndex
+      },
+      {
+        renderRoute,
+        transformHtml,
+        injectRoutePayload
+      }
+    );
+    const htmlPath = join(resolvedOutDir, route.htmlFile);
+    await mkdir(dirname(htmlPath), { recursive: true });
+    await writeFile(htmlPath, html);
+    routes.push({
+      path: route.path,
+      htmlFile: route.htmlFile,
+      bytes: Buffer.byteLength(html)
+    });
+  }
+  return {
+    manifest: resolvedManifest,
+    outDir: resolvedOutDir,
+    routes
+  };
+}
+
+const vueServerRendererPackage = "@vue/server-renderer";
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isVueSsgAppFactoryResult(value) {
+  return typeof value === "object" && value !== null && "app" in value;
+}
+async function loadVueRenderToString() {
+  try {
+    const renderer = await import(vueServerRendererPackage);
+    if (typeof renderer.renderToString === "function") {
+      return renderer.renderToString;
+    }
+  } catch (error) {
+    throw new Error(
+      [
+        "Unable to load @vue/server-renderer for SSG rendering.",
+        "Install it in the app that calls createVueSsgRouteRenderer(),",
+        "or pass a custom renderToString option.",
+        error instanceof Error ? `Original error: ${error.message}` : void 0
+      ].filter(Boolean).join(" ")
+    );
+  }
+  throw new Error("@vue/server-renderer did not export renderToString.");
+}
+function replaceMountElement(appHtml, renderedAppHtml, appMountId) {
+  const mountId = escapeRegExp(appMountId);
+  const mountElementRE = new RegExp(
+    `<([a-zA-Z][\\w:-]*)([^>]*\\bid=["']${mountId}["'][^>]*)>\\s*</\\1>`
+  );
+  if (!mountElementRE.test(appHtml)) {
+    throw new Error(`Could not find empty app mount element with id "${appMountId}".`);
+  }
+  return appHtml.replace(mountElementRE, `<$1$2>${renderedAppHtml}</$1>`);
+}
+async function pushRouterLocation(appResult, route, context, options) {
+  const router = appResult.router;
+  if (!router) {
+    return;
+  }
+  const location = appResult.routeLocation ?? options.routeLocation?.(route, context) ?? route.path;
+  const navigate = options.useRouterReplace === true ? router.replace ?? router.push : router.push ?? router.replace;
+  if (navigate) {
+    await navigate.call(router, location);
+  }
+  await router.isReady?.();
+}
+function createVueSsgRouteRenderer(options) {
+  return async (route, context) => {
+    const createdApp = await options.createApp(route, context);
+    const appResult = isVueSsgAppFactoryResult(createdApp) ? createdApp : { app: createdApp };
+    await pushRouterLocation(appResult, route, context, options);
+    const renderToString = options.renderToString ?? await loadVueRenderToString();
+    const renderedAppHtml = await renderToString(appResult.app, appResult.ssrContext);
+    const transformedAppHtml = await options.transformRenderedAppHtml?.(renderedAppHtml, route, context) ?? renderedAppHtml;
+    const html = options.replaceAppHtml ? options.replaceAppHtml(context.appHtml, transformedAppHtml, route, context) : replaceMountElement(context.appHtml, transformedAppHtml, options.appMountId ?? "q-app");
+    await appResult.onRendered?.();
+    return html;
+  };
+}
+async function prerenderVueSsgRoutes(options) {
+  const {
+    createApp,
+    renderToString,
+    appMountId,
+    routeLocation,
+    useRouterReplace,
+    transformRenderedAppHtml,
+    replaceAppHtml,
+    ...prerenderOptions
+  } = options;
+  return prerenderSsgRoutes({
+    ...prerenderOptions,
+    renderRoute: createVueSsgRouteRenderer({
+      createApp,
+      renderToString,
+      appMountId,
+      routeLocation,
+      useRouterReplace,
+      transformRenderedAppHtml,
+      replaceAppHtml
+    })
+  });
+}
+
+function isBundleAsset(entry) {
+  return typeof entry === "object" && entry !== null && "type" in entry && entry.type === "asset" && "fileName" in entry && typeof entry.fileName === "string" && "source" in entry;
+}
+function assetSourceToString(source) {
+  return typeof source === "string" ? source : Buffer.from(source).toString("utf8");
+}
+function findHtmlAsset(bundle, fileName) {
+  return Object.values(bundle).find(
+    (entry) => isBundleAsset(entry) && entry.fileName === fileName
+  );
+}
+function serializeManifestModule(manifest) {
+  const serializedManifest = JSON.stringify(manifest, null, 2);
+  return [
+    `export const ssgRouteManifest = ${serializedManifest}`,
+    "export const ssgRoutes = ssgRouteManifest.routes",
+    "export default ssgRouteManifest",
+    ""
+  ].join("\n");
+}
+async function resolveRouteInputs(options) {
+  const routeSource = options.routes;
+  const markdownRoutes = options.markdown ? discoverMarkdownSsgRoutes(options.markdown) : [];
+  if (!routeSource) {
+    return markdownRoutes;
+  }
+  if (typeof routeSource === "function") {
+    return [...markdownRoutes, ...await routeSource()];
+  }
+  return [...markdownRoutes, ...routeSource];
+}
+function viteSsgPlugin(options = {}) {
+  const virtualModuleId = options.virtualModuleId ?? defaultSsgVirtualModuleId;
+  const resolvedVirtualModuleId = `\0${virtualModuleId}`;
+  let config;
+  let manifest;
+  async function refreshManifest() {
+    const routes = await resolveRouteInputs(options);
+    manifest = createSsgRouteManifest(routes, {
+      base: options.base ?? config?.base ?? "/"
+    });
+    return manifest;
+  }
+  async function getManifest() {
+    return manifest ?? refreshManifest();
+  }
+  return {
+    name: "@md-plugins/vite-ssg-plugin",
+    enforce: "post",
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+    async buildStart() {
+      await refreshManifest();
+    },
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+      return void 0;
+    },
+    async load(id) {
+      if (id !== resolvedVirtualModuleId) {
+        return void 0;
+      }
+      return serializeManifestModule(await getManifest());
+    },
+    async generateBundle(_outputOptions, bundle) {
+      if (options.enabled === false) {
+        return;
+      }
+      const resolvedManifest = await refreshManifest();
+      const appHtmlFile = options.appHtmlFile ?? "index.html";
+      const appHtmlAsset = findHtmlAsset(bundle, appHtmlFile);
+      this.emitFile({
+        type: "asset",
+        fileName: options.manifestFile ?? defaultSsgManifestFile,
+        source: `${JSON.stringify(resolvedManifest, null, 2)}
+`
+      });
+      if (options.emitHtml === false) {
+        return;
+      }
+      const htmlAsset = appHtmlAsset;
+      if (!htmlAsset) {
+        this.warn(
+          `Could not find ${appHtmlFile}; skipped SSG route HTML generation. The route manifest was still emitted.`
+        );
+        return;
+      }
+      const appHtml = assetSourceToString(htmlAsset.source);
+      for (const [routeIndex, route] of resolvedManifest.routes.entries()) {
+        const context = {
+          appHtml,
+          manifest: resolvedManifest,
+          routeIndex
+        };
+        const transformedHtml = await renderSsgRouteHtml(route, context, {
+          renderRoute: options.renderRoute,
+          transformHtml: options.transformHtml,
+          injectRoutePayload: options.injectRoutePayload
+        });
+        if (route.htmlFile === appHtmlFile) {
+          htmlAsset.source = transformedHtml;
+          continue;
+        }
+        this.emitFile({
+          type: "asset",
+          fileName: route.htmlFile,
+          source: transformedHtml
+        });
+      }
+    }
+  };
+}
+
+export { createSsgRouteHtml, createSsgRouteManifest, createSsgRoutePayloadScript, createVueSsgRouteRenderer, defaultSsgManifestFile, defaultSsgVirtualModuleId, discoverMarkdownSsgRoutes, escapeJsonForHtml, injectSsgRoutePayload, markdownFileToRoutePath, normalizeSsgBase, normalizeSsgRoute, normalizeSsgRoutePath, prerenderSsgRoutes, prerenderVueSsgRoutes, renderSsgRouteHtml, routePathToHtmlFile, routePathToId, viteSsgPlugin };

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@md-plugins/vite-ssg-plugin",
+  "version": "0.1.0-beta.23",
+  "description": "A Vite plugin for @md-plugins static route inventory and future SSG output.",
+  "keywords": [
+    "markdown-it",
+    "quasarframework",
+    "ssg",
+    "static-site-generation",
+    "utils",
+    "vite",
+    "vite-plugin",
+    "vue"
+  ],
+  "homepage": "https://github.com/md-plugins",
+  "bugs": {
+    "url": "https://github.com/md-plugins/md-plugins/issues"
+  },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/md-plugins/md-plugins.git"
+  },
+  "files": [
+    "./dist"
+  ],
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tinyglobby": "^0.2.17"
+  },
+  "devDependencies": {
+    "vite": "^8.0.16"
+  },
+  "peerDependencies": {
+    "@vue/server-renderer": "^3.5.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@vue/server-renderer": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "unbuild",
+    "clean": "rm -rf dist/ node_modules/"
+  }
+}