doc: anchor link parity between markdown and html-generated docs

Main changes: - Replace current HTML anchor generation to match header anchor generation in Github markdown. - Remove unnecessary double namespacing on generated anchors/links (E.G. `esm.md#loaders` instead of `esm.md#esm_loaders`). - Anchors/links are automatically prefixed with their respective modules when concatenated for usage in `all.html`. Benefits: - All anchor links within and between markdown API docs actually work. - Adding new anchor links no longer requires contributors to generate the HTML docs first to look up the correct anchors. - Anchors are much shorter. - All previous anchor links are preserved by generating hidden legacy anchors. PR-URL: #39304 Reviewed-By: Antoine du Hamel <[email protected]>
nodejs · Aug 29, 2021 · 6fdd582 · 6fdd582
1 parent b6b638b
commit 6fdd582
Show file tree

Hide file tree

Showing 59 changed files with 1,499 additions and 1,436 deletions.
diff --git a/doc/api/addons.md b/doc/api/addons.md
@@ -456,7 +456,7 @@ in the Node-API are used.
 
 Creating and maintaining an addon that benefits from the ABI stability
 provided by Node-API carries with it certain
-[implementation considerations](n-api.md#n_api_implications_of_abi_stability).
+[implementation considerations][].
 
 To use Node-API in the above "Hello world" example, replace the content of
 `hello.cc` with the following. All other instructions remain the same.
@@ -1362,15 +1362,16 @@ console.log(result);
 
 [Electron]: https://electronjs.org/
 [Embedder's Guide]: https://github.com/v8/v8/wiki/Embedder's%20Guide
-[Linking to libraries included with Node.js]: #addons_linking_to_libraries_included_with_node_js
+[Linking to libraries included with Node.js]: #linking-to-libraries-included-with-nodejs
 [Native Abstractions for Node.js]: https://github.com/nodejs/nan
 [V8]: https://v8.dev/
-[`Worker`]: worker_threads.md#worker_threads_class_worker
+[`Worker`]: worker_threads.md#class-worker
 [bindings]: https://github.com/TooTallNate/node-bindings
 [download]: https://github.com/nodejs/node-addon-examples
 [examples]: https://github.com/nodejs/nan/tree/HEAD/examples/
+[implementation considerations]: n-api.md#implications-of-abi-stability
 [installation instructions]: https://github.com/nodejs/node-gyp#installation
 [libuv]: https://github.com/libuv/libuv
 [node-gyp]: https://github.com/nodejs/node-gyp
-[require]: modules.md#modules_require_id
+[require]: modules.md#requireid
 [v8-docs]: https://v8docs.nodesource.com/
diff --git a/doc/api/assert.md b/doc/api/assert.md
@@ -99,7 +99,7 @@ assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);
 To deactivate the colors, use the `NO_COLOR` or `NODE_DISABLE_COLORS`
 environment variables. This will also deactivate the colors in the REPL. For
 more on color support in terminal environments, read the tty
-[getColorDepth()](tty.md#tty_writestream_getcolordepth_env) documentation.
+[`getColorDepth()`][] documentation.
 
 ## Legacy assertion mode
 
@@ -2420,34 +2420,35 @@ argument.
 [Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
 [SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue
 [Strict Equality Comparison]: https://tc39.github.io/ecma262/#sec-strict-equality-comparison
-[`AssertionError`]: #assert_class_assert_assertionerror
-[`CallTracker`]: #assert_class_assert_calltracker
+[`AssertionError`]: #class-assertassertionerror
+[`CallTracker`]: #class-assertcalltracker
 [`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
-[`ERR_INVALID_RETURN_VALUE`]: errors.md#errors_err_invalid_return_value
-[`Error.captureStackTrace`]: errors.md#errors_error_capturestacktrace_targetobject_constructoropt
-[`Error`]: errors.md#errors_class_error
+[`ERR_INVALID_RETURN_VALUE`]: errors.md#err_invalid_return_value
+[`Error.captureStackTrace`]: errors.md#errorcapturestacktracetargetobject-constructoropt
+[`Error`]: errors.md#class-error
 [`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
 [`Object.is()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
 [`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
 [`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
 [`Symbol`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
-[`TypeError`]: errors.md#errors_class_typeerror
+[`TypeError`]: errors.md#class-typeerror
 [`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
 [`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
-[`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message
-[`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message
-[`assert.doesNotThrow()`]: #assert_assert_doesnotthrow_fn_error_message
-[`assert.equal()`]: #assert_assert_equal_actual_expected_message
-[`assert.notDeepEqual()`]: #assert_assert_notdeepequal_actual_expected_message
-[`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message
-[`assert.notEqual()`]: #assert_assert_notequal_actual_expected_message
-[`assert.notStrictEqual()`]: #assert_assert_notstrictequal_actual_expected_message
-[`assert.ok()`]: #assert_assert_ok_value_message
-[`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message
-[`assert.throws()`]: #assert_assert_throws_fn_error_message
-[`process.on('exit')`]: process.md#process_event_exit
-[`tracker.calls()`]: #assert_tracker_calls_fn_exact
-[`tracker.verify()`]: #assert_tracker_verify
+[`assert.deepEqual()`]: #assertdeepequalactual-expected-message
+[`assert.deepStrictEqual()`]: #assertdeepstrictequalactual-expected-message
+[`assert.doesNotThrow()`]: #assertdoesnotthrowfn-error-message
+[`assert.equal()`]: #assertequalactual-expected-message
+[`assert.notDeepEqual()`]: #assertnotdeepequalactual-expected-message
+[`assert.notDeepStrictEqual()`]: #assertnotdeepstrictequalactual-expected-message
+[`assert.notEqual()`]: #assertnotequalactual-expected-message
+[`assert.notStrictEqual()`]: #assertnotstrictequalactual-expected-message
+[`assert.ok()`]: #assertokvalue-message
+[`assert.strictEqual()`]: #assertstrictequalactual-expected-message
+[`assert.throws()`]: #assertthrowsfn-error-message
+[`getColorDepth()`]: tty.md#writestreamgetcolordepthenv
+[`process.on('exit')`]: process.md#event-exit
+[`tracker.calls()`]: #trackercallsfn-exact
+[`tracker.verify()`]: #trackerverify
 [enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
 [prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots
-[strict assertion mode]: #assert_strict_assertion_mode
+[strict assertion mode]: #strict-assertion-mode
diff --git a/doc/api/async_context.md b/doc/api/async_context.md
@@ -786,8 +786,8 @@ const server = createServer((req, res) => {
 }).listen(3000);
 ```
 
-[`AsyncResource`]: #async_context_class_asyncresource
-[`EventEmitter`]: events.md#events_class_eventemitter
-[`Stream`]: stream.md#stream_stream
-[`Worker`]: worker_threads.md#worker_threads_class_worker
-[`util.promisify()`]: util.md#util_util_promisify_original
+[`AsyncResource`]: #class-asyncresource
+[`EventEmitter`]: events.md#class-eventemitter
+[`Stream`]: stream.md#stream
+[`Worker`]: worker_threads.md#class-worker
+[`util.promisify()`]: util.md#utilpromisifyoriginal
diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md
@@ -841,14 +841,14 @@ The documentation for this class has moved [`AsyncResource`][].
 
 The documentation for this class has moved [`AsyncLocalStorage`][].
 
-[Hook Callbacks]: #async_hooks_hook_callbacks
+[Hook Callbacks]: #hook-callbacks
 [PromiseHooks]: https://docs.google.com/document/d/1rda3yKGHimKIhg5YeoAmCOtyURgsbTH_qaYR79FELlk/edit
-[`AsyncLocalStorage`]: async_context.md#async_context_class_asynclocalstorage
-[`AsyncResource`]: async_context.md#async_context_class_asyncresource
-[`Worker`]: worker_threads.md#worker_threads_class_worker
-[`after` callback]: #async_hooks_after_asyncid
-[`before` callback]: #async_hooks_before_asyncid
-[`destroy` callback]: #async_hooks_destroy_asyncid
-[`init` callback]: #async_hooks_init_asyncid_type_triggerasyncid_resource
-[`promiseResolve` callback]: #async_hooks_promiseresolve_asyncid
-[promise execution tracking]: #async_hooks_promise_execution_tracking
+[`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
+[`AsyncResource`]: async_context.md#class-asyncresource
+[`Worker`]: worker_threads.md#class-worker
+[`after` callback]: #afterasyncid
+[`before` callback]: #beforeasyncid
+[`destroy` callback]: #destroyasyncid
+[`init` callback]: #initasyncid-type-triggerasyncid-resource
+[`promiseResolve` callback]: #promiseresolveasyncid
+[promise execution tracking]: #promise-execution-tracking
diff --git a/doc/api/buffer.md b/doc/api/buffer.md
@@ -5199,19 +5199,19 @@ introducing security vulnerabilities into an application.
 [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
 [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
 [`Blob`]: https://developer.mozilla.org/en-US/docs/Web/API/Blob
-[`Buffer.alloc()`]: #buffer_static_method_buffer_alloc_size_fill_encoding
-[`Buffer.allocUnsafe()`]: #buffer_static_method_buffer_allocunsafe_size
-[`Buffer.allocUnsafeSlow()`]: #buffer_static_method_buffer_allocunsafeslow_size
-[`Buffer.concat()`]: #buffer_static_method_buffer_concat_list_totallength
-[`Buffer.from(array)`]: #buffer_static_method_buffer_from_array
-[`Buffer.from(arrayBuf)`]: #buffer_static_method_buffer_from_arraybuffer_byteoffset_length
-[`Buffer.from(buffer)`]: #buffer_static_method_buffer_from_buffer
-[`Buffer.from(string)`]: #buffer_static_method_buffer_from_string_encoding
-[`Buffer.poolSize`]: #buffer_class_property_buffer_poolsize
+[`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
+[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
+[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
+[`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
+[`Buffer.from(array)`]: #static-method-bufferfromarray
+[`Buffer.from(arrayBuf)`]: #static-method-bufferfromarraybuffer-byteoffset-length
+[`Buffer.from(buffer)`]: #static-method-bufferfrombuffer
+[`Buffer.from(string)`]: #static-method-bufferfromstring-encoding
+[`Buffer.poolSize`]: #class-property-bufferpoolsize
 [`DataView`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
-[`ERR_INVALID_ARG_VALUE`]: errors.md#ERR_INVALID_ARG_VALUE
-[`ERR_INVALID_BUFFER_SIZE`]: errors.md#ERR_INVALID_BUFFER_SIZE
-[`ERR_OUT_OF_RANGE`]: errors.md#ERR_OUT_OF_RANGE
+[`ERR_INVALID_ARG_VALUE`]: errors.md#err_invalid_arg_value
+[`ERR_INVALID_BUFFER_SIZE`]: errors.md#err_invalid_buffer_size
+[`ERR_OUT_OF_RANGE`]: errors.md#err_out_of_range
 [`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
 [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
 [`String.prototype.indexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf
@@ -5223,20 +5223,20 @@ introducing security vulnerabilities into an application.
 [`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
 [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
-[`buf.buffer`]: #buffer_buf_buffer
-[`buf.compare()`]: #buffer_buf_compare_target_targetstart_targetend_sourcestart_sourceend
-[`buf.entries()`]: #buffer_buf_entries
-[`buf.fill()`]: #buffer_buf_fill_value_offset_end_encoding
-[`buf.indexOf()`]: #buffer_buf_indexof_value_byteoffset_encoding
-[`buf.keys()`]: #buffer_buf_keys
-[`buf.length`]: #buffer_buf_length
-[`buf.slice()`]: #buffer_buf_slice_start_end
-[`buf.toString()`]: #buffer_buf_tostring_encoding_start_end
-[`buf.values()`]: #buffer_buf_values
-[`buffer.constants.MAX_LENGTH`]: #buffer_buffer_constants_max_length
-[`buffer.constants.MAX_STRING_LENGTH`]: #buffer_buffer_constants_max_string_length
-[`buffer.kMaxLength`]: #buffer_buffer_kmaxlength
-[`util.inspect()`]: util.md#util_util_inspect_object_options
+[`buf.buffer`]: #bufbuffer
+[`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
+[`buf.entries()`]: #bufentries
+[`buf.fill()`]: #buffillvalue-offset-end-encoding
+[`buf.indexOf()`]: #bufindexofvalue-byteoffset-encoding
+[`buf.keys()`]: #bufkeys
+[`buf.length`]: #buflength
+[`buf.slice()`]: #bufslicestart-end
+[`buf.toString()`]: #buftostringencoding-start-end
+[`buf.values()`]: #bufvalues
+[`buffer.constants.MAX_LENGTH`]: #bufferconstantsmax_length
+[`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
+[`buffer.kMaxLength`]: #bufferkmaxlength
+[`util.inspect()`]: util.md#utilinspectobject-options
 [`v8::TypedArray::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1TypedArray.html#a54a48f4373da0850663c4393d843b9b0
 [base64url]: https://tools.ietf.org/html/rfc4648#section-5
 [binary strings]: https://developer.mozilla.org/en-US/docs/Web/API/DOMString/Binary

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
@@ -1780,42 +1780,42 @@ Therefore, this feature requires opting in by setting the
 `serialization` option to `'advanced'` when calling [`child_process.spawn()`][]
 or [`child_process.fork()`][].
 
-[Advanced serialization]: #child_process_advanced_serialization
-[Default Windows shell]: #child_process_default_windows_shell
+[Advanced serialization]: #advanced-serialization
+[Default Windows shell]: #default-windows-shell
 [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
-[Shell requirements]: #child_process_shell_requirements
-[Signal Events]: process.md#process_signal_events
-[`'disconnect'`]: process.md#process_event_disconnect
-[`'error'`]: #child_process_event_error
-[`'exit'`]: #child_process_event_exit
-[`'message'`]: process.md#process_event_message
-[`ChildProcess`]: #child_process_class_childprocess
-[`Error`]: errors.md#errors_class_error
-[`EventEmitter`]: events.md#events_class_eventemitter
-[`child_process.exec()`]: #child_process_child_process_exec_command_options_callback
-[`child_process.execFile()`]: #child_process_child_process_execfile_file_args_options_callback
-[`child_process.execFileSync()`]: #child_process_child_process_execfilesync_file_args_options
-[`child_process.execSync()`]: #child_process_child_process_execsync_command_options
-[`child_process.fork()`]: #child_process_child_process_fork_modulepath_args_options
-[`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options
-[`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options
-[`maxBuffer` and Unicode]: #child_process_maxbuffer_and_unicode
-[`net.Server`]: net.md#net_class_net_server
-[`net.Socket`]: net.md#net_class_net_socket
-[`options.detached`]: #child_process_options_detached
-[`process.disconnect()`]: process.md#process_process_disconnect
-[`process.env`]: process.md#process_process_env
-[`process.execPath`]: process.md#process_process_execpath
-[`process.send()`]: process.md#process_process_send_message_sendhandle_options_callback
-[`stdio`]: #child_process_options_stdio
-[`subprocess.connected`]: #child_process_subprocess_connected
-[`subprocess.disconnect()`]: #child_process_subprocess_disconnect
-[`subprocess.kill()`]: #child_process_subprocess_kill_signal
-[`subprocess.send()`]: #child_process_subprocess_send_message_sendhandle_options_callback
-[`subprocess.stderr`]: #child_process_subprocess_stderr
-[`subprocess.stdin`]: #child_process_subprocess_stdin
-[`subprocess.stdio`]: #child_process_subprocess_stdio
-[`subprocess.stdout`]: #child_process_subprocess_stdout
-[`util.promisify()`]: util.md#util_util_promisify_original
-[synchronous counterparts]: #child_process_synchronous_process_creation
-[v8.serdes]: v8.md#v8_serialization_api
+[Shell requirements]: #shell-requirements
+[Signal Events]: process.md#signal-events
+[`'disconnect'`]: process.md#event-disconnect
+[`'error'`]: #event-error
+[`'exit'`]: #event-exit
+[`'message'`]: process.md#event-message
+[`ChildProcess`]: #class-childprocess
+[`Error`]: errors.md#class-error
+[`EventEmitter`]: events.md#class-eventemitter
+[`child_process.exec()`]: #child_processexeccommand-options-callback
+[`child_process.execFile()`]: #child_processexecfilefile-args-options-callback
+[`child_process.execFileSync()`]: #child_processexecfilesyncfile-args-options
+[`child_process.execSync()`]: #child_processexecsynccommand-options
+[`child_process.fork()`]: #child_processforkmodulepath-args-options
+[`child_process.spawn()`]: #child_processspawncommand-args-options
+[`child_process.spawnSync()`]: #child_processspawnsynccommand-args-options
+[`maxBuffer` and Unicode]: #maxbuffer-and-unicode
+[`net.Server`]: net.md#class-netserver
+[`net.Socket`]: net.md#class-netsocket
+[`options.detached`]: #optionsdetached
+[`process.disconnect()`]: process.md#processdisconnect
+[`process.env`]: process.md#processenv
+[`process.execPath`]: process.md#processexecpath
+[`process.send()`]: process.md#processsendmessage-sendhandle-options-callback
+[`stdio`]: #optionsstdio
+[`subprocess.connected`]: #subprocessconnected
+[`subprocess.disconnect()`]: #subprocessdisconnect
+[`subprocess.kill()`]: #subprocesskillsignal
+[`subprocess.send()`]: #subprocesssendmessage-sendhandle-options-callback
+[`subprocess.stderr`]: #subprocessstderr
+[`subprocess.stdin`]: #subprocessstdin
+[`subprocess.stdio`]: #subprocessstdio
+[`subprocess.stdout`]: #subprocessstdout
+[`util.promisify()`]: util.md#utilpromisifyoriginal
+[synchronous counterparts]: #synchronous-process-creation
+[v8.serdes]: v8.md#serialization-api