build: lint Markdown (#535)

* build: lint Markdown

* chore: cleanup linting errors

* chore: lowercase a few more URL fragments

* chore: fix broken links

* build: add option to check external links on workflow

* build: always lint link even if markdownlint fails

* chore: cleanup linting errors from latest @electron/lint-roller

* chore: missed one

.github/workflows/lint.yml

@@ -0,0 +1,39 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      fetch-external-links:
+        type: boolean
+        description: Check if external links are broken
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c  # tag: v3.3.0
+    - name: Setup Node.js
+      uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c  # tag: v3.6.0
+      with:
+        node-version: 18.x
+    - name: Create a Temporary package.json
+      run: npm init --yes
+    - name: Install @electron/lint-roller
+      run: npm install --save-dev @electron/lint-roller
+    - name: Run markdownlint
+      run: npx electron-markdownlint "**/*.md"
+    - name: Lint links
+      run: npx electron-lint-markdown-links --root . --ignore-path .markdownlintignore "**/*.md"
+      if: ${{ always() }}
+    - name: Check external links
+      run: npx electron-lint-markdown-links --root . --ignore-path .markdownlintignore --fetch-external-links "**/*.md"
+      if: ${{ github.event.inputs.fetch-external-links }}

.markdownlint.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@electron/lint-roller/configs/markdownlint.json",
+  "blanks-around-fences": false,
+  "blanks-around-headings": false,
+  "blanks-around-headers": false,
+  "blanks-around-lists": false,
+  "fenced-code-language": false,
+  "ol-prefix": false,
+  "no-multiple-blanks": false,
+  "no-shortcut-reference-links": false,
+  "no-trailing-spaces": false,
+  "ul-indent": false,
+  "ul-style": false
+}

.markdownlintignore

