Spec markdoen build refactor

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
           cache: npm
       - run: npm ci
       - run: npm run lint
-      - run: npm run build-all
+      - run: npm run build -- specs
 
   specs-ietf:
     runs-on: ubuntu-latest

.remarkrc-lint.js

@@ -0,0 +1,20 @@
+import remarkValidateLinks from "remark-validate-links";
+import remarkPresetLintConsistent from "remark-preset-lint-consistent";
+import remarkPresetLintRecommended from "remark-preset-lint-recommended";
+import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide";
+import remarkLintListItemIndent from "remark-lint-list-item-indent";
+import remarkLintListItemSpacing from "remark-lint-list-item-spacing";
+import remarkLintNoFileNameMixedCase from "remark-lint-no-file-name-mixed-case";
+
+
+export default {
+  plugins: [
+    remarkValidateLinks,
+    remarkPresetLintConsistent,
+    remarkPresetLintRecommended,
+    remarkPresetLintMarkdownStyleGuide,
+    [remarkLintListItemIndent, "one"],
+    [remarkLintListItemSpacing, { checkBlanks: true }],
+    [remarkLintNoFileNameMixedCase, false]
+  ]
+};

Makefile

@@ -6,13 +6,13 @@ OUT = \
 
 all: $(VENV) $(OUT)
 
-%.txt: %.xml
+%.txt: specs/%.xml
 	$(XML2RFC) --text $< -o $@
 
-%.pdf: %.xml
+%.pdf: specs/%.xml
 	$(XML2RFC) --pdf $< -o $@
 
-%.html: %.xml
+%.html: specs/%.xml
 	$(XML2RFC) --html $< -o $@
 
 json-schema.tar.gz: $(OUT)

README.md

@@ -25,15 +25,17 @@ Labels are assigned based on [Sensible Github Labels](https://github.com/Releque
 ## Authoring and Building
 
 ### Specification
-To build the spec files to HTML from the Markdown sources, run `npm run
-build-all`.
-You can also build each individually with `npm run build -- filename.md`
-(Example: `npm run build -- jsonschema-core.md`). You can also use wildcards to
-build multiple specs at the same time: `npm run build -- jsonschema-*.md`. The
-HTML files will be available in the `web` folder.
+To build all the spec files to HTML from the Markdown sources, run `npm run
+build -- specs`. You can also build each individually with `npm run build --
+specs/filename.md` (Example: `npm run build -- specs/jsonschema-core.md`). You
+can also use wildcards to build multiple specs at the same time: `npm run build
+-- specs/jsonschema-*.md`. The HTML files will be available in the `web` folder.
 
 The spec is built using [Remark](https://remark.js.org/), a markdown engine with
-good support for plugins and lots of existing plugins we can use.
+good support for plugins and lots of existing plugins we can use. Remark also
+has a [language server](https://github.com/remarkjs/remark-language-server) and
+a [VSCode extension](https://github.com/remarkjs/vscode-remark) we can use to
+get linting an link checking while developing the spec.
 
 #### Plugins
 The following is a not-necessarily-complete list of configured plugins and the
@@ -52,7 +54,7 @@ features they make available to you.
 - [remark-headings](/json-schema-org/json-schema-spec/blob/main/remark-headings.js)
   -- A collection of enhancements for headings.
   - Adds hierarchical section numbers to headings.
-    - Use the `[Appendix]` prefix on headings that should be numbered as an
+    - Use the `%appendix%` prefix on headings that should be numbered as an
       appendix.
   - Adds id anchors to headers that don't have one
     - Example: `#section-2-13`

eslint.config.js

@@ -3,6 +3,7 @@ import globals from "globals";
 import stylistic from "@stylistic/eslint-plugin";
 import importPlugin from "eslint-plugin-import";
 
+
 export default [
   js.configs.recommended,
   importPlugin.flatConfigs.recommended,
@@ -34,7 +35,7 @@ export default [
 
       // Imports
       "import/extensions": ["error", "ignorePackages"],
-      "import/newline-after-import": ["error", { count: 2, exactCount: false, considerComments: true }], // Doesn't respect @import
+      "import/newline-after-import": ["error", { count: 2, exactCount: false, considerComments: true }],
 
       // Stylistic
       "@stylistic/yield-star-spacing": ["error", "after"],