{"id":12933,"library":"builddocs","title":"Builddocs","description":"Builddocs is a utility designed to transform source code documented with `getdocs-ts`-style comments into HTML documentation. It processes the structured documentation data (typically generated by `getdocs-ts`) and renders it into a final HTML output, leveraging configurable templates and Markdown processing. The current stable version is 1.0.8, indicating a mature and stable codebase for its specific purpose. Unlike comprehensive documentation generators like JSDoc or TypeDoc, Builddocs specializes in the rendering phase, allowing developers to define custom HTML layouts using Mold templating and extend Markdown rendering via `markdown-it`. Its key differentiator lies in its focused approach to consuming `getdocs-ts` output and offering granular control over the final HTML structure and styling, rather than handling the entire parsing-to-rendering lifecycle independently. While a specific release cadence isn't stated, its versioning suggests stability over rapid feature iteration, likely maintained in sync with its primary dependency, `getdocs-ts`.","status":"active","version":"1.0.8","language":"javascript","source_language":"en","source_url":"git://github.com/marijnh/builddocs","tags":["javascript","documentation","comment","getdocs"],"install":[{"cmd":"npm install builddocs","lang":"bash","label":"npm"},{"cmd":"yarn add builddocs","lang":"bash","label":"yarn"},{"cmd":"pnpm add builddocs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to parse documentation comments from source code, which builddocs then renders into HTML.","package":"getdocs-ts","optional":false},{"reason":"Used for parsing and rendering Markdown content within documentation comments and templates.","package":"markdown-it","optional":false},{"reason":"The templating engine used by builddocs for rendering HTML documentation.","package":"mold","optional":false}],"imports":[{"note":"The primary function for generating documentation; ES Modules preferred.","wrong":"const build = require('builddocs').build","symbol":"build","correct":"import { build } from 'builddocs'"},{"note":"Used to explicitly read documentation data using getdocs-ts, typically before passing to `build`.","wrong":"const { read } = require('builddocs')","symbol":"read","correct":"import { read } from 'builddocs'"},{"note":"An object containing common browser type mappings for linking, intended for use with the `imports` or `qualifiedImports` configuration options.","wrong":"const browserImports = require('builddocs').browserImports","symbol":"browserImports","correct":"import { browserImports } from 'builddocs'"}],"quickstart":{"code":"import { build } from 'builddocs';\nimport * as fs from 'fs';\nimport * as path from 'path';\n\n// Simulate a source file with getdocs-ts comments\nconst sourceCode = `\n/**\n * Represents a point in 2D space.\n * @class\n * @property {number} x - The X coordinate.\n * @property {number} y - The Y coordinate.\n */\nclass Point {\n  /**\n   * Creates a new Point instance.\n   * @param {number} x Initial X coordinate.\n   * @param {number} y Initial Y coordinate.\n   */\n  constructor(x, y) {\n    this.x = x;\n    this.y = y;\n  }\n\n  /**\n   * Calculates the distance from the origin (0,0).\n   * @returns {number} The distance.\n   */\n  distance() {\n    return Math.sqrt(this.x ** 2 + this.y ** 2);\n  }\n}\n\nexport { Point };\n`;\n\nconst tempDir = path.join(process.cwd(), 'temp-docs');\nif (!fs.existsSync(tempDir)) {\n  fs.mkdirSync(tempDir);\n}\nconst tempSourceFile = path.join(tempDir, 'point.js');\nfs.writeFileSync(tempSourceFile, sourceCode);\n\nconst config = {\n  name: 'GeometryLib',\n  filename: tempSourceFile,\n  mainText: `\n# Geometry Library Documentation\n\nThis document describes the core components of our geometry library.\n\n@Point\n  `,\n  anchorPrefix: 'geom.',\n  allowUnresolvedTypes: true,\n  env: { currentDate: new Date().toLocaleDateString() }\n};\n\ntry {\n  const htmlOutput = build(config);\n  const outputFile = path.join(tempDir, 'index.html');\n  fs.writeFileSync(outputFile, htmlOutput);\n  console.log(`Documentation generated successfully to ${outputFile}`);\n  console.log(`\\n--- Generated HTML ---\\n${htmlOutput.substring(0, 500)}...`);\n} catch (error) {\n  console.error('Error generating documentation:', error);\n} finally {\n  // Clean up temporary files\n  fs.unlinkSync(tempSourceFile);\n  fs.rmdirSync(tempDir);\n}\n","lang":"typescript","description":"This quickstart demonstrates how to use `builddocs` to generate HTML documentation from a simple JavaScript source file containing `getdocs-ts`-style comments. It configures the build process with a module name, input filename, a basic Markdown template, and options for anchor prefixes and environment variables. The output HTML is written to a temporary file."},"warnings":[{"fix":"To prevent errors for unknown types, set the `allowUnresolvedTypes` option to `true` in your configuration object: `{ allowUnresolvedTypes: true }`.","message":"By default, `builddocs` will throw an error if it encounters a type name that it cannot resolve (i.e., not defined in the source or explicitly imported via `imports`/`qualifiedImports`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your template's `@itemName` placeholders correspond precisely to the names of the documented items extracted by `getdocs-ts`. Alternatively, omit the `main` or `mainText` option to let `builddocs` output items in the order they are found without explicit placeholders.","message":"When using a custom `main` or `mainText` template, `builddocs` requires that all `@itemName` placeholders in the template exactly match the set of documented items found in the source files. Mismatches will result in an error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure compatibility between `builddocs` and `getdocs-ts` versions. Refer to the respective package documentation and release notes for any breaking changes in `getdocs-ts`'s output structure that might affect `builddocs`.","message":"Builddocs is heavily reliant on the output format of `getdocs-ts`. Changes or incompatibilities in `getdocs-ts`'s JSON output could break builddocs' rendering pipeline.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Either define 'MyType' in your source code, add it to the `imports` or `qualifiedImports` configuration, or set `allowUnresolvedTypes: true` in your `build` configuration to ignore unknown types.","cause":"The documentation source contained a type reference ('MyType') that was not defined in the parsed files nor resolved via the `imports` or `qualifiedImports` configuration options.","error":"Error: Unknown type 'MyType' encountered"},{"fix":"Correct the placeholder name in your template to match an existing documented item, or ensure the item is correctly documented and parsed by `getdocs-ts`. Remove the placeholder if the item is not intended to be documented.","cause":"The `main` or `mainText` template contained an `@MyItem` placeholder, but no documented item named 'MyItem' was found in the source code.","error":"Error: Template placeholder '@MyItem' does not match any documented item."},{"fix":"Verify that the paths specified in `filename`, `main`, or `templates` configuration options are correct and accessible from where the `builddocs` command is executed.","cause":"The `filename` or `templates` configuration option points to a file or directory that does not exist.","error":"Error: ENOENT: no such file or directory, open 'path/to/nonexistent-file.js'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"builddocs"}