Skip to content

Commit 10b7406

Browse files
jdesrosiersjdesrosiers
committed
Convert core/validation specs to non-IETF markdown
1 parent fb89a3b commit 10b7406

9 files changed

+4601
-5921
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,6 @@ relative-json-pointer.txt
77

88
# For the Python enviornment
99
.venv
10+
11+
package-lock.json
12+
node_modules/

‎README.md

Lines changed: 53 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -22,29 +22,59 @@ For the current status of issues and pull requests, please see the following lab
2222

2323
Labels are assigned based on [Sensible Github Labels](https://github.com/Relequestual/sensible-github-labels).
2424

25-
## Contents
26-
27-
* Makefile - scripts to build the Internet-Draft txt/html
28-
* _Internet-Draft sources_
29-
* jsonschema-core.xml - source for JSON Schema's "core" I-D
30-
* jsonschema-validation.xml - source for the validation vocabulary I-D
31-
* relative-json-pointer.xml - source for the Relative JSON Pointer I-D
32-
* _meta-schemas and recommended output formats_
33-
* schema.json - JSON Schema "core" and Validation meta-schema
34-
35-
The Makefile will create the necessary Python venv for you as part of the regular make target.
36-
37-
`make clean` will remove all output including the venv. To clean just the spec output and
38-
keep the venv, use `make spec-clean`.
39-
40-
If you want to run `xml2rfc` manually after running make for the first time, you will
41-
need to activate the virtual environment:
42-
43-
```sh
44-
source .venv/bin/activate
45-
```
46-
47-
The version of "xml2rfc" that this project uses is updated by modifying `requirements.in` and running `pip-compile requirements.in`.
25+
## Authoring and Building
26+
27+
### Specification
28+
To build the spec files to HTML from the Markdown sources, run `npm run build`.
29+
You can also build each individually with `npm run build-core` and `npm run
30+
build-validation`.
31+
32+
The spec is built using [Remark](https://remark.js.org/), a markdown engine with
33+
good support for plugins and lots of existing plugins we can use.
34+
35+
#### Plugins
36+
The following is a not-necessarily-complete list of configured plugins and the
37+
features they make available to you.
38+
39+
- [remark-lint](https://github.com/remarkjs/remark-lint) -- Enforce markdown
40+
styles guide.
41+
- [remark-gfm](https://github.com/remarkjs/remark-gfm) -- Adds support for
42+
Github Flavored Markdown specific markdown features such as autolink literals,
43+
footnotes, strikethrough, tables, and tasklists.
44+
- [remark-number-headings](/json-schema-org/json-schema-spec/blob/main/remark-number-headings.js)
45+
-- Adds hierarchical section numbers to headings.
46+
- [remark-toc](https://github.com/remarkjs/remark-toc) -- Adds a table of
47+
contents in a section with a header called "Table of Contents".
48+
- [remark-torchlight](https://github.com/torchlight-api/remark-torchlight) --
49+
Syntax highlighting and more using https://torchlight.dev. Features include
50+
line numbers and line highlighting.
51+
- [rehype-slug](https://github.com/rehypejs/rehype-slug) -- Adds `id` anchors to
52+
header so they can be linked to with URI fragment syntax.
53+
- [rehype-autolink-headings](https://github.com/rehypejs/rehype-autolink-headings)
54+
-- Makes headings clickable.
55+
- [remark-flexible-containers](https://github.com/ipikuka/remark-flexible-containers)
56+
-- Add a callout box using the following syntax. Supported container types are
57+
`warning`, `note`, and `experimental`.
58+
59+
```
60+
::: {type} {title}
61+
{content}
62+
:::
63+
```
64+
65+
### Internet-Drafts
66+
To build components that are being maintained as IETF Internet-Drafts, run
67+
`make`. The Makefile will create the necessary Python venv for you as part of
68+
the regular make target.
69+
70+
`make clean` will remove all output including the venv. To clean just the spec
71+
output and keep the venv, use `make spec-clean`.
72+
73+
If you want to run `xml2rfc` manually after running make for the first time, you
74+
will need to activate the virtual environment: `source .venv/bin/activate`.
75+
76+
The version of "xml2rfc" that this project uses is updated by modifying
77+
`requirements.in` and running `pip-compile requirements.in`.
4878
4979
Descriptions of the xml2rfc, I-D documents, and RFC processes:
5080

‎build/build.js

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
/* eslint-disable no-console */
2+
import dotenv from "dotenv";
3+
import { readFileSync, writeFileSync } from "node:fs";
4+
import { reporter } from "vfile-reporter";
5+
import { remark } from "remark";
6+
import remarkPresetLintMarkdownStyleGuide from "remark-preset-lint-markdown-style-guide";
7+
import remarkGfm from "remark-gfm";
8+
import remarkToc from "remark-toc";
9+
import torchLight from "remark-torchlight";
10+
import remarkRehype from "remark-rehype";
11+
import rehypeSlug from "rehype-slug";
12+
import rehypeAutolinkHeadings from "rehype-autolink-headings";
13+
import rehypeStringify from "rehype-stringify";
14+
import remarkNumberHeadings from "./remark-number-headings.js";
15+
import remarkFlexibleContainers from "remark-flexible-containers";
16+
17+
18+
dotenv.config();
19+
20+
(async function () {
21+
const md = readFileSync(0, "utf-8");
22+
const html = await remark()
23+
.use(remarkPresetLintMarkdownStyleGuide)
24+
.use(remarkGfm)
25+
.use(remarkNumberHeadings, { startDepth: 2, skip: ["Abstract", "Note to Readers", "Table of Contents"] })
26+
.use(remarkToc, { tight: true, heading: "Table of Contents" })
27+
.use(torchLight)
28+
.use(remarkFlexibleContainers)
29+
.use(remarkRehype)
30+
.use(rehypeSlug)
31+
.use(rehypeAutolinkHeadings, { behavior: "wrap" })
32+
.use(rehypeStringify)
33+
.process(md);
34+
35+
writeFileSync(1, `<!DOCTYPE html>
36+
<html>
37+
<head>
38+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/dark.css">
39+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/font/bootstrap-icons.css">
40+
41+
<style>
42+
svg {
43+
fill: currentColor;
44+
}
45+
46+
/* Torchlight */
47+
pre {
48+
border-radius: 0.25rem;
49+
margin-top: 1rem;
50+
margin-bottom: 1rem;
51+
overflow-x: auto;
52+
}
53+
54+
pre.torchlight code {
55+
display: block;
56+
min-width: -webkit-max-content;
57+
min-width: -moz-max-content;
58+
min-width: max-content;
59+
padding-top: 1rem;
60+
padding-bottom: 1rem;
61+
}
62+
63+
pre.torchlight code .line {
64+
padding-left: 1rem;
65+
padding-right: 1rem;
66+
}
67+
68+
pre.torchlight code .line-number,
69+
pre.torchlight code .summary-caret {
70+
margin-right: 1rem;
71+
}
72+
73+
/* Flexible Containers */
74+
.remark-container {
75+
border: thin solid black;
76+
border-radius: 1rem;
77+
margin-bottom: 1rem;
78+
}
79+
80+
.remark-container-title {
81+
border-radius: 1rem 1rem 0 0;
82+
position: relative;
83+
padding: .5rem 0 .5rem 2.5rem;
84+
background-color: var(--background);
85+
background-repeat: no-repeat;
86+
background-size: 1.75rem;
87+
background-position-y: center;
88+
background-position-x: .25rem;
89+
}
90+
91+
.remark-container > :not(.remark-container-title) {
92+
padding: 0 1rem 0 1rem;
93+
}
94+
95+
.remark-container-title.warning {
96+
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cg id='SVGRepo_bgCarrier' stroke-width='0'%3E%3C/g%3E%3Cg id='SVGRepo_tracerCarrier' stroke-linecap='round' stroke-linejoin='round'%3E%3C/g%3E%3Cg id='SVGRepo_iconCarrier'%3E%3Ccircle cx='12' cy='17' r='1' fill='%23ffffff'%3E%3C/circle%3E%3Cpath d='M12 10L12 14' stroke='%23ffffff' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3C/path%3E%3Cpath d='M3.44722 18.1056L10.2111 4.57771C10.9482 3.10361 13.0518 3.10362 13.7889 4.57771L20.5528 18.1056C21.2177 19.4354 20.2507 21 18.7639 21H5.23607C3.7493 21 2.78231 19.4354 3.44722 18.1056Z' stroke='%23ffffff' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3C/path%3E%3C/g%3E%3C/svg%3E");
97+
}
98+
99+
.remark-container-title.note {
100+
background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 32 32' version='1.1' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns:sketch='http://www.bohemiancoding.com/sketch/ns' fill='%23ffffff'%3E%3Cg id='SVGRepo_bgCarrier' stroke-width='0'%3E%3C/g%3E%3Cg id='SVGRepo_tracerCarrier' stroke-linecap='round' stroke-linejoin='round'%3E%3C/g%3E%3Cg id='SVGRepo_iconCarrier'%3E%3Ctitle%3Enote-text%3C/title%3E%3Cdesc%3ECreated with Sketch Beta.%3C/desc%3E%3Cdefs%3E%3C/defs%3E%3Cg id='Page-1' stroke='none' stroke-width='1' fill='none' fill-rule='evenodd' sketch:type='MSPage'%3E%3Cg id='Icon-Set' sketch:type='MSLayerGroup' transform='translate(-308.000000, -99.000000)' fill='%23ffffff'%3E%3Cpath d='M332,107 L316,107 C315.447,107 315,107.448 315,108 C315,108.553 315.447,109 316,109 L332,109 C332.553,109 333,108.553 333,108 C333,107.448 332.553,107 332,107 L332,107 Z M338,127 C338,128.099 336.914,129.012 335.817,129.012 L311.974,129.012 C310.877,129.012 309.987,128.122 309.987,127.023 L309.987,103.165 C309.987,102.066 310.902,101 312,101 L336,101 C337.098,101 338,101.902 338,103 L338,127 L338,127 Z M336,99 L312,99 C309.806,99 308,100.969 308,103.165 L308,127.023 C308,129.22 309.779,131 311.974,131 L335.817,131 C338.012,131 340,129.196 340,127 L340,103 C340,100.804 338.194,99 336,99 L336,99 Z M332,119 L316,119 C315.447,119 315,119.448 315,120 C315,120.553 315.447,121 316,121 L332,121 C332.553,121 333,120.553 333,120 C333,119.448 332.553,119 332,119 L332,119 Z M332,113 L316,113 C315.447,113 315,113.448 315,114 C315,114.553 315.447,115 316,115 L332,115 C332.553,115 333,114.553 333,114 C333,113.448 332.553,113 332,113 L332,113 Z' id='note-text' sketch:type='MSShapeGroup'%3E%3C/path%3E%3C/g%3E%3C/g%3E%3C/g%3E%3C/svg%3E");
101+
}
102+
103+
.remark-container-title.experimental {
104+
background-image: url("data:image/svg+xml,%3Csvg version='1.1' id='designs' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' viewBox='0 0 32 32' xml:space='preserve' fill='%23ffffff'%3E%3Cg id='SVGRepo_bgCarrier' stroke-width='0'%3E%3C/g%3E%3Cg id='SVGRepo_tracerCarrier' stroke-linecap='round' stroke-linejoin='round'%3E%3C/g%3E%3Cg id='SVGRepo_iconCarrier'%3E%3Cstyle type='text/css'%3E .sketchy_een%7Bfill:%23ffffff;%7D %3C/style%3E%3Cpath class='sketchy_een' d='M27.958,26.693c-0.023-0.207-0.066-0.377-0.22-0.531c-0.006-0.006-0.015-0.008-0.021-0.014 c0.06-0.187,0.051-0.395-0.057-0.573c-0.326-0.538-0.64-1.08-0.942-1.631c-0.345-0.629-0.716-1.241-1.059-1.87 c-0.351-0.642-0.676-1.296-1.016-1.942c-0.352-0.675-0.773-1.309-1.142-1.974c-0.506-0.907-0.961-1.842-1.47-2.749 c-0.494-0.88-0.958-1.772-1.422-2.667c0.008-0.161-0.007-0.328-0.012-0.488c-0.004-0.168-0.009-0.337-0.017-0.506 c-0.015-0.364-0.042-0.726-0.064-1.087c-0.045-0.722-0.102-1.444-0.133-2.167c-0.062-1.561-0.036-3.121,0.043-4.68 c0.159,0.001,0.318,0.002,0.478,0.001c0.26-0.004,0.519-0.023,0.779-0.011c0.485,0.023,0.89-0.422,0.89-0.89 c0-0.235-0.095-0.462-0.261-0.629c-0.176-0.178-0.386-0.242-0.629-0.261C21.443,2.005,21.202,2,20.96,2 c-0.264,0-0.528,0.006-0.789,0.008C20.05,2.01,19.929,2.01,19.808,2.01c-0.201,0-0.402,0-0.602,0.002 c-0.347,0.004-0.695,0.026-1.042,0.034c-0.39,0.006-0.782,0.002-1.173,0.01c-0.402,0.01-0.803,0.028-1.203,0.042 c-0.769,0.025-1.536,0.068-2.308,0.068c-0.441,0-0.883,0.004-1.322,0c-0.5-0.004-0.998-0.045-1.499-0.066 c-0.445-0.021-0.818,0.386-0.818,0.818c0,0.458,0.373,0.805,0.818,0.82c0.12,0.004,0.24,0.003,0.36,0.006 c0.038,0.704,0.098,1.408,0.133,2.114c0.036,0.722,0.028,1.444,0.049,2.165c0.021,0.68,0.04,1.362,0.061,2.042 c0.019,0.608,0.055,1.214,0.07,1.822c-0.354,0.653-0.68,1.32-1.049,1.964c-0.195,0.341-0.385,0.682-0.563,1.031 c-0.172,0.333-0.316,0.68-0.468,1.023c-0.15,0.337-0.296,0.676-0.46,1.006c-0.165,0.328-0.333,0.656-0.489,0.987 c-0.165,0.352-0.324,0.708-0.493,1.061c-0.155,0.33-0.328,0.652-0.489,0.979c-0.263,0.534-0.496,1.082-0.746,1.622 c-0.267,0.58-0.525,1.165-0.777,1.752c-0.241,0.561-0.519,1.104-0.758,1.665c-0.225,0.529-0.428,1.068-0.647,1.6 c-0.039,0.093-0.079,0.184-0.118,0.278c-0.052,0.117-0.081,0.229-0.091,0.344c-0.087,0.136-0.152,0.288-0.159,0.459 c-0.019,0.46-0.019,0.911,0.218,1.324c0.159,0.281,0.358,0.478,0.618,0.663c0.135,0.095,0.305,0.14,0.457,0.199 c0.241,0.095,0.519,0.097,0.777,0.114c0.368,0.023,0.733,0.002,1.101-0.009c0.402-0.013,0.801-0.034,1.203-0.062 c0.405-0.03,0.813-0.036,1.218-0.047c0.801-0.025,1.605-0.019,2.406-0.004c0.762,0.013,1.519,0.038,2.279,0.1 c0.765,0.064,1.525,0.066,2.292,0.064c0.159,0,0.32,0,0.479,0c0.64,0.002,1.281,0.002,1.923-0.032 c0.756-0.042,1.514-0.053,2.271-0.085c0.392-0.017,0.781-0.055,1.169-0.093c0.377-0.036,0.756-0.047,1.133-0.062 c0.686-0.027,1.37-0.023,2.05-0.117c0.138-0.019,0.277-0.042,0.415-0.07c0.195-0.042,0.369-0.116,0.551-0.195 c0.282-0.121,0.527-0.314,0.748-0.525c0.275-0.261,0.421-0.599,0.53-0.957c0.097-0.314,0.138-0.656,0.114-0.983 C27.973,26.817,27.965,26.756,27.958,26.693z M15.375,3.768c0.449-0.004,0.9-0.002,1.351,0.002c0.322,0.002,0.644,0.006,0.966,0.004 c0.385-0.001,0.77,0.01,1.154,0.021c-0.028,0.789-0.017,1.581-0.015,2.372c0,0.754-0.009,1.51,0.01,2.264 c0.019,0.716,0.047,1.434,0.1,2.15c0.019,0.259,0.042,0.521,0.062,0.782c-0.342,0.013-0.685,0.025-1.027,0.039 c-0.572,0.021-1.146,0.025-1.718,0.068c-1.152,0.088-2.305,0.091-3.46,0.077c-0.036-0.807-0.057-1.615-0.065-2.424 c0.384-0.011,0.768-0.021,1.152-0.032c0.424-0.013,0.781-0.345,0.781-0.781c0-0.42-0.352-0.781-0.774-0.781 c-0.002,0-0.004,0-0.007,0c-0.389,0.004-0.779,0.008-1.168,0.011c-0.002-0.539,0.001-1.077-0.023-1.615 c-0.032-0.719-0.05-1.437-0.076-2.154C13.537,3.779,14.456,3.778,15.375,3.768z M26.457,27.054c-0.021,0.106-0.049,0.21-0.085,0.312 c-0.036,0.076-0.077,0.15-0.122,0.221c-0.054,0.056-0.112,0.108-0.172,0.159c-0.078,0.053-0.159,0.1-0.243,0.141 c-0.225,0.079-0.462,0.123-0.698,0.158c-0.307,0.032-0.615,0.033-0.922,0.049c-0.311,0.015-0.62,0.043-0.928,0.059 c-0.771,0.034-1.535,0.121-2.306,0.154c-0.758,0.032-1.519,0.034-2.279,0.061c-0.803,0.028-1.608,0.028-2.412,0.019 c-0.377-0.004-0.754-0.002-1.131-0.011c-0.366-0.008-0.729-0.034-1.095-0.059c-0.779-0.049-1.557-0.042-2.338-0.03 c-0.799,0.011-1.599,0.04-2.398,0.057c-0.798,0.017-1.591,0.055-2.389,0.055c-0.263,0.002-0.525-0.011-0.786-0.034 c-0.09-0.015-0.179-0.033-0.266-0.059c-0.03-0.015-0.059-0.032-0.087-0.049c-0.01-0.01-0.021-0.02-0.031-0.03 c-0.011-0.018-0.022-0.036-0.032-0.054c-0.005-0.17,0.01-0.342,0.017-0.511c0.005-0.097-0.021-0.188-0.051-0.275 c0.126-0.329,0.26-0.655,0.383-0.984c0.13-0.346,0.26-0.691,0.401-1.033c0.134-0.304,0.277-0.606,0.412-0.91 c0.007-0.015,0.013-0.031,0.02-0.046c0.333,0.005,0.668,0.002,1-0.004c0.582-0.008,1.165-0.017,1.749,0.021 c0.404,0.027,0.741-0.356,0.741-0.741c0-0.411-0.337-0.731-0.741-0.741c-0.692-0.016-1.384-0.045-2.076-0.07 c0.233-0.516,0.471-1.031,0.707-1.547c0.116-0.252,0.241-0.499,0.365-0.746c0.093,0.037,0.192,0.061,0.296,0.058 c0.36-0.008,0.722-0.021,1.082-0.04c0.258-0.013,0.523-0.049,0.782-0.032c0.436,0.03,0.801-0.386,0.801-0.801 c0-0.458-0.366-0.777-0.801-0.803c-0.023-0.002-0.045-0.002-0.068-0.002c-0.083,0-0.165,0.009-0.249,0.014 c-0.15,0.006-0.301,0.006-0.451,0.008c-0.209,0.002-0.419,0.003-0.628,0.004c0.099-0.22,0.198-0.441,0.301-0.66 c0.157-0.33,0.32-0.654,0.468-0.987c0.078-0.177,0.155-0.354,0.232-0.532c0.057,0.012,0.111,0.034,0.171,0.031 c0.754-0.044,1.506-0.097,2.262-0.14c0.419-0.023,0.771-0.333,0.771-0.771c0-0.426-0.35-0.765-0.771-0.773 c-0.067-0.001-0.133-0.001-0.2-0.001c-0.495,0-0.991,0.026-1.486,0.054c0.052-0.101,0.095-0.206,0.15-0.305 c0.34-0.613,0.68-1.226,1.023-1.838c0.055,0.013,0.107,0.034,0.166,0.034c1.25,0.002,2.497-0.082,3.745-0.146 c0.572-0.028,1.146-0.036,1.718-0.049c0.246-0.006,0.494-0.002,0.741,0c0.059,0.002,0.119,0.002,0.18,0.002 c0.034,0,0.069,0.003,0.103,0.003c0,0.14,0.021,0.28,0.091,0.41c0.383,0.71,0.799,1.404,1.203,2.101 c0.385,0.669,0.763,1.338,1.122,2.021c0.356,0.676,0.709,1.355,1.097,2.012c0.189,0.318,0.4,0.623,0.584,0.945 c0.188,0.324,0.358,0.657,0.53,0.991c0.466,0.89,0.949,1.77,1.47,2.631c0.241,0.398,0.468,0.803,0.703,1.205 c0.21,0.356,0.441,0.705,0.629,1.072c0.021,0.042,0.058,0.068,0.088,0.103c-0.04,0.091-0.062,0.19-0.059,0.295 C26.462,26.814,26.465,26.934,26.457,27.054z M24.139,25.03c0.191,0.358,0.093,0.807-0.267,1.017 c-0.172,0.1-0.381,0.129-0.572,0.076c-0.172-0.047-0.368-0.174-0.445-0.341c-0.481-1.029-1.029-2.027-1.555-3.031 c-0.286-0.546-0.557-1.099-0.852-1.641c-0.313-0.576-0.61-1.157-0.894-1.747c-0.093-0.193-0.136-0.383-0.078-0.593 c0.053-0.193,0.182-0.36,0.354-0.46c0.117-0.069,0.253-0.105,0.389-0.105c0.069,0,0.137,0.009,0.204,0.027 c0.178,0.049,0.379,0.182,0.458,0.354c0.28,0.593,0.557,1.186,0.851,1.771c0.277,0.551,0.54,1.11,0.832,1.654 c0.28,0.521,0.57,1.038,0.839,1.565c0.131,0.26,0.26,0.519,0.396,0.773C23.917,24.575,24.02,24.807,24.139,25.03z'%3E%3C/path%3E%3C/g%3E%3C/svg%3E");
105+
}
106+
</style>
107+
</head>
108+
<body>
109+
${String(html)}
110+
</body>
111+
</html>`);
112+
113+
console.error(reporter(html));
114+
}());

‎build/remark-number-headings.js

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
import { visit } from "unist-util-visit";
2+
3+
4+
const defaultOptions = {
5+
startDepth: 1,
6+
skip: []
7+
};
8+
9+
const remarkNumberHeadings = (options) => (tree) => {
10+
options = { ...defaultOptions, ...options };
11+
12+
let sectionNumbers = [];
13+
14+
visit(tree, "heading", (node) => {
15+
if (node.depth < options.startDepth) {
16+
return;
17+
}
18+
19+
visit(node, "text", (textNode) => {
20+
const text = textNode.value ? textNode.value.trim() : "";
21+
22+
if (options.skip.includes(text)) {
23+
return;
24+
}
25+
26+
sectionNumbers[node.depth] = (sectionNumbers[node.depth] ?? 0) + 1;
27+
sectionNumbers = sectionNumbers.slice(0, node.depth + 1);
28+
29+
const sectionNumber = sectionNumbers.slice(options.startDepth, node.depth + 1).join(".");
30+
textNode.value = `${sectionNumber}. ${text}`;
31+
});
32+
});
33+
};
34+
35+
export default remarkNumberHeadings;

0 commit comments

Comments
 (0)