doc: format doc/guides using format-md task

PR-URL: #40358
Reviewed-By: Tobias Nießen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>

Author: Trott

doc/guides/backporting-to-release-lines.md

@@ -32,58 +32,65 @@ branch. In order to submit a backport pull request to another branch, simply
 replace that with the staging branch for the targeted release line.
 
 1. Checkout the staging branch for the targeted release line.
+
 2. Make sure that the local staging branch is up to date with the remote.
+
 3. Create a new branch off of the staging branch, as shown below.
 
-    ```bash
-    # Assuming your fork of Node.js is checked out in $NODE_DIR,
-    # the origin remote points to your fork, and the upstream remote points
-    # to git://github.com/nodejs/node
-    cd $NODE_DIR
-    # If v10.x-staging is checked out `pull` should be used instead of `fetch`
-    git fetch upstream v10.x-staging:v10.x-staging -f
-    # Assume we want to backport PR #10157
-    git checkout -b backport-10157-to-v10.x v10.x-staging
-    # Ensure there are no test artifacts from previous builds
-    # Note that this command deletes all files and directories
-    # not under revision control below the ./test directory.
-    # It is optional and should be used with caution.
-    git clean -xfd ./test/
-    ```
+   ```bash
+   # Assuming your fork of Node.js is checked out in $NODE_DIR,
+   # the origin remote points to your fork, and the upstream remote points
+   # to git://github.com/nodejs/node
+   cd $NODE_DIR
+   # If v10.x-staging is checked out `pull` should be used instead of `fetch`
+   git fetch upstream v10.x-staging:v10.x-staging -f
+   # Assume we want to backport PR #10157
+   git checkout -b backport-10157-to-v10.x v10.x-staging
+   # Ensure there are no test artifacts from previous builds
+   # Note that this command deletes all files and directories
+   # not under revision control below the ./test directory.
+   # It is optional and should be used with caution.
+   git clean -xfd ./test/
+   ```
 
 4. After creating the branch, apply the changes to the branch. The cherry-pick
    will likely fail due to conflicts. In that case, you will see something
    like this:
 
-    ```console
-    # Say the $SHA is 773cdc31ef
-    $ git cherry-pick $SHA # Use your commit hash
-    error: could not apply 773cdc3... <commit title>
-    hint: after resolving the conflicts, mark the corrected paths
-    hint: with 'git add <paths>' or 'git rm <paths>'
-    hint: and commit the result with 'git commit'
-    ```
+   ```console
+   # Say the $SHA is 773cdc31ef
+   $ git cherry-pick $SHA # Use your commit hash
+   error: could not apply 773cdc3... <commit title>
+   hint: after resolving the conflicts, mark the corrected paths
+   hint: with 'git add <paths>' or 'git rm <paths>'
+   hint: and commit the result with 'git commit'
+   ```
 
 5. Make the required changes to remove the conflicts, add the files to the index
    using `git add`, and then commit the changes. That can be done with
    `git cherry-pick --continue`.
+
 6. Leave the commit message as is. If you think it should be modified, comment
    in the pull request. The `Backport-PR-URL` metadata does need to be added to
    the commit, but this will be done later.
+
 7. Make sure `make -j4 test` passes.
+
 8. Push the changes to your fork.
+
 9. Open a pull request:
    1. Be sure to target the `v10.x-staging` branch in the pull request.
-   1. Include the backport target in the pull request title in the following
+   2. Include the backport target in the pull request title in the following
       format: `[v10.x backport] <commit title>`.
       Example: `[v10.x backport] process: improve performance of nextTick`
-   1. Check the checkbox labeled "Allow edits and access to secrets by
+   3. Check the checkbox labeled "Allow edits and access to secrets by
       maintainers".
-   1. In the description add a reference to the original pull request.
-   1. Amend the commit message and include a `Backport-PR-URL:` metadata and
+   4. In the description add a reference to the original pull request.
+   5. Amend the commit message and include a `Backport-PR-URL:` metadata and
       re-push the change to your fork.
