Fix spec markdown lint errors

jdesrosiers · jdesrosiers · commit 005b8127dec1 · 2024-10-16T14:59:00.000-07:00
diff --git a/build/build.js b/build/build.js
@@ -11,6 +11,7 @@ import remarkGfm from "remark-gfm";
 import remarkHeadingId from "remark-heading-id";
 import remarkHeadings from "./remark-headings.js";
 import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide";
+import remarkLintMaximumHeadingLength from "remark-lint-maximum-heading-length";
 import remarkRehype from "remark-rehype";
 import remarkReferenceLinks from "./remark-reference-links.js";
 import remarkTableOfContents from "./remark-table-of-contents.js";
@@ -25,6 +26,7 @@ const build = async (filename) => {
   const md = readFileSync(filename, "utf-8");
   const file = await remark()
     .use(remarkPresetLintMarkdownStyleGuide)
+    .use(remarkLintMaximumHeadingLength, false)
     .use(remarkGfm)
     .use(remarkHeadingId)
     .use(remarkHeadings, {
diff --git a/proposals/propertyDependencies-adr.md b/proposals/propertyDependencies-adr.md
@@ -1,14 +1,16 @@
 # Add New Keyword: `propertyDependencies`
 
-* Status: proposed
-* Deciders: @gregsdennis, @jdesrosiers, @relequestual
-* Date: 2022-04-07
+- Status: proposed
+- Deciders: @gregsdennis, @jdesrosiers, @relequestual
+- Date: 2022-04-07
 
 Technical Story:
 
-- Issue discussing feature - https://github.com/json-schema-org/json-schema-spec/issues/1082
-- PR to add to the spec - https://github.com/json-schema-org/json-schema-spec/pull/1143
-- ADR to extract from the spec and use feature life cycle - https://github.com/json-schema-org/json-schema-spec/pull/1505
+- Issue discussing feature - <https://github.com/json-schema-org/json-schema-spec/issues/1082>
+- PR to add to the spec - <https://github.com/json-schema-org/json-schema-spec/pull/1143>
+- ADR to extract from the spec and use feature life cycle - <https://github.com/json-schema-org/json-schema-spec/pull/1505>
+
+## Table of Contents
 
 ## Context and Problem Statement
 
@@ -33,7 +35,8 @@ adopt or redefine `discriminator`.
 
 ## Considered Options
 
-All of the following options have the same validation result as the following schema.
+All of the following options have the same validation result as the following
+schema.
 
 ```json
 {
@@ -64,10 +67,10 @@ that concept to solve this problem.
 }
 ```
 
-* Good, because it handle the most common use case: string property values
-* Good, because all property values are grouped together
-* Good, because it's less verbose
-* Bad, because it doesn't handle non-string property values
+- Good, because it handle the most common use case: string property values
+- Good, because all property values are grouped together
+- Good, because it's less verbose
+- Bad, because it doesn't handle non-string property values
 
 ### Option 2
 
@@ -97,7 +100,9 @@ prone.
 * Good, because it supports all use cases
 * Bad, because properties are not naturally grouped together
 * Bad, because it's quite verbose
-* Bad, because we have no precedent for a keyword which explicitly defines its own properties.  This would be new operational functionality, which we try to avoid if we can.
+* Bad, because we have no precedent for a keyword which explicitly defines its
+  own properties. This would be new operational functionality, which we try to
+  avoid if we can.
 
 ### Option 3
 
@@ -124,7 +129,9 @@ object. It's still too verbose.
 * Good, because it supports all use cases
 * Good, because all property values are grouped together
 * Bad, because it's quite verbose
-* Bad, because we have no precedent for a keyword which explicitly defines its own properties.  This would be new operational functionality, which we try to avoid if we can.
+* Bad, because we have no precedent for a keyword which explicitly defines its
+  own properties. This would be new operational functionality, which we try to
+  avoid if we can.
 
 ### Option 4
 
@@ -148,10 +155,11 @@ naming aside), but otherwise has all the same problems as the other examples.
 }
 ```
 
-* Good, because it supports all use cases
-* Bad, because properties are not naturally grouped together
-* Bad, because it's very verbose
-* Bad, because it introduces a lot of inter-keyword dependencies, which we'd have to exhaustively define
+- Good, because it supports all use cases
+- Bad, because properties are not naturally grouped together
+- Bad, because it's very verbose
+- Bad, because it introduces a lot of inter-keyword dependencies, which we'd
+  have to exhaustively define
 
 ### Option 5
 
@@ -183,7 +191,8 @@ verbose.
 * Good, because it's a familiar syntax
 * Bad, because properties are not naturally grouped together
 * Bad, because it's very verbose
-* Bad, because `ifProperties` is very niche.  Will this spawn a new series of `if*` keywords?  How would it interact with `if`?
+* Bad, because `ifProperties` is very niche.  Will this spawn a new series of
+  `if*` keywords?  How would it interact with `if`?
 
 ### Option 6
 
diff --git a/proposals/propertyDependencies.md b/proposals/propertyDependencies.md
@@ -91,23 +91,27 @@ those goals means that some trade-offs need to be made.
 The `propertyDependencies` keyword will be added to the `https://json-schema.org/vocab/applicator` [applicator
 vocabulary](../jsonschema-core.html#applicatorvocab).
 
-1. The following will be added to the JSON Schema Core specification as a
+1.  The following will be added to the JSON Schema Core specification as a
 subsection of "Keywords for Applying Subschemas Conditionally".
     > ### `propertyDependencies`
     >
     > This keyword specifies subschemas that are evaluated if the instance is an
     > object and contains a certain property with a certain string value.
     >
-    > This keyword's value MUST be an object. Each value in the object MUST be an
-    > object whose values MUST be valid JSON Schemas.
+    > This keyword's value MUST be an object. Each value in the object MUST be
+    > an object whose values MUST be valid JSON Schemas.
     >
-    > If the outer object key is a property in the instance and the inner object key
-    > is equal to the value of that property, the entire instance must validate
-    > against the schema. Its use is dependent on the presence and value of the
-    > property.
+    > If the outer object key is a property in the instance and the inner object
+    > key is equal to the value of that property, the entire instance must
+    > validate against the schema. Its use is dependent on the presence and
+    > value of the property.
     >
     > Omitting this keyword has the same behavior as an empty object.
-2. The following subschema will be added to the Applicator Vocabulary schema, `https://json-schema.org/<version>/<release>/meta/applicator` at `/properties/propertyDependencies`:
+
+2.  The following subschema will be added to the Applicator Vocabulary schema,
+   `https://json-schema.org/<version>/<release>/meta/applicator` at
+   `/properties/propertyDependencies`:
+
     ```json
     {
       "type": "object",
@@ -124,9 +128,9 @@ subsection of "Keywords for Applying Subschemas Conditionally".
 
 ## [Appendix] Change Log
 
-* [March 2021] - Initially proposed
-* [October 2021] Added to specification document
-* [May 2024] Extracted from specification document as experimental feature
+- [March 2021] - Initially proposed
+- [October 2021] Added to specification document
+- [May 2024] Extracted from specification document as experimental feature
 
 ## Champions
 
diff --git a/proposals/vocabularies-adr.md b/proposals/vocabularies-adr.md
@@ -1,13 +1,15 @@
-# [short title of solved problem and solution]
+# Rational for the Vocabulary System proposal
 
-* Status: proposed
-* Deciders: @gregsdennis, @jdesrosiers
-* Date: 2024-06-10
+- Status: proposed
+- Deciders: @gregsdennis, @jdesrosiers
+- Date: 2024-06-10
 
 Technical Story:
 
-- Issues discussing feature - https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aopen+is%3Aissue+label%3Avocabulary
-- ADR to extract from the spec and use feature life cycle - https://github.com/json-schema-org/json-schema-spec/pull/1510
+- Issues discussing feature - <https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aopen+is%3Aissue+label%3Avocabulary>
+- ADR to extract from the spec and use feature life cycle - <https://github.com/json-schema-org/json-schema-spec/pull/1510>
+
+## Table of Contents
 
 ## Context and Problem Statement
 
@@ -27,9 +29,9 @@ and a new Core keyword, `$vocabulary` to support it.
 
 ### Current design as included in 2019-09 and 2020-12.
 
-A vocabulary is a collection of keywords and is defined by a vocabulary document.
-For the 2019-09 and 2020-12 vocabularies, the documents are integrated into the
-specifications themselves.
+A vocabulary is a collection of keywords and is defined by a vocabulary
+document. For the 2019-09 and 2020-12 vocabularies, the documents are integrated
+into the specifications themselves.
 
 With vocabularies as the primary method for defining individual keywords,
 dialects can be created by combining different vocabularies.
@@ -42,37 +44,37 @@ identify each vocab, and the values indicate whether the implementation must
 "understand" that vocab in order to process the schema. This keyword is only
 processed when it is found as part of a meta-schema.
 
-* Good because it provides a language-agnostic method of defining extension
+- Good because it provides a language-agnostic method of defining extension
   keywords that's built into JSON Schema itself
-* Bad because unknown keywords are now unsupported, which implies that
+- Bad because unknown keywords are now unsupported, which implies that
   [unknown vocabularies are implicitly unsupported](https://github.com/orgs/json-schema-org/discussions/342)
 
 ### [option 2]
 
 [example | description | pointer to more information | …]
 
-* Good, because [argument a]
-* Good, because [argument b]
-* Bad, because [argument c]
-* … <!-- numbers of pros and cons can vary -->
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- ... <!-- numbers of pros and cons can vary -->
 
 ### [option 3]
 
 [example | description | pointer to more information | …]
 
-* Good, because [argument a]
-* Good, because [argument b]
-* Bad, because [argument c]
-* … <!-- numbers of pros and cons can vary -->
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- ... <!-- numbers of pros and cons can vary -->
 
 ## Decision Outcome
 
-_TBD_
+*TBD*
 
 ### Positive Consequences <!-- optional -->
 
-_TBD_
+*TBD*
 
 ### Negative Consequences <!-- optional -->
 
-_TBD_
+*TBD*
diff --git a/proposals/vocabularies.md b/proposals/vocabularies.md
@@ -252,14 +252,17 @@ For example
     ```
 -->
 
-_**NOTE** Since the design of vocabularies will be changing anyway, it's not worth the time and effort to fill in this section just yet.  As such, please read the above sections for loose requirements.  For tighter requirements, please assume conformance with the 2020-12 Core and Validation specifications._
+***NOTE** Since the design of vocabularies will be changing anyway, it's not
+worth the time and effort to fill in this section just yet.  As such, please
+read the above sections for loose requirements.  For tighter requirements,
+please assume conformance with the 2020-12 Core and Validation specifications.*
 
 ## [Appendix] Change Log
 
 * 2024-06-10 - Created
 
 ## [Appendix] Champions
 
-| Champion                   | Company | Email                   | URI                              |
-|----------------------------|---------|-------------------------|----------------------------------|
-| Greg Dennis                |         | gregsdennis@yahoo.com   | https://github.com/gregsennis    |
+| Champion    | Company | Email                          | URI                             |
+|-------------|---------|--------------------------------|---------------------------------|
+| Greg Dennis |         | <mailto:gregsdennis@yahoo.com> | <https://github.com/gregsennis> |
