@t8/docsgen 0.3.13 → 0.3.15

package/dist/bin.js

@@ -511,7 +511,7 @@ function buildNav(ctx, dom) {
 
 // src/bin/parsing/getInstallationCode.ts
 function getInstallationCode(element) {
-  return element.querySelector("code")?.innerHTML.trim().match(/(\S\s*)?(npm (i|install) .*)/)?.[2];
+  return element.querySelector("code")?.textContent.trim().match(/(\S\s*)?(npm (i|install) .*)/)?.[2];
 }
 
 // src/bin/parsing/getSectionPostprocess.ts
@@ -569,7 +569,7 @@ var md = new Markdown({
   html: true
 });
 async function getParsedContent(ctx) {
-  let { singlePage, firstLineDescription, linkMap } = ctx;
+  let { singlePage, firstLineDescription, hasCoverIntro = true, linkMap } = ctx;
   let rawContent = await fetchContent(
     getLocation(ctx, "README.md", ctx.source)
   );
@@ -628,7 +628,11 @@ async function getParsedContent(ctx) {
       description.push(outerHTML);
       continue;
     }
-    intro.push(outerHTML);
+    if (hasCoverIntro) {
+      intro.push(outerHTML);
+      continue;
+    }
+    indexComplete = true;
   }
   if (section.length !== 0) sections.push(joinLines(section));
   let postprocess = getSectionPostprocess({
@@ -695,6 +699,7 @@ async function setContent(ctx) {
     title,
     htmlTitle,
     description: packageDescription,
+    isDevDep,
     backstory,
     redirect
   } = ctx;
@@ -760,6 +765,8 @@ ${getInjectedContent(ctx, "redirect", "body", "append")}
   );
   let coverTitle = htmlTitle || parsedTitle || plainTitle;
   let descriptionContent = tweakTypography(description) || (escapedPackageDescription ? `<p>${tweakTypography(escapedPackageDescription)}<p>` : "");
+  if (!installation || isDevDep !== void 0)
+    installation = `npm i${isDevDep ? " -D" : ""} ${name}`;
   let navContent = await getNav(ctx, nav);
   let dirs = [contentDir];
   await Promise.all(
@@ -862,7 +869,7 @@ ${getInjectedContent(ctx, "index", "body", "prepend")}
       ${getRepoLink(ctx)}
     </p>
     ${backstory ? `<p class="ref"><a href="${backstory}">Backstory</a></p>` : ""}
-    <p class="installation"><code>${installation}</code></p>
+    <p class="installation"><code>${escapeHTML(installation)}</code></p>
     ${getInjectedContent(ctx, "index", "cover", "append")}
   </div>
 </section>

package/package.json

@@ -1,36 +1,36 @@
-{
-  "name": "@t8/docsgen",
-  "version": "0.3.13",
-  "description": "",
-  "main": "dist/bin.js",
-  "type": "module",
-  "bin": {
-    "docsgen": "dist/bin.js"
-  },
-  "scripts": {
-    "build": "npx npm-run-all clean build-bin build-css",
-    "build-bin": "npx esbuild ./src/bin/run.ts --bundle --outfile=dist/bin.js --platform=node --external:jsdom --external:markdown-it --format=esm",
-    "build-css": "node -e \"require('node:fs').cpSync('src/css', 'dist/css', { force: true, recursive: true });\"",
-    "clean": "node -e \"require('node:fs').rmSync('dist', { force: true, recursive: true });\"",
-    "patch": "node src/scripts/patch.ts",
-    "preversion": "npx npm-run-all shape build",
-    "schema": "npx ts-json-schema-generator -p src/types/Config.ts -t Config -o schema.json --minify",
-    "shape": "npx codeshape --check"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/t8js/docsgen.git"
-  },
-  "license": "MIT",
-  "author": "axtk",
-  "devDependencies": {
-    "@types/jsdom": "^27.0.0",
-    "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.0.2"
-  },
-  "dependencies": {
-    "args-json": "^1.2.9",
-    "jsdom": "^27.3.0",
-    "markdown-it": "^14.1.0"
-  }
-}
+{
+  "name": "@t8/docsgen",
+  "version": "0.3.15",
+  "description": "",
+  "main": "dist/bin.js",
+  "type": "module",
+  "bin": {
+    "docsgen": "dist/bin.js"
+  },
+  "scripts": {
+    "build": "npx npm-run-all clean build-bin build-css",
+    "build-bin": "npx esbuild ./src/bin/run.ts --bundle --outfile=dist/bin.js --platform=node --external:jsdom --external:markdown-it --format=esm",
+    "build-css": "node -e \"require('node:fs').cpSync('src/css', 'dist/css', { force: true, recursive: true });\"",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { force: true, recursive: true });\"",
+    "patch": "node src/scripts/patch.ts",
+    "preversion": "npx npm-run-all shape build",
+    "schema": "npx ts-json-schema-generator -p src/types/Config.ts -t Config -o schema.json --minify",
+    "shape": "npx codeshape --check"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t8js/docsgen.git"
+  },
+  "license": "MIT",
+  "author": "axtk",
+  "devDependencies": {
+    "@types/jsdom": "^27.0.0",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^25.0.2"
+  },
+  "dependencies": {
+    "args-json": "^1.2.9",
+    "jsdom": "^27.3.0",
+    "markdown-it": "^14.1.0"
+  }
+}

package/schema.json

@@ -1 +1 @@
-{"$ref":"#/definitions/Config","$schema":"http://json-schema.org/draft-07/schema#","definitions":{"Config":{"additionalProperties":false,"properties":{"$schema":{"type":"string"},"append":{"$ref":"#/definitions/ContentInjectionMap"},"assetsDir":{"description":"Directory path for assets, relative to `dir`. If not provided, the assets will be added via the package URLs.","type":"string"},"backstory":{"description":"Backstory link URL to be added to the front page.","type":"string"},"cname":{"description":"Content of the './CNAME' file.","type":"string"},"contentDir":{"description":"Generated section content directory.","type":"string"},"description":{"type":"string"},"dir":{"type":"string"},"entries":{"items":{"$ref":"#/definitions/EntryConfig"},"type":"array"},"favicon":{"description":"Favicon URL.","type":"string"},"faviconType":{"type":"string"},"firstLineDescription":{"description":"Whether the first line following the main title is the package description.","type":"boolean"},"htmlTitle":{"type":"string"},"id":{"type":"string"},"jsorg":{"description":"As a boolean, it means whether to add the '<package_name>.js.org' domain to the './CNAME' file.\n\nAs a string, it sets the '<jsorg_value>.js.org' domain to the './CNAME' file.","type":["boolean","string"]},"linkMap":{"additionalProperties":{"anyOf":[{"type":"string"},{"not":{}}]},"description":"Link substitution map.","type":"object"},"mainBranch":{"type":"string"},"name":{"type":"string"},"nav":{"description":"URL of an HTML file inserted into the navigation bar.","type":"string"},"npm":{"type":"string"},"prepend":{"$ref":"#/definitions/ContentInjectionMap"},"redirect":{"description":"Redirection URL.","type":"string"},"remove":{"description":"Whether to remove the GitHub Pages branch and quit.","type":"boolean"},"repo":{"type":"string"},"root":{"description":"Main page root path.","type":"string"},"singlePage":{"description":"Whether to show all sections on a single page.","type":"boolean"},"source":{"type":"string"},"targetBranch":{"description":"Target branch.","examples":["gh-pages"],"type":"string"},"targetIds":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"version":{"type":"string"},"ymid":{"type":["number","string"]}},"type":"object"},"ContentInjectionMap":{"additionalProperties":false,"properties":{":has-code":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]},"body":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]},"cover":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]},"head":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]}},"type":"object"},"EntryConfig":{"additionalProperties":false,"properties":{"append":{"$ref":"#/definitions/ContentInjectionMap"},"assetsDir":{"description":"Directory path for assets, relative to `dir`. If not provided, the assets will be added via the package URLs.","type":"string"},"backstory":{"description":"Backstory link URL to be added to the front page.","type":"string"},"cname":{"description":"Content of the './CNAME' file.","type":"string"},"contentDir":{"description":"Generated section content directory.","type":"string"},"description":{"type":"string"},"dir":{"type":"string"},"favicon":{"description":"Favicon URL.","type":"string"},"faviconType":{"type":"string"},"firstLineDescription":{"description":"Whether the first line following the main title is the package description.","type":"boolean"},"htmlTitle":{"type":"string"},"id":{"type":"string"},"jsorg":{"description":"As a boolean, it means whether to add the '<package_name>.js.org' domain to the './CNAME' file.\n\nAs a string, it sets the '<jsorg_value>.js.org' domain to the './CNAME' file.","type":["boolean","string"]},"linkMap":{"additionalProperties":{"anyOf":[{"type":"string"},{"not":{}}]},"description":"Link substitution map.","type":"object"},"mainBranch":{"type":"string"},"name":{"type":"string"},"nav":{"description":"URL of an HTML file inserted into the navigation bar.","type":"string"},"npm":{"type":"string"},"prepend":{"$ref":"#/definitions/ContentInjectionMap"},"redirect":{"description":"Redirection URL.","type":"string"},"remove":{"description":"Whether to remove the GitHub Pages branch and quit.","type":"boolean"},"repo":{"type":"string"},"root":{"description":"Main page root path.","type":"string"},"singlePage":{"description":"Whether to show all sections on a single page.","type":"boolean"},"source":{"type":"string"},"targetBranch":{"description":"Target branch.","examples":["gh-pages"],"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"ymid":{"type":["number","string"]}},"type":"object"},"Page":{"enum":["index","start","section","redirect"],"type":"string"}}}
+{"$ref":"#/definitions/Config","$schema":"http://json-schema.org/draft-07/schema#","definitions":{"Config":{"additionalProperties":false,"properties":{"$schema":{"type":"string"},"append":{"$ref":"#/definitions/ContentInjectionMap"},"assetsDir":{"description":"Directory path for assets, relative to `dir`. If not provided, the assets will be added via the package URLs.","type":"string"},"backstory":{"description":"Backstory link URL to be added to the front page.","type":"string"},"cname":{"description":"Content of the './CNAME' file.","type":"string"},"contentDir":{"description":"Generated section content directory.","type":"string"},"description":{"type":"string"},"dir":{"type":"string"},"entries":{"items":{"$ref":"#/definitions/EntryConfig"},"type":"array"},"favicon":{"description":"Favicon URL.","type":"string"},"faviconType":{"type":"string"},"firstLineDescription":{"description":"Whether the first line following the main title is the package description.","type":"boolean"},"hasCoverIntro":{"type":"boolean"},"htmlTitle":{"type":"string"},"id":{"type":"string"},"isDevDep":{"description":"Whether the package installation instruction should include the \"-D\" flag.","type":"boolean"},"jsorg":{"description":"As a boolean, it means whether to add the '<package_name>.js.org' domain to the './CNAME' file.\n\nAs a string, it sets the '<jsorg_value>.js.org' domain to the './CNAME' file.","type":["boolean","string"]},"linkMap":{"additionalProperties":{"anyOf":[{"type":"string"},{"not":{}}]},"description":"Link substitution map.","type":"object"},"mainBranch":{"type":"string"},"name":{"type":"string"},"nav":{"description":"URL of an HTML file inserted into the navigation bar.","type":"string"},"npm":{"type":"string"},"prepend":{"$ref":"#/definitions/ContentInjectionMap"},"redirect":{"description":"Redirection URL.","type":"string"},"remove":{"description":"Whether to remove the GitHub Pages branch and quit.","type":"boolean"},"repo":{"type":"string"},"root":{"description":"Main page root path.","type":"string"},"singlePage":{"description":"Whether to show all sections on a single page.","type":"boolean"},"source":{"type":"string"},"targetBranch":{"description":"Target branch.","examples":["gh-pages"],"type":"string"},"targetIds":{"items":{"type":"string"},"type":"array"},"title":{"type":"string"},"version":{"type":"string"},"ymid":{"type":["number","string"]}},"type":"object"},"ContentInjectionMap":{"additionalProperties":false,"properties":{":has-code":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]},"body":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]},"cover":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]},"head":{"anyOf":[{"type":"string"},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"},{"items":{"anyOf":[{"type":"string"},{"not":{}},{"additionalProperties":false,"properties":{"content":{"type":"string"},"pages":{"items":{"$ref":"#/definitions/Page"},"type":"array"}},"type":"object"}]},"type":"array"}]}},"type":"object"},"EntryConfig":{"additionalProperties":false,"properties":{"append":{"$ref":"#/definitions/ContentInjectionMap"},"assetsDir":{"description":"Directory path for assets, relative to `dir`. If not provided, the assets will be added via the package URLs.","type":"string"},"backstory":{"description":"Backstory link URL to be added to the front page.","type":"string"},"cname":{"description":"Content of the './CNAME' file.","type":"string"},"contentDir":{"description":"Generated section content directory.","type":"string"},"description":{"type":"string"},"dir":{"type":"string"},"favicon":{"description":"Favicon URL.","type":"string"},"faviconType":{"type":"string"},"firstLineDescription":{"description":"Whether the first line following the main title is the package description.","type":"boolean"},"hasCoverIntro":{"type":"boolean"},"htmlTitle":{"type":"string"},"id":{"type":"string"},"isDevDep":{"description":"Whether the package installation instruction should include the \"-D\" flag.","type":"boolean"},"jsorg":{"description":"As a boolean, it means whether to add the '<package_name>.js.org' domain to the './CNAME' file.\n\nAs a string, it sets the '<jsorg_value>.js.org' domain to the './CNAME' file.","type":["boolean","string"]},"linkMap":{"additionalProperties":{"anyOf":[{"type":"string"},{"not":{}}]},"description":"Link substitution map.","type":"object"},"mainBranch":{"type":"string"},"name":{"type":"string"},"nav":{"description":"URL of an HTML file inserted into the navigation bar.","type":"string"},"npm":{"type":"string"},"prepend":{"$ref":"#/definitions/ContentInjectionMap"},"redirect":{"description":"Redirection URL.","type":"string"},"remove":{"description":"Whether to remove the GitHub Pages branch and quit.","type":"boolean"},"repo":{"type":"string"},"root":{"description":"Main page root path.","type":"string"},"singlePage":{"description":"Whether to show all sections on a single page.","type":"boolean"},"source":{"type":"string"},"targetBranch":{"description":"Target branch.","examples":["gh-pages"],"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"ymid":{"type":["number","string"]}},"type":"object"},"Page":{"enum":["index","start","section","redirect"],"type":"string"}}}

package/src/bin/parsing/getInstallationCode.ts

@@ -1,6 +1,6 @@
 export function getInstallationCode(element: Element) {
   return element
     .querySelector("code")
-    ?.innerHTML.trim()
+    ?.textContent.trim()
     .match(/(\S\s*)?(npm (i|install) .*)/)?.[2];
 }

package/src/bin/parsing/getParsedContent.ts

@@ -15,7 +15,7 @@ const md = new Markdown({
 });
 
 export async function getParsedContent(ctx: Context) {
-  let { singlePage, firstLineDescription, linkMap } = ctx;
+  let { singlePage, firstLineDescription, hasCoverIntro = true, linkMap } = ctx;
   let rawContent = await fetchContent(
     getLocation(ctx, "README.md", ctx.source),
   );
@@ -97,7 +97,12 @@ export async function getParsedContent(ctx: Context) {
       continue;
     }
 
-    intro.push(outerHTML);
+    if (hasCoverIntro) {
+      intro.push(outerHTML);
+      continue;
+    }
+
+    indexComplete = true;
   }
 
   if (section.length !== 0) sections.push(joinLines(section));

package/src/bin/setContent.ts

@@ -47,6 +47,7 @@ export async function setContent(ctx: Context) {
     title,
     htmlTitle,
     description: packageDescription,
+    isDevDep,
     backstory,
     redirect,
   } = ctx;
@@ -136,6 +137,9 @@ ${getInjectedContent(ctx, "redirect", "body", "append")}
       ? `<p>${tweakTypography(escapedPackageDescription)}<p>`
       : "");
 
+  if (!installation || isDevDep !== undefined)
+    installation = `npm i${isDevDep ? " -D" : ""} ${name}`;
+
   let navContent = await getNav(ctx, nav);
   let dirs = [contentDir];
 
@@ -246,7 +250,7 @@ ${getInjectedContent(ctx, "index", "body", "prepend")}
       ${getRepoLink(ctx)}
     </p>
     ${backstory ? `<p class="ref"><a href="${backstory}">Backstory</a></p>` : ""}
-    <p class="installation"><code>${installation}</code></p>
+    <p class="installation"><code>${escapeHTML(installation)}</code></p>
     ${getInjectedContent(ctx, "index", "cover", "append")}
   </div>
 </section>

package/src/types/EntryConfig.ts

@@ -18,6 +18,12 @@ export type EntryConfig = {
    * description.
    */
   firstLineDescription?: boolean;
+  hasCoverIntro?: boolean;
+  /**
+   * Whether the package installation instruction should include the
+   * "-D" flag.
+   */
+  isDevDep?: boolean;
   version?: string;
   repo?: string;
   npm?: string;