-   1. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the
+   6. Run a [`node-test-pull-request`][] CI job (with `REBASE_ONTO` set to the
       default `<pr base branch>`)
+
 10. If during the review process conflicts arise, use the following to rebase:
     `git pull --rebase upstream v10.x-staging`
 

doc/guides/collaborator-guide.md

@@ -2,7 +2,7 @@
 
 > Stability: 1 - Experimental
 
-*tl;dr: You can land pull requests by adding the `commit-queue` label to it.*
+_tl;dr: You can land pull requests by adding the `commit-queue` label to it._
 
 Commit Queue is an experimental feature for the project which simplifies the
 landing process by automating it via GitHub Actions. With it, collaborators can
@@ -58,17 +58,17 @@ events every five minutes. Five minutes is the smallest number accepted by
 the scheduler. The scheduler is not guaranteed to run every five minutes, it
 might take longer between runs.
 
-Using the scheduler is preferable over using pull_request_target for two
+Using the scheduler is preferable over using pull\_request\_target for two
 reasons:
 
 1. if two Commit Queue Actions execution overlap, there's a high-risk that
    the last one to finish will fail because the local branch will be out of
    sync with the remote after the first Action pushes. `issue_comment` event
    has the same limitation.
 2. `pull_request_target` will only run if the Action exists on the base commit
-    of a pull request, and it will run the Action version present on that
-    commit, meaning we wouldn't be able to use it for already opened PRs
-    without rebasing them first.
+   of a pull request, and it will run the Action version present on that
+   commit, meaning we wouldn't be able to use it for already opened PRs
+   without rebasing them first.
 
 `node-core-utils` is configured with a personal token and
 a Jenkins token from
@@ -79,16 +79,16 @@ that into a list of PR ids we can pass as arguments to
 [`commit-queue.sh`](../../tools/actions/commit-queue.sh).
 
 > The personal token only needs permission for public repositories and to read
-> profiles, we can use the GITHUB_TOKEN for write operations. Jenkins token is
+> profiles, we can use the GITHUB\_TOKEN for write operations. Jenkins token is
 > required to check CI status.
 
 `commit-queue.sh` receives the following positional arguments:
 
 1. The repository owner
 2. The repository name
-3. The Action GITHUB_TOKEN
+3. The Action GITHUB\_TOKEN
 4. Every positional argument starting at this one will be a pull request ID of
-    a pull request with commit-queue set.
+   a pull request with commit-queue set.
 
 The script will iterate over the pull requests. `ncu-ci` is used to check if
 the last CI is still pending, and calls to the GitHub API are used to check if

doc/guides/commit-queue.md

@@ -1,7 +1,7 @@
 # Code of Conduct
 
-The Node.js project has a [Code of Conduct][] that *all* contributors are
-expected to follow. This code describes the *minimum* behavior expectations
+The Node.js project has a [Code of Conduct][] that _all_ contributors are
+expected to follow. This code describes the _minimum_ behavior expectations
 for all contributors.
 
 As a contributor to Node.js, how you choose to act and interact towards your
@@ -12,7 +12,7 @@ allows anyone and everyone who wants to contribute to feel safe doing so.
 
 Should any individual act in any way that is considered in violation of the
 [Code of Conduct][], corrective actions will be taken. It is possible, however,
-for any individual to *act* in such a manner that is not in violation of the
+for any individual to _act_ in such a manner that is not in violation of the
 strict letter of the Code of Conduct guidelines while still going completely
 against the spirit of what that Code is intended to accomplish.
 
@@ -26,17 +26,17 @@ All contributors to Node.js tacitly agree to abide by both the letter and
 spirit of the [Code of Conduct][]. Failure, or unwillingness, to do so will
 result in contributions being respectfully declined.
 
