{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-api-links","path":"/generators/api-links","type":"module","module":"generators-api-links","title":"API links","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `api-links` generator reads your JavaScript sources and writes\n`apilinks.json`, which maps each exported API, such as `fs.readFile`, to the\nline on GitHub that defines it. It's built for the Node.js `lib/` folder, and\nworks for any CommonJS codebase laid out the same way.\n\n**Target:** `api-links` · **Package:** [`@node-core/doc-kit`](https://doc-kit.nodejs.org/packages/node) · **Reads:** [Parsing JavaScript](https://doc-kit.nodejs.org/generators/ast-js) · **Writes:** `apilinks.json`\n\n> \\[!NOTE]\n> The other doc-kit generators don't read `apilinks.json`, so load it from your\n> own tooling. To link a page of the\n> [website](https://doc-kit.nodejs.org/generators/html) to its source file, use\n> the `source_link` directive instead (see\n> [Page metadata](https://doc-kit.nodejs.org/writing-docs#page-metadata)).","summary":"The `api-links` generator reads your JavaScript sources and writes `apilinks.json`, which maps each exported API, such as `fs.readFile`, to the line on GitHub that defines it. It's built for the Node.js `lib/` folder, and works for any CommonJS codebase laid out the same way.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The links are GitHub URLs, so the generator needs your repository. There is\nno flag for it, so set it in your\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  global: {\n    repository: 'my-org/my-lib',\n  },\n};\n```\n\n```bash\nnpm install --save-dev @doc-kit/cli @node-core/doc-kit\nnpx doc-kit generate -t api-links -i \"lib/*.js\" -o out\n```\n\nThis writes `out/apilinks.json`. Links point at `HEAD`; pass `--git-ref` to\nlink to a tag or commit, such as `--git-ref v24.0.0`. To build the Node.js\ndocs, extend the\n[Node.js preset](https://doc-kit.nodejs.org/packages/node#the-nodejs-preset)\ninstead, which sets `nodejs/node`.\n\n> \\[!IMPORTANT]\n> Without a `repository`, every link keeps the literal `{repository}`\n> placeholder, and nothing warns you about it.","summary":"The links are GitHub URLs, so the generator needs your repository. There is no flag for it, so set it in your configuration file:","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  global: {\n    repository: 'my-org/my-lib',\n  },\n};"},{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @node-core/doc-kit\nnpx doc-kit generate -t api-links -i \"lib/*.js\" -o out"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Options go in the `api-links` section of the configuration file:\n\n* `sourceURL` {string} URL template for the file each link points into. See\n  [Source URLs](#source-urls). **Default:**\n  `'https://github.com/{repository}/blob/{ref}/lib/{fileName}'`.\n* `repository` {string} The GitHub repository, as `owner/name`.\n  **Default:** from `global.repository`.\n* `ref` {string} The Git branch, tag or commit the links point to.\n  **Default:** `'HEAD'`, from `global.ref` (`--git-ref`).\n* `output` {string} The directory to write `apilinks.json` to. Without one,\n  nothing is written. **Default:** from `global.output` (`--output`).\n* `minify` {boolean} Write the JSON on a single line instead of indented.\n  **Default:** `false`, from `global.minify` (`--minify`).","summary":"Options go in the `api-links` section of the configuration file:","examples":[],"children":[{"kind":"section","id":"source-urls","name":"Source URLs","title":"Source URLs","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"In `sourceURL`, `{fileName}` is the source file's name, such as `fs.js`,\nwithout its directories. Other placeholders take configuration values, global\noptions included, such as `{repository}`, `{ref}` and `{version}`, and\n`{name|fallback}` uses `fallback` when the option has no value. `{version}` has\nno leading `v` (`24.0.0`), so write `v{version}` to point at a release tag.\nEach link is the filled-in template followed by `#L` and a line number.\n\nThe default assumes the files live in `lib/` at the root of a GitHub\nrepository. For sources in `src/` on GitLab:\n\n```js displayName=\"doc-kit.config.mjs\"\nexport default {\n  'api-links': {\n    sourceURL: 'https://gitlab.com/{repository}/-/blob/{ref}/src/{fileName}',\n  },\n};\n```","summary":"In `sourceURL`, `{fileName}` is the source file's name, such as `fs.js`, without its directories. Other placeholders take configuration values, global options included, such as `{repository}`, `{ref}` and `{version}`, and `{name|fallback}` uses `fallback` when the option has no value. `{version}` has no leading `v` (`24.0.0`), so write `v{version}` to point at a release tag. Each link is the filled-in template followed by `#L` and a line number.","examples":[{"language":"js","displayName":"doc-kit.config.mjs","code":"export default {\n  'api-links': {\n    sourceURL: 'https://gitlab.com/{repository}/-/blob/{ref}/src/{fileName}',\n  },\n};"}],"children":[]}]},{"kind":"section","id":"input","name":"Input","title":"Input","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The [Parsing JavaScript](https://doc-kit.nodejs.org/generators/ast-js) stage\nreads the files `input` matches and parses them with Acorn:\n\n* Only files ending in `.js` are read. Other matches, `.cjs` and `.mjs`\n  included, are skipped.\n* Files are parsed as CommonJS scripts. A file that uses `import` or `export`\n  stops the run with a syntax error.\n* Links use the file's name without its directories, so match the files of a\n  single folder, as `lib/*.js` does. With `lib/**/*.js`,\n  `lib/internal/util.js` would link to `lib/util.js`, and files with the same\n  name would overwrite each other's keys.\n\nWhen the same run builds the website or other Markdown targets, give the\nJavaScript to `ast-js` through its own `input`, and keep `global.input` for\nyour docs (see\n[Parsing JavaScript](https://doc-kit.nodejs.org/generators/ast-js#configuring)).","summary":"The Parsing JavaScript stage reads the files `input` matches and parses them with Acorn:","examples":[],"children":[]},{"kind":"section","id":"output","name":"Output","title":"Output","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"`apilinks.json` is one flat object for all the input files. Each key names an\nAPI, and each value links to the line that defines it. For this file:\n\n```js displayName=\"lib/fs.js\"\n'use strict';\n\nfunction readFile() {}\n\nclass Stats {\n  constructor() {}\n  isFile() {}\n}\n\nfunction Dirent() {}\n\nDirent.prototype.isDirectory = function () {};\nDirent.from = function () {};\n\nmodule.exports = {\n  readFile,\n  Stats,\n  Dirent,\n};\n```\n\nthe generator writes:\n\n```json displayName=\"out/apilinks.json\"\n{\n  \"fs.readFile\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L3\",\n  \"Stats\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L5\",\n  \"new Stats\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L6\",\n  \"stats.isFile\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L7\",\n  \"fs.Dirent\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L10\",\n  \"dirent.isDirectory\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L12\",\n  \"Dirent.from\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L13\"\n}\n```","summary":"`apilinks.json` is one flat object for all the input files. Each key names an API, and each value links to the line that defines it. For this file:","examples":[{"language":"js","displayName":"lib/fs.js","code":"'use strict';\n\nfunction readFile() {}\n\nclass Stats {\n  constructor() {}\n  isFile() {}\n}\n\nfunction Dirent() {}\n\nDirent.prototype.isDirectory = function () {};\nDirent.from = function () {};\n\nmodule.exports = {\n  readFile,\n  Stats,\n  Dirent,\n};"},{"language":"json","displayName":"out/apilinks.json","code":"{\n  \"fs.readFile\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L3\",\n  \"Stats\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L5\",\n  \"new Stats\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L6\",\n  \"stats.isFile\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L7\",\n  \"fs.Dirent\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L10\",\n  \"dirent.isDirectory\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L12\",\n  \"Dirent.from\": \"https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L13\"\n}"}],"children":[{"kind":"section","id":"how-keys-are-named","name":"How keys are named","title":"How keys are named","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The generator first finds what each file exports, then where each export is\ndefined. With the file named `fs.js`:\n\n| In the source                                                                                          | Key                  | Links to        |\n| ------------------------------------------------------------------------------------------------------ | -------------------- | --------------- |\n| `function readFile() {}`, exported as `module.exports = { readFile }` or `exports.readFile = readFile` | `fs.readFile`        | The function    |\n| `exports.writeFile = function () {}`                                                                   | `fs.writeFile`       | The assignment  |\n| `class Stats {}`, exported as `module.exports = { Stats }`                                             | `Stats`              | The class       |\n| The class's `constructor()`                                                                            | `new Stats`          | The constructor |\n| A method of the class, such as `isFile()`                                                              | `stats.isFile`       | The method      |\n| `function Dirent() {}`, exported as `module.exports = { Dirent }`                                      | `fs.Dirent`          | The function    |\n| `Dirent.prototype.isDirectory = function () {}`                                                        | `dirent.isDirectory` | The assignment  |\n| `Dirent.from = function () {}`                                                                         | `Dirent.from`        | The assignment  |\n| `const assert = module.exports = ok`                                                                   | `assert`             | The declaration |\n| `assert.strictEqual = function () {}`                                                                  | `assert.strictEqual` | The assignment  |\n\n* A class, and the members of a class or constructor function, are picked up\n  for a capitalized name listed in `module.exports = { ... }`, for the class in\n  `module.exports = new Agent()`, and for the variable in\n  `const assert = module.exports = ok`. The last two work whatever the name's\n  case.\n* Prototype methods lowercase the whole name (`Dirent` becomes `dirent`), and\n  the methods of a `class`, static ones included, lowercase only its first\n  letter (`WASI` becomes `wASI`). `Buffer` prototype methods use `buf`\n  instead, as in `buf.toString`, matching the Node.js docs.\n* A function exported as `deprecate(fn, message)` in `module.exports = { ... }`\n  counts as `fn`.\n* In a file whose name starts with `_`, functions exported by name through\n  `module.exports` (as `module.exports = { fn }` or `module.exports.fn = fn`)\n  are left out as internal. Functions exported through `exports.fn = ...` are\n  still linked.\n* Other forms aren't linked, among them arrow functions\n  (`exports.read = () => {}`), `module.exports.read = function () {}`, and\n  classes exported as `module.exports.Agent = Agent` or\n  `module.exports = Agent`.","summary":"The generator first finds what each file exports, then where each export is defined. With the file named `fs.js`:","examples":[],"children":[]}]}]}