@md-plugins/vite-ssg-plugin 0.1.0-rc.2 → 0.1.0-rc.3

package/README.md

@@ -6,12 +6,16 @@ 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.
+- Flatten static Vue Router route records for non-Markdown pages.
+- Exclude routes from manifests or prerender passes.
 - 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.
+- Crawl safe internal links, follow redirects, skip 404s, and write generation reports during
+  post-build prerendering when those behaviors are enabled.
 
 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
@@ -43,6 +47,25 @@ export default {
 }
 ```
 
+To include static Vue Router routes:
+
+```ts
+import { flattenStaticSsgRouterRoutes, viteSsgPlugin } from '@md-plugins/vite-ssg-plugin'
+import routes from './src/router/routes'
+
+export default {
+  plugins: [
+    viteSsgPlugin({
+      markdown: {
+        root: './src/markdown',
+      },
+      routes: flattenStaticSsgRouterRoutes(routes),
+      exclude: ['/drafts/private', /^\/admin/],
+    }),
+  ],
+}
+```
+
 For Q-Press-style Markdown docs:
 
 ```ts
@@ -121,6 +144,10 @@ import { prerenderSsgRoutes } from '@md-plugins/vite-ssg-plugin'
 
 await prerenderSsgRoutes({
   outDir: 'dist/spa',
+  concurrency: 4,
+  crawlLinks: true,
+  redirects: 'follow',
+  notFound: 'skip',
   async renderRoute(route, { appHtml }) {
     const renderedAppHtml = await renderMyAppAt(route.path)
 
@@ -133,12 +160,20 @@ The helper reads `q-press-ssg-routes.json`, renders every route, and writes each
 `index.html` file. The renderer can be a Vue SSR renderer, a Quasar SSR adapter, or any
 project-specific static renderer.
 
+The output directory is configurable. Q-Press defaults to `dist/spa` because that keeps existing
+static-host deployments simple, but non-Q-Press projects can use another output folder.
+
+By default, post-build prerendering writes `q-press-ssg-report.json`. Pass `reportFile: false` to
+disable reports, or provide hooks such as `onRouteRendered`, `onPageGenerated`, and `afterGenerate`
+for custom output.
+
 ## Vue / Quasar Build-Time Rendering
 
 For Q-Press apps, run the generated Q-Press command after a normal SPA build:
 
 ```bash
 pnpm build:ssg
+pnpm preview:ssg
 ```
 
 Projects that already have a Quasar SSR bundle can opt into that renderer with
@@ -181,5 +216,4 @@ 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.
+- Define project conventions for browser-only examples and lazy client hydration.

package/dist/index.d.mts

@@ -27,6 +27,7 @@ interface SsgRouteManifest {
     routes: SsgRoute[];
 }
 type SsgRouteSource = SsgRouteInput[] | (() => MaybePromise<SsgRouteInput[]>);
+type SsgRouteExclusion = string | RegExp;
 interface MarkdownSsgRoutesOptions {
     /**
      * Directory containing Markdown pages.
@@ -83,17 +84,95 @@ interface PrerenderSsgRoutesOptions extends SsgRouteHtmlOptions {
      * Manifest to use instead of reading one from disk.
      */
     manifest?: SsgRouteManifest;
+    /**
+     * Routes to skip while prerendering. String values are matched after route
+     * normalization; RegExp values are tested against normalized route paths.
+     */
+    exclude?: SsgRouteExclusion[];
+    /**
+     * Number of routes to prerender at the same time. Defaults to 1.
+     */
+    concurrency?: number;
+    /**
+     * Milliseconds to wait between prerender batches. Defaults to 0.
+     */
+    interval?: number;
+    /**
+     * Crawl rendered HTML for safe internal links and enqueue missing routes.
+     * Defaults to false.
+     */
+    crawlLinks?: boolean;
+    /**
+     * Redirect behavior for renderer errors with a string `url` property.
+     * Defaults to error to preserve strict generic behavior.
+     */
+    redirects?: 'error' | 'follow' | 'skip';
+    /**
+     * Not-found behavior for renderer errors with code/status/statusCode 404.
+     * Defaults to error to preserve strict generic behavior.
+     */
+    notFound?: 'error' | 'skip';
+    /**
+     * Optional JSON report file written inside outDir. Defaults to
+     * q-press-ssg-report.json. Pass false to disable report output.
+     */
+    reportFile?: string | false;
+    /**
+     * Hook after a route is rendered and transformed, before crawling and writing.
+     */
+    onRouteRendered?: SsgRouteRenderedHook;
+    /**
+     * Hook before a generated page is written. Can adjust html and output path.
+     */
+    onPageGenerated?: SsgPageGeneratedHook;
+    /**
+     * Hook after all routes have completed and the report has been assembled.
+     */
+    afterGenerate?: SsgAfterGenerateHook;
 }
 interface PrerenderedSsgRoute {
     path: string;
     htmlFile: string;
     bytes: number;
+    milliseconds?: number;
+}
+interface SkippedSsgRoute {
+    path: string;
+    reason: 'excluded' | 'not-found' | 'redirected' | 'skipped-redirect';
+    target?: string;
+}
+interface SsgGenerationWarning {
+    path: string;
+    message: string;
+}
+interface SsgGenerationReport {
+    generatedAt: string;
+    outDir: string;
+    manifestFile: string;
+    routeCount: number;
+    generated: PrerenderedSsgRoute[];
+    skipped: SkippedSsgRoute[];
+    warnings: SsgGenerationWarning[];
 }
 interface PrerenderSsgRoutesResult {
     manifest: SsgRouteManifest;
     outDir: string;
     routes: PrerenderedSsgRoute[];
+    skipped: SkippedSsgRoute[];
+    warnings: SsgGenerationWarning[];
+    report?: SsgGenerationReport;
 }
+interface SsgGeneratedPage {
+    route: SsgRoute;
+    html: string;
+    htmlFile: string;
+    filePath: string;
+}
+type SsgRouteRenderedHook = (html: string, route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string | void>;
+type SsgPageGeneratedHook = (page: SsgGeneratedPage, context: SsgRouteRenderContext) => MaybePromise<Partial<Pick<SsgGeneratedPage, 'html' | 'htmlFile' | 'filePath'>> | void>;
+type SsgAfterGenerateHook = (result: Omit<PrerenderSsgRoutesResult, 'report'> & {
+    report: SsgGenerationReport;
+}) => MaybePromise<void>;
 interface VueSsgRouterAdapter {
     push?: (location: unknown) => MaybePromise<unknown>;
     replace?: (location: unknown) => MaybePromise<unknown>;
@@ -152,6 +231,10 @@ interface ViteSsgPluginOptions {
      * Static route declarations or a function that resolves them.
      */
     routes?: SsgRouteSource;
+    /**
+     * Routes to exclude from the generated manifest.
+     */
+    exclude?: SsgRouteExclusion[];
     /**
      * Optional Markdown route discovery. This can be combined with explicit routes.
      */
@@ -185,28 +268,94 @@ interface ViteSsgPluginOptions {
     virtualModuleId?: string;
 }
 
+/**
+ * Escapes JSON so it can be embedded safely inside an HTML `<script>` tag.
+ */
 declare function escapeJsonForHtml(json: string): string;
+/**
+ * Serializes an SSG route into the route payload script consumed during hydration.
+ */
 declare function createSsgRoutePayloadScript(route: SsgRoute): string;
+/**
+ * Injects the route payload script into an HTML shell without duplicating it.
+ */
 declare function injectSsgRoutePayload(html: string, route: SsgRoute): string;
+/**
+ * Creates the default per-route HTML shell for a static SSG route.
+ */
 declare function createSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, { injectRoutePayload }?: {
     injectRoutePayload?: boolean;
 }): string;
+/**
+ * Renders one SSG route, optionally delegating to a framework renderer and HTML transform.
+ */
 declare function renderSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, options?: SsgRouteHtmlOptions): Promise<string>;
 
+/**
+ * Converts a Markdown file path into the route path generated by Q-Press conventions.
+ */
 declare function markdownFileToRoutePath(markdownFile: string, { landingPage }?: Pick<MarkdownSsgRoutesOptions, 'landingPage'>): string;
+/**
+ * Discovers Markdown files and converts them into SSG route inputs.
+ */
 declare function discoverMarkdownSsgRoutes({ root, include, exclude, landingPage, }: MarkdownSsgRoutesOptions): SsgRouteInput[];
 
-declare function prerenderSsgRoutes({ outDir, appHtmlFile, manifestFile, manifest, renderRoute, transformHtml, injectRoutePayload, }: PrerenderSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
+/**
+ * Prerenders every route in an SSG manifest into static HTML files.
+ *
+ * The renderer can use the default HTML-shell mode, a custom route renderer, or
+ * a framework-specific renderer such as the Vue adapter.
+ */
+declare function prerenderSsgRoutes({ outDir, appHtmlFile, manifestFile, manifest, exclude, concurrency, interval, crawlLinks, redirects, notFound, reportFile, onRouteRendered, onPageGenerated, afterGenerate, renderRoute, transformHtml, injectRoutePayload, }: PrerenderSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
 
 declare const defaultSsgManifestFile = "q-press-ssg-routes.json";
+declare const defaultSsgReportFile = "q-press-ssg-report.json";
 declare const defaultSsgVirtualModuleId = "virtual:md-plugins/ssg-routes";
+interface SsgRouterRouteLike {
+    path?: string;
+    children?: SsgRouterRouteLike[];
+}
+/**
+ * Normalizes a Vite base value for use in generated SSG manifests and links.
+ */
 declare function normalizeSsgBase(base?: string): string;
+/**
+ * Normalizes a route path into an absolute path without query, hash, or trailing slash.
+ */
 declare function normalizeSsgRoutePath(path: string): string;
+/**
+ * Checks whether a route path can be emitted as a static HTML file.
+ */
+declare function isStaticSsgRoutePath(path: string): boolean;
+/**
+ * Converts a route path to the HTML file emitted for that route.
+ */
 declare function routePathToHtmlFile(routePath: string): string;
+/**
+ * Converts a route path into a stable id for manifest entries and diagnostics.
+ */
 declare function routePathToId(routePath: string): string;
+/**
+ * Returns whether a normalized route path matches one of the configured exclusions.
+ */
+declare function isSsgRouteExcluded(path: string, exclude?: SsgRouteExclusion[]): boolean;
+/**
+ * Flattens Vue Router-style route records into static SSG route paths.
+ */
+declare function flattenStaticSsgRouterRoutes(routes: SsgRouterRouteLike[], { base, exclude }?: {
+    base?: string;
+    exclude?: SsgRouteExclusion[];
+}): string[];
+/**
+ * Converts a string or object route input into a complete manifest route entry.
+ */
 declare function normalizeSsgRoute(input: SsgRouteInput): SsgRoute;
-declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base }?: {
+/**
+ * Builds and validates an SSG route manifest from route inputs.
+ */
+declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base, exclude }?: {
     base?: string;
+    exclude?: SsgRouteExclusion[];
 }): SsgRouteManifest;
 
 /**
@@ -214,11 +363,14 @@ declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base }?:
  */
 declare function createVueSsgRouteRenderer(options: VueSsgRouteRendererOptions): SsgRouteRenderer;
 /**
- * Convenience wrapper for projects that prerender after a normal Vite/Quasar build.
+ * Prerenders Vite/Quasar routes with a Vue app factory in one call.
  */
 declare function prerenderVueSsgRoutes(options: PrerenderVueSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
 
+/**
+ * Creates the Vite plugin that emits SSG route manifests and optional route HTML shells.
+ */
 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 };
+export { createSsgRouteHtml, createSsgRouteManifest, createSsgRoutePayloadScript, createVueSsgRouteRenderer, defaultSsgManifestFile, defaultSsgReportFile, defaultSsgVirtualModuleId, discoverMarkdownSsgRoutes, escapeJsonForHtml, flattenStaticSsgRouterRoutes, injectSsgRoutePayload, isSsgRouteExcluded, isStaticSsgRoutePath, markdownFileToRoutePath, normalizeSsgBase, normalizeSsgRoute, normalizeSsgRoutePath, prerenderSsgRoutes, prerenderVueSsgRoutes, renderSsgRouteHtml, routePathToHtmlFile, routePathToId, viteSsgPlugin };
+export type { JsonPrimitive, JsonValue, MarkdownSsgRoutesOptions, MaybePromise, PrerenderSsgRoutesOptions, PrerenderSsgRoutesResult, PrerenderVueSsgRoutesOptions, PrerenderedSsgRoute, SkippedSsgRoute, SsgAfterGenerateHook, SsgGeneratedPage, SsgGenerationReport, SsgGenerationWarning, SsgPageGeneratedHook, SsgRoute, SsgRouteExclusion, SsgRouteHtmlOptions, SsgRouteHtmlTransformer, SsgRouteInput, SsgRouteManifest, SsgRouteMeta, SsgRouteObject, SsgRouteParams, SsgRouteRenderContext, SsgRouteRenderedHook, SsgRouteRenderer, SsgRouteSource, SsgRouterRouteLike, ViteSsgPluginOptions, VueSsgAppFactory, VueSsgAppFactoryResult, VueSsgAppHtmlReplacer, VueSsgRenderToString, VueSsgRenderedAppHtmlTransformer, VueSsgRouteLocationResolver, VueSsgRouteRendererOptions, VueSsgRouterAdapter };

package/dist/index.d.ts

@@ -27,6 +27,7 @@ interface SsgRouteManifest {
     routes: SsgRoute[];
 }
 type SsgRouteSource = SsgRouteInput[] | (() => MaybePromise<SsgRouteInput[]>);
+type SsgRouteExclusion = string | RegExp;
 interface MarkdownSsgRoutesOptions {
     /**
      * Directory containing Markdown pages.
@@ -83,17 +84,95 @@ interface PrerenderSsgRoutesOptions extends SsgRouteHtmlOptions {
      * Manifest to use instead of reading one from disk.
      */
     manifest?: SsgRouteManifest;
+    /**
+     * Routes to skip while prerendering. String values are matched after route
+     * normalization; RegExp values are tested against normalized route paths.
+     */
+    exclude?: SsgRouteExclusion[];
+    /**
+     * Number of routes to prerender at the same time. Defaults to 1.
+     */
+    concurrency?: number;
+    /**
+     * Milliseconds to wait between prerender batches. Defaults to 0.
+     */
+    interval?: number;
+    /**
+     * Crawl rendered HTML for safe internal links and enqueue missing routes.
+     * Defaults to false.
+     */
+    crawlLinks?: boolean;
+    /**
+     * Redirect behavior for renderer errors with a string `url` property.
+     * Defaults to error to preserve strict generic behavior.
+     */
+    redirects?: 'error' | 'follow' | 'skip';
+    /**
+     * Not-found behavior for renderer errors with code/status/statusCode 404.
+     * Defaults to error to preserve strict generic behavior.
+     */
+    notFound?: 'error' | 'skip';
+    /**
+     * Optional JSON report file written inside outDir. Defaults to
+     * q-press-ssg-report.json. Pass false to disable report output.
+     */
+    reportFile?: string | false;
+    /**
+     * Hook after a route is rendered and transformed, before crawling and writing.
+     */
+    onRouteRendered?: SsgRouteRenderedHook;
+    /**
+     * Hook before a generated page is written. Can adjust html and output path.
+     */
+    onPageGenerated?: SsgPageGeneratedHook;
+    /**
+     * Hook after all routes have completed and the report has been assembled.
+     */
+    afterGenerate?: SsgAfterGenerateHook;
 }
 interface PrerenderedSsgRoute {
     path: string;
     htmlFile: string;
     bytes: number;
+    milliseconds?: number;
+}
+interface SkippedSsgRoute {
+    path: string;
+    reason: 'excluded' | 'not-found' | 'redirected' | 'skipped-redirect';
+    target?: string;
+}
+interface SsgGenerationWarning {
+    path: string;
+    message: string;
+}
+interface SsgGenerationReport {
+    generatedAt: string;
+    outDir: string;
+    manifestFile: string;
+    routeCount: number;
+    generated: PrerenderedSsgRoute[];
+    skipped: SkippedSsgRoute[];
+    warnings: SsgGenerationWarning[];
 }
 interface PrerenderSsgRoutesResult {
     manifest: SsgRouteManifest;
     outDir: string;
     routes: PrerenderedSsgRoute[];
+    skipped: SkippedSsgRoute[];
+    warnings: SsgGenerationWarning[];
+    report?: SsgGenerationReport;
 }
+interface SsgGeneratedPage {
+    route: SsgRoute;
+    html: string;
+    htmlFile: string;
+    filePath: string;
+}
+type SsgRouteRenderedHook = (html: string, route: SsgRoute, context: SsgRouteRenderContext) => MaybePromise<string | void>;
+type SsgPageGeneratedHook = (page: SsgGeneratedPage, context: SsgRouteRenderContext) => MaybePromise<Partial<Pick<SsgGeneratedPage, 'html' | 'htmlFile' | 'filePath'>> | void>;
+type SsgAfterGenerateHook = (result: Omit<PrerenderSsgRoutesResult, 'report'> & {
+    report: SsgGenerationReport;
+}) => MaybePromise<void>;
 interface VueSsgRouterAdapter {
     push?: (location: unknown) => MaybePromise<unknown>;
     replace?: (location: unknown) => MaybePromise<unknown>;
@@ -152,6 +231,10 @@ interface ViteSsgPluginOptions {
      * Static route declarations or a function that resolves them.
      */
     routes?: SsgRouteSource;
+    /**
+     * Routes to exclude from the generated manifest.
+     */
+    exclude?: SsgRouteExclusion[];
     /**
      * Optional Markdown route discovery. This can be combined with explicit routes.
      */
@@ -185,28 +268,94 @@ interface ViteSsgPluginOptions {
     virtualModuleId?: string;
 }
 
+/**
+ * Escapes JSON so it can be embedded safely inside an HTML `<script>` tag.
+ */
 declare function escapeJsonForHtml(json: string): string;
+/**
+ * Serializes an SSG route into the route payload script consumed during hydration.
+ */
 declare function createSsgRoutePayloadScript(route: SsgRoute): string;
+/**
+ * Injects the route payload script into an HTML shell without duplicating it.
+ */
 declare function injectSsgRoutePayload(html: string, route: SsgRoute): string;
+/**
+ * Creates the default per-route HTML shell for a static SSG route.
+ */
 declare function createSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, { injectRoutePayload }?: {
     injectRoutePayload?: boolean;
 }): string;
+/**
+ * Renders one SSG route, optionally delegating to a framework renderer and HTML transform.
+ */
 declare function renderSsgRouteHtml(route: SsgRoute, context: SsgRouteRenderContext, options?: SsgRouteHtmlOptions): Promise<string>;
 
+/**
+ * Converts a Markdown file path into the route path generated by Q-Press conventions.
+ */
 declare function markdownFileToRoutePath(markdownFile: string, { landingPage }?: Pick<MarkdownSsgRoutesOptions, 'landingPage'>): string;
+/**
+ * Discovers Markdown files and converts them into SSG route inputs.
+ */
 declare function discoverMarkdownSsgRoutes({ root, include, exclude, landingPage, }: MarkdownSsgRoutesOptions): SsgRouteInput[];
 
-declare function prerenderSsgRoutes({ outDir, appHtmlFile, manifestFile, manifest, renderRoute, transformHtml, injectRoutePayload, }: PrerenderSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
+/**
+ * Prerenders every route in an SSG manifest into static HTML files.
+ *
+ * The renderer can use the default HTML-shell mode, a custom route renderer, or
+ * a framework-specific renderer such as the Vue adapter.
+ */
+declare function prerenderSsgRoutes({ outDir, appHtmlFile, manifestFile, manifest, exclude, concurrency, interval, crawlLinks, redirects, notFound, reportFile, onRouteRendered, onPageGenerated, afterGenerate, renderRoute, transformHtml, injectRoutePayload, }: PrerenderSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
 
 declare const defaultSsgManifestFile = "q-press-ssg-routes.json";
+declare const defaultSsgReportFile = "q-press-ssg-report.json";
 declare const defaultSsgVirtualModuleId = "virtual:md-plugins/ssg-routes";
+interface SsgRouterRouteLike {
+    path?: string;
+    children?: SsgRouterRouteLike[];
+}
+/**
+ * Normalizes a Vite base value for use in generated SSG manifests and links.
+ */
 declare function normalizeSsgBase(base?: string): string;
+/**
+ * Normalizes a route path into an absolute path without query, hash, or trailing slash.
+ */
 declare function normalizeSsgRoutePath(path: string): string;
+/**
+ * Checks whether a route path can be emitted as a static HTML file.
+ */
+declare function isStaticSsgRoutePath(path: string): boolean;
+/**
+ * Converts a route path to the HTML file emitted for that route.
+ */
 declare function routePathToHtmlFile(routePath: string): string;
+/**
+ * Converts a route path into a stable id for manifest entries and diagnostics.
+ */
 declare function routePathToId(routePath: string): string;
+/**
+ * Returns whether a normalized route path matches one of the configured exclusions.
+ */
+declare function isSsgRouteExcluded(path: string, exclude?: SsgRouteExclusion[]): boolean;
+/**
+ * Flattens Vue Router-style route records into static SSG route paths.
+ */
+declare function flattenStaticSsgRouterRoutes(routes: SsgRouterRouteLike[], { base, exclude }?: {
+    base?: string;
+    exclude?: SsgRouteExclusion[];
+}): string[];
+/**
+ * Converts a string or object route input into a complete manifest route entry.
+ */
 declare function normalizeSsgRoute(input: SsgRouteInput): SsgRoute;
-declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base }?: {
+/**
+ * Builds and validates an SSG route manifest from route inputs.
+ */
+declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base, exclude }?: {
     base?: string;
+    exclude?: SsgRouteExclusion[];
 }): SsgRouteManifest;
 
 /**
@@ -214,11 +363,14 @@ declare function createSsgRouteManifest(routeInputs: SsgRouteInput[], { base }?:
  */
 declare function createVueSsgRouteRenderer(options: VueSsgRouteRendererOptions): SsgRouteRenderer;
 /**
- * Convenience wrapper for projects that prerender after a normal Vite/Quasar build.
+ * Prerenders Vite/Quasar routes with a Vue app factory in one call.
  */
 declare function prerenderVueSsgRoutes(options: PrerenderVueSsgRoutesOptions): Promise<PrerenderSsgRoutesResult>;
 
+/**
+ * Creates the Vite plugin that emits SSG route manifests and optional route HTML shells.
+ */
 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 };
+export { createSsgRouteHtml, createSsgRouteManifest, createSsgRoutePayloadScript, createVueSsgRouteRenderer, defaultSsgManifestFile, defaultSsgReportFile, defaultSsgVirtualModuleId, discoverMarkdownSsgRoutes, escapeJsonForHtml, flattenStaticSsgRouterRoutes, injectSsgRoutePayload, isSsgRouteExcluded, isStaticSsgRoutePath, markdownFileToRoutePath, normalizeSsgBase, normalizeSsgRoute, normalizeSsgRoutePath, prerenderSsgRoutes, prerenderVueSsgRoutes, renderSsgRouteHtml, routePathToHtmlFile, routePathToId, viteSsgPlugin };
+export type { JsonPrimitive, JsonValue, MarkdownSsgRoutesOptions, MaybePromise, PrerenderSsgRoutesOptions, PrerenderSsgRoutesResult, PrerenderVueSsgRoutesOptions, PrerenderedSsgRoute, SkippedSsgRoute, SsgAfterGenerateHook, SsgGeneratedPage, SsgGenerationReport, SsgGenerationWarning, SsgPageGeneratedHook, SsgRoute, SsgRouteExclusion, SsgRouteHtmlOptions, SsgRouteHtmlTransformer, SsgRouteInput, SsgRouteManifest, SsgRouteMeta, SsgRouteObject, SsgRouteParams, SsgRouteRenderContext, SsgRouteRenderedHook, SsgRouteRenderer, SsgRouteSource, SsgRouterRouteLike, ViteSsgPluginOptions, VueSsgAppFactory, VueSsgAppFactoryResult, VueSsgAppHtmlReplacer, VueSsgRenderToString, VueSsgRenderedAppHtmlTransformer, VueSsgRouteLocationResolver, VueSsgRouteRendererOptions, VueSsgRouterAdapter };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { globSync } from 'tinyglobby';
 import { Buffer } from 'node:buffer';
-import { readFile, mkdir, writeFile, readdir } from 'node:fs/promises';
-import { resolve, join, dirname } from 'node:path';
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { resolve, join, dirname, posix } 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");
@@ -77,6 +77,7 @@ function discoverMarkdownSsgRoutes({
 }
 
 const defaultSsgManifestFile = "q-press-ssg-routes.json";
+const defaultSsgReportFile = "q-press-ssg-report.json";
 const defaultSsgVirtualModuleId = "virtual:md-plugins/ssg-routes";
 function normalizeSsgBase(base = "/") {
   const trimmed = base.trim();
@@ -107,6 +108,10 @@ function normalizeSsgRoutePath(path) {
   }
   return compacted.replace(/\/+$/, "");
 }
+function isStaticSsgRoutePath(path) {
+  const normalized = normalizeSsgRoutePath(path);
+  return normalized.startsWith("/") && !normalized.startsWith("//") && !normalized.includes(":") && !normalized.includes("*") && !/\.[a-z0-9]+$/i.test(normalized);
+}
 function routePathToHtmlFile(routePath) {
   const normalized = normalizeSsgRoutePath(routePath);
   if (normalized === "/") {
@@ -121,6 +126,37 @@ function routePathToId(routePath) {
   }
   return normalized.slice(1).replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
+function isSsgRouteExcluded(path, exclude = []) {
+  const normalized = normalizeSsgRoutePath(path);
+  return exclude.some(
+    (pattern) => typeof pattern === "string" ? normalizeSsgRoutePath(pattern) === normalized : pattern.test(normalized)
+  );
+}
+function joinRoutePaths(parentPath, childPath) {
+  if (!childPath || childPath === "/") {
+    return parentPath || "/";
+  }
+  if (childPath.startsWith("/")) {
+    return childPath;
+  }
+  return `${parentPath.replace(/\/+$/, "")}/${childPath}` || "/";
+}
+function flattenStaticSsgRouterRoutes(routes, { base = "", exclude = [] } = {}) {
+  const routePaths = [];
+  function visit(route, parentPath) {
+    const path = joinRoutePaths(parentPath, route.path ?? "");
+    if (isStaticSsgRoutePath(path) && !isSsgRouteExcluded(path, exclude)) {
+      routePaths.push(path);
+    }
+    for (const child of route.children ?? []) {
+      visit(child, path);
+    }
+  }
+  for (const route of routes) {
+    visit(route, base);
+  }
+  return Array.from(new Set(routePaths.map(normalizeSsgRoutePath)));
+}
 function normalizeSsgRoute(input) {
   const route = typeof input === "string" ? {
     path: input,
@@ -139,8 +175,8 @@ function normalizeSsgRoute(input) {
     ...Object.hasOwn(route, "data") ? { data: route.data } : {}
   };
 }
-function createSsgRouteManifest(routeInputs, { base = "/" } = {}) {
-  const routes = routeInputs.map(normalizeSsgRoute);
+function createSsgRouteManifest(routeInputs, { base = "/", exclude = [] } = {}) {
+  const routes = routeInputs.map(normalizeSsgRoute).filter((route) => !isSsgRouteExcluded(route.path, exclude));
   const routePaths = /* @__PURE__ */ new Set();
   for (const route of routes) {
     if (routePaths.has(route.path)) {
@@ -192,51 +228,263 @@ async function injectMissingCssAssets(appHtml, outDir, base) {
 `;
   return appHtml.includes("</head>") ? appHtml.replace("</head>", `${content}</head>`) : `${content}${appHtml}`;
 }
+function clampConcurrency(concurrency) {
+  return Math.max(1, Math.floor(concurrency ?? 1));
+}
+function clampInterval(interval) {
+  return Math.max(0, Math.floor(interval ?? 0));
+}
+function wait(milliseconds) {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, milliseconds);
+  });
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function getRedirectTarget(error) {
+  if (!isRecord(error)) {
+    return void 0;
+  }
+  return typeof error.url === "string" ? error.url : void 0;
+}
+function isNotFoundError(error) {
+  if (!isRecord(error)) {
+    return false;
+  }
+  return error.code === 404 || error.status === 404 || error.statusCode === 404;
+}
+function extractAnchorHrefs(html) {
+  const hrefs = [];
+  const anchorHrefRE = /<a\b[^>]*\bhref\s*=\s*(["'])(.*?)\1/gi;
+  let match;
+  while (match = anchorHrefRE.exec(html)) {
+    hrefs.push(match[2]);
+  }
+  return hrefs;
+}
+function isExternalHref(href) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("//");
+}
+function stripBaseFromPath(path, base) {
+  if (base === "/" || base === "./" || base.startsWith("http://") || base.startsWith("https://")) {
+    return path;
+  }
+  const normalizedBase = normalizeSsgRoutePath(base);
+  if (path === normalizedBase) {
+    return "/";
+  }
+  return path.startsWith(`${normalizedBase}/`) ? path.slice(normalizedBase.length) : path;
+}
+function resolveHrefPath(hrefPath, fromRoutePath) {
+  if (hrefPath.startsWith("/")) {
+    return hrefPath;
+  }
+  const routeBase = fromRoutePath === "/" ? "/" : posix.dirname(fromRoutePath);
+  return posix.normalize(posix.join(routeBase, hrefPath));
+}
+function hrefToSsgRoutePath(href, base, fromRoutePath = "/") {
+  const trimmed = href.trim();
+  if (!trimmed || trimmed.startsWith("#") || isExternalHref(trimmed)) {
+    return void 0;
+  }
+  const withoutHash = trimmed.split("#")[0] ?? "";
+  const withoutQuery = withoutHash.split("?")[0] ?? "";
+  if (!withoutQuery || withoutQuery.startsWith(".")) {
+    return void 0;
+  }
+  try {
+    const routePath = stripBaseFromPath(resolveHrefPath(withoutQuery, fromRoutePath), base);
+    return isStaticSsgRoutePath(routePath) ? normalizeSsgRoutePath(routePath) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function extractSsgRouteLinks(html, base, fromRoutePath) {
+  return Array.from(
+    new Set(
+      extractAnchorHrefs(html).map((href) => hrefToSsgRoutePath(href, base, fromRoutePath)).filter((path) => path !== void 0)
+    )
+  );
+}
+function createReport({
+  generated,
+  manifest,
+  manifestFile,
+  outDir,
+  skipped,
+  warnings
+}) {
+  return {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    outDir,
+    manifestFile,
+    routeCount: manifest.routes.length,
+    generated,
+    skipped,
+    warnings
+  };
+}
 async function prerenderSsgRoutes({
   outDir,
   appHtmlFile = "index.html",
   manifestFile = defaultSsgManifestFile,
   manifest,
+  exclude,
+  concurrency,
+  interval,
+  crawlLinks = false,
+  redirects = "error",
+  notFound = "error",
+  reportFile = defaultSsgReportFile,
+  onRouteRendered,
+  onPageGenerated,
+  afterGenerate,
   renderRoute,
   transformHtml,
   injectRoutePayload
 }) {
   const resolvedOutDir = resolve(outDir);
-  const resolvedManifest = manifest ?? await readSsgRouteManifest(resolvedOutDir, manifestFile);
+  const rawManifest = manifest ?? await readSsgRouteManifest(resolvedOutDir, manifestFile);
+  const resolvedManifest = createSsgRouteManifest(rawManifest.routes, {
+    base: rawManifest.base,
+    exclude
+  });
   const appHtml = await injectMissingCssAssets(
     await readFile(join(resolvedOutDir, appHtmlFile), "utf8"),
     resolvedOutDir,
     resolvedManifest.base
   );
   const routes = [];
-  for (const [routeIndex, route] of resolvedManifest.routes.entries()) {
-    const html = await renderSsgRouteHtml(
-      route,
-      {
-        appHtml,
-        manifest: resolvedManifest,
-        routeIndex
-      },
-      {
+  const skipped = rawManifest.routes.filter((route) => isSsgRouteExcluded(route.path, exclude ?? [])).map((route) => ({
+    path: route.path,
+    reason: "excluded"
+  }));
+  const warnings = [];
+  const queue = [...resolvedManifest.routes];
+  const enqueuedPaths = new Set(queue.map((route) => route.path));
+  const maxConcurrency = clampConcurrency(concurrency);
+  const batchInterval = clampInterval(interval);
+  function enqueueRoute(routeInput) {
+    const route = normalizeSsgRoute(routeInput);
+    if (isSsgRouteExcluded(route.path, exclude ?? []) || enqueuedPaths.has(route.path)) {
+      return void 0;
+    }
+    enqueuedPaths.add(route.path);
+    resolvedManifest.routes.push(route);
+    queue.push(route);
+    return route;
+  }
+  async function renderOne(route) {
+    const start = performance.now();
+    const routeIndex = resolvedManifest.routes.findIndex((entry) => entry.path === route.path);
+    const context = {
+      appHtml,
+      manifest: resolvedManifest,
+      routeIndex
+    };
+    try {
+      let html = await renderSsgRouteHtml(route, context, {
         renderRoute,
         transformHtml,
         injectRoutePayload
+      });
+      const renderedHtml = await onRouteRendered?.(html, route, context);
+      if (typeof renderedHtml === "string") {
+        html = renderedHtml;
       }
-    );
-    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)
-    });
+      if (crawlLinks) {
+        for (const linkedRoute of extractSsgRouteLinks(html, resolvedManifest.base, route.path)) {
+          enqueueRoute(linkedRoute);
+        }
+      }
+      const htmlPath = join(resolvedOutDir, route.htmlFile);
+      const page = {
+        route,
+        html,
+        htmlFile: route.htmlFile,
+        filePath: htmlPath
+      };
+      const pageUpdate = await onPageGenerated?.(page, context);
+      const finalHtml = pageUpdate?.html ?? page.html;
+      const finalHtmlFile = pageUpdate?.htmlFile ?? page.htmlFile;
+      const finalFilePath = pageUpdate?.filePath ?? join(resolvedOutDir, finalHtmlFile);
+      await mkdir(dirname(finalFilePath), { recursive: true });
+      await writeFile(finalFilePath, finalHtml);
+      routes.push({
+        path: route.path,
+        htmlFile: finalHtmlFile,
+        bytes: Buffer.byteLength(finalHtml),
+        milliseconds: Math.round(performance.now() - start)
+      });
+    } catch (error) {
+      const redirectTarget = getRedirectTarget(error);
+      if (redirectTarget !== void 0) {
+        if (redirects === "follow") {
+          const target = hrefToSsgRoutePath(redirectTarget, resolvedManifest.base, route.path);
+          if (target) {
+            enqueueRoute(target);
+          }
+          skipped.push({
+            path: route.path,
+            reason: "redirected",
+            target: target ?? redirectTarget
+          });
+          return;
+        }
+        if (redirects === "skip") {
+          skipped.push({
+            path: route.path,
+            reason: "skipped-redirect",
+            target: redirectTarget
+          });
+          return;
+        }
+      }
+      if (isNotFoundError(error) && notFound === "skip") {
+        skipped.push({
+          path: route.path,
+          reason: "not-found"
+        });
+        return;
+      }
+      throw error;
+    }
   }
-  return {
+  while (queue.length > 0) {
+    const batch = queue.splice(0, maxConcurrency);
+    await Promise.all(batch.map((route) => renderOne(route)));
+    if (queue.length > 0 && batchInterval > 0) {
+      await wait(batchInterval);
+    }
+  }
+  await writeFile(
+    join(resolvedOutDir, manifestFile),
+    `${JSON.stringify(resolvedManifest, null, 2)}
+`
+  );
+  const report = createReport({
+    generated: routes,
     manifest: resolvedManifest,
+    manifestFile,
     outDir: resolvedOutDir,
-    routes
+    skipped,
+    warnings
+  });
+  if (reportFile !== false) {
+    await writeFile(join(resolvedOutDir, reportFile), `${JSON.stringify(report, null, 2)}
+`);
+  }
+  const result = {
+    manifest: resolvedManifest,
+    outDir: resolvedOutDir,
+    routes,
+    skipped,
+    warnings,
+    report
   };
+  await afterGenerate?.(result);
+  return result;
 }
 
 const vueServerRendererPackage = "@vue/server-renderer";
@@ -363,7 +611,8 @@ function viteSsgPlugin(options = {}) {
   async function refreshManifest() {
     const routes = await resolveRouteInputs(options);
     manifest = createSsgRouteManifest(routes, {
-      base: options.base ?? config?.base ?? "/"
+      base: options.base ?? config?.base ?? "/",
+      exclude: options.exclude
     });
     return manifest;
   }
@@ -440,4 +689,4 @@ function viteSsgPlugin(options = {}) {
   };
 }
 
-export { createSsgRouteHtml, createSsgRouteManifest, createSsgRoutePayloadScript, createVueSsgRouteRenderer, defaultSsgManifestFile, defaultSsgVirtualModuleId, discoverMarkdownSsgRoutes, escapeJsonForHtml, injectSsgRoutePayload, markdownFileToRoutePath, normalizeSsgBase, normalizeSsgRoute, normalizeSsgRoutePath, prerenderSsgRoutes, prerenderVueSsgRoutes, renderSsgRouteHtml, routePathToHtmlFile, routePathToId, viteSsgPlugin };
+export { createSsgRouteHtml, createSsgRouteManifest, createSsgRoutePayloadScript, createVueSsgRouteRenderer, defaultSsgManifestFile, defaultSsgReportFile, defaultSsgVirtualModuleId, discoverMarkdownSsgRoutes, escapeJsonForHtml, flattenStaticSsgRouterRoutes, injectSsgRoutePayload, isSsgRouteExcluded, isStaticSsgRoutePath, markdownFileToRoutePath, normalizeSsgBase, normalizeSsgRoute, normalizeSsgRoutePath, prerenderSsgRoutes, prerenderVueSsgRoutes, renderSsgRouteHtml, routePathToHtmlFile, routePathToId, viteSsgPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md-plugins/vite-ssg-plugin",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.3",
   "description": "A Vite plugin for @md-plugins static route inventory and future SSG output.",
   "keywords": [
     "markdown-it",