-A *bad actor* is someone who repeatedly violates the spirit of the Code of
+A _bad actor_ is someone who repeatedly violates the spirit of the Code of
 Conduct through failure to regulate how they
 interact with others. In doing so, bad actors
 alienate other contributors, discourage collaboration, and generally reflect
 poorly on the project as a whole.
 
 Being a bad actor may be intentional or unintentional. Typically, unintentional
 bad behavior can be easily corrected by being quick to apologize and correct
-course *even if you are not entirely convinced you need to*. Giving other
+course _even if you are not entirely convinced you need to_. Giving other
 contributors the benefit of the doubt and having a sincere willingness to admit
-that you *might* be wrong is critical for any successful open collaboration.
+that you _might_ be wrong is critical for any successful open collaboration.
 
 Don't be a bad actor.
 

doc/guides/contributing/code-of-conduct.md

@@ -30,7 +30,7 @@ test case we can use to recreate the problem on our own. If we cannot recreate
 the issue, it becomes impossible for us to fix.
 
 In order to rule out the possibility of bugs introduced by userland code, test
-cases should be limited, as much as possible, to using *only* Node.js APIs.
+cases should be limited, as much as possible, to using _only_ Node.js APIs.
 If the bug occurs only when you're using a specific userland module, there is
 a very good chance that either (a) the module has a bug or (b) something in
 Node.js changed that broke the module.
@@ -53,7 +53,7 @@ project's GitHub organization plus a few contributions to the project
 (commenting on issues or PRs) can apply for and become a triager. Open a PR
 on the README.md of this project with: i) a request to be added as a triager,
 ii) the motivation for becoming a triager, and iii) agreement on reading,
-understanding, and adhering to the project's [Code Of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md).
+understanding, and adhering to the project's [Code Of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE\_OF\_CONDUCT.md).
 
 The triage role enables the ability to carry out the most common triage
 activities, such as applying labels and closing/reopening/assigning issues.

doc/guides/contributing/issues.md

@@ -34,7 +34,7 @@
 
 ## Dependencies
 
