Improve markdownlint rules, fix up markdown root files

Author: lornajane

.markdownlint.yaml

@@ -1,16 +1,33 @@
-# Unordered list symbol
-MD004:
-    style: asterisk
+# First heading is a top-level heading
+MD002: true
 
-# Unordered list indentation
+# Heading style (ATX is leading # symbols)
+MD003:
+  style: atx
+
+# Unordered list symbol can be anything
+MD004: false
+
+# Unordered list indentation size
 MD007:
     indent: 2
 
-MD012: false # allow blank lines
+# Allow additional blank lines
+MD012: false
 
+# Maximum line length
 MD013:
     line_length: 800
     tables: false
 
-MD024: false # duplicate headings
-MD033: false # inline HTML
+# Headings need blank lines before and after
+MD022: true
+
+# Duplicate headings are allowed
+MD024: false
+
+# Surround lists with blank lines
+MD032: true
+
+# Allow inline HTML
+MD033: false

CONTRIBUTING.md

@@ -45,9 +45,9 @@ Most ideas start as discussions.
 
 Please do come and start a discussion to:
 
- - ask questions
- - make suggestions
- - give feedback
+- ask questions
+- make suggestions
+- give feedback
 
 Anyone can start a discussion and you're very welcome to do so! Write a message and pick a relevant discussion category.
 
@@ -57,11 +57,11 @@ Participation in discussions and especially answering of questions is encouraged
 
 Discussions are closed when:
 
- - the question has been answered.
- - no further action or conversation would be useful.
- - there has been no engagement for a while, or a previously popular thread has been inactive for an extended period.
- - activity is now taking place elsewhere, such as in an issue.
- - the discussion is out of scope for the project.
+- the question has been answered.
+- no further action or conversation would be useful.
+- there has been no engagement for a while, or a previously popular thread has been inactive for an extended period.
+- activity is now taking place elsewhere, such as in an issue.
+- the discussion is out of scope for the project.
 
 ## Issues
 
@@ -212,7 +212,7 @@ The steps for creating a `vX.Y.Z-rel` branch are:
 4. Create `vX.Y.Z-rel` from `vX.Y-dev` and adjust it
    - move `src/oas.md` to `versions/X.Y.Z.md`
    - copy `EDITORS.md` to `versions/X.Y.Z-editors.md`
-   - delete `src/schemas` 
+   - delete `src/schemas`
    - delete `tests/schema`
    - bash script `scripts/adjust-release-branch.sh` performs these steps
 5. Merge `vX.Y.Z-rel` into `main` via PR
@@ -339,7 +339,7 @@ For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and e
 
 ### Branch roles
 
-* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed.  The `src` tree is ***not*** present on `main`.
+* `main` is used to publish finished work and hold the authoritative versions of general documentation such as this document, which can be merged out to other branches as needed.  The `src` tree is _**not**_ present on `main`.
 * `dev` is the primary branch for working with the `src` tree.  Development infrastructure that is not needed on `main` is maintained here, and can be merged out to other non-`main` branches as needed.
   Changes on `main` are automatically included in a pull request to `dev` (see the (section on [branch sync](#branch-sync-automation)).
 * `vX.Y-dev` is the minor release line development branch for X.Y, including both the initial X.Y.0 minor version and all subsequent X.Y.Z patch versions.  All PRs are made to oldest active `vX.Y-dev` branch to which the change is relevant, and then merged forward as shown in the diagram further down in this document.
@@ -350,17 +350,17 @@ For information on the branch and release strategy for OAS 3.0.4 and 3.1.1 and e
 Upon release:
 
 * Pre-release steps:
-    * The most recent _published_ patch release from the previous line is merged up to `vX.Y-dev`, if relevant
-    * If doing simultaneous releases on multiple lines, do them from the oldest to newest line
-    * For example, if releasing 3.1.3 and 3.2.0:
-        * release 3.1.3 first
-        * release 3.2.0 second
+  * The most recent _published_ patch release from the previous line is merged up to `vX.Y-dev`, if relevant
+  * If doing simultaneous releases on multiple lines, do them from the oldest to newest line
+  * For example, if releasing 3.1.3 and 3.2.0:
+    * release 3.1.3 first
+    * release 3.2.0 second
 * Release branching and merging:
-    * branch `vX.Y.Z-rel` from `vX.Y-dev` (same commit that was merged to `dev` if relevant)
-    * After renaming `src/oas.md` to `versions/X.Y.Z.md` and [other adjustments](#specification-versions), merge `vX.Y.Z-rel` to `main`
+  * branch `vX.Y.Z-rel` from `vX.Y-dev` (same commit that was merged to `dev` if relevant)
+  * After renaming `src/oas.md` to `versions/X.Y.Z.md` and [other adjustments](#specification-versions), merge `vX.Y.Z-rel` to `main`
 * Publishing to the [spec site](https://spec.openapis.org) is triggered by the merge to `main`
 * Post-release steps:
-    * If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `vX.Y-dev`
+  * If this was a major or minor release (Z == 0), branch `vX.Y+1-dev` from `vX.Y-dev`
 
 _Release lines are grouped by color, although the colors of `dev` and `main` are not significant as these diagrams are limited to only 8 colors._
 

EDITORS.md

@@ -1,6 +1,7 @@
 # OpenAPI Specification Editors
 
 ## Active
+
 * Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
 * Henry Andrews [@handrews](https://github.com/handrews)
 * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
@@ -12,6 +13,7 @@
 * Ron Ratovsky [@webron](https://github.com/webron)
 
 ## Emeritus
+
 * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
 * Uri Sarid [@usarid](https://github.com/usarid)
 * Jason Harmon [@jharmn](https://github.com/jharmn)

GOVERNANCE.md

@@ -2,31 +2,36 @@
 
 The OpenAPI Specification is a project of the OpenAPI Initiative (OAI), under the auspices of the Linux Foundation. For governance of the OAI, review the [OAI's charter](https://www.openapis.org/participate/how-to-contribute/governance).
 
-# Processes and procedures of the Technical Steering Committee (TSC)
+## Processes and procedures of the Technical Steering Committee (TSC)
 
 The TSC is a self-organizing sub-group of the OAI. Herein are its principles and guidelines.
 
-## 1. The establishment of roles and the responsibilities for each role
+### 1. The establishment of roles and the responsibilities for each role
 
 Roles:
 
 * [Liaison](https://www.merriam-webster.com/dictionary/liaison) — Elected by TSC members in a plurality vote (oral count). Liaison represents the TSC to the OAI's Business Governing Board (BGB) at board meetings (though this itself does not confer voting rights) and is the public facing mouthpiece of the TSC.
 
-* [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible for approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members. 
+* [Maintainer](https://www.merriam-webster.com/dictionary/maintainer) — all and only members of the TSC are maintainers, and are responsible for approving proposed changes to the specification. If membership drops below 3, work is suspended until the BGB can re-establish the minimum. To maintain agility, the TSC should be capped at a maximum 9 members, though that number can be reconsidered by the TSC in the future. Past members will be noted as emeritus status once they are no longer members.
 
 * [Community Manager](https://en.wikipedia.org/wiki/Online_community_manager) — responsible for onboarding of new contributors, dealing with antisocial behaviour before it becomes a code of conduct violation, and managing the issue triage team.
 
 * [Rick](https://www.youtube.com/watch?v=dQw4w9WgXcQ) — Responsible for not giving up or letting down. Requires plurality vote of TSC members.
 
-## 2. Adding members to the TSC
+### 2. Adding members to the TSC
 
-A call-for-nominations period may be agreed upon by the TSC voting members and announced in a timely manner on a weekly TDC call (and documented on the agenda issue), assuming the TSC membership is not already at its maximum. A candidate may be nominated through a motion by a voting TSC member in a closed TSC meeting. A nominee must not receive opposition votes of more than 25% of the TSC voting membership via a confidential vote held electronically within a week following the nomination meeting. Approved nominees become provisional members and are expected to comport themselves as full members of the TSC during the provisional period of 6 months. The provisional period is concluded by a second, confidential vote similar to the nomination period's vote, after which newly confirmed members gain their voting rights. At most there are four voting periods per year (no more than one every three months), with a minimum of one per year.
+A call-for-nominations period may be agreed upon by the TSC voting members and announced in a timely manner on a weekly TDC call (and documented on the agenda issue), assuming the TSC membership is not already at its maximum.
+A candidate may be nominated through a motion by a voting TSC member in a closed TSC meeting.
+A nominee must not receive opposition votes of more than 25% of the TSC voting membership via a confidential vote held electronically within a week following the nomination meeting.
+Approved nominees become provisional members and are expected to comport themselves as full members of the TSC during the provisional period of 6 months.
+The provisional period is concluded by a second, confidential vote similar to the nomination period's vote, after which newly confirmed members gain their voting rights.
+At most there are four voting periods per year (no more than one every three months), with a minimum of one per year.
 
-## 3. Removal of membership from the TSC
+### 3. Removal of membership from the TSC
 
 Occasionally it may be necessary to remove a TSC member, such as behavior that violates the code of conduct or prolonged absenteeism. A 66% vote (confidential, electronic) of the other TSC members is required to remove a member. Otherwise, TSC members are removed when they renounce their position by informing the TSC of their effective resignation date via email.
 
-## 4. Criteria for decisions
+### 4. Criteria for decisions
 
 The group will strive to achieve all decisions via unopposed consensus. When not possible, unresolved conflicts will be raised to the OAI's Technical Oversight Board (TOB).
 

IMPLEMENTATIONS.md

@@ -1,9 +1,9 @@
-### Implementations
+# Implementations
 
 The list of implementations formerly in this file is no-longer maintained here.
 
-You may find a more comprehensive list at https://tools.openapis.org
+You may find a more comprehensive list at <https://tools.openapis.org>
 
-Instructions on listing your projects are contained in https://github.com/OAI/Tooling#how-can-you-help
+Instructions on listing your projects are contained in <https://github.com/OAI/Tooling#how-can-you-help>
 
 These tools are not endorsed by the OAI.

MAINTAINERS.md

@@ -1,6 +1,7 @@
 # OpenAPI Initiative Technical Steering Committee Members
 
 ## Active
+
 * Darrel Miller [@darrelmiller](https://github.com/darrelmiller)
 * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
 * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh)
@@ -11,6 +12,7 @@
 * Ralf Handl [@ralfhandl](https://github.com/ralfhandl)
 
 ## Emeritus
+
 * Mike Ralphson [@MikeRalphson](https://github.com/MikeRalphson)
 * Uri Sarid [@usarid](https://github.com/usarid)
 * Jason Harmon [@jharmn](https://github.com/jharmn)

README.md

@@ -2,7 +2,7 @@
 
 ![Build Status](https://github.com/OAI/OpenAPI-Specification/workflows/validate-markdown/badge.svg) [![Issue triagers](https://www.codetriage.com/oai/openapi-specification/badges/users.svg)](https://www.codetriage.com/oai/openapi-specification)
 
-![](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200)
+![OpenAPI logo](https://avatars3.githubusercontent.com/u/16343502?v=3&s=200)
 
 
 The OpenAPI Specification is a community-driven open specification within the [OpenAPI Initiative](https://www.openapis.org/), a Linux Foundation Collaborative Project.
@@ -30,7 +30,7 @@ Looking to see how you can create your own OpenAPI definition, present it, or ot
 
 ## Participation
 
-The current process for developing the OpenAPI Specification is described in 
+The current process for developing the OpenAPI Specification is described in
 the [Contributing Guidelines](CONTRIBUTING.md).
 
 Developing the next version of the OpenAPI Specification is guided by the [Technical Steering Committee (TSC)](https://www.openapis.org/participate/how-to-contribute/governance#TDC). This group of committers bring their API expertise, incorporate feedback from the community, and expand the group of committers as appropriate. All development activity on the future specification will be performed as features and merged into this branch. Upon release of the future specification, this branch will be merged to `main`.

SECURITY_CONSIDERATIONS.md

@@ -3,6 +3,7 @@
 ## OpenAPI Document Formats
 
 OpenAPI documents use JSON, YAML, and JSON Schema, and therefore share their security considerations:
+
 - [JSON](https://www.iana.org/assignments/media-types/application/json)
 - [YAML](https://www.iana.org/assignments/media-types/application/yaml)
 - [JSON Schema Core](https://json-schema.org/draft/2020-12/json-schema-core#section-13)
@@ -22,4 +23,4 @@ OpenAPI documents may contain references to external resources that may be deref
 
 ## Markdown and HTML Sanitization
 
-Certain properties allow the use of Markdown which can contain HTML including script. It is the responsibility of tooling to appropriately sanitize the Markdown.
+Certain properties allow the use of Markdown which can contain HTML including script. It is the responsibility of tooling to appropriately sanitize the Markdown.

TOB.md

@@ -1,14 +1,16 @@
 # Technical Oversight Board ("TOB")
 
-## Description: 
+## Description
+>
 > The TOB is responsible for managing conflicts, violations of procedures or guidelines or other issues that cannot be resolved in the TSC for the OAS. For further details please consult the OpenAPI Project Charter.
 
 ## TSC Elected - terms through May 2023
+
 Isabelle Mauny @isamauny
 
 Uri Sarid @usarid
 
-Marsh Gardiner @earth2marsh 
+Marsh Gardiner @earth2marsh
 
 Ron Ratovsky @webron
 

spec.markdownlint.yaml

@@ -0,0 +1,28 @@
+# Heading style (ATX is leading # symbols)
+MD003:
+  style: atx
+
+# Unordered list symbol must be *
+MD004:
+  style: asterisk
+
+# Unordered list indentation size
+MD007:
+    indent: 2
+
+# Allow additional blank lines
+MD012: false
+
+# Maximum line length
+MD013:
+    line_length: 800
+    tables: false
+
+# Headings need blank lines before and after
+MD022: true
+
+# Duplicate headings are allowed
+MD024: false
+
+# Allow inline HTML
+MD033: false

style-guide.md

@@ -1,8 +1,8 @@
-## Style Guide
+# Style Guide
 
 Contributions to this repository should follow the style guide as described in this section.
 
-### Markdown
+## Markdown
 
 Markdown files in this project should follow the style enforced by the [markdownlint tool](https://www.npmjs.com/package/markdownlint),
 as configured by the `.markdownlint.yaml` file in the root of the project.
@@ -35,14 +35,14 @@ Plus some suggestions, rather than rules:
   A blank line is needed to cause a paragraph break in Markdown.
 * In examples, use realistic values rather than foo/bar.
 
-### Use of "keyword", "field", "property", and "attribute"
+## Use of "keyword", "field", "property", and "attribute"
 
 * JSON Schema keywords -> "keyword"
 * OpenAPI fixed fields -> "field"
 * property of a "plain" JSON object that is not an OpenAPI-defined Foo Object -> "property"
 * "attribute" is only used in the XML context and means "XML attribute"
 
-### Field Names and Values in YAML comments
+## Field Names and Values in YAML comments
 
 Field names and keywords should be in backticks.
 Values like "Dog" should be double quoted.