Skip to content

Commit 36e55c0

Browse files
foxxyzfoxxyz
committed
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: nodejs#39304 Reviewed-By: Antoine du Hamel <[email protected]>
1 parent b3f51ee commit 36e55c0

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+1407
-1343
lines changed

‎doc/api/addons.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -454,7 +454,7 @@ in the Node-API are used.
454454

455455
Creating and maintaining an addon that benefits from the ABI stability
456456
provided by Node-API carries with it certain
457-
[implementation considerations](n-api.md#n_api_implications_of_abi_stability).
457+
[implementation considerations][].
458458

459459
To use Node-API in the above "Hello world" example, replace the content of
460460
`hello.cc` with the following. All other instructions remain the same.
@@ -1360,15 +1360,16 @@ console.log(result);
13601360

13611361
[Electron]: https://electronjs.org/
13621362
[Embedder's Guide]: https://github.com/v8/v8/wiki/Embedder's%20Guide
1363-
[Linking to libraries included with Node.js]: #addons_linking_to_libraries_included_with_node_js
1363+
[Linking to libraries included with Node.js]: #linking-to-libraries-included-with-nodejs
13641364
[Native Abstractions for Node.js]: https://github.com/nodejs/nan
13651365
[V8]: https://v8.dev/
1366-
[`Worker`]: worker_threads.md#worker_threads_class_worker
1366+
[`Worker`]: worker_threads.md#class-worker
13671367
[bindings]: https://github.com/TooTallNate/node-bindings
13681368
[download]: https://github.com/nodejs/node-addon-examples
13691369
[examples]: https://github.com/nodejs/nan/tree/HEAD/examples/
1370+
[implementation considerations]: n-api.md#implications-of-abi-stability
13701371
[installation instructions]: https://github.com/nodejs/node-gyp#installation
13711372
[libuv]: https://github.com/libuv/libuv
13721373
[node-gyp]: https://github.com/nodejs/node-gyp
1373-
[require]: modules.md#modules_require_id
1374+
[require]: modules.md#requireid
13741375
[v8-docs]: https://v8docs.nodesource.com/

‎doc/api/assert.md

+23-22
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);
6565
To deactivate the colors, use the `NO_COLOR` or `NODE_DISABLE_COLORS`
6666
environment variables. This will also deactivate the colors in the REPL. For
6767
more on color support in terminal environments, read the tty
68-
[getColorDepth()](tty.md#tty_writestream_getcolordepth_env) documentation.
68+
[`getColorDepth()`][] documentation.
6969

7070
## Legacy assertion mode
7171

@@ -1584,34 +1584,35 @@ argument.
15841584
[Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
15851585
[SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue
15861586
[Strict Equality Comparison]: https://tc39.github.io/ecma262/#sec-strict-equality-comparison
1587-
[`AssertionError`]: #assert_class_assert_assertionerror
1587+
[`AssertionError`]: #class-assertassertionerror
1588+
[`CallTracker`]: #class-assertcalltracker
15881589
[`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
1589-
[`ERR_INVALID_RETURN_VALUE`]: errors.md#errors_err_invalid_return_value
1590-
[`Error.captureStackTrace`]: errors.md#errors_error_capturestacktrace_targetobject_constructoropt
1591-
[`Error`]: errors.md#errors_class_error
1590+
[`ERR_INVALID_RETURN_VALUE`]: errors.md#err_invalid_return_value
1591+
[`Error.captureStackTrace`]: errors.md#errorcapturestacktracetargetobject-constructoropt
1592+
[`Error`]: errors.md#class-error
15921593
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
15931594
[`Object.is()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
15941595
[`RegExp`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
15951596
[`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
15961597
[`Symbol`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
1597-
[`TypeError`]: errors.md#errors_class_typeerror
1598+
[`TypeError`]: errors.md#class-typeerror
15981599
[`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
15991600
[`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
1600-
[`CallTracker`]: #assert_class_assert_calltracker
1601-
[`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message
1602-
[`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message
1603-
[`assert.doesNotThrow()`]: #assert_assert_doesnotthrow_fn_error_message
1604-
[`assert.equal()`]: #assert_assert_equal_actual_expected_message
1605-
[`assert.notDeepEqual()`]: #assert_assert_notdeepequal_actual_expected_message
1606-
[`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message
1607-
[`assert.notEqual()`]: #assert_assert_notequal_actual_expected_message
1608-
[`assert.notStrictEqual()`]: #assert_assert_notstrictequal_actual_expected_message
1609-
[`assert.ok()`]: #assert_assert_ok_value_message
1610-
[`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message
1611-
[`assert.throws()`]: #assert_assert_throws_fn_error_message
1612-
[`process.on('exit')`]: process.md#process_event_exit
1613-
[`tracker.calls()`]: #assert_tracker_calls_fn_exact
1614-
[`tracker.verify()`]: #assert_tracker_verify
1615-
[strict assertion mode]: #assert_strict_assertion_mode
1601+
[`assert.deepEqual()`]: #assertdeepequalactual-expected-message
1602+
[`assert.deepStrictEqual()`]: #assertdeepstrictequalactual-expected-message
1603+
[`assert.doesNotThrow()`]: #assertdoesnotthrowfn-error-message
1604+
[`assert.equal()`]: #assertequalactual-expected-message
1605+
[`assert.notDeepEqual()`]: #assertnotdeepequalactual-expected-message
1606+
[`assert.notDeepStrictEqual()`]: #assertnotdeepstrictequalactual-expected-message
1607+
[`assert.notEqual()`]: #assertnotequalactual-expected-message
1608+
[`assert.notStrictEqual()`]: #assertnotstrictequalactual-expected-message
1609+
[`assert.ok()`]: #assertokvalue-message
1610+
[`assert.strictEqual()`]: #assertstrictequalactual-expected-message
1611+
[`assert.throws()`]: #assertthrowsfn-error-message
1612+
[`getColorDepth()`]: tty.md#writestreamgetcolordepthenv
1613+
[`process.on('exit')`]: process.md#event-exit
1614+
[`tracker.calls()`]: #trackercallsfn-exact
1615+
[`tracker.verify()`]: #trackerverify
16161616
[enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
16171617
[prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots
1618+
[strict assertion mode]: #strict-assertion-mode

‎doc/api/async_hooks.md

+12-12
Original file line numberDiff line numberDiff line change
@@ -1193,16 +1193,16 @@ If you need to keep using callback-based API, or your code assumes
11931193
a custom thenable implementation, use the [`AsyncResource`][] class
11941194
to associate the asynchronous operation with the correct execution context.
11951195

1196-
[Hook Callbacks]: #async_hooks_hook_callbacks
1196+
[Hook Callbacks]: #hook-callbacks
11971197
[PromiseHooks]: https://docs.google.com/document/d/1rda3yKGHimKIhg5YeoAmCOtyURgsbTH_qaYR79FELlk/edit
1198-
[`AsyncResource`]: #async_hooks_class_asyncresource
1199-
[`after` callback]: #async_hooks_after_asyncid
1200-
[`before` callback]: #async_hooks_before_asyncid
1201-
[`destroy` callback]: #async_hooks_destroy_asyncid
1202-
[`init` callback]: #async_hooks_init_asyncid_type_triggerasyncid_resource
1203-
[`promiseResolve` callback]: #async_hooks_promiseresolve_asyncid
1204-
[`EventEmitter`]: events.md#events_class_eventemitter
1205-
[`Stream`]: stream.md#stream_stream
1206-
[`Worker`]: worker_threads.md#worker_threads_class_worker
1207-
[`util.promisify()`]: util.md#util_util_promisify_original
1208-
[promise execution tracking]: #async_hooks_promise_execution_tracking
1198+
[`AsyncResource`]: #class-asyncresource
1199+
[`EventEmitter`]: events.md#class-eventemitter
1200+
[`Stream`]: stream.md#stream
1201+
[`Worker`]: worker_threads.md#class-worker
1202+
[`after` callback]: #afterasyncid
1203+
[`before` callback]: #beforeasyncid
1204+
[`destroy` callback]: #destroyasyncid
1205+
[`init` callback]: #initasyncid-type-triggerasyncid-resource
1206+
[`promiseResolve` callback]: #promiseresolveasyncid
1207+
[`util.promisify()`]: util.md#utilpromisifyoriginal
1208+
[promise execution tracking]: #promise-execution-tracking

‎doc/api/buffer.md

+26-26
Original file line numberDiff line numberDiff line change
@@ -3511,19 +3511,19 @@ introducing security vulnerabilities into an application.
35113511
[WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/
35123512
[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
35133513
[`Blob`]: https://developer.mozilla.org/en-US/docs/Web/API/Blob
3514-
[`Buffer.alloc()`]: #buffer_static_method_buffer_alloc_size_fill_encoding
3515-
[`Buffer.allocUnsafe()`]: #buffer_static_method_buffer_allocunsafe_size
3516-
[`Buffer.allocUnsafeSlow()`]: #buffer_static_method_buffer_allocunsafeslow_size
3517-
[`Buffer.concat()`]: #buffer_static_method_buffer_concat_list_totallength
3518-
[`Buffer.from(array)`]: #buffer_static_method_buffer_from_array
3519-
[`Buffer.from(arrayBuf)`]: #buffer_static_method_buffer_from_arraybuffer_byteoffset_length
3520-
[`Buffer.from(buffer)`]: #buffer_static_method_buffer_from_buffer
3521-
[`Buffer.from(string)`]: #buffer_static_method_buffer_from_string_encoding
3522-
[`Buffer.poolSize`]: #buffer_class_property_buffer_poolsize
3514+
[`Buffer.alloc()`]: #static-method-bufferallocsize-fill-encoding
3515+
[`Buffer.allocUnsafe()`]: #static-method-bufferallocunsafesize
3516+
[`Buffer.allocUnsafeSlow()`]: #static-method-bufferallocunsafeslowsize
3517+
[`Buffer.concat()`]: #static-method-bufferconcatlist-totallength
3518+
[`Buffer.from(array)`]: #static-method-bufferfromarray
3519+
[`Buffer.from(arrayBuf)`]: #static-method-bufferfromarraybuffer-byteoffset-length
3520+
[`Buffer.from(buffer)`]: #static-method-bufferfrombuffer
3521+
[`Buffer.from(string)`]: #static-method-bufferfromstring-encoding
3522+
[`Buffer.poolSize`]: #class-property-bufferpoolsize
35233523
[`DataView`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
3524-
[`ERR_INVALID_BUFFER_SIZE`]: errors.md#ERR_INVALID_BUFFER_SIZE
3525-
[`ERR_INVALID_OPT_VALUE`]: errors.md#ERR_INVALID_OPT_VALUE
3526-
[`ERR_OUT_OF_RANGE`]: errors.md#ERR_OUT_OF_RANGE
3524+
[`ERR_INVALID_BUFFER_SIZE`]: errors.md#err_invalid_buffer_size
3525+
[`ERR_INVALID_OPT_VALUE`]: errors.md#err_invalid_opt_value
3526+
[`ERR_OUT_OF_RANGE`]: errors.md#err_out_of_range
35273527
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
35283528
[`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
35293529
[`String.prototype.indexOf()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf
@@ -3535,20 +3535,20 @@ introducing security vulnerabilities into an application.
35353535
[`TypedArray.prototype.subarray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray
35363536
[`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
35373537
[`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
3538-
[`buf.buffer`]: #buffer_buf_buffer
3539-
[`buf.compare()`]: #buffer_buf_compare_target_targetstart_targetend_sourcestart_sourceend
3540-
[`buf.entries()`]: #buffer_buf_entries
3541-
[`buf.fill()`]: #buffer_buf_fill_value_offset_end_encoding
3542-
[`buf.indexOf()`]: #buffer_buf_indexof_value_byteoffset_encoding
3543-
[`buf.keys()`]: #buffer_buf_keys
3544-
[`buf.length`]: #buffer_buf_length
3545-
[`buf.slice()`]: #buffer_buf_slice_start_end
3546-
[`buf.toString()`]: #buffer_buf_tostring_encoding_start_end
3547-
[`buf.values()`]: #buffer_buf_values
3548-
[`buffer.constants.MAX_LENGTH`]: #buffer_buffer_constants_max_length
3549-
[`buffer.constants.MAX_STRING_LENGTH`]: #buffer_buffer_constants_max_string_length
3550-
[`buffer.kMaxLength`]: #buffer_buffer_kmaxlength
3551-
[`util.inspect()`]: util.md#util_util_inspect_object_options
3538+
[`buf.buffer`]: #bufbuffer
3539+
[`buf.compare()`]: #bufcomparetarget-targetstart-targetend-sourcestart-sourceend
3540+
[`buf.entries()`]: #bufentries
3541+
[`buf.fill()`]: #buffillvalue-offset-end-encoding
3542+
[`buf.indexOf()`]: #bufindexofvalue-byteoffset-encoding
3543+
[`buf.keys()`]: #bufkeys
3544+
[`buf.length`]: #buflength
3545+
[`buf.slice()`]: #bufslicestart-end
3546+
[`buf.toString()`]: #buftostringencoding-start-end
3547+
[`buf.values()`]: #bufvalues
3548+
[`buffer.constants.MAX_LENGTH`]: #bufferconstantsmax_length
3549+
[`buffer.constants.MAX_STRING_LENGTH`]: #bufferconstantsmax_string_length
3550+
[`buffer.kMaxLength`]: #bufferkmaxlength
3551+
[`util.inspect()`]: util.md#utilinspectobject-options
35523552
[`v8::TypedArray::kMaxLength`]: https://v8.github.io/api/head/classv8_1_1TypedArray.html#a54a48f4373da0850663c4393d843b9b0
35533553
[base64url]: https://tools.ietf.org/html/rfc4648#section-5
35543554
[binary strings]: https://developer.mozilla.org/en-US/docs/Web/API/DOMString/Binary

‎doc/api/child_process.md

+38-38
Original file line numberDiff line numberDiff line change
@@ -1680,42 +1680,42 @@ Therefore, this feature requires opting in by setting the
16801680
`serialization` option to `'advanced'` when calling [`child_process.spawn()`][]
16811681
or [`child_process.fork()`][].
16821682

1683-
[Advanced serialization]: #child_process_advanced_serialization
1684-
[Default Windows shell]: #child_process_default_windows_shell
1683+
[Advanced serialization]: #advanced-serialization
1684+
[Default Windows shell]: #default-windows-shell
16851685
[HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
1686-
[Shell requirements]: #child_process_shell_requirements
1687-
[Signal Events]: process.md#process_signal_events
1688-
[`'disconnect'`]: process.md#process_event_disconnect
1689-
[`'error'`]: #child_process_event_error
1690-
[`'exit'`]: #child_process_event_exit
1691-
[`'message'`]: process.md#process_event_message
1692-
[`ChildProcess`]: #child_process_class_childprocess
1693-
[`Error`]: errors.md#errors_class_error
1694-
[`EventEmitter`]: events.md#events_class_eventemitter
1695-
[`child_process.exec()`]: #child_process_child_process_exec_command_options_callback
1696-
[`child_process.execFile()`]: #child_process_child_process_execfile_file_args_options_callback
1697-
[`child_process.execFileSync()`]: #child_process_child_process_execfilesync_file_args_options
1698-
[`child_process.execSync()`]: #child_process_child_process_execsync_command_options
1699-
[`child_process.fork()`]: #child_process_child_process_fork_modulepath_args_options
1700-
[`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options
1701-
[`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options
1702-
[`maxBuffer` and Unicode]: #child_process_maxbuffer_and_unicode
1703-
[`net.Server`]: net.md#net_class_net_server
1704-
[`net.Socket`]: net.md#net_class_net_socket
1705-
[`options.detached`]: #child_process_options_detached
1706-
[`process.disconnect()`]: process.md#process_process_disconnect
1707-
[`process.env`]: process.md#process_process_env
1708-
[`process.execPath`]: process.md#process_process_execpath
1709-
[`process.send()`]: process.md#process_process_send_message_sendhandle_options_callback
1710-
[`stdio`]: #child_process_options_stdio
1711-
[`subprocess.connected`]: #child_process_subprocess_connected
1712-
[`subprocess.disconnect()`]: #child_process_subprocess_disconnect
1713-
[`subprocess.kill()`]: #child_process_subprocess_kill_signal
1714-
[`subprocess.send()`]: #child_process_subprocess_send_message_sendhandle_options_callback
1715-
[`subprocess.stderr`]: #child_process_subprocess_stderr
1716-
[`subprocess.stdin`]: #child_process_subprocess_stdin
1717-
[`subprocess.stdio`]: #child_process_subprocess_stdio
1718-
[`subprocess.stdout`]: #child_process_subprocess_stdout
1719-
[`util.promisify()`]: util.md#util_util_promisify_original
1720-
[synchronous counterparts]: #child_process_synchronous_process_creation
1721-
[v8.serdes]: v8.md#v8_serialization_api
1686+
[Shell requirements]: #shell-requirements
1687+
[Signal Events]: process.md#signal-events
1688+
[`'disconnect'`]: process.md#event-disconnect
1689+
[`'error'`]: #event-error
1690+
[`'exit'`]: #event-exit
1691+
[`'message'`]: process.md#event-message
1692+
[`ChildProcess`]: #class-childprocess
1693+
[`Error`]: errors.md#class-error
1694+
[`EventEmitter`]: events.md#class-eventemitter
1695+
[`child_process.exec()`]: #child_processexeccommand-options-callback
1696+
[`child_process.execFile()`]: #child_processexecfilefile-args-options-callback
1697+
[`child_process.execFileSync()`]: #child_processexecfilesyncfile-args-options
1698+
[`child_process.execSync()`]: #child_processexecsynccommand-options
1699+
[`child_process.fork()`]: #child_processforkmodulepath-args-options
1700+
[`child_process.spawn()`]: #child_processspawncommand-args-options
1701+
[`child_process.spawnSync()`]: #child_processspawnsynccommand-args-options
1702+
[`maxBuffer` and Unicode]: #maxbuffer-and-unicode
1703+
[`net.Server`]: net.md#class-netserver
1704+
[`net.Socket`]: net.md#class-netsocket
1705+
[`options.detached`]: #optionsdetached
1706+
[`process.disconnect()`]: process.md#processdisconnect
1707+
[`process.env`]: process.md#processenv
1708+
[`process.execPath`]: process.md#processexecpath
1709+
[`process.send()`]: process.md#processsendmessage-sendhandle-options-callback
1710+
[`stdio`]: #optionsstdio
1711+
[`subprocess.connected`]: #subprocessconnected
1712+
[`subprocess.disconnect()`]: #subprocessdisconnect
1713+
[`subprocess.kill()`]: #subprocesskillsignal
1714+
[`subprocess.send()`]: #subprocesssendmessage-sendhandle-options-callback
1715+
[`subprocess.stderr`]: #subprocessstderr
1716+
[`subprocess.stdin`]: #subprocessstdin
1717+
[`subprocess.stdio`]: #subprocessstdio
1718+
[`subprocess.stdout`]: #subprocessstdout
1719+
[`util.promisify()`]: util.md#utilpromisifyoriginal
1720+
[synchronous counterparts]: #synchronous-process-creation
1721+
[v8.serdes]: v8.md#serialization-api

0 commit comments

Comments
 (0)