-Node.js has several bundled dependencies in the *deps/* and the *tools/*
+Node.js has several bundled dependencies in the _deps/_ and the _tools/_
 directories that are not part of the project proper. Changes to files in those
 directories should be sent to their respective projects. Do not send a patch to
 Node.js. We cannot accept such patches.
@@ -161,33 +161,37 @@ notes about [commit squashing](#commit-squashing).
 A good commit message should describe what changed and why.
 
 1. The first line should:
+
    * contain a short description of the change (preferably 50 characters or
      less, and no more than 72 characters)
    * be entirely in lowercase with the exception of proper nouns, acronyms, and
-   the words that refer to code, like function/variable names
+     the words that refer to code, like function/variable names
    * be prefixed with the name of the changed [subsystem](#appendix-subsystems)
-   and start with an imperative verb. Check the output of `git log --oneline
-   files/you/changed` to find out what subsystems your changes touch.
+     and start with an imperative verb. Check the output of `git log --oneline
+     files/you/changed` to find out what subsystems your changes touch.
 
    Examples:
+
    * `net: add localAddress and localPort to Socket`
    * `src: fix typos in async_wrap.h`
 
 2. Keep the second line blank.
+
 3. Wrap all other lines at 72 columns (except for long URLs).
 
 4. If your patch fixes an open issue, you can add a reference to it at the end
    of the log. Use the `Fixes:` prefix and the full issue URL. For other
    references use `Refs:`.
 
    Examples:
+
    * `Fixes: https://github.com/nodejs/node/issues/1337`
    * `Refs: https://eslint.org/docs/rules/space-in-parens.html`
    * `Refs: https://github.com/nodejs/node/pull/3615`
 
 5. If your commit introduces a breaking change (`semver-major`), it should
-contain an explanation about the reason of the breaking change, which
-situation would trigger the breaking change and what is the exact change.
+   contain an explanation about the reason of the breaking change, which
+   situation would trigger the breaking change and what is the exact change.
 
 Sample complete commit message:
 
@@ -322,7 +326,7 @@ reviews a pull request they may find specific details that they would like to
 see changed or fixed. These may be as simple as fixing a typo, or may involve
 substantive changes to the code you have written. While such requests are
 intended to be helpful, they may come across as abrupt or unhelpful, especially
-requests to change things that do not include concrete suggestions on *how* to
+requests to change things that do not include concrete suggestions on _how_ to
 change them.
 
 Try not to be discouraged. If you feel that a particular review is unfair,
@@ -384,7 +388,7 @@ Focus first on the most significant aspects of the change:
 4. Is the commit message readable and correct? If it contains a breaking change
    is it clear enough?
 
-When changes are necessary, *request* them, do not *demand* them, and do not
+When changes are necessary, _request_ them, do not _demand_ them, and do not
 assume that the submitter already knows how to add a test or run a benchmark.
 
 Specific performance optimization techniques, coding styles and conventions
@@ -404,7 +408,7 @@ with the appropriate reason to keep the conversation flow concise and relevant.
 
 ### Be aware of the person behind the code
 
-Be aware that *how* you communicate requests and reviews in your feedback can
+Be aware that _how_ you communicate requests and reviews in your feedback can
 have a significant impact on the success of the pull request. Yes, we may land
 a particular change that makes Node.js better, but the individual might just
 not want to have anything to do with Node.js ever again. The goal is not just
@@ -446,7 +450,7 @@ or by leaving an `LGTM` ("Looks Good To Me") comment.
 When explicitly using the "Changes requested" component of the GitHub Approval
 Workflow, show empathy. That is, do not be rude or abrupt with your feedback
 and offer concrete suggestions for improvement, if possible. If you're not
-sure *how* a particular change can be improved, say so.
+sure _how_ a particular change can be improved, say so.
 
 Most importantly, after leaving such requests, it is courteous to make yourself
 available later to check whether your comments have been addressed.
@@ -494,7 +498,7 @@ changing working functional code just for the sake of changing.
 
 If a particular pull request introduces a performance or functional
 regression, rather than simply rejecting the pull request, take the time to
-work *with* the contributor on improving the change. Offer feedback and
+work _with_ the contributor on improving the change. Offer feedback and
 advice on what would make the pull request acceptable, and do not assume that
 the contributor should already know how to do that. Be explicit in your
 feedback.

doc/guides/contributing/pull-requests.md

@@ -14,9 +14,9 @@ Node.js codebase not related to stylistic issues.
   * [Align function arguments vertically](#align-function-arguments-vertically)
   * [Initialization lists](#initialization-lists)
   * [CamelCase for methods, functions, and classes](#camelcase-for-methods-functions-and-classes)
-  * [`snake_case` for local variables and parameters](#snake_case-for-local-variables-and-parameters)
-  * [`snake_case_` for private class fields](#snake_case_-for-private-class-fields)
-  * [`snake_case` for C-like structs](#snake_case-for-c-like-structs)
+  * [`snake_case` for local variables and parameters](#snake\_case-for-local-variables-and-parameters)
+  * [`snake_case_` for private class fields](#snake\_case\_-for-private-class-fields)
+  * [`snake_case` for C-like structs](#snake\_case-for-c-like-structs)
   * [Space after `template`](#space-after-template)
 * [Memory management](#memory-management)
   * [Memory allocation](#memory-allocation)
@@ -174,7 +174,7 @@ class Foo {
 
 ### `snake_case` for C-like structs
 
-For plain C-like structs snake_case can be used.
+For plain C-like structs snake\_case can be used.
 
 ```cpp
 struct foo_bar {
@@ -267,7 +267,8 @@ class ExampleClass {
 
 When working with typed arrays that involve direct data modification
 from C++, use an `AliasedBuffer` when possible. The API abstraction and
-the usage scope of `AliasedBuffer` are documented in [aliased_buffer.h][].
+the usage scope of `AliasedBuffer` are documented in
+[aliased\_buffer.h][aliased_buffer.h].
 
 ```cpp
 // Create an AliasedBuffer.