@t8/docsgen 0.1.0

package/src/bin/getParsedContent.ts

@@ -0,0 +1,180 @@
+import { JSDOM } from "jsdom";
+import Markdown from "markdown-it";
+import type { Context } from "../types/Context";
+import type { NavItem } from "../types/NavItem";
+import { fetchText } from "./fetchText";
+import { getSlug } from "./getSlug";
+
+const md = new Markdown({
+  html: true,
+});
+
+function joinLines(x: string[]) {
+  return x.join("\n").trim();
+}
+
+function buildNav(ctx: Context, dom: JSDOM) {
+  let { root, contentDir, singlePage } = ctx;
+  let linkMap: Record<string, string> = {};
+
+  let navItem: NavItem | null = null;
+  let nav: NavItem[] = [];
+
+  if (singlePage)
+    nav.push({
+      id: "Overview",
+      title: "Overview",
+      items: [],
+    });
+  else {
+    let headings =
+      dom.window.document.body.querySelectorAll("h2, h3, h4, h5, h6");
+
+    for (let element of headings) {
+      let tagName = element.tagName.toLowerCase();
+
+      let isSectionTitle = tagName === "h2";
+      let isSubsectionTitle = tagName === "h3";
+
+      let sectionId = isSectionTitle
+        ? getSlug(element.textContent)
+        : (navItem?.id ?? "");
+      let elementId = element.id;
+
+      if (!elementId)
+        elementId = getSlug(element.textContent)
+          .toLowerCase()
+          .replace(/_/g, "-");
+
+      if (elementId) {
+        element.id = elementId;
+
+        let link = `${root}${contentDir}/${sectionId}`;
+
+        if (!isSectionTitle) link += `#${elementId}`;
+
+        linkMap[`#${elementId}`] = link;
+      }
+
+      if (isSectionTitle) {
+        if (navItem) nav.push(navItem);
+
+        navItem = {
+          id: getSlug(element.textContent),
+          title: element.innerHTML.trim(),
+          items: [],
+        };
+      } else if (isSubsectionTitle) {
+        if (navItem)
+          navItem.items.push({
+            id: getSlug(element.textContent),
+            title: element.innerHTML.trim(),
+          });
+      }
+    }
+
+    if (navItem) nav.push(navItem);
+  }
+
+  return {
+    nav,
+    linkMap,
+  };
+}
+
+function getInstallationCode(element: Element) {
+  return element
+    .querySelector("code")
+    ?.innerHTML.trim()
+    .match(/(\S\s*)?(npm (i|install) .*)/)?.[2];
+}
+
+function getSectionPostprocess(linkMap: Record<string, string>) {
+  return (content: string) => {
+    let s = content;
+
+    s = s.replace(/<a href="([^"]+)">/g, (_, url) => {
+      if (url?.startsWith("#")) return `<a href="${linkMap[url] ?? url}">`;
+      return `<a href="${url}" target="_blank">`;
+    });
+
+    return s;
+  };
+}
+
+export async function getParsedContent(ctx: Context) {
+  let { source = "README.md", singlePage } = ctx;
+  let content = md.render(await fetchText(source));
+  let dom = new JSDOM(content);
+
+  let { nav, linkMap } = buildNav(ctx, dom);
+
+  let badges: string[] = [];
+  let title = "";
+  let description: string[] = [];
+  let features: string[] = [];
+  let note: string[] = [];
+  let installation = "";
+
+  let section: string[] = [];
+  let sections: string[] = [];
+
+  let hasTitle = false;
+  let hasFeatures = false;
+  let indexComplete = false;
+
+  let element = dom.window.document.body.firstElementChild;
+
+  while (element !== null) {
+    if (element.matches("h1")) hasTitle = true;
+    else {
+      if (element.matches("h2")) {
+        if (!indexComplete) indexComplete = true;
+
+        if (!singlePage && section.length !== 0) {
+          sections.push(joinLines(section));
+          section = [];
+        }
+      }
+
+      let { outerHTML } = element;
+
+      if (indexComplete) section.push(outerHTML);
+      else if (!hasTitle) {
+        badges.push(outerHTML);
+      } else if (!hasFeatures) {
+        if (element.matches("ul")) {
+          hasFeatures = true;
+          features.push(outerHTML);
+        } else {
+          let installationCode = getInstallationCode(element);
+
+          if (installationCode) installation = installationCode;
+          else description.push(outerHTML);
+        }
+      } else {
+        let installationCode = getInstallationCode(element);
+
+        if (installationCode) installation = installationCode;
+        else note.push(outerHTML);
+      }
+    }
+
+    element = element.nextElementSibling;
+  }
+
+  if (section.length !== 0) sections.push(joinLines(section));
+
+  let postprocess = getSectionPostprocess(linkMap);
+
+  return {
+    badges: joinLines(badges),
+    title,
+    description: joinLines(description),
+    features: joinLines(features),
+    note: joinLines(note),
+    installation,
+    sections: sections.map(postprocess),
+    nav,
+  };
+}

