API links

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.

Note

The other doc-kit generators don't read apilinks.json, so load it from your own tooling. To link a page of the website to its source file, use the source_link directive instead (see Page metadata).

Usage

The links are GitHub URLs, so the generator needs your repository. There is no flag for it, so set it in your configuration file:

export default {
  global: {
    repository: 'my-org/my-lib',
  },
};

JavaScript

npx @doc-kit/cli generate -t api-links -i "lib/*.js" -o out

This writes out/apilinks.json. To build the Node.js docs, extend the Node.js preset instead, which sets nodejs/node.

The JavaScript is parsed by the Parsing JavaScript stage, which explains which files it reads and how to keep them apart from your Markdown. Links use the file's name without its directories, so match the files of a single folder, as lib/*.js does.

Configuring

Attributes

sourceURL?:string

URL template for the file each link points into. {fileName} is the source file's name, such as fs.js, without its directories; the other placeholders take configuration values (see templates). Each link is the filled-in template followed by #L and a line number. Default: 'https://github.com/{repository}/blob/{ref}/lib/{fileName}'.

It also reads the global options output, minify, and repository and ref, which the default sourceURL points into.

The default assumes the files live in lib/ at the root of a GitHub repository. For sources in src/ on GitLab:

export default {
  'api-links': {
    sourceURL: 'https://gitlab.com/{repository}/-/blob/{ref}/src/{fileName}',
  },
};

JavaScript

Output

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:

'use strict';

function readFile() {}

class Stats {
  constructor() {}
  isFile() {}
}

function Dirent() {}

Dirent.prototype.isDirectory = function () {};
Dirent.from = function () {};

module.exports = {
  readFile,
  Stats,
  Dirent,
};

JavaScript

the generator writes:

{
  "fs.readFile": "https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L3",
  "Stats": "https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L5",
  "new Stats": "https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L6",
  "stats.isFile": "https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L7",
  "fs.Dirent": "https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L10",
  "dirent.isDirectory": "https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L12",
  "Dirent.from": "https://github.com/my-org/my-lib/blob/HEAD/lib/fs.js#L13"
}

JSON

How keys are named

The generator first finds what each file exports, then where each export is defined. With the file named fs.js:

In the source	Key	Links to
`function readFile() {}`, exported as `module.exports = { readFile }` or `exports.readFile = readFile`	`fs.readFile`	The function
`exports.writeFile = function () {}`	`fs.writeFile`	The assignment
`class Stats {}`, exported as `module.exports = { Stats }`	`Stats`	The class
The class's `constructor()`	`new Stats`	The constructor
A method of the class, such as `isFile()`	`stats.isFile`	The method
`function Dirent() {}`, exported as `module.exports = { Dirent }`	`fs.Dirent`	The function
`Dirent.prototype.isDirectory = function () {}`	`dirent.isDirectory`	The assignment
`Dirent.from = function () {}`	`Dirent.from`	The assignment
`const assert = module.exports = ok`	`assert`	The declaration
`assert.strictEqual = function () {}`	`assert.strictEqual`	The assignment

A class, and the members of a class or constructor function, are picked up for a capitalized name listed in module.exports = { ... }, for the class in module.exports = new Agent(), and for the variable in const assert = module.exports = ok. The last two work whatever the name's case.
Prototype methods lowercase the whole name (Dirent becomes dirent), and the methods of a class, static ones included, lowercase only its first letter (WASI becomes wASI). Buffer prototype methods use buf instead, as in buf.toString, matching the Node.js docs.
A function exported as deprecate(fn, message) in module.exports = { ... } counts as fn.
In a file whose name starts with _, functions exported by name through module.exports (as module.exports = { fn } or module.exports.fn = fn) are left out as internal. Functions exported through exports.fn = ... are still linked.
Other forms aren't linked, among them arrow functions (exports.read = () => {}), module.exports.read = function () {}, and classes exported as module.exports.Agent = Agent or module.exports = Agent.