Auto number appendices and other cleanup

Author: jdesrosiers

README.md

@@ -38,6 +38,8 @@ features they make available to you.
 
 - [remark-lint](https://github.com/remarkjs/remark-lint) -- Enforce markdown
   styles guide.
+- [remark-validate-links](https://github.com/remarkjs/remark-validate-links) --
+  Check for broken links.
 - [remark-gfm](https://github.com/remarkjs/remark-gfm) -- Adds support for
   Github Flavored Markdown specific markdown features such as autolink literals,
   footnotes, strikethrough, tables, and tasklists.

build/build.js

@@ -1,18 +1,18 @@
-/* eslint-disable no-console */
 import dotenv from "dotenv";
 import { readFileSync, writeFileSync } from "node:fs";
 import { reporter } from "vfile-reporter";
 import { remark } from "remark";
-import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide";
-import remarkGfm from "remark-gfm";
-import remarkToc from "remark-toc";
-import torchLight from "remark-torchlight";
-import remarkRehype from "remark-rehype";
-import rehypeSlug from "rehype-slug";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeSlug from "rehype-slug";
 import rehypeStringify from "rehype-stringify";
-import remarkNumberHeadings from "./remark-number-headings.js";
 import remarkFlexibleContainers from "remark-flexible-containers";
+import remarkGfm from "remark-gfm";
+import remarkNumberHeadings from "./remark-number-headings.js";
+import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide";
+import remarkRehype from "remark-rehype";
+import remarkToc from "remark-toc";
+import remarkValidateLinks from "remark-validate-links";
+import torchLight from "remark-torchlight";
 
 
 dotenv.config();
@@ -22,10 +22,20 @@ dotenv.config();
   const html = await remark()
     .use(remarkPresetLintMarkdownStyleGuide)
     .use(remarkGfm)
-    .use(remarkNumberHeadings, { startDepth: 2, skip: ["Abstract", "Note to Readers", "Table of Contents"] })
-    .use(remarkToc, { tight: true, heading: "Table of Contents" })
     .use(torchLight)
     .use(remarkFlexibleContainers)
+    .use(remarkNumberHeadings, {
+      startDepth: 2,
+      skip: ["Abstract", "Note to Readers", "Table of Contents", "Authors' Addresses", "\\[.*\\]", "draft-.*"],
+      appendixToken: "[Appendix]",
+      appendixPrefix: "Appendix"
+    })
+    .use(remarkToc, {
+      tight: true,
+      heading: "Table of Contents",
+      skip: "\\[.*\\]|draft-.*"
+    })
+    .use(remarkValidateLinks)
     .use(remarkRehype)
     .use(rehypeSlug)
     .use(rehypeAutolinkHeadings, { behavior: "wrap" })

build/remark-number-headings.js

@@ -8,6 +8,7 @@ const defaultOptions = {
 
 const remarkNumberHeadings = (options) => (tree) => {
   options = { ...defaultOptions, ...options };
+  options.skip = new RegExp(`^(${options.skip.join("|")})$`, "u");
 
   let sectionNumbers = [];
 
@@ -17,17 +18,28 @@ const remarkNumberHeadings = (options) => (tree) => {
     }
 
     visit(node, "text", (textNode) => {
-      const text = textNode.value ? textNode.value.trim() : "";
+      let text = textNode.value ? textNode.value.trim() : "";
 
-      if (options.skip.includes(text)) {
+      if (options.skip.test(text)) {
         return;
       }
 
-      sectionNumbers[node.depth] = (sectionNumbers[node.depth] ?? 0) + 1;
-      sectionNumbers = sectionNumbers.slice(0, node.depth + 1);
-
-      const sectionNumber = sectionNumbers.slice(options.startDepth, node.depth + 1).join(".");
-      textNode.value = `${sectionNumber}. ${text}`;
+      if (text.startsWith(options.appendixToken)) {
+        const currentIndex = typeof sectionNumbers[node.depth] === "string"
+          ? sectionNumbers[node.depth]
+          : "@";
+        sectionNumbers[node.depth] = String.fromCharCode(currentIndex.charCodeAt(0) + 1);
+        sectionNumbers = sectionNumbers.slice(0, node.depth + 1);
+
+        const sectionNumber = sectionNumbers.slice(options.startDepth, node.depth + 1).join(".");
+        textNode.value = `${options.appendixPrefix} ${sectionNumber}. ${text.slice(options.appendixToken.length + 1)}`;
+      } else {
+        sectionNumbers[node.depth] = (sectionNumbers[node.depth] ?? 0) + 1;
+        sectionNumbers = sectionNumbers.slice(0, node.depth + 1);
+
+        const sectionNumber = sectionNumbers.slice(options.startDepth, node.depth + 1).join(".");
+        textNode.value = `${sectionNumber}. ${text}`;
+      }
     });
   });
 };

jsonschema-core.md

@@ -2768,7 +2768,7 @@ Bray, T., Ed., Hollander, D., Ed., Layman, A., Ed., and R. Tobin, Ed.,
 "Namespaces in XML 1.1 (Second Edition)", August 2006,
 <<http://www.w3.org/TR/2006/REC-xml-names11-20060816>>.
 
-## Appendix A. Schema identification examples
+## [Appendix] Schema identification examples
 Consider the following schema, which shows `$id` being used to identify both the
 root schema and various subschemas, and `$anchor` being used to define plain
 name fragment identifiers.
@@ -2841,12 +2841,12 @@ embedded schema
 resources](#921-json-pointer-fragments-and-embedded-schema-resources) section
 for futher comments.
 
-## Appendix B. Manipulating schema documents and references
+## [Appendix] Manipulating schema documents and references
 Various tools have been created to rearrange schema documents based on how and
 where references (`$ref`) appear. This appendix discusses which use cases and
 actions are compliant with this specification.
 
-### B.1. Bundling schema resources into a single document
+### Bundling schema resources into a single document
 A set of schema resources intended for use together can be organized with each
 in its own schema document, all in the same schema document, or any granularity
 of document grouping in between.
@@ -2868,7 +2868,7 @@ changing any aspect of validation or annotation results. The names of the
 schemas under `$defs` do not affect behavior, assuming they are each unique, as
 they do not appear in the canonical IRIs for the embedded resources.
 
-### B.2. Reference removal is not always safe
+### Reference removal is not always safe
 Attempting to remove all references and produce a single schema document does
 not, in all cases, produce a schema with identical behavior to the original
 form.
@@ -2880,7 +2880,7 @@ scope of this specification to determine or provide a set of safe `$ref` removal
 transformations, as they depend not only on the schema structure but also on the
 intended usage.
 
-## Appendix C. Example of recursive schema extension
+## [Appendix] Example of recursive schema extension
 Consider the following two schemas describing a simple recursive tree structure,
 where each node in the tree can have a "data" field of any type. The first
 schema allows and ignores other instance properties. The second is more strict
@@ -2976,9 +2976,9 @@ of the node schema objects were moved under `$defs`. It is the matching
 `$dynamicAnchor` values which tell us how to resolve the dynamic reference, not
 any sort of correlation in JSON structure.
 
-## Appendix D. Working with vocabularies
+## [Appendix] Working with vocabularies
 
-### D.1. Best practices for vocabulary and meta-schema authors
+### Best practices for vocabulary and meta-schema authors
 Vocabulary authors should take care to avoid keyword name collisions if the
 vocabulary is intended for broad use, and potentially combined with other
 vocabularies. JSON Schema does not provide any formal namespacing system, but
@@ -3026,7 +3026,7 @@ resulting behavior is undefined.
 Meta-schemas intended for local use, with no need to test for vocabulary support
 in arbitrary implementations, can safely omit `$vocabulary` entirely.
 
-### D.2. Example meta-schema with vocabulary declarations
+### Example meta-schema with vocabulary declarations
 This meta-schema explicitly declares both the Core and Applicator vocabularies,
 together with an extension vocabulary, and combines their meta-schemas with an
 `allOf`. The extension vocabulary's meta-schema, which describes only the
@@ -3118,7 +3118,7 @@ to ensure that it is validated even when `format` functions purely as an
 annotation, as explained in the [Validation
 specification](#json-schema-validation).
 
-## Appendix E. References and generative use cases
+## [Appendix] References and generative use cases
 While the presence of references is expected to be transparent to validation
 results, generative use cases such as code generators and UI renderers often
 consider references to be semantically significant.
@@ -3167,7 +3167,7 @@ instance of a distinct class.
 This style of usage requires the annotation to be in the same object as the
 reference, which must be recognizable as a reference.
 
-## Appendix F. Acknowledgments
+## [Appendix] Acknowledgments
 Thanks to Gary Court, Francis Galiegue, Kris Zyp, Geraint Luff, and Henry
 Andrews for their work on the initial drafts of JSON Schema.
 
@@ -3176,16 +3176,16 @@ Bowman, Gowry Sankar, Donald Pipowitch, Dave Finlay, Denis Laxalde, Phil
 Sturgeon, Shawn Silverman, and Karen Etheridge for their submissions and patches
 to the document.
 
-## Appendix G. Change Log[^19]
+## [Appendix] Change Log[^19]
 [^19]: This section to be removed before leaving Internet-Draft status.
 
-### G.1. draft-bhutton-json-schema-next
+### draft-bhutton-json-schema-next
 - `contains` now applies to objects as well as arrays
 - Use IRIs instead of URIs
 - Remove bookending requirement for `$dynamicRef`
 - Add `propertyDependencies` keyword
 
-### G.2. draft-bhutton-json-schema-01
+### draft-bhutton-json-schema-01
 - Improve and clarify the `type`, `contains`, `unevaluatedProperties`, and
 `unevaluatedItems` keyword explanations
 - Clarify various aspects of "canonical URIs"
@@ -3194,7 +3194,7 @@ to the document.
 - Remove references to remaining media-type parameters
 - Fix multiple examples
 
-### G.3. draft-bhutton-json-schema-00
+### draft-bhutton-json-schema-00
 - `$schema` MAY change for embedded resources
 - Array-value `items` functionality is now `prefixItems`
 - `items` subsumes the old function of `additionalItems`
@@ -3211,7 +3211,7 @@ interactions now specified
 - Moved `unevaluatedItems` and `unevaluatedProperties` from core into their own
 vocabulary
 
-### G.4. draft-handrews-json-schema-02
+### draft-handrews-json-schema-02
 - Update to RFC 8259 for JSON specification
 - Moved `definitions` from the Validation specification here as `$defs`
 - Moved applicator keywords from the Validation specification as their own
@@ -3237,7 +3237,7 @@ meta-schemas
 - Clarified that the behavior of JSON Pointers across `$id` boundary is
 unreliable
 
-### G.5. draft-handrews-json-schema-01
+### draft-handrews-json-schema-01
 - This draft is purely a clarification with no functional changes
 - Emphasized annotations as a primary usage of JSON Schema
 - Clarified $id by use cases
@@ -3250,7 +3250,7 @@ schema identifiers during parsing
 same process
 - Minor formatting improvements
 
-### G.6. draft-handrews-json-schema-00
+### draft-handrews-json-schema-00
 - Make the concept of a schema keyword vocabulary more clear
 - Note that the concept of "integer" is from a vocabulary, not the data model
 - Classify keywords as assertions or annotations and describe their general
@@ -3262,7 +3262,7 @@ behavior
 - Add `application/schema-instance+json` media type
 - Recommend a "schema" link relation / parameter instead of "profile"
 
-### G.7. draft-wright-json-schema-01
+### draft-wright-json-schema-01
 - Updated intro
 - Allowed for any schema to be a boolean
 - `$schema` SHOULD NOT appear in subschemas, although that may change
@@ -3271,7 +3271,7 @@ behavior
 - Note applicability to formats such as CBOR that can be represented in the JSON
 data model
 
-### G.8. draft-wright-json-schema-00
+### draft-wright-json-schema-00
 - Updated references to JSON
 - Updated references to HTTP
 - Updated references to JSON Pointer
@@ -3286,7 +3286,7 @@ data model
 - Rewrote section on usage with rel="describedBy" and rel="profile"
 - Fixed numerous invalid examples
 
-### G.9. draft-zyp-json-schema-04
+### draft-zyp-json-schema-04
 - Salvaged from draft v3.
 - Split validation keywords into separate document.
 - Split hypermedia keywords into separate document.
@@ -3295,23 +3295,12 @@ data model
 - Define the role of `id`. Define URI resolution scope.
 - Add interoperability considerations.
 
-### G.10. draft-zyp-json-schema-00
+### draft-zyp-json-schema-00
 - Initial draft.
 
 ## Authors' Addresses
-
-### Austin Wright (*editor*)
-Email: <[email protected]>
-
-### Ben Hutton (*editor*)
-Postman
-
-Email: <[email protected]>
-
-URI: <https://jsonschema.dev>
-
-### Greg Dennis
-
-Email: <[email protected]>
-
-URI: <https://github.com/gregsdennis>
+| Author                   | Company | Email                   | URI                              |
+|--------------------------|---------|-------------------------|----------------------------------|
+| Austin Wright (*editor*) |         | <[email protected]>          |                                  |
+| Ben Hutton (*editor*)    | Postman | <[email protected]>    | <https://jsonschema.dev>         |
+| Greg Dennis              |         | <[email protected]> | <https://github.com/gregsdennis> |

jsonschema-validation.md

@@ -895,7 +895,7 @@ draft-bhutton-json-schema-01, June 2022,
 Hoehrmann, B., "Scripting Media Types", RFC 4329, DOI 10.17487/RFC4329, April
 2006, <<https://www.rfc-editor.org/info/rfc4329>>.
 
-## Appendix A. Keywords Moved from Validation to Core
+## [Appendix] Keywords Moved from Validation to Core
 Several keywords have been moved from this document into the [Core
 Specification](#json-schema) starting with draft 2019-09, in some cases with
 re-naming or other changes. This affects the following former validation
@@ -928,7 +928,7 @@ property. The property name array form is retained here and renamed to
 `dependentRequired`, as it is an assertion which is a shortcut for the
 conditional use of the `required` assertion keyword.
 
-## Appendix B. Acknowledgments
+## [Appendix] Acknowledgments
 Thanks to Gary Court, Francis Galiegue, Kris Zyp, Geraint Luff, and Henry
 Andrews for their work on the initial drafts of JSON Schema.
 
@@ -937,7 +937,7 @@ Bowman, Gowry Sankar, Donald Pipowitch, Dave Finlay, Denis Laxalde, Phil
 Sturgeon, Shawn Silverman, and Karen Etheridge for their submissions and patches
 to the document.
 
-## Appendix C. ChangeLog[^6]
+## [Appendix] ChangeLog[^6]
 [^6]: This section to be removed before leaving Internet-Draft status.
 
 - *draft-next*
@@ -1032,15 +1032,7 @@ schema form to the core spec
     - Add interoperability considerations.
 
 ## Authors' Addresses
-
-### Austin Wright (*editor*)
-
-Email: <[email protected]>
-
-### Ben Hutton (*editor*)
-
-Postman
-
-Email: <[email protected]>
-
-URI: <https://jsonschema.dev>
+| Author                   | Company | Email                | URI                      |
+|--------------------------|---------|----------------------|--------------------------|
+| Austin Wright (*editor*) |         | <[email protected]>       |                          |
+| Ben Hutton (*editor*)    | Postman | <[email protected]> | <https://jsonschema.dev> |

package.json

@@ -5,7 +5,6 @@
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "lint": "eslint *.js",
     "build": "npm run build-core && npm run build-validation",
     "build-core": "node build/build.js < jsonschema-core.md > jsonschema-core.html",
     "build-validation": "node build/build.js < jsonschema-validation.md > jsonschema-validation.html"
@@ -22,12 +21,10 @@
     "remark-rehype": "^10.1.0",
     "remark-toc": "^8.0.1",
     "remark-torchlight": "^0.0.5",
+    "remark-validate-links": "^12.1.1",
     "vfile-reporter": "^8.0.0"
   },
   "devDependencies": {
-    "dotenv": "^16.3.1",
-    "eslint": "*",
-    "eslint-import-resolver-node": "*",
-    "eslint-plugin-import": "*"
+    "dotenv": "^16.3.1"
   }
 }