{"$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> \\[!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\nnpx @doc-kit/cli generate -t api-links -i \"lib/*.js\" -o out\n```\n\nThis writes `out/apilinks.json`. To build the Node.js docs, extend the\n[Node.js preset](https://doc-kit.nodejs.org/packages/node#the-nodejs-preset)\ninstead, which sets `nodejs/node`.\n\nThe JavaScript is parsed by the\n[Parsing JavaScript](https://doc-kit.nodejs.org/generators/ast-js) stage, which\nexplains which files it reads and how to keep them apart from your Markdown.\nLinks use the file's name without its directories, so match the files of a\nsingle folder, as `lib/*.js` does.","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":"npx @doc-kit/cli 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":"* `sourceURL` {string} URL template for the file each link points into.\n  `{fileName}` is the source file's name, such as `fs.js`, without its\n  directories; the other placeholders take configuration values (see\n  [templates](https://doc-kit.nodejs.org/configuration#generator-options)).\n  Each link is the filled-in template followed by `#L` and a line number.\n  **Default:** `'https://github.com/{repository}/blob/{ref}/lib/{fileName}'`.\n\nIt also reads the\n[global options](https://doc-kit.nodejs.org/configuration#global-options)\n`output`, `minify`, and `repository` and `ref`, which the default `sourceURL`\npoints into.\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":"It also reads the global options `output`, `minify`, and `repository` and `ref`, which the default `sourceURL` points into.","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":"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":[]}]}]}