Parsing JavaScript

The ast-js stage parses the .js files among your inputs into syntax trees with Acorn, for generators that read source code rather than Markdown. API links is the built-in generator that reads it, and a generator of your own can too. You don't ask for ast-js yourself: it runs when a target depends on it, once per run however many targets read it.

ast-js has no options of its own. It parses the files input matches, minus those ignore matches (see Global options), and of those only the ones ending in .js.

When the same run builds pages, keep global.input for your docs and give ast-js its own: the Markdown stage parses every file global.input matches as Markdown, whatever its extension.

export default {
  target: ['html', 'api-links'],
  global: {
    input: ['doc/api/*.md'],
    output: 'out',
  },
  'ast-js': {
    input: ['lib/*.js'],
    ignore: ['lib/*.test.js'],
  },
};

Files are parsed as scripts, so import, export and top-level await are syntax errors, and a file that fails to parse stops the run. Leave ES modules out with ignore. Acorn doesn't parse JSX or type annotations either; to document TypeScript sources, see Documenting TypeScript.

An array with one ESTree Program node per file, as Acorn returns it with locations on, plus a path property: the file's path as the glob matched it, such as lib/fs.js. Files are collected as their chunks finish, so the array isn't in input order. A generator with dependsOn: '@doc-kit/core/ast-js' receives this array.