Enhancing styling with Pico CSS and adding some features (#1672)

* Attempt to make the spec look stylish

* Code block styling

* Adding Pico CSS for better styling

* Fixing ToC format & highlighting

* Fixing code block & ToC format

* removing extra customizations

* Rely more on pico

* fixing padding and margins

* Update the padding to work with smaller screens

* better color for links

* fixing horizontal scroll & editing links style

* Less indentation in the table of contents

* Try a new color theme based on the code highlighting theme

* Cleanup some code styling

---------

Co-authored-by: Jason Desrosiers <jdesrosi@gmail.com>

Author: Ahmedmhmud

remark/remark-code-titles.js

@@ -15,7 +15,7 @@ const remarkNumberHeadings = () => (tree) => {
     }
 
     let title = "";
-    const titleClasses = ["remark-code-title"];
+    const titleClasses = [];
 
     const language = codeNode.lang ?? "";
     if (language.toLowerCase() === "jsonschema") {
@@ -43,23 +43,34 @@ const remarkNumberHeadings = () => (tree) => {
 
     const containerChildren = [];
     if (title) {
-      const titleNode = div([text(title)], { className: titleClasses });
+      const titleNode = figcaption([text(title)], { className: titleClasses });
       containerChildren.push(titleNode);
     }
     containerChildren.push(codeNode);
 
-    const wrappedCodeNode = div(containerChildren, { className: ["remark-code-container"] });
+    const wrappedCodeNode = figure(containerChildren);
 
     parent.children.splice(index, 1, wrappedCodeNode);
   });
 };
 