@@ -0,0 +1,3 @@
+**/retros/**
+**/meeting-notes/**
+node_modules/**

README.md

@@ -58,16 +58,16 @@ The Electron governance system is comprised of Working Groups that oversee diffe
 * A _collaborator_ is active in the community, but not in governance.
 * A _participant_ is anyone who is a maintainer or collaborator.
 * A _working group_ is a group of maintainers that is formed to take responsibility for certain aspects of the Electron project. Normally these groups will meet regularly but in some cases will only meet as required to fulfill their responsibilities.
-* A [_chair_](charter/README.md#Leadership) leads a working group.
+* A [_chair_](charter/rotating-chair-model.md) leads a working group.
 
 ## Responsibilities
 
 All Working Groups have these core responsibilities:
 
 * They shall decide for themselves, and publicly post, their rules, e.g. how decisions are made, when meetings are held, and who may attend.
-* They shall [select](charter/README.md#Leadership-Terms-and-Selection) a chair to [represent](charter/README.md#Leadership-Responsibilities) the group.
+* They shall [select](charter/rotating-chair-model.md#chair-terms-and-selection) a chair to [represent](charter/rotating-chair-model.md#chair-responsibilities) the group.
 * They shall keep meeting notes, including agenda items, discussion points, and outcomes for everyone to review.
-* They shall be collaborative and work [in good faith](charter/README.md#Core-Values) with other Working Groups.
+* They shall be collaborative and work [in good faith](charter/README.md#core-values) with other Working Groups.
 
 See [charter/README.md](./charter/README.md) for more information.
 

charter/README.md

@@ -42,7 +42,7 @@ These are our core values, as voted by the maintainers, in order of importance.
  * A _participant_ is anyone who is a maintainer or collaborator.
  * A _Working Group_ is a group of maintainers that is formed to take responsibility for certain aspects of the Electron project. Normally these groups will meet regularly but in some cases will only meet as required to fulfill their responsibilities.
  * A _chair_ is the acting leader of a Working Group that uses the [Rotating Chair Model](rotating-chair-model.md).
- * A [_delegate_](#Delegation) is a chosen representative of a Working Group.
+ * A [_delegate_](#delegation) is a chosen representative of a Working Group.
 
 ## Participation
 
@@ -70,7 +70,7 @@ All Working Groups have these core responsibilities:
  * They shall decide for themselves, and publicly post, their rules, e.g. how decisions are made, when meetings are held, and who may attend.
  * They shall choose a model of work to support reaching the Working Group's goals.
  * They shall keep meeting notes, including agenda items, discussion points, and outcomes for everyone to review.
- * They shall be collaborative and work [in good faith](#Core-Values) with other Working Groups.
+ * They shall be collaborative and work [in good faith](#core-values) with other Working Groups.
 
 ### Meetings
 
@@ -84,11 +84,11 @@ Members should have the opportunity to read a summary of the meeting and share p
 
 Delegates have responsibilities to their Working Group: they represent the collective will of that group to others.
 
-Delegates are [chosen](#Reaching-Agreement) by the members of their Working Group, either when the need for one arises or for a short period of time not longer than four weeks when a delegate may be needed multiple times in rapid succession.
+Delegates are [chosen](#reaching-agreement) by the members of their Working Group, either when the need for one arises or for a short period of time not longer than four weeks when a delegate may be needed multiple times in rapid succession.
 
 ### Reaching Agreement
 
-If an issue affects only one Working Group, that group can make decisions [on its own](#Meetings).
+If an issue affects only one Working Group, that group can make decisions [on its own](#meetings).
 
 If an issue affects more than one Working Group, those groups are encouraged to work towards agreement together.
 
@@ -100,7 +100,7 @@ Regardless of how agreement is reached, the participating groups must make a rea
 
 # Electorate
 
-The **Electorate** is the body who holds the ability to alter the charter and appoint members of the [Administrative Working Group](#Administrative-Working-Group).
+The **Electorate** is the body who holds the ability to alter the charter and appoint members of the [Administrative Working Group](#administrative-working-group).
 
 The Electorate should try to balance several factors in its composition of members:
 

charter/interest-groups.md

@@ -23,13 +23,13 @@ Interest groups will be listed in this repository with a link for maintainers to
 3. Members of interest groups will be notified via GitHub notifications when a PR has a reviewer set to the interest group teams that member belongs to.
 4. Interest group members provide feedback using the GitHub PR review process.  Members of affected Interest Groups who do not provide feedback will be considered to be providing implicit approval of the PR.
 5. If there are conflicting opinions on the PR, the reviewers involved should seek to resolve the conflicts within the PR.
-6. If resolution cannot be agreed upon in the PR, the issue can be raised for resolution using [Electron's conflict resolution process](policy/charter.md#Reaching-Agreement)
+6. If resolution cannot be agreed upon in the PR, the issue can be raised for resolution using [Electron's conflict resolution process](./README.md#reaching-agreement)
 7. The resolution/decision on the PR should be documented in the issue via a GitHub comment.
 
 ## Interest Group RFC/Intent To Ship Workflow
 
 1. Any maintainer can create a RFC or Intent To Ship issue in the [electron/electron](https://github.com/electron/electron) repository.  These issues would be used to gather input on ideas (RFCs) and feedback on planned implementations (Intent To Ship).  When creating a RFC or Intent To Ship issue, the submitter should pick the proper issue template which will include a link to the list of interest groups so that the issue creator has a list of group(s) to ask for input from.
 2. Once input has been solicited, it is the responsibility of Interest Group members to provide feedback in these issues.  Members of affected Interest Groups who do not provide feedback will be considered to be providing implicit approval of the issue.
 3. If there are conflicting opinions on the issue, the maintainers involved should seek to resolve the conflicts within the issue.
-4. If resolution cannot be agreed upon in the issue, the issue can be raised for resolution using [Electron's conflict resolution process](policy/charter.md#Reaching-Agreement)
+4. If resolution cannot be agreed upon in the issue, the issue can be raised for resolution using [Electron's conflict resolution process](./README.md#reaching-agreement)
 5. The resolution/decision on the issue should be documented in the issue via a GitHub comment.

charter/rotating-chair-model.md

@@ -5,7 +5,7 @@ The Rotating Chair Model is a model of a Working Group that appoints a leader to
 ## Working Group Responsibilities
 
 A Working Group that uses the Rotating Chair Model has an additional core responsibility:
-* They shall [select](#Chair-Terms-and-Selection) a rotating chair to [lead](#Chair-Responsibilities) the group and ensure the Working Group's goals are fulfilled.
+* They shall [select](#chair-terms-and-selection) a rotating chair to [lead](#chair-responsibilities) the group and ensure the Working Group's goals are fulfilled.
 
 ## Chair Terms and Selection
 

playbooks/issue-triage.md

@@ -80,17 +80,17 @@ Once an issue is triaged, the maintainers can work on addressing it. {{Insert st
 * The issue is closed with `help-wanted` and an explanation that this is not something the maintainers will be working on soon, but well-written Pull Requests would be accepted
 * The issue is closed for some other reason
 
-Just because something goes on the backlog doesn't mean that it will be addressed immediately. But the idea is that all issues that are open will be periodically reviewed and kept in the priority list. Since we will be reviewing _all_ open issues at fixed time intervals, we will need to keep this list manageable and realistic.
+Just because something goes on the backlog doesn't mean that it will be addressed immediately. But the idea is that all issues that are open will be periodically reviewed and kept in the priority list. Since we will be reviewing *all* open issues at fixed time intervals, we will need to keep this list manageable and realistic.
 
 ## Old, Untouched Issues
 
-Despite everyone's best efforts, old issues will always exist. If you find one that hasn't been touched in a quite a while _and_ you are unable to recreate the behavior, update the issue with the [`old-untouched` response](responses/old-untouched.md)
+Despite everyone's best efforts, old issues will always exist. If you find one that hasn't been touched in a quite a while *and* you are unable to recreate the behavior, update the issue with the [`old-untouched` response](responses/old-untouched.md)
 
 ## Common Responses
 
 This section outlines several common scenarios, and the responses and labels we recommend using for issue triage. It also tries to address several commonly asked questions for those new to the issue triage process.
 
-_NB: The reponses below are meant to be a guide for someone new to triaging issues in Electron, not requirements. If you find an issue while triaging that you think needs a different response than is recommended here, use your own judgement._
+*NB: The reponses below are meant to be a guide for someone new to triaging issues in Electron, not requirements. If you find an issue while triaging that you think needs a different response than is recommended here, use your own judgement.*
 
 #### Low Quality/Spam
 

playbooks/pull-request-triage.md

@@ -43,7 +43,7 @@ Keep in mind that this is not the 100% complete maintainer's guide to pull reque
 
 ## Work In Progress
 
-Pull requests that are works in progress should be the exception rather than the rule. If the pull request doesn't see any updates to the body or its content within two weeks of the time we look at it, close the pull request with [the stale pull request message](responses/stale-pull-request.md).
+Pull requests that are works in progress should be the exception rather than the rule. If the pull request doesn't see any updates to the body or its content within two weeks of the time we look at it, close the pull request with [the stale pull request message](responses/work-in-progress.md).
 
 ## More Information Needed
 

playbooks/responses/close-enhancement-request.md

@@ -1,2 +1,2 @@
 Hi, while we appreciate this enhancement request it's not something that our team
-will be able to implement in the near future, and since we use our issues tab as the team's backlog, we prefer to only retain issues that are on our immediate roadmap. If you'd like to make a PR for this request we would welcome that but in the meantime I'm going to go ahead and close this.
+will be able to implement in the near future, and since we use our issues tab as the team's backlog, we prefer to only retain issues that are on our immediate roadmap. If you'd like to make a PR for this request we would welcome that but in the meantime I'm going to go ahead and close this.

playbooks/responses/crash-report.md

@@ -13,4 +13,4 @@ crashReporter.start({ submitURL: '', uploadToServer: false })
 ```
 Then reproduce the crash, zip up the crash dumps directory and attach it here. I'm adding the `blocked/need-info` label until we have access to the crash dumps.
 
-Thanks in advance! Your help is appreciated.
+Thanks in advance! Your help is appreciated.

wg-administrative/README.md

@@ -18,7 +18,7 @@ The initial group members consist of management from Microsoft, and Slack whose
 
 The AWG aims to ensure the collective health of the maintainers and working groups, while offering support as necessary through means that may not fall on any existing working group, such as a mechanism for escalation.
 
-*The AWG should not make individual technical decisions.*
+_The AWG should not make individual technical decisions._
 
 It is important that other working groups have autonomy and agency to fulfill their responsibilities.
 

wg-api/README.md

@@ -45,8 +45,8 @@ In order to become formal members of the WG, prospective members must:
     1. The meeting notes shall contain only the outcome of the vote (approved/not approved), not the individual votes.
     1. Members not able to attend the meeting at which the vote occurs may submit their vote to the Chair prior to the meeting.
 
-If you're interested in joining the API Working Group, reach out to an [existing member](#Membership) and ask to be invited to the regular meeting and as a guest to the #wg-api channel in Slack.
+If you're interested in joining the API Working Group, reach out to an [existing member](#membership) and ask to be invited to the regular meeting and as a guest to the #wg-api channel in Slack.
 
 ### Actively contributing
 
-"Actively contributing" doesn't necessarily mean writing code. It does mean that you should be in regular communication with the API WG (including attending meetings), and it does mean that you should be materially contributing to the project in some way. If you're not sure whether the work you're doing counts as "materially contributing", reach out to a [member](#Membership) and ask. 🙂
+"Actively contributing" doesn't necessarily mean writing code. It does mean that you should be in regular communication with the API WG (including attending meetings), and it does mean that you should be materially contributing to the project in some way. If you're not sure whether the work you're doing counts as "materially contributing", reach out to a [member](#membership) and ask. 🙂

wg-api/spec-documents/message-ports.md

@@ -36,7 +36,7 @@ Node.js took inspiration from the Channel Messaging API when they designed the [
 
 ### Transferables
 
-In the `postMessage` API, one of the options available when sending a message is to pass a list of _transferables_ to be passed along with the message. These objects, once transferred through `postMessage`, are no longer accessible to the sender, and ownership is transferred to the receiver. Some examples of transferable objects are `ArrayBuffer`, `ImageBitmap` and `MessagePort`.
+In the `postMessage` API, one of the options available when sending a message is to pass a list of *transferables* to be passed along with the message. These objects, once transferred through `postMessage`, are no longer accessible to the sender, and ownership is transferred to the receiver. Some examples of transferable objects are `ArrayBuffer`, `ImageBitmap` and `MessagePort`.
 
 References to transferred objects can appear in the message data, and when deserialized, the message on the receiving end will contain references to those transferred objects in the appropriate place.
 
@@ -117,7 +117,7 @@ Emitted when the channel is closed.
 ::::
 
 > [name=Samuel Attard]
-> Is there a way to tell if a message port has been closed _after_ the fact.  E.g. `port.isClosed` or something?  Otherwise I assume `postMessage` will throw if the port is closed and you try to send a message.
+> Is there a way to tell if a message port has been closed *after* the fact.  E.g. `port.isClosed` or something?  Otherwise I assume `postMessage` will throw if the port is closed and you try to send a message.
 
 ## Example usage of new API
 
@@ -190,7 +190,7 @@ In Blink, `MessagePort` is a fairly thin wrapper around a Mojo pipe. Node's mess
 In our current IPC implementation we have a boolean flag for whether an IPC message is 'internal' or not, and we avoid exposing internal IPCs to users. Using the new channel messaging API, it would be possible to create an 'internal' channel over which such messages could be sent—in fact, we could create as many different channels as we liked. In particular, it would be useful to separate each different Electron API into its own channel, which would eliminate the possibility of namespace collision between APIs, and additionally provide a security feature: possession of the channel port implies permission to use the API, and without a port it would be impossible to use that feature.
 
 > [name=Samuel Attard]
-> This design would be that _all_ APIs would by definition become async in the renderer if they required IPC to back them as I'm assuming we wouldn't make a `postMessageSync` API.  This means all usages of `sendSync` or `invokeSync` either get stuck on the old API or have to have breaking API changes.  It sounds like a lot of our internal impls wouldn't be able to use this because of this restriction.
+> This design would be that *all* APIs would by definition become async in the renderer if they required IPC to back them as I'm assuming we wouldn't make a `postMessageSync` API.  This means all usages of `sendSync` or `invokeSync` either get stuck on the old API or have to have breaking API changes.  It sounds like a lot of our internal impls wouldn't be able to use this because of this restriction.
 
 ### 'close' event
 

wg-api/spec-documents/scroll-view.md

@@ -18,7 +18,7 @@ It is currently not possible to add scrolling functionality around BrowserViews:
 
 More details of the use-case and challenges related to workarounds: [#32751](https://github.com/electron/electron/issues/32751)
 
-![](https://user-images.githubusercontent.com/2891206/150981006-84fe796e-60bd-43c0-952d-831d1bfd9998.gif)
+![ScrollView concept](https://user-images.githubusercontent.com/2891206/150981006-84fe796e-60bd-43c0-952d-831d1bfd9998.gif)
 
 ## Usage Example