@forsakringskassan/docs-generator 2.11.4 → 2.13.0

package/dist/index.js

@@ -1,13 +1,13 @@
 'use strict';
 
 var fs = require('node:fs/promises');
-var vendor = require('./vendor-WsR_tA03.js');
-var path = require('node:path');
+var path = require('node:path/posix');
+var vendor = require('./vendor-Bb38Rlio.js');
+var path$1 = require('node:path');
 var require$$1 = require('crypto');
-var createMarkdownRenderer = require('./create-markdown-renderer-B1v_YUfy.js');
-var node_child_process = require('node:child_process');
-var path$1 = require('node:path/posix');
 require('node:crypto');
+var createMarkdownRenderer = require('./create-markdown-renderer-CYEpF6C3.js');
+var node_child_process = require('node:child_process');
 var util = require('node:util');
 var vueDocgenApi = require('vue-docgen-api');
 var fs$1 = require('node:fs');
@@ -16,13 +16,13 @@ var node_url = require('node:url');
 var Module = require('node:module');
 var esbuild$1 = require('esbuild');
 var nunjucks = require('nunjucks');
-var vue = require('vue');
-var vue3 = require('./vue3-CGUitvvB.js');
 var express = require('express');
 require('fs');
 require('node:events');
 require('node:stream');
 require('node:string_decoder');
+require('@vue/compiler-sfc');
+require('typescript');
 require('constants');
 require('stream');
 require('util');
@@ -32,8 +32,6 @@ require('readline');
 require('events');
 require('node:process');
 require('node:stream/promises');
-require('@vue/compiler-sfc');
-require('typescript');
 require('fs/promises');
 require('os');
 require('http');
@@ -44,6 +42,8 @@ require('net');
 require('tls');
 require('tty');
 require('querystring');
+require('vue');
+require('./vue3-BqgRpcI0.js');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function toArray$2(value) {
@@ -225,21 +225,6 @@ function interpolate(value, data) {
   });
 }
 