-const div = (children, properties) => {
+const figure = (children, properties) => {
   return {
     type: "container",
     children,
     data: {
-      hName: "div",
+      hName: "figure",
+      hProperties: properties
+    }
+  };
+};
+
+const figcaption = (children, properties) => {
+  return {
+    type: "container",
+    children,
+    data: {
+      hName: "figcaption",
       hProperties: properties
     }
   };

remark/remark-rfc2119.js

@@ -0,0 +1,75 @@
+import { text } from "mdast-builder";
+import { visit } from "unist-util-visit";
+
+
+/**
+ * RFC 2119 / RFC 8174 keywords
+ * Order matters: longer phrases first
+ */
+const KEYWORDS = [
+  "MUST NOT",
+  "NOT REQUIRED",
+  "SHALL NOT",
+  "SHOULD NOT",
+  "NOT RECOMMENDED",
+  "MUST",
+  "REQUIRED",
+  "SHALL",
+  "SHOULD",
+  "RECOMMENDED",
+  "MAY",
+  "OPTIONAL"
+];
+
+const KEYWORD_REGEX = new RegExp(`(?:${KEYWORDS.map((k) => k.replace(" ", "\\s")).join("|")})`, "gm");
+
+const skipNodes = new Set(["code", "inlineCode", "link", "definition", "html"]);
+
+export default function remarkRfc2119() {
+  return (tree) => {
+    visit(tree, "text", (node, index, parent) => {
+      // Do not touch code, inlineCode, links, or HTML
+      if (skipNodes.has(parent.type)) {
+        return;
+      }
+
+      const value = node.value;
+      let match;
+      let lastIndex = 0;
+      const children = [];
+
+      KEYWORD_REGEX.lastIndex = 0;
+
+      while ((match = KEYWORD_REGEX.exec(value)) !== null) {
+        const [keyword] = match;
+        const start = match.index;
+        const end = start + keyword.length;
+
+        if (start > lastIndex) {
+          children.push(text(value.slice(lastIndex, start)));
+        }
+
+        const keywordNode = text(keyword);
+        keywordNode.data = {
+          hName: "span",
+          hProperties: {
+            className: ["rfc2119", keyword.toLowerCase().replace(/\s+/g, "-")]
+          }
+        };
+        children.push(keywordNode);
+
+        lastIndex = end;
+      }
+
+      if (children.length === 0) {
+        return;
+      }
+
+      if (lastIndex < value.length) {
+        children.push(text(value.slice(lastIndex)));
+      }
+
+      parent.children.splice(index, 1, ...children);
+    });
+  };
+}

remark/remark-table-of-contents.js

@@ -25,6 +25,17 @@ const remarkTableOfContents = (options) => (tree, file) => {
     const headingText = nodeToString(headingNode);
 
     if (headingText === options.heading) {
+      headingNode.data = {
+        hProperties: {
+          className: ["toc-heading"]
+        }
+      };
+      tableOfContents.data = {
+        hProperties: {
+          className: ["toc"]
+        }
+      };
+
       insertTableOfContents = () => {
         parent.children.splice(index + 1, 0, tableOfContents);
       };
@@ -37,7 +48,7 @@ const remarkTableOfContents = (options) => (tree, file) => {
     while (headingNode.depth > currentDepth) {
       const newList = list("unordered");
       listStack.push(newList);
-      currentList.children.push(newList);
+      currentList.children.push(listItem(newList));
       currentList = newList;
       currentDepth++;
     }

specs/.remarkrc-build.js

@@ -18,9 +18,21 @@ export default {
     [rehypeHighlightCodeLines, { showLineNumbers: true }],
     rehypeLinkTransformer,
     [rehypeDocument, {
-      css: [
-        "https://cdn.jsdelivr.net/npm/water.css@2/out/dark.css",
-        "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/github-dark-dimmed.min.css"
+      link: [
+        {
+          rel: "stylesheet",
+          href: "https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.classless.min.css"
+        },
+        {
+          rel: "stylesheet",
+          href: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/github-dark-dimmed.min.css",
+          media: "(prefers-color-scheme: dark)"
+        },
+        {
+          rel: "stylesheet",
+          href: "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.0/styles/github.min.css",
+          media: "(prefers-color-scheme: light)"
+        }
       ],
       style: readFileSync(resolve(import.meta.dirname, "spec.css"), "utf8")
     }],

specs/.remarkrc-specs.js

@@ -5,6 +5,7 @@ import remarkCodeTitles from "../remark/remark-code-titles.js";
 import remarkHeadings from "../remark/remark-headings.js";
 import remarkReferenceLinks from "../remark/remark-reference-links.js";
 import remarkTableOfContents from "../remark/remark-table-of-contents.js";
+import remarkRfc2119 from "../remark/remark-rfc2119.js";
 
 
 export default {
@@ -37,6 +38,7 @@ export default {
       ]
     }],
     remarkFlexibleContainers,
-    remarkCodeTitles
+    remarkCodeTitles,
+    remarkRfc2119
   ]
 };

specs/jsonschema-core.md

@@ -1484,7 +1484,7 @@ In the cases where optimizations are enabled and a schema containing a
 non-resolvable reference would be skipped, as in the example below, behavior is
 implementation-defined.
 
-```json
+```jsonschema
 {
   "anyOf": [
     true,
@@ -1518,7 +1518,7 @@ downloadable JSON Schema using the link relation "describedby", as defined by
 In HTTP, such links can be attached to any response using the [Link
 header][rfc8288]. An example of such a header would be:
 
-```
+```http noLineNumbers
 Link: <https://example.com/my-hyper-schema>; rel="describedby"
 ```
 
@@ -1541,7 +1541,7 @@ implementation or software product. Since symbols are listed in decreasing order
 of significance, the JSON Schema library name/version should precede the more
 generic HTTP library name (if any). For example:
 
-```
+```http noLineNumbers
 User-Agent: product-name/5.4.1 so-cool-json-schema/1.0.2 curl/7.43.0
 ```
 
@@ -1969,7 +1969,7 @@ which evaluation passes to reach the schema object that produced a specific
 result. The value MUST be expressed as a JSON Pointer, and it MUST include any
 by-reference applicators such as `$ref` or `$dynamicRef`.
 
-```
+```text noLineNumbers
 /properties/width/$ref/allOf/1
 ```
 
@@ -1986,7 +1986,7 @@ Pointer fragment indicating the subschema that produced a result. In contrast
 with the evaluation path, the schema location MUST NOT include by-reference
 applicators such as `$ref` or `$dynamicRef`.
 
-```
+```text noLineNumbers
 https://example.com/schemas/common#/$defs/allOf/1
 ```
 

specs/proposals/propertyDependencies.md

@@ -54,7 +54,7 @@ The `dependentSchemas` keyword is very close to what is needed except it checks
 for the presence of a property rather than it's value. The chosen solution is to
 build on that concept to solve this problem.
 
-```json
+```jsonschema
 {
   "propertyDependencies": {
     "foo": {
@@ -66,7 +66,7 @@ build on that concept to solve this problem.
 
 The validation result is equivalent to the following schema.
 
-```json
+```jsonschema
 {
   "if": {
     "properties": {
@@ -115,7 +115,7 @@ vocabulary](../jsonschema-core.md#applicators).
    `https://json-schema.org/<version>/<release>/meta/applicator` at
    `/properties/propertyDependencies`:
 
-    ```json
+    ```jsonschema
     {
       "type": "object",
       "additionalProperties": {

specs/proposals/vocabularies.md

@@ -82,7 +82,7 @@ booleans as values. This keyword only has meaning within a meta-schema. A
 meta-schema which includes a vocabulary's URI in its `$vocabulary` keyword is
 said to "include" that vocabulary.
 
-```jsonc
+```jsonschema
 {
   "$schema": "https://example.org/draft/next/schema",
   "$id": "https://example.org/schema",
@@ -132,7 +132,7 @@ schemas.) To facilitate this extra validation, when a vocabulary schema is
 provided, any meta-schema which includes the vocabulary should also contain a
 reference (via `$ref`) to the vocabulary schema's `$id` value.
 
-```jsonc
+```jsonschema
 {
   "$schema": "https://example.org/draft/next/schema",
   "$id": "https://example.org/schema",
@@ -156,7 +156,7 @@ the meta-schema and added to vocabulary schemas to which the meta-schema will
 contain references. In this way, the meta-schema's functionality remains the
 same.
 
-```json
+```jsonschema
 {
   "$schema": "https://json-schema.org/draft/next/schema",
   "$id": "https://json-schema.org/draft/next/schema",
@@ -246,7 +246,7 @@ For example
 2. The following subschema will be added to the Applicator Vocabulary schema,
    `https://json-schema.org/<version>/<release>/meta/applicator`, at
    `/properties/{keyword}`:
-    ```jsonc
+    ```jsonschema
     {
       // keyword schema
     }