Skip to content

Spec markdoen build refactor #1554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 20 additions & 0 deletions .remarkrc-lint.js
Original file line number Diff line number Diff line change
@@ -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]
]
};
6 changes: 3 additions & 3 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
18 changes: 10 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`
Expand Down
199 changes: 0 additions & 199 deletions build/build.js

This file was deleted.

3 changes: 2 additions & 1 deletion eslint.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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"],
Expand Down
Loading
Loading