-function parseImport(raw) {
-  const comments = [];
-  const stripped = raw.replace(/<!--.*?-->/gms, (match) => {
-    comments.push(match);
-    return "";
-  });
-  const filename = stripped.trim();
-  const extension = path.parse(filename).ext.slice(1);
-  return {
-    filename,
-    extension,
-    comments
-  };
-}
-
 function quote(text) {
   return String(text).replace(/"/g, "&quot;");
 }
@@ -277,6 +262,108 @@ function slugify(value) {
   return value.toLowerCase().replace(/\//g, "--").replace(/[^a-z]+/g, "-").replace(/(^-+|-+$)/, "");
 }
 
+const md$2 = vendor.MarkdownIt();
+md$2.renderer.rules.fence = (tokens, idx, _options, collected) => {
+  const { content, info } = tokens[idx];
+  const { language, tags } = createMarkdownRenderer.parseInfostring(info);
+  if (language === "import") {
+    return "";
+  }
+  collected.push({
+    content,
+    language,
+    tags
+  });
+  return "";
+};
+function findExamples$1(doc) {
+  if (doc.format !== "markdown") {
+    return [];
+  }
+  const collected = [];
+  md$2.render(doc.body, collected);
+  return collected;
+}
+function getSuffix(tags) {
+  const relevant = tags.filter((it) => ["nocompile", "nolint"].includes(it));
+  if (relevant.length > 0) {
+    return `-${relevant.join("-")}`;
+  } else {
+    return "";
+  }
+}
+function getExtension(lang) {
+  switch (lang) {
+    case "typescript":
+      return "ts";
+    case "javascript":
+      return "js";
+    default:
+      return lang;
+  }
+}
+function extractExamplesProcessor(options) {
+  const {
+    enabled = true,
+    outputFolder,
+    languages = ["javascript", "typescript", "css", "scss"]
+  } = options;
+  function isRelevant(example) {
+    return languages.includes(example.language);
+  }
+  return {
+    stage: "render",
+    name: "extract-examples-processor",
+    async handler(context) {
+      if (!enabled) {
+        return;
+      }
+      if (!outputFolder) {
+        throw new Error(
+          `"outputFolder" not set in "extractExamplesProcessor(..)"`
+        );
+      }
+      await fs.rm(outputFolder, { recursive: true, force: true });
+      let total = 0;
+      for (const doc of context.docs.filter(haveOutput)) {
+        const examples = findExamples$1(doc).filter(isRelevant);
+        if (examples.length === 0) {
+          continue;
+        }
+        const dir = createMarkdownRenderer.normalizePath(outputFolder, doc.fileInfo.fullPath);
+        await fs.mkdir(dir, { recursive: true });
+        let n = 1;
+        for (const example of examples) {
+          const suffix = getSuffix(example.tags);
+          const extension = getExtension(example.language);
+          const filename = `example-${String(n++)}${suffix}.${extension}`;
+          const filePath = path.join(dir, filename);
+          await fs.writeFile(filePath, example.content, "utf-8");
+          total++;
+        }
+      }
+      context.log(total, "examples extracted");
+    }
+  };
+}
+
+const md$1 = vendor.MarkdownIt();
+md$1.renderer.rules.fence = (tokens, idx, _options, collected) => {
+  const { content, info, map } = tokens[idx];
+  const { language, tags } = createMarkdownRenderer.parseInfostring(info);
+  const hashContent = `${map?.[0]}:${map?.[1]}:${info}:${content}`;
+  const fingerprint = createMarkdownRenderer.getFingerprint(hashContent);
+  let extension = void 0;
+  if (language === "import") {
+    extension = content.split(".").at(-1)?.trim();
+  }
+  collected.push({
+    selector: `#example-${fingerprint}`,
+    language: extension ?? language,
+    tags
+  });
+  return "";
+};
 function flattenOutline(outline) {
   return outline.flatMap((entry) => {
     return [
@@ -290,36 +377,26 @@ function findExamples(doc) {
     return [];
   }
   const collected = [];
-  const md = vendor.MarkdownIt();
-  md.renderer.rules.fence = (tokens, idx) => {
-    const { content, info, map } = tokens[idx];
-    const [language, ...tags] = info.split(/\s+/);
-    const hashContent = `${map?.[0]}:${map?.[1]}:${info}:${content}`;
-    const fingerprint = createMarkdownRenderer.getFingerprint(hashContent);
-    let extension = void 0;
-    if (language === "import") {
-      extension = content.split(".").at(-1)?.trim();
-    }
-    collected.push({
-      selector: `#example-${fingerprint}`,
-      language: extension ?? language,
-      tags
-    });
-    return "";
-  };
-  md.render(doc.body);
+  md$1.render(doc.body, collected);
   return collected;
 }
 function manifestPageFromDocument(doc) {
-  const { fileInfo } = doc;
+  const { body, fileInfo, format } = doc;
   return {
     path: createMarkdownRenderer.getOutputFilePath("", fileInfo),
     title: doc.attributes.title ?? doc.name ?? "",
+    redirect: format === "redirect" ? body : null,
     outline: flattenOutline(doc.outline),
     examples: findExamples(doc)
   };
 }
 
+function line(page) {
+  if (page.redirect) {
+    return `${page.path} -> ${page.redirect}`;
+  }
+  return page.path;
+}
 function renderMarkdown(manifest) {
   return [
     "## Documentation manifest",
@@ -327,7 +404,7 @@ function renderMarkdown(manifest) {
     "> Do not edit this file. It is a automatically generated by `@forsakringskassan/docs-generator`.",
     "",
     "```",
-    ...manifest.pages.map((it) => it.path),
+    ...manifest.pages.map(line),
     "```",
     ""
   ].join("\n");
@@ -367,7 +444,7 @@ function normalizeOptions(options) {
   };
   return { ...defaults, ...options };
 }
-function motdProcessor(options) {
+function motdProcessor(options = {}) {
   const { enabled, container, message } = normalizeOptions(options);
   return {
     name: "motd-processor",
@@ -433,6 +510,157 @@ function themeSelectProcessor() {
   };
 }
 
+function dump(value) {
+  return `<pre>${JSON.stringify(value, null, 2)}</pre>`;
+}
+
+function json(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+function isExternalUrl(url) {
+  return url.startsWith("http://") || url.startsWith("https://") || url.startsWith("//");
+}
+function isAbsoluteUrl(url) {
+  return url.startsWith("/");
+}
+function relative(url, { fileInfo }) {
+  if (isExternalUrl(url)) {
+    return url;
+  }
+  if (isAbsoluteUrl(url)) {
+    url = `.${url}`;
+  }
+  url = createMarkdownRenderer.normalizePath(url);
+  const outputPath = createMarkdownRenderer.normalizePath(fileInfo.path);
+  if (outputPath === url || `${outputPath}/` === url) {
+    return "./";
+  }
+  const relative2 = path.relative(outputPath, url);
+  const prefix = relative2.startsWith(".") ? "" : "./";
+  const suffix = url.endsWith("/") ? "/" : "";
+  return [prefix, relative2, suffix].join("");
+}
+
+function take(haystack, key, value) {
+  return haystack.filter((it) => it[key] === value);
+}
+
+const template = (dst) => (
+  /* HTML */
+  `
+    <!doctype html>
+    <html lang="en">
+        <head>
+            <meta http-equiv="refresh" content="0; url=${dst}" />
+        </head>
+        <body>
+            <p>
+                This page has moved to
+                <a href="${dst}"> ${dst} </a>.
+            </p>
+        </body>
+    </html>
+`
+);
+function htmlRedirectProcessor() {
+  return {
+    name: "html-redirect-processor",
+    after: "render",
+    async handler(context) {
+      const { docs, outputFolder } = context;
+      for (const doc of docs.filter(haveOutput)) {
+        if (doc.format !== "redirect") {
+          continue;
+        }
+        const filePath = createMarkdownRenderer.getOutputFilePath(outputFolder, doc.fileInfo);
+        const dst = relative(doc.body, doc);
+        const content = template(dst);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, vendor.dedent(content), "utf-8");
+      }
+    }
+  };
+}
+
+function isRedirect(doc) {
+  return doc.format === "redirect";
+}
+function redirectFileProcessor(prefix = "/", filename = "_redirects") {
+  return {
+    name: "redirect-file-processor",
+    after: "render",
+    async handler(context) {
+      const { docs } = context;
+      const lines = docs.filter(haveOutput).filter(isRedirect).map((doc) => {
+        const src = createMarkdownRenderer.normalizePath(
+          doc.fileInfo.path,
+          doc.fileInfo.outputName
+        );
+        const dst = doc.body;
+        return `${prefix}${src} ${prefix}${dst} 301
+`;
+      });
+      const filePath = path.join(context.outputFolder, filename);
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await fs.writeFile(filePath, lines.join(""), "utf-8");
+      context.log(filename, "generated");
+    }
+  };
+}
+
+function getRedirects(docs) {
+  return docs.map((it) => {
+    const { fileInfo } = it;
+    const { path, outputName } = fileInfo;
+    if (outputName === false) {
+      return [];
+    }
+    return it.attributes.redirectFrom.map((jt) => {
+      return {
+        from: jt.startsWith("/") ? jt.slice(1) : jt,
+        to: createMarkdownRenderer.normalizePath(path, outputName)
+      };
+    });
+  }).flat();
+}
+
+function redirectProcessor() {
+  return {
+    name: "redirect-processor",
+    after: "generate-docs",
+    async handler(context) {
+      const redirects = getRedirects(context.docs);
+      for (const redirect of redirects) {
+        const { dir, base, name } = path.parse(redirect.from);
+        context.addDocument({
+          id: `redirect:${redirect.from}-${redirect.to}`,
+          name: `${redirect.from}-${redirect.to}`,
+          alias: [],
+          visible: false,
+          attributes: {
+            sortorder: Infinity,
+            redirectFrom: []
+          },
+          body: redirect.to,
+          outline: [],
+          format: "redirect",
+          tags: [],
+          template: "redirect",
+          fileInfo: {
+            path: dir,
+            name,
+            fullPath: "virtual:redirect",
+            outputName: base
+          }
+        });
+      }
+      const s = redirects.length === 1 ? "" : "s";
+      context.log(redirects.length, `redirect${s} found`);
+    }
+  };
+}
+
 function selectableVersionProcessor(pkg, container, options) {
   const { enabled = true, message = "Det finns en nyare version" } = options ?? {};
   return {
@@ -463,7 +691,7 @@ function selectableVersionProcessor(pkg, container, options) {
 
 function generateNavigation(entries) {
   const children = entries.map((it, index) => {
-    const key = path$1.parse(it.path).name;
+    const key = path.parse(it.path).name;
     return {
       key,
       sortorder: index,
@@ -647,7 +875,7 @@ function toArray$1(value) {
   return Array.isArray(value) ? value : [value];
 }
 function isIndexPage(parsed) {
-  const folder = path.basename(parsed.dir);
+  const folder = path$1.basename(parsed.dir);
   if (parsed.name === folder) {
     return true;
   }
@@ -699,8 +927,8 @@ function getComponent(attrs) {
   });
 }
 function parseFile$1(filePath, basePath, content) {
-  const relative = basePath ? path.relative(basePath, createMarkdownRenderer.normalizePath(filePath)) : createMarkdownRenderer.normalizePath(filePath);
-  const parsed = path.parse(relative);
+  const relative = basePath ? path$1.relative(basePath, createMarkdownRenderer.normalizePath(filePath)) : createMarkdownRenderer.normalizePath(filePath);
+  const parsed = path$1.parse(relative);
   const blocks = vendor.fm(content);
   const attributes = blocks.attributes;
   const isIndex = isIndexPage(parsed);
@@ -721,6 +949,7 @@ function parseFile$1(filePath, basePath, content) {
       status: attributes.status,
       badge: getBadge(attributes),
       component: getComponent(attributes),
+      redirectFrom: toArray$1(attributes.redirect_from ?? []),
       sortorder: attributes.sortorder ?? Infinity
     },
     body: blocks.body,
@@ -879,7 +1108,7 @@ function parseAPIToArray(api) {
 }
 function parseAPI(filePath, api) {
   const relative = createMarkdownRenderer.normalizePath(filePath);
-  const parsedPath = path.parse(relative);
+  const parsedPath = path$1.parse(relative);
   const componentName = parsedPath.name;
   let html = "";
   if (api.props.length) {
@@ -899,7 +1128,7 @@ function parseAPI(filePath, api) {
     name: `vue:${componentName}`,
     alias: [],
     visible: false,
-    attributes: { sortorder: Infinity },
+    attributes: { sortorder: Infinity, redirectFrom: [] },
     body: html,
     outline: [],
     format: "html",
@@ -926,7 +1155,9 @@ async function globAll(pattern) {
   if (!Array.isArray(pattern)) {
     return globAll([pattern]);
   }
-  const results = await Promise.all(pattern.map((it) => vendor.glob(it)));
+  const results = await Promise.all(
+    pattern.map((it) => vendor.glob(it, { nodir: true }))
+  );
   return new Set(results.flat());
 }
 async function getDocumentsForSource(src) {
@@ -967,8 +1198,8 @@ function parseFile(filePath, basePath, content) {
   if (!title) {
     throw new Error(`No title property set in "${filePath}"`);
   }
-  const relative = basePath ? path.relative(basePath, createMarkdownRenderer.normalizePath(filePath)) : createMarkdownRenderer.normalizePath(filePath);
-  const parsed = path.parse(relative);
+  const relative = basePath ? path$1.relative(basePath, createMarkdownRenderer.normalizePath(filePath)) : createMarkdownRenderer.normalizePath(filePath);
+  const parsed = path$1.parse(relative);
   const filename = parsed.name.toLowerCase();
   const name = parsed.name;
   const urlpath = parsed.dir;
@@ -980,7 +1211,8 @@ function parseFile(filePath, basePath, content) {
     attributes: {
       title,
       href,
-      sortorder: attributes.sortorder ?? Infinity
+      sortorder: attributes.sortorder ?? Infinity,
+      redirectFrom: []
     },
     body: content,
     outline: [],
@@ -1002,7 +1234,7 @@ async function navigationFileReader(filePath, basePath) {
 }
 
 function resolveFrom(fromDirectory, moduleId) {
-  const fromFile = path.join(fs$1.realpathSync(fromDirectory), "noop.js");
+  const fromFile = path$1.join(fs$1.realpathSync(fromDirectory), "noop.js");
   return Module._resolveFilename(moduleId, {
     id: fromFile,
     filename: fromFile,
@@ -1018,8 +1250,8 @@ function moduleImporter(options) {
       if (url.startsWith(WEBPACK_NODE_MODULE_PREFIX)) {
         findUrl = url.substring(1);
       }
-      const directory = path.dirname(findUrl);
-      const fileName = path.basename(findUrl);
+      const directory = path$1.dirname(findUrl);
+      const fileName = path$1.basename(findUrl);
       const search = [
         `${fileName}.css`,
         `${fileName}.scss`,
@@ -1028,7 +1260,7 @@ function moduleImporter(options) {
       ];
       for (const variant of search) {
         try {
-          const moduleName = path.posix.join(directory, variant);
+          const moduleName = path$1.posix.join(directory, variant);
           const resolved = resolveFrom(cwd, moduleName);
           return new URL(node_url.pathToFileURL(resolved));
         } catch (err) {
@@ -1048,21 +1280,21 @@ async function compileSassString(dst, style, options = {}) {
     style: "expanded",
     importers: [new sass.NodePackageImporter(), moduleImporter({ cwd })]
   });
-  await fs.mkdir(path.dirname(dst), { recursive: true });
+  await fs.mkdir(path$1.dirname(dst), { recursive: true });
   await fs.writeFile(dst, result.css, "utf-8");
 }
 
 async function compileStyle(assetFolder, name, src, options) {
   const { cwd } = options;
   try {
-    const outfile = path$1.join("temp", `asset-${name}.css`);
+    const outfile = path.join("temp", `asset-${name}.css`);
     const source = await fs.readFile(src, "utf-8");
     await compileSassString(outfile, source, { cwd });
     const content = await fs.readFile(outfile, "utf-8");
     const fingerprint = createMarkdownRenderer.getFingerprint(content);
     const integrity = getIntegrity(content);
     const filename = `${name}-${fingerprint}.css`;
-    const dst = path$1.join(assetFolder, filename);
+    const dst = path.join(assetFolder, filename);
     await fs.rename(outfile, dst);
     const stat = await fs.stat(dst);
     return {
@@ -1138,7 +1370,7 @@ async function compileScript(options) {
   const iconLib = process.env.DOCS_ICON_LIB ?? "@fkui/icon-lib-default";
   try {
     const entryPoints = [src instanceof URL ? node_url.fileURLToPath(src) : src];
-    const outfile = path.join("temp", `asset-${name}.js`);
+    const outfile = path$1.join("temp", `asset-${name}.js`);
     await esbuild({
       entryPoints,
       outfile,
@@ -1146,7 +1378,7 @@ async function compileScript(options) {
       format: "iife",
       platform: "browser",
       external: ["vue", "@fkui/vue"],
-      tsconfig: path.join(__dirname, "../tsconfig-examples.json"),
+      tsconfig: path$1.join(__dirname, "../tsconfig-examples.json"),
       ...buildOptions,
       define: {
         "process.env.DOCS_ICON_LIB": JSON.stringify(iconLib),
@@ -1157,8 +1389,8 @@ async function compileScript(options) {
     const fingerprint = createMarkdownRenderer.getFingerprint(content);
     const integrity = getIntegrity(content);
     const filename = `${name}-${fingerprint}.js`;
-    const dst = path.join(assetFolder, filename);
-    await fs$1.mkdir(path.dirname(dst), { recursive: true });
+    const dst = path$1.join(assetFolder, filename);
+    await fs$1.mkdir(path$1.dirname(dst), { recursive: true });
     await fs$1.rename(outfile, dst);
     const stat = await fs$1.stat(dst);
     return {
@@ -1224,7 +1456,7 @@ function staticResourcesProcessor(assetFolder, resources) {
     async handler(context) {
       for (const resource of [...resources, ...context.resources]) {
         const src = resource.from;
-        const dst = path$1.join(assetFolder, resource.to);
+        const dst = path.join(assetFolder, resource.to);
         await fs.cp(src, dst, {
           recursive: true
         });
@@ -1250,7 +1482,7 @@ function compileProcessorRuntime(generator, distDir, processors) {
       const assetName = [
         "processors",
         processor.name.replace(/-processor/, ""),
-        entry.name ?? path.parse(entry.src).name
+        entry.name ?? path$1.parse(entry.src).name
       ].join("/");
       const name = processorRuntimeName(processor, entry);
       const bundled = new URL(`${name}.js`, distDir);
@@ -1270,110 +1502,6 @@ function compileProcessorRuntime(generator, distDir, processors) {
   }
 }
 
-function getExampleImport(searchDirs, filename) {
-  const pattern = searchDirs.map((dir) => `${dir}/**/${filename}`);
-  const matches = vendor.globSync(pattern);
-  if (matches.length === 0) {
-    const message = `No files matched import "${filename}"`;
-    throw new Error(message);
-  } else if (matches.length > 1) {
-    const message = `Multiple files matched import "${filename}"`;
-    throw new Error(message);
-  } else {
-    return createMarkdownRenderer.normalizePath(matches[0]);
-  }
-}
-
-function getExampleName(filename) {
-  return path.parse(filename).name;
-}
-
-const vueMajor = parseInt(vue.version.split(".", 2)[0], 10);
-function vueGenerator() {
-  switch (vueMajor) {
-    case 2:
-      throw new Error(
-        "Vue 2 is no longer supported, upgrade to Vue 3 or downgrade docs-generator"
-      );
-    case 3:
-      return vue3.generateCode;
-  }
-}
-function generateExample(options) {
-  const { language } = options;
-  if (language === "import") {
-    const parsed = parseImport(options.source);
-    const filename = getExampleImport(
-      options.exampleFolders,
-      parsed.filename
-    );
-    const source = fs$1.readFileSync(filename, "utf-8");
-    const language2 = parsed.extension;
-    const comments = parsed.comments;
-    const example = generateExample({
-      ...options,
-      source,
-      language: language2,
-      filename
-    });
-    return { ...example, comments };
-  }
-  switch (language) {
-    case "vue":
-      return generateVueExample(options);
-    case "html":
-      return generateStaticExample(options);
-    default:
-      return generateStaticExample(options);
-  }
-}
-function generateVueExample(options) {
-  const { filename, source, parent, setupPath, tags } = options;
-  const fn = vueGenerator();
-  const slug = getExampleName(filename);
-  const fingerprint = createMarkdownRenderer.getFingerprint(source);
-  const { markup, sourcecode, output } = fn({
-    filename,
-    slug,
-    fingerprint,
-    code: source,
-    setupPath
-  });
-  return {
-    source,
-    language: options.language,
-    comments: [],
-    tags,
-    markup,
-    output,
-    runtime: true,
-    task: {
-      outputFile: output,
-      sourcecode,
-      sourceFile: filename,
-      parent
-    }
-  };
-}
-function generateStaticExample(options) {
-  const { filename, source, language, tags } = options;
-  const slug = getExampleName(filename);
-  const fingerprint = createMarkdownRenderer.getFingerprint(source);
-  const asset = `${slug}-${fingerprint}.${language}`;
-  const runtimeLanguages = ["html"];
-  const runtime = runtimeLanguages.includes(language);
-  return {
-    source,
-    language: options.language,
-    comments: [],
-    tags,
-    markup: source,
-    output: runtime ? asset : null,
-    runtime,
-    task: null
-  };
-}
-
 function isNavigationSection(node) {
   return "key" in node;
 }
@@ -1382,7 +1510,7 @@ function pathFromDoc({ fileInfo }) {
     return [fileInfo.path.replace(/\\/g, "/"), true];
   } else {
     return [
-      `./${path.join(fileInfo.path, fileInfo.name).replace(/\\/g, "/")}`,
+      `./${path$1.join(fileInfo.path, fileInfo.name).replace(/\\/g, "/")}`,
       false
     ];
   }
@@ -1451,6 +1579,9 @@ function generateNavtree(docs) {
     return parent;
   }
   for (const doc of docs) {
+    if (doc.format === "redirect") {
+      continue;
+    }
     const [name, isSection] = pathFromDoc(doc);
     const title = doc.attributes.shortTitle ?? doc.attributes.title ?? doc.fileInfo.name;
     const sortorder = doc.attributes.sortorder;
@@ -1577,7 +1708,7 @@ class TemplateLoader {
   folders;
   templateCache;
   constructor(folders = []) {
-    this.folders = [...folders, path.join(__dirname, "../templates")];
+    this.folders = [...folders, path$1.join(__dirname, "../templates")];
     this.templateCache = /* @__PURE__ */ new Map();
   }
   async getSource(name, callback) {
@@ -1628,47 +1759,11 @@ Make sure the name is correct and the template file exists in one of the listed
   }
   findTemplateFile(name) {
     const { folders } = this;
-    const searchPaths = folders.map((it) => path.join(it, name));
+    const searchPaths = folders.map((it) => path$1.join(it, name));
     return searchPaths.find((it) => fs$1.existsSync(it));
   }
 }
 
-function dump(value) {
-  return `<pre>${JSON.stringify(value, null, 2)}</pre>`;
-}
-
-function json(value) {
-  return JSON.stringify(value, null, 2);
-}
-
-function isExternalUrl(url) {
-  return url.startsWith("http://") || url.startsWith("https://") || url.startsWith("//");
-}
-function isAbsoluteUrl(url) {
-  return url.startsWith("/");
-}
-function relative(url, { fileInfo }) {
-  if (isExternalUrl(url)) {
-    return url;
-  }
-  if (isAbsoluteUrl(url)) {
-    url = `.${url}`;
-  }
-  url = createMarkdownRenderer.normalizePath(url);
-  const outputPath = createMarkdownRenderer.normalizePath(fileInfo.path);
-  if (outputPath === url || `${outputPath}/` === url) {
-    return "./";
-  }
-  const relative2 = path$1.relative(outputPath, url);
-  const prefix = relative2.startsWith(".") ? "" : "./";
-  const suffix = url.endsWith("/") ? "/" : "";
-  return [prefix, relative2, suffix].join("");
-}
-
-function take(haystack, key, value) {
-  return haystack.filter((it) => it[key] === value);
-}
-
 class MissingTemplateError extends Error {
   searchDir;
   constructor(fileInfo, template, format, searchDir) {
@@ -1686,7 +1781,7 @@ class MissingTemplateError extends Error {
     ].join("\n");
   }
 }
-const templateDirectory = path.join(__dirname, "../templates");
+const templateDirectory = path$1.join(__dirname, "../templates");
 const cache$1 = /* @__PURE__ */ new Map();
 function cacheKey(layout, extension) {
   return [layout, extension].join("|");
@@ -1708,7 +1803,7 @@ function findTemplate(folders, from, src, format) {
   folders = [...folders, templateDirectory];
   const template = `${layout}.template.${format}`;
   const searchPaths = folders.map((it) => {
-    return path.join(it, template);
+    return path$1.join(it, template);
   });
   const found = searchPaths.find((it) => fs$1.existsSync(it));
   if (!found) {
@@ -1718,7 +1813,7 @@ function findTemplate(folders, from, src, format) {
   return template;
 }
 
-const scriptPath = path.join(__dirname, "compile-example.js");
+const scriptPath = path$1.join(__dirname, "compile-example.js");
 let loader = null;
 function haveOutputFile(fileInfo) {
   return fileInfo.outputName !== false;
@@ -1752,8 +1847,8 @@ function findSidenav(doc, tree) {
 }
 function cache(cacheFolder, outputFolder) {
   return (it) => {
-    const cacheFile = path.join(cacheFolder, it.outputFile);
-    const outputFile = path.join(outputFolder, it.outputFile);
+    const cacheFile = path$1.join(cacheFolder, it.outputFile);
+    const outputFile = path$1.join(outputFolder, it.outputFile);
     if (fs$1.existsSync(cacheFile)) {
       fs$1.copyFileSync(cacheFile, outputFile);
       return false;
@@ -1767,8 +1862,8 @@ async function compileExamples(options) {
   if (tasks.length === 0) {
     return;
   }
-  const cacheFolder = path.posix.join(options.cacheFolder, fileInfo.path);
-  const outputFolder = path.posix.join(options.outputFolder, fileInfo.path);
+  const cacheFolder = path$1.posix.join(options.cacheFolder, fileInfo.path);
+  const outputFolder = path$1.posix.join(options.outputFolder, fileInfo.path);
   const cacheMiss = cache(cacheFolder, outputFolder);
   const dirtyTasks = tasks.filter(cacheMiss);
   if (dirtyTasks.length === 0) {
@@ -1791,8 +1886,8 @@ async function compileStandalones(options) {
   if (tasks.length === 0) {
     return;
   }
-  const cacheFolder = path.posix.join(options.cacheFolder, fileInfo.path);
-  const outputFolder = path.posix.join(options.outputFolder, fileInfo.path);
+  const cacheFolder = path$1.posix.join(options.cacheFolder, fileInfo.path);
+  const outputFolder = path$1.posix.join(options.outputFolder, fileInfo.path);
   const cacheMiss = cache(cacheFolder, outputFolder);
   const dirtyTasks = tasks.filter(cacheMiss);
   const standaloneTemplate = findTemplate(
@@ -1801,7 +1896,7 @@ async function compileStandalones(options) {
     "example"
   );
   for (const task of dirtyTasks) {
-    const outputFile = path.join(outputFolder, task.outputFile);
+    const outputFile = path$1.join(outputFolder, task.outputFile);
     const content = await renderTemplate(standaloneTemplate, {
       ...templateData,
       content: task.content
@@ -1820,7 +1915,7 @@ async function render(doc, docs, nav, vendors, options) {
     return null;
   }
   const dst = createMarkdownRenderer.getOutputFilePath(outputFolder, fileInfo);
-  const mkdir = fs.mkdir(path.dirname(dst), { recursive: true });
+  const mkdir = fs.mkdir(path$1.dirname(dst), { recursive: true });
   const topnav = nav.topnav;
   const sidenav = findSidenav(doc, nav.sidenav);
   if (sidenav && isNavigationSection(sidenav)) {
@@ -1837,7 +1932,7 @@ async function render(doc, docs, nav, vendors, options) {
     topnav,
     rootUrl(doc2) {
       const { fileInfo: fileInfo2 } = doc2;
-      const relative = path$1.relative(fileInfo2.path, ".");
+      const relative = path.relative(fileInfo2.path, ".");
       return relative !== "" ? relative : ".";
     },
     sidenav,
@@ -1848,7 +1943,7 @@ async function render(doc, docs, nav, vendors, options) {
   const markdownRenderer = createMarkdownRenderer.createMarkdownRenderer({
     docs,
     generateExample({ source, language, filename, tags }) {
-      const example = generateExample({
+      const example = createMarkdownRenderer.generateExample({
         source,
         language,
         filename,
@@ -1858,12 +1953,12 @@ async function render(doc, docs, nav, vendors, options) {
         tags
       });
       if (example.output) {
-        const { dir, name } = path.parse(example.output);
+        const { dir, name } = path$1.parse(example.output);
         if (example.task) {
           generatedExamples.push(example.task);
         }
         generatedStandalone.push({
-          outputFile: path.join(dir, `${name}.html`),
+          outputFile: path$1.join(dir, `${name}.html`),
           content: example.markup
         });
       }
@@ -1990,7 +2085,11 @@ function nunjucksProcessor(options) {
           }
         });
       }
+      const formats = ["markdown", "json"];
       const docs = context.docs.filter((it) => {
+        if (!formats.includes(it.format)) {
+          return false;
+        }
         return it.fileInfo.outputName;
       });
       progressbar.start(docs.length, 0, {
@@ -1998,7 +2097,7 @@ function nunjucksProcessor(options) {
       });
       const generatedFiles = [];
       try {
-        for (const doc of context.docs) {
+        for (const doc of docs) {
           const filePath = await renderDocument(doc);
           if (filePath) {
             generatedFiles.push(filePath);
@@ -2059,12 +2158,12 @@ function getAssetSource(asset, require) {
   return lines.join("\n");
 }
 async function compileVendor(assetFolder, vendor, options) {
-  const name = path.isAbsolute(vendor.package) ? path.basename(vendor.package) : vendor.package;
+  const name = path$1.isAbsolute(vendor.package) ? path$1.basename(vendor.package) : vendor.package;
   const slug = slugify(name);
   const outfile = `temp/vendor-${slug}.out.js`;
   const tmpfile = `temp/vendor-${slug}.in.js`;
   const source = getAssetSource(vendor, customRequire.toString());
-  const tsconfig = path.resolve(__dirname, "../tsconfig-examples.json");
+  const tsconfig = path$1.resolve(__dirname, "../tsconfig-examples.json");
   await fs.writeFile(tmpfile, source, "utf-8");
   await esbuild$1.build({
     entryPoints: [tmpfile],
@@ -2086,7 +2185,7 @@ async function compileVendor(assetFolder, vendor, options) {
   const fingerprint = createMarkdownRenderer.getFingerprint(content);
   const integrity = getIntegrity(content);
   const filename = `vendor-${slug}-${fingerprint}.js`;
-  const dst = path.join(assetFolder, filename).replace(/\\/g, "/");
+  const dst = path$1.join(assetFolder, filename).replace(/\\/g, "/");
   await fs.rename(outfile, dst);
   const stat = await fs.stat(dst);
   return {
@@ -2139,7 +2238,7 @@ function vendorProcessor(assetFolder, vendor) {
       const assets = await generateVendorAssets(assetFolder, vendor);
       context.addVendorAsset(assets);
       for (const asset of assets) {
-        const filename = path$1.basename(asset.publicPath);
+        const filename = path.basename(asset.publicPath);
         context.log(filename, formatSize(asset.size));
       }
     }
@@ -2219,7 +2318,7 @@ async function serve(options) {
   const watcher = vendor.watch(options.watch);
   const rebuild = createRebuilder(options.rebuild, (filePath) => {
     const files = filePath.map((it) => {
-      return path$1.relative(options.outputFolder, it);
+      return path.relative(options.outputFolder, it);
     });
     livereload.changed({ body: { files } });
   });
@@ -2296,7 +2395,7 @@ async function stage(stage2, context, processors, { verbose } = { verbose: true
   }
   return generatedFiles;
 }
-function createContext(templateLoader) {
+function createContext(outputFolder, templateLoader) {
   let docs = [];
   let vendors = [];
   const resources = [];
@@ -2334,6 +2433,7 @@ function createContext(templateLoader) {
     get sidenav() {
       return sidenav;
     },
+    outputFolder,
     addDocument(document) {
       docs = [...docs, ...toArray(document)];
     },
@@ -2397,10 +2497,10 @@ class Generator {
       throw new Error("site metadata not set in configuration");
     }
     this.site = options.site;
-    this.outputFolder = options.outputFolder;
-    this.cacheFolder = options.cacheFolder;
-    this.assetFolder = path.posix.join(options.outputFolder, "assets");
-    this.exampleFolders = options.exampleFolders;
+    this.outputFolder = options.outputFolder ?? "./public";
+    this.cacheFolder = options.cacheFolder ?? "./temp/docs";
+    this.assetFolder = path$1.posix.join(this.outputFolder, "assets");
+    this.exampleFolders = options.exampleFolders ?? [];
     this.templateFolders = options.templateFolders ?? [];
     this.processors = options.processors ?? [];
     this.vendor = options.vendor ?? [];
@@ -2464,10 +2564,11 @@ class Generator {
   async manifest(sourceFiles) {
     const processors = [
       fileReaderProcessor(sourceFiles),
+      redirectProcessor(),
       ...this.processors
     ];
     const templateLoader = createTemplateLoader([]);
-    const context = createContext(templateLoader);
+    const context = createContext("", templateLoader);
     await stage("generate-docs", context, processors, { verbose: false });
     const docs = context.docs.filter(haveOutput);
     const pages = docs.map(manifestPageFromDocument);
@@ -2488,6 +2589,7 @@ class Generator {
     await this._prepareFolders();
     const processors = [
       fileReaderProcessor(sourceFiles),
+      redirectProcessor(),
       vendorProcessor(assetFolder, this.vendor),
       cssAssetProcessor(assetFolder, this.styles, { cwd }),
       jsAssetProcessor(assetFolder, this.scripts),
@@ -2509,7 +2611,7 @@ class Generator {
     ];
     compileProcessorRuntime(this, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)), processors);
     const templateLoader = createTemplateLoader(templateFolders);
-    const context = createContext(templateLoader);
+    const context = createContext(outputFolder, templateLoader);
     const generatedFiles = [
       await stage("generate-docs", context, processors),
       await stage("generate-nav", context, processors),
@@ -2536,7 +2638,7 @@ class Generator {
     const { outputFolder, cacheFolder, assetFolder } = this;
     await fs.rm(cacheFolder, { force: true, recursive: true });
     if (fs$1.existsSync(outputFolder)) {
-      await fs.mkdir(path.dirname(cacheFolder), { recursive: true });
+      await fs.mkdir(path$1.dirname(cacheFolder), { recursive: true });
       await vendor.fse.copy(outputFolder, cacheFolder);
       await fs.rm(outputFolder, { recursive: true });
     }
@@ -2580,7 +2682,9 @@ function extractTerms(doc) {
   }
 }
 function isIndexable(doc) {
-  return Boolean(doc.visible && doc.fileInfo.outputName);
+  return Boolean(
+    doc.visible && doc.fileInfo.outputName && doc.format !== "redirect"
+  );
 }
 function getTerms(doc) {
   return {
@@ -2609,7 +2713,8 @@ function searchProcessor() {
         alias: [],
         visible: false,
         attributes: {
-          sortorder: Infinity
+          sortorder: Infinity,
+          redirectFrom: []
         },
         body,
         outline: [],
@@ -2638,13 +2743,16 @@ exports.Generator = Generator;
 exports.availableProcessors = availableProcessors;
 exports.cookieProcessor = cookieProcessor;
 exports.defineSources = defineSources;
+exports.extractExamplesProcessor = extractExamplesProcessor;
 exports.frontMatterFileReader = frontMatterFileReader;
+exports.htmlRedirectProcessor = htmlRedirectProcessor;
 exports.livereloadProcessor = livereloadProcessor;
 exports.manifestProcessor = manifestProcessor;
 exports.matomoProcessor = matomoProcessor;
 exports.motdProcessor = motdProcessor;
 exports.navigationFileReader = navigationFileReader;
 exports.processorRuntimeName = processorRuntimeName;
+exports.redirectFileProcessor = redirectFileProcessor;
 exports.searchProcessor = searchProcessor;
 exports.selectableVersionProcessor = selectableVersionProcessor;
 exports.sourceUrlProcessor = sourceUrlProcessor;