@t8/docsgen 0.3.32 → 0.3.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t8/docsgen",
-  "version": "0.3.32",
+  "version": "0.3.34",
   "description": "",
   "main": "dist/bin.js",
   "type": "module",

package/src/bin/content/createDirs.ts

@@ -0,0 +1,21 @@
+import { access, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { Context } from "../../types/Context.ts";
+
+export async function createDirs(ctx: Context) {
+  let { dir = "", contentDir = "" } = ctx;
+
+  let dirs = [contentDir];
+
+  await Promise.all(
+    dirs.map(async (path) => {
+      let dirPath = join(dir, path);
+
+      try {
+        await access(dirPath);
+      } catch {
+        await mkdir(dirPath);
+      }
+    }),
+  );
+}

package/src/bin/content/getCSSRoot.ts

@@ -0,0 +1,50 @@
+import { exec as defaultExec } from "node:child_process";
+import { cp } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { packageName } from "../../const/packageName.ts";
+import type { Context } from "../../types/Context.ts";
+
+const exec = promisify(defaultExec);
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+let packageURL = "";
+
+export async function getCSSRoot(ctx: Context, type: "index" | "content") {
+  let { dir = "", assetsDir } = ctx;
+
+  let cssRoot = {
+    index: "",
+    content: "",
+  };
+
+  if (assetsDir) {
+    cssRoot.index = assetsDir;
+    cssRoot.content = `../${assetsDir}`;
+
+    await cp(join(__dirname, "css"), join(dir, cssRoot.index), {
+      force: true,
+      recursive: true,
+    });
+  } else {
+    if (!packageURL) {
+      let packageVersion = (
+        await exec(`npm view ${packageName} version`)
+      ).stdout
+        .trim()
+        .split(".")
+        .slice(0, 2)
+        .join(".");
+
+      packageURL = `https://unpkg.com/${packageName}@${packageVersion}`;
+    }
+
+    cssRoot.index = `${packageURL}/dist/css`;
+    cssRoot.content = `${packageURL}/dist/css`;
+  }
+
+  return cssRoot[type];
+}

package/src/bin/{getCounterContent.ts → content/getCounterContent.ts}

@@ -1,4 +1,4 @@
-import type { Context } from "../types/Context.ts";
+import type { Context } from "../../types/Context.ts";
 
 export function getCounterContent({ ymid }: Context) {
   if (!ymid) return "";

package/src/bin/content/getDefaultCodeStyleContent.ts

@@ -0,0 +1,9 @@
+export function getDefaultCodeStyleContent(cssRoot: string) {
+  return `
+<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/styles/stackoverflow-light.min.css" media="(prefers-color-scheme: light)">
+<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/styles/base16/material.min.css" media="(prefers-color-scheme: dark)">
+<link rel="stylesheet" href="${cssRoot}/code.css">
+<script src="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/highlight.min.js"></script>
+<script>hljs.highlightAll()</script>
+  `.trim();
+}

package/src/bin/{getIcon.ts → content/getIcon.ts}

@@ -1,4 +1,4 @@
-import type { Context } from "../types/Context.ts";
+import type { Context } from "../../types/Context.ts";
 
 const iconTypeMap: Record<string, string> = {
   ico: "image/x-icon",

package/src/bin/content/getIconTag.ts

@@ -0,0 +1,10 @@
+import type { Context } from "../../types/Context.ts";
+import { getIcon } from "./getIcon.ts";
+
+export function getIconTag(ctx: Context) {
+  let { url, type } = getIcon(ctx);
+
+  return url
+    ? `<link rel="icon"${type ? ` type="${type}"` : ""} href="${url}">`
+    : "";
+}

package/src/bin/content/getIndexContent.ts

@@ -0,0 +1,119 @@
+import type { Context } from "../../types/Context.ts";
+import { escapeHTML } from "../../utils/escapeHTML.ts";
+import { getRepoLink } from "../getRepoLink.ts";
+import { getParsedContent } from "../parsing/getParsedContent.ts";
+import { getCounterContent } from "./getCounterContent.ts";
+import { getCSSRoot } from "./getCSSRoot.ts";
+import { getDefaultCodeStyleContent } from "./getDefaultCodeStyleContent.ts";
+import { getIconTag } from "./getIconTag.ts";
+import { getInjectedContent } from "./getInjectedContent.ts";
+import { getPlainTitle } from "./getPlainTitle.ts";
+import { toFileContent } from "./toFileContent.ts";
+import { tweakTypography } from "./tweakTypography.ts";
+
+export async function getIndexContent(ctx: Context) {
+  let {
+    root,
+    contentDir = "",
+    name,
+    htmlTitle,
+    description: packageDescription,
+    isDevDep,
+    backstory,
+  } = ctx;
+
+  let counterContent = getCounterContent(ctx);
+  let escapedPackageDescription = escapeHTML(packageDescription);
+
+  let {
+    title: parsedTitle,
+    description,
+    intro,
+    features,
+    note,
+    installation,
+    nav,
+  } = await getParsedContent(ctx);
+
+  let plainTitle = await getPlainTitle(ctx);
+  let coverTitle = htmlTitle || parsedTitle || plainTitle;
+
+  let descriptionContent =
+    tweakTypography(description) ||
+    (escapedPackageDescription
+      ? `<p>${tweakTypography(escapedPackageDescription)}<p>`
+      : "");
+
+  if (!installation || isDevDep !== undefined)
+    installation = `npm i${isDevDep ? " -D" : ""} ${name}`;
+
+  let cssRoot = await getCSSRoot(ctx, "index");
+
+  return toFileContent(`
+<!DOCTYPE html>
+<html lang="en" data-layout="index">
+<head>
+  ${getInjectedContent(ctx, "index", "head", "prepend")}
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="${plainTitle}${escapedPackageDescription ? `: ${escapedPackageDescription}` : ""}">
+  <title>${plainTitle}${escapedPackageDescription ? ` | ${escapedPackageDescription}` : ""}</title>
+  <link rel="stylesheet" href="${cssRoot}/base.css">
+  <link rel="stylesheet" href="${cssRoot}/index.css">
+  ${getIconTag(ctx)}
+  <link rel="prefetch" href="${root}start">
+  ${nav[0] ? `<link rel="prefetch" href="${root}${contentDir}/${nav[0]?.id ?? ""}">` : ""}
+  ${getInjectedContent(ctx, "index", "head", "append")}
+</head>
+<body>
+${getInjectedContent(ctx, "index", "body", "prepend")}
+<div class="layout">
+<main>
+<section class="aux intro-title">
+  <div class="section-content">
+    ${getInjectedContent(ctx, "index", "cover", "prepend")}
+    <h1>${coverTitle}</h1>
+    <div class="description">
+      ${descriptionContent}
+    </div>
+    <p class="actions">
+      <a href="${root}start" class="primary">Docs</a>
+      <span class="sep"> • </span>
+      ${getRepoLink(ctx)}
+    </p>
+    ${backstory ? `<p class="ref"><a href="${backstory}">Backstory</a></p>` : ""}
+    <p class="installation"><code>${escapeHTML(installation)}</code></p>
+    ${getInjectedContent(ctx, "index", "cover", "append")}
+  </div>
+</section>
+${
+  intro || features || note
+    ? `
+<section class="intro">
+  <div class="section-content">
+    ${intro ? `<div class="intro">${intro}</div>` : ""}
+    ${features ? `<div class="features">${features}</div>` : ""}
+    ${note ? `<div class="note">${note}</div>` : ""}
+    <p class="pagenav">
+      <span class="next"><a href="${root}start">To the docs</a> <span class="icon">→</span></span>
+    </p>
+  </div>
+</section>
+`
+    : ""
+}
+</main>
+</div>
+
+${
+  [description, intro, features, note].some((s) => s.includes("<pre><code "))
+    ? getInjectedContent(ctx, "index", ":has-code", "append") ||
+      getDefaultCodeStyleContent(cssRoot)
+    : ""
+}
+${counterContent}
+${getInjectedContent(ctx, "index", "body", "append")}
+</body>
+</html>
+  `);
+}

package/src/bin/{getInjectedContent.ts → content/getInjectedContent.ts}

@@ -1,6 +1,6 @@
-import type { ContentInjectionTarget } from "../types/ContentInjectionTarget.ts";
-import type { Context } from "../types/Context.ts";
-import type { Page } from "../types/Page.ts";
+import type { ContentInjectionTarget } from "../../types/ContentInjectionTarget.ts";
+import type { Context } from "../../types/Context.ts";
+import type { Page } from "../../types/Page.ts";
 
 export function getInjectedContent(
   ctx: Context,

package/src/bin/{getNav.ts → content/getNav.ts}

@@ -1,13 +1,50 @@
 import { JSDOM } from "jsdom";
-import type { Context } from "../types/Context.ts";
-import type { NavItem } from "../types/NavItem.ts";
-import { fetchContent } from "./fetchContent.ts";
-import { getNpmLink } from "./getNpmLink.ts";
-import { getRepoLink } from "./getRepoLink.ts";
+import type { Context } from "../../types/Context.ts";
+import type { NavItem } from "../../types/NavItem.ts";
+import { fetchContent } from "../fetchContent.ts";
+import { getNpmLink } from "../getNpmLink.ts";
+import { getRepoLink } from "../getRepoLink.ts";
+
+let cachedNavContent = new Map<string, string>();
+
+async function getNavContent({ name, nav }: Context) {
+  if (!nav) return "";
+
+  let navContent = cachedNavContent.get(nav);
+
+  if (navContent !== undefined) return navContent;
+
+  navContent = await fetchContent(nav);
+
+  if (navContent) {
+    let navDom = new JSDOM(navContent).window.document.body;
+
+    for (let link of navDom.querySelectorAll("a")) {
+      if (link.dataset.name === name) {
+        let parent = link.parentElement;
+
+        link.remove();
+
+        while (parent && parent.innerHTML.trim() === "") {
+          let nextParent = parent.parentElement;
+
+          parent.remove();
+          parent = nextParent;
+        }
+      }
+    }
+
+    navContent = navDom.innerHTML;
+  }
+
+  cachedNavContent.set(nav, navContent);
+
+  return navContent;
+}
 
 export async function getNav(ctx: Context, navItems: NavItem[]) {
-  let { name, root, contentDir, backstory, nav } = ctx;
-  let navContent = await fetchContent(nav);
+  let { name, root, contentDir, backstory } = ctx;
+  let navContent = await getNavContent(ctx);
   let s = "";
 
   if (navContent) {

package/src/bin/content/getPlainTitle.ts

@@ -0,0 +1,12 @@
+import type { Context } from "../../types/Context.ts";
+import { escapeHTML } from "../../utils/escapeHTML.ts";
+import { getParsedContent } from "../parsing/getParsedContent.ts";
+import { stripHTML } from "../stripHTML.ts";
+
+export async function getPlainTitle(ctx: Context) {
+  let { name, title, htmlTitle } = ctx;
+
+  let { title: parsedTitle } = await getParsedContent(ctx);
+
+  return escapeHTML(title || stripHTML(htmlTitle || parsedTitle, true) || name);
+}

package/src/bin/content/getRedirectContent.ts

@@ -0,0 +1,31 @@
+import type { Context } from "../../types/Context.ts";
+import { escapeHTML } from "../../utils/escapeHTML.ts";
+import { getCounterContent } from "./getCounterContent.ts";
+import { getIconTag } from "./getIconTag.ts";
+import { getInjectedContent } from "./getInjectedContent.ts";
+import { toFileContent } from "./toFileContent.ts";
+
+export function getRedirectContent(ctx: Context) {
+  let { redirect } = ctx;
+  let escapedRedirect = escapeHTML(redirect);
+
+  return toFileContent(`
+<!DOCTYPE html>
+<html lang="en" data-layout="redirect" class="blank">
+<head>
+  ${getInjectedContent(ctx, "redirect", "head", "prepend")}
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+  <meta http-equiv="refresh" content="0; URL=${escapedRedirect}">
+  ${getIconTag(ctx)}
+  ${getInjectedContent(ctx, "redirect", "head", "append")}
+</head>
+<body>
+${getInjectedContent(ctx, "redirect", "body", "prepend")}
+${getCounterContent(ctx)}
+${getInjectedContent(ctx, "redirect", "body", "append")}
+<script>window.location.replace("${escapedRedirect}");</script>
+</body>
+</html>
+  `);
+}

package/src/bin/content/getSectionContent.ts

@@ -0,0 +1,80 @@
+import type { Context } from "../../types/Context.ts";
+import { escapeHTML } from "../../utils/escapeHTML.ts";
+import { escapeRegExp } from "../../utils/escapeRegExp.ts";
+import { getRepoLink } from "../getRepoLink.ts";
+import { getParsedContent } from "../parsing/getParsedContent.ts";
+import { stripHTML } from "../stripHTML.ts";
+import { getCounterContent } from "./getCounterContent.ts";
+import { getCSSRoot } from "./getCSSRoot.ts";
+import { getDefaultCodeStyleContent } from "./getDefaultCodeStyleContent.ts";
+import { getIconTag } from "./getIconTag.ts";
+import { getInjectedContent } from "./getInjectedContent.ts";
+import { getNav } from "./getNav.ts";
+import { getPlainTitle } from "./getPlainTitle.ts";
+import { toFileContent } from "./toFileContent.ts";
+
+export async function getSectionContent(ctx: Context, index: number) {
+  let { root, contentDir = "" } = ctx;
+
+  let cssRoot = await getCSSRoot(ctx, "content");
+  let { sections, nav } = await getParsedContent(ctx);
+
+  let content = sections[index];
+  let navContent = await getNav(ctx, nav);
+  let plainTitle = await getPlainTitle(ctx);
+
+  return toFileContent(`
+<!DOCTYPE html>
+<html lang="en" data-layout="section">
+<head>
+  ${getInjectedContent(ctx, "section", "head", "prepend")}
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="${plainTitle}: ${escapeHTML(stripHTML(nav[index]?.title, true))}">
+  <title>${escapeHTML(stripHTML(nav[index]?.title, true))} | ${plainTitle}</title>
+  <link rel="stylesheet" href="${cssRoot}/base.css">
+  <link rel="stylesheet" href="${cssRoot}/section.css">
+  ${getIconTag(ctx)}
+  ${nav[index + 1]?.id ? `<link rel="prefetch" href="${root}${contentDir}/${nav[index + 1]?.id}">` : ""}
+  ${nav[index - 1]?.id ? `<link rel="prefetch" href="${root}${contentDir}/${nav[index - 1]?.id}">` : ""}
+  ${getInjectedContent(ctx, "section", "head", "append")}
+</head>
+<body>
+${getInjectedContent(ctx, "section", "body", "prepend")}
+<div class="layout">
+<div class="${navContent ? "" : "no-nav "}body">
+<main>
+<h1><a href="${root}">${plainTitle}</a></h1>
+${content}
+
+<p class="pagenav">
+  <span class="prev">
+    <span class="icon">←</span>
+    ${nav[index - 1]?.id ? `<a href="${root}${contentDir}/${nav[index - 1]?.id}">${nav[index - 1]?.title}</a>` : `<a href="${root}">Intro</a>`}
+  </span>
+  <span class="sep">|</span>
+  ${nav[index + 1]?.id ? `<span class="next"><a href="${root}${contentDir}/${nav[index + 1]?.id}">${nav[index + 1]?.title}</a> <span class="icon">→</span></span>` : `<span class="repo">${getRepoLink(ctx)}</span>`}
+</p>
+</main>
+${navContent ? "<hr>" : ""}
+${navContent.replace(
+  new RegExp(
+    `(<li data-id="${escapeRegExp(nav[index]?.id)}">)<a href="[^"]+">([^<]+)</a>`,
+  ),
+  "$1<strong>$2</strong>",
+)}
+</div>
+</div>
+
+${
+  content.includes("<pre><code ")
+    ? getInjectedContent(ctx, "section", ":has-code", "append") ||
+      getDefaultCodeStyleContent(cssRoot)
+    : ""
+}
+${getCounterContent(ctx)}
+${getInjectedContent(ctx, "section", "body", "append")}
+</body>
+</html>
+  `);
+}

package/src/bin/content/getStartContent.ts

@@ -0,0 +1,40 @@
+import type { Context } from "../../types/Context.ts";
+import { getParsedContent } from "../parsing/getParsedContent.ts";
+import { getCounterContent } from "./getCounterContent.ts";
+import { getCSSRoot } from "./getCSSRoot.ts";
+import { getIconTag } from "./getIconTag.ts";
+import { getInjectedContent } from "./getInjectedContent.ts";
+import { getPlainTitle } from "./getPlainTitle.ts";
+import { toFileContent } from "./toFileContent.ts";
+
+export async function getStartContent(ctx: Context) {
+  let { root, contentDir = "" } = ctx;
+  let { nav } = await getParsedContent(ctx);
+  let plainTitle = await getPlainTitle(ctx);
+
+  return toFileContent(`
+<!DOCTYPE html>
+<html lang="en" data-layout="start" class="blank">
+<head>
+  ${getInjectedContent(ctx, "start", "head", "prepend")}
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+  <meta http-equiv="refresh" content="0; URL=${root}${contentDir}/${nav[0]?.id}">
+  <title>${plainTitle}</title>
+  <link rel="stylesheet" href="${await getCSSRoot(ctx, "index")}/base.css">
+  ${getIconTag(ctx)}
+  <script>window.location.replace("${root}${contentDir}/${nav[0]?.id}");</script>
+  ${getInjectedContent(ctx, "start", "head", "append")}
+</head>
+<body>
+${getInjectedContent(ctx, "start", "body", "prepend")}
+<div class="layout">
+  <h1>${plainTitle}</h1>
+</div>
+
+${getCounterContent(ctx)}
+${getInjectedContent(ctx, "start", "body", "append")}
+</body>
+</html>
+  `);
+}

package/src/bin/content/tweakTypography.ts

@@ -0,0 +1,5 @@
+export function tweakTypography(s = "") {
+  return s
+    .replace(/\b(for|in|on|at|to|with|a|an|the|its)\s+/gi, "$1\xa0")
+    .replace(/\b(React)\s+(apps?)\b/gi, "$1\xa0$2");
+}

package/src/bin/parsing/getParsedContent.ts

@@ -1,6 +1,7 @@
 import { JSDOM } from "jsdom";
 import Markdown from "markdown-it";
 import type { Context } from "../../types/Context.ts";
+import type { NavItem } from "../../types/NavItem.ts";
 import { fetchContent } from "../fetchContent.ts";
 import { getLocation } from "../getLocation.ts";
 import { buildNav } from "./buildNav.ts";
@@ -10,15 +11,33 @@ import { isBadgeContainer } from "./isBadgeContainer.ts";
 import { joinLines } from "./joinLines.ts";
 import { preprocessContent } from "./preprocessContent.ts";
 
+export type ParsedContent = {
+  badges: string;
+  title: string;
+  description: string;
+  intro: string;
+  features: string;
+  note: string;
+  installation: string;
+  sections: string[];
+  nav: NavItem[];
+};
+
 const md = new Markdown({
   html: true,
 });
 
-export async function getParsedContent(ctx: Context) {
+const parsedContentCache = new Map<string, ParsedContent>();
+
+export async function getParsedContent(ctx: Context): Promise<ParsedContent> {
+  let contentLocation = getLocation(ctx, "README.md", ctx.source);
+  let parsedContent = parsedContentCache.get(contentLocation);
+
+  if (parsedContent) return parsedContent;
+
   let { singlePage, firstLineDescription, linkMap } = ctx;
-  let rawContent = await fetchContent(
-    getLocation(ctx, "README.md", ctx.source),
-  );
+
+  let rawContent = await fetchContent(contentLocation);
   let content = md.render(preprocessContent(rawContent));
   let dom = new JSDOM(content);
 
@@ -123,7 +142,7 @@ export async function getParsedContent(ctx: Context) {
     }
   }
 
-  return {
+  parsedContent = {
     badges, // postprocessBadges(joinLines(badges)),
     title,
     description: joinLines(description),
@@ -134,4 +153,8 @@ export async function getParsedContent(ctx: Context) {
     sections: sections.map(postprocess),
     nav,
   };
+
+  parsedContentCache.set(contentLocation, parsedContent);
+
+  return parsedContent;
 }