package/src/bin/getRepoLink.ts

@@ -0,0 +1,9 @@
+import type { Context } from "../types/Context";
+
+export function getRepoLink({ repo }: Context, className?: string) {
+  if (!repo) return "";
+
+  let caption = /\bgithub\.com\//.test(repo) ? "GitHub" : "Repository";
+
+  return `<a href="${repo}"${className ? ` class="${className}"` : ""} target="_blank">${caption}</a>`;
+}

package/src/bin/getSlug.ts

@@ -0,0 +1,21 @@
+export function getSlug(title: string | null) {
+  if (!title) return "";
+
+  let slug = title.trim();
+
+  if (
+    (slug.startsWith("<") && slug.endsWith(">")) ||
+    (slug.startsWith("`") && slug.endsWith("`"))
+  )
+    slug = slug.slice(1, -1);
+
+  slug = slug
+    .replace(/[<>`:?!.,]+/g, " ")
+    .trim()
+    .replace(/\s+/g, "_")
+    .replace(/'/g, "");
+
+  if (/^\w+\(\)$/.test(slug)) slug = slug.slice(0, -2);
+
+  return slug;
+}

package/src/bin/getTitle.ts

@@ -0,0 +1,49 @@
+import type { Context } from "../types/Context";
+import { escapeHTML } from "../utils/escapeHTML";
+
+type GetTitleParams = {
+  cover?: boolean;
+  originalContent?: string;
+  withPackageURL?: boolean;
+};
+
+export function getTitle(
+  ctx: Context,
+  { cover, originalContent, withPackageURL }: GetTitleParams = {},
+) {
+  let { root, name, title: packageTitle, scope, theme } = ctx;
+
+  if (originalContent && ![name, packageTitle].includes(originalContent.trim()))
+    return originalContent;
+
+  if (packageTitle) {
+    let escapedTitle = escapeHTML(packageTitle);
+
+    if (cover && theme === "t8" && packageTitle.startsWith("T8 "))
+      return `<a href="/">T8</a> <span class="name">${packageTitle.replace(/^T8 /, "")}</span>`;
+
+    return withPackageURL
+      ? `<a href="${root}" class="name">${escapedTitle}</a>`
+      : `<span class="name">${escapedTitle}</span>`;
+  }
+
+  let scopeMatches = name?.match(/^(@[^/]+)\/?(.*)/);
+
+  if (!scope || !scopeMatches) {
+    let escapedName = escapeHTML(name);
+
+    return withPackageURL
+      ? `<a href="${root}" class="name">${escapedName}</a>`
+      : `<span class="name">${escapedName}</span>`;
+  }
+
+  let title =
+    `<a href="${scope}" class="scope">${scopeMatches[1]}</a>` +
+    '<span class="sep">/</span>';
+
+  title += withPackageURL
+    ? `<a href="${root}" class="name">${scopeMatches[2]}</a>`
+    : `<span class="name">${scopeMatches[2]}</span>`;
+
+  return title;
+}

package/src/bin/run.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { getConfig } from "./getConfig";
+import { runEntry } from "./runEntry";
+
+async function run() {
+  let { targetId, entries, ...rootCtx } = await getConfig();
+
+  if (!entries) {
+    if (!targetId || targetId === rootCtx.id) return await runEntry(rootCtx);
+
+    console.warn(`Specified config entry not found: '${targetId}'`);
+    return;
+  }
+
+  if (targetId) {
+    let entryCtx = entries.find(({ id }) => id === targetId);
+
+    if (entryCtx) runEntry(entryCtx);
+    else console.warn(`Specified config entry not found: '${targetId}'`);
+  } else {
+    await Promise.all(
+      entries.map((entryCtx) => {
+        return runEntry({ ...rootCtx, ...entryCtx });
+      }),
+    );
+  }
+}
+
+(async () => {
+  await run();
+})();

package/src/bin/runEntry.ts

@@ -0,0 +1,55 @@
+import { exec as defaultExec } from "node:child_process";
+import { access } from "node:fs/promises";
+import { promisify } from "node:util";
+import type { Context } from "../types/Context";
+import { cleanup } from "./cleanup";
+import { createFiles } from "./createFiles";
+
+const exec = promisify(defaultExec);
+const stdout = async (cmd: string) => (await exec(cmd)).stdout.trim();
+
+async function isGitDir() {
+  try {
+    await access("./.git");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runEntry(ctx: Context) {
+  let { targetBranch, mainBranch, remove } = ctx;
+
+  if (!targetBranch || !(await isGitDir())) {
+    await cleanup(ctx);
+    await createFiles(ctx);
+    return;
+  }
+
+  let originalBranch = await stdout("git rev-parse --abbrev-ref HEAD");
+
+  if (originalBranch === targetBranch) await exec(`git checkout ${mainBranch}`);
+
+  try {
+    await exec(`git branch -D ${targetBranch}`);
+  } catch {}
+  try {
+    await exec(`git push origin ${targetBranch} --delete`);
+  } catch {}
+
+  if (remove) return;
+
+  await exec(`git checkout -b ${targetBranch}`);
+  await createFiles(ctx);
+  await exec("git add *");
+
+  let updated = (await stdout("git diff --cached --name-only")) !== "";
+
+  if (updated) {
+    await exec('git commit -m "release gh-pages"');
+    await exec(`git push -u origin ${targetBranch} -f`);
+  }
+
+  if (originalBranch && originalBranch !== targetBranch)
+    await exec(`git checkout ${originalBranch}`);
+}

package/src/bin/setCName.ts

@@ -0,0 +1,13 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Context } from "../types/Context";
+
+export async function setCName({ dir = "", name, cname, jsorg }: Context) {
+  let domain = "";
+
+  if (cname) domain = cname;
+  else if (typeof jsorg === "string") domain = jsorg ? `${jsorg}.js.org` : "";
+  else if (jsorg === true) domain = name ? `${name}.js.org` : "";
+
+  if (domain !== "") await writeFile(join(dir, "CNAME"), domain);
+}

package/src/bin/setContent.ts

@@ -0,0 +1,251 @@
+import { exec as defaultExec } from "node:child_process";
+import { access, mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { packageName } from "../const/packageName";
+import type { Context } from "../types/Context";
+import { escapeHTML } from "../utils/escapeHTML";
+import { escapeRegExp } from "../utils/escapeRegExp";
+import { getCounterContent } from "./getCounterContent";
+import { getNav } from "./getNav";
+import { getParsedContent } from "./getParsedContent";
+import { getRepoLink } from "./getRepoLink";
+import { getTitle } from "./getTitle";
+import { toFileContent } from "./toFileContent";
+
+const exec = promisify(defaultExec);
+
+export async function setContent(ctx: Context) {
+  let {
+    dir = "",
+    colorScheme,
+    theme,
+    root,
+    contentDir = "",
+    name,
+    title,
+    description: packageDescription,
+    backstory,
+    redirect,
+  } = ctx;
+
+  let counterContent = getCounterContent(ctx);
+  let escapedName = escapeHTML(name);
+  let escapedTitle = title ? escapeHTML(title) : escapedName;
+
+  let packageVersion = (await exec(`npm view ${packageName} version`)).stdout
+    .trim()
+    .split(".")
+    .slice(0, 2)
+    .join(".");
+
+  let packageUrl = `https://unpkg.com/${packageName}@${packageVersion}`;
+  let rootAttrs = "";
+
+  let icon = {
+    url: `${root}favicon.svg`,
+    type: "image/svg+xml",
+  };
+
+  if (theme) rootAttrs += ` data-theme="${escapeHTML(theme)}"`;
+
+  if (colorScheme)
+    rootAttrs += ` style="--color-scheme: ${escapeHTML(colorScheme)}"`;
+
+  if (theme === "t8")
+    icon = {
+      url: "/assets/t8.png",
+      type: "image/png",
+    };
+
+  if (redirect) {
+    let escapedRedirect = escapeHTML(redirect);
+
+    await writeFile(
+      join(dir, "index.html"),
+      toFileContent(`
+<!DOCTYPE html>
+<html lang="en" class="blank"${rootAttrs}>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+  <meta http-equiv="refresh" content="0; URL=${escapedRedirect}">
+</head>
+<body>
+${counterContent}
+<script>window.location.replace("${escapedRedirect}");</script>
+</body>
+</html>
+            `),
+    );
+
+    return;
+  }
+
+  let { badges, description, features, installation, sections, nav } =
+    await getParsedContent(ctx);
+
+  let navContent = await getNav(ctx, nav);
+  let dirs = [contentDir];
+
+  await Promise.all(
+    dirs.map(async (path) => {
+      let dirPath = join(dir, path);
+
+      try {
+        await access(dirPath);
+      } catch {
+        await mkdir(dirPath);
+      }
+    }),
+  );
+
+  await Promise.all([
+    ...sections.map(async (content, i) =>
+      writeFile(
+        join(dir, contentDir, `${nav[i]?.id ?? `_untitled_${i}`}.html`),
+        toFileContent(`
+<!DOCTYPE html>
+<html lang="en"${rootAttrs}>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHTML(nav[i]?.title)} | ${escapedTitle}</title>
+<link rel="stylesheet" href="${packageUrl}/dist/css/base.css">
+<link rel="stylesheet" href="${packageUrl}/dist/css/section.css">
+<link rel="icon" type="${icon.type}" href="${icon.url}">
+${nav[i + 1]?.id ? `<link rel="prefetch" href="${root}${contentDir}/${nav[i + 1]?.id}">` : ""}
+${nav[i - 1]?.id ? `<link rel="prefetch" href="${root}${contentDir}/${nav[i - 1]?.id}">` : ""}
+</head>
+<body>
+<div class="layout">
+<div class="${navContent ? "" : "no-nav "}body">
+<main>
+<h1>${getTitle(ctx, { withPackageURL: true })}</h1>
+${content}
+
+<p class="pagenav">
+  <span class="prev">
+    <span class="icon">←</span>
+    ${nav[i - 1]?.id ? `<a href="${root}${contentDir}/${nav[i - 1]?.id}">${nav[i - 1]?.title}</a>` : `<a href="${root}">Intro</a>`}
+  </span>
+  <span class="sep">|</span>
+  ${nav[i + 1]?.id ? `<span class="next"><a href="${root}${contentDir}/${nav[i + 1]?.id}">${nav[i + 1]?.title}</a> <span class="icon">→</span></span>` : `<span class="repo next">${getRepoLink(ctx)} <span class="icon">✦</span></span>`}
+</p>
+</main>
+${navContent ? "<hr>" : ""}
+${navContent.replace(
+  new RegExp(
+    `(<li data-id="${escapeRegExp(nav[i]?.id)}">)<a href="[^"]+">([^<]+)</a>(</li>)`,
+  ),
+  "$1<strong>$2</strong>$3",
+)}
+</div>
+</div>
+
+${
+  content.includes("<pre><code ")
+    ? `
+<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/styles/base16/material.min.css">
+<link rel="stylesheet" href="${packageUrl}/dist/css/code.css">
+<script src="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/highlight.min.js"></script>
+<script>hljs.highlightAll()</script>
+`.trim()
+    : ""
+}
+${counterContent}
+</body>
+</html>
+        `),
+      ),
+    ),
+    writeFile(
+      join(dir, "index.html"),
+      toFileContent(`
+<!DOCTYPE html>
+<html lang="en"${rootAttrs}>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapedTitle}${packageDescription ? ` | ${escapeHTML(packageDescription)}` : ""}</title>
+<link rel="stylesheet" href="${packageUrl}/dist/css/base.css">
+<link rel="stylesheet" href="${packageUrl}/dist/css/index.css">
+<link rel="icon" type="${icon.type}" href="${icon.url}">
+<link rel="prefetch" href="${root}start">
+${nav[0] ? `<link rel="prefetch" href="${root}${contentDir}/${nav[0]?.id ?? ""}">` : ""}
+</head>
+<body>
+<div class="layout">
+<main>
+<section class="intro-title">
+  <div class="badges">
+    ${badges}
+  </div>
+  <h1>${getTitle(ctx, { cover: true })}</h1>
+  <div class="description">
+    ${description}
+  </div>
+  <p class="actions">
+    <a href="${root}start" class="primary button">Docs</a>
+    <span class="sep"> • </span>
+    ${getRepoLink(ctx, "button")}
+  </p>
+  ${backstory ? `<p class="ref"><a href="${backstory}">Backstory</a></p>` : ""}
+  <p class="installation"><code>${installation}</code></p>
+</section>
+${
+  features
+    ? `
+<section class="intro">
+  <div class="features">
+    <h2>Features</h2>
+    ${features}
+  </div>
+</section>
+`
+    : ""
+}
+</main>
+</div>
+
+${
+  [description, features].some((s) => s.includes("<pre><code "))
+    ? `
+<link rel="stylesheet" href="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/styles/base16/material.min.css">
+<link rel="stylesheet" href="${packageUrl}/dist/css/code.css">
+<script src="https://unpkg.com/@highlightjs/cdn-assets@11.11.1/highlight.min.js"></script>
+<script>hljs.highlightAll()</script>
+`.trim()
+    : ""
+}
+${counterContent}
+</body>
+</html>
+            `),
+    ),
+    writeFile(
+      join(dir, "start.html"),
+      toFileContent(`
+<!DOCTYPE html>
+<html lang="en" class="blank"${rootAttrs}>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+  <meta http-equiv="refresh" content="0; URL=${root}${contentDir}/${nav[0]?.id}">
+  <title>${escapedTitle}</title>
+  <link rel="stylesheet" href="${packageUrl}/dist/css/base.css">
+  <link rel="icon" type="${icon.type}" href="${icon.url}">
+  <script>window.location.replace("${root}${contentDir}/${nav[0]?.id}");</script>
+</head>
+<body>
+<div class="layout">
+  <h1>${escapedTitle}</h1>
+</div>
+
+${counterContent}
+</body>
+</html>
+            `),
+    ),
+  ]);
+}

package/src/bin/setImages.ts

@@ -0,0 +1,8 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Context } from "../types/Context";
+import { getIcon } from "../utils/getIcon";
+
+export async function setImages({ dir = "", colorScheme }: Context) {
+  await writeFile(join(dir, "./favicon.svg"), `${getIcon(colorScheme)}\n`);
+}

package/src/bin/toConfig.ts

@@ -0,0 +1,14 @@
+import type { BinConfig } from "../types/BinConfig";
+import type { PackageMetadata } from "../types/PackageMetadata";
+import { toRepoURL } from "./toRepoURL";
+
+export function toConfig(metadata: PackageMetadata): Partial<BinConfig> {
+  let { name, description, version, repository } = metadata;
+
+  return {
+    name,
+    description,
+    version,
+    repo: toRepoURL(repository),
+  };
+}

package/src/bin/toFileContent.ts

@@ -0,0 +1,3 @@
+export function toFileContent(x: string) {
+  return `${x.trim()}\n`;
+}

package/src/bin/toRepoURL.ts

@@ -0,0 +1,22 @@
+import type { PackageMetadata } from "../types/PackageMetadata";
+
+export function toRepoURL(x: PackageMetadata["repository"]) {
+  if (!x) return "";
+
+  let s = typeof x === "string" ? x : x.url;
+
+  if (!s) return;
+
+  if (/^https?:\/\//.test(s)) return s;
+
+  if (/^git\+https?:\/\/.*\.git$/.test(s))
+    return s.replace(/^git\+(https?:\/\/.*)\.git$/, "$1");
+
+  if (/^git:\/\/.*\.git$/.test(s))
+    return s.replace(/^git(:\/\/.*)\.git$/, "https$1");
+
+  if (/^github:/.test(s))
+    return `https://github.com/${s.replace(/^github:/, "")}`;
+
+  return "";
+}

package/src/const/packageName.ts

@@ -0,0 +1 @@
+export const packageName = "@t8/docsgen";