docs: improve rendering of specification files on GH pages

Fixes coreos#183
Okeanos · Mar 31, 2023 · ea0bd32 · ea0bd32
1 parent b28e42e
commit ea0bd32
Show file tree

Hide file tree

Showing 22 changed files with 68 additions and 1 deletion.
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,7 +1,7 @@
 title: coreos/butane
 description: Butane documentation
 baseurl: "/butane"
-url: "https://coreos.github.io"
+url: "https://okeanos.github.io"
 # Comment above and use below for local development
 # url: "http://localhost:4000"
 permalink: /:title/

diff --git a/docs/_sass/custom/custom.scss b/docs/_sass/custom/custom.scss
@@ -0,0 +1,27 @@
+/*
+ because we don't have a particular class at hand (or a unique id) to select the specification lists we do some
+ CSS voodoo with selector syntax (https://www.w3.org/TR/selectors-3/#selectors) instead to target them based on context
+ clues:
+ select unordered lists that are preceded by an h1 element whose id attribute contains the substring "-specification-"
+ */
+/*h1[id*="-specification-"] ~ ul {
+  ul {
+    border-left: 1px solid $grey-lt-300;
+  }
+
+  li::before {
+    content: unset;
+    margin-left: unset;
+    position: unset;
+  }
+}*/
+
+#spec-docs ~ ul {
+  ul {
+    border-left: 1px solid $grey-lt-300;
+  }
+
+  li::before {
+    margin-left: -0.8em;
+  }
+}
diff --git a/docs/config-fcos-v1_0.md b/docs/config-fcos-v1_0.md
@@ -8,6 +8,8 @@ nav_order: 49
 
 The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `fcos` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.0.0` and generates Ignition configs with version `3.0.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-fcos-v1_1.md b/docs/config-fcos-v1_1.md
@@ -8,6 +8,8 @@ nav_order: 48
 
 The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `fcos` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.1.0` and generates Ignition configs with version `3.1.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-fcos-v1_2.md b/docs/config-fcos-v1_2.md
@@ -8,6 +8,8 @@ nav_order: 47
 
 The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `fcos` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.2.0` and generates Ignition configs with version `3.2.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-fcos-v1_3.md b/docs/config-fcos-v1_3.md
@@ -8,6 +8,8 @@ nav_order: 46
 
 The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `fcos` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.3.0` and generates Ignition configs with version `3.2.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-fcos-v1_4.md b/docs/config-fcos-v1_4.md
@@ -8,6 +8,8 @@ nav_order: 45
 
 The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `fcos` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.4.0` and generates Ignition configs with version `3.3.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-fcos-v1_5.md b/docs/config-fcos-v1_5.md
@@ -8,6 +8,8 @@ nav_order: 44
 
 The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `fcos` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.5.0` and generates Ignition configs with version `3.4.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-fcos-v1_6-exp.md b/docs/config-fcos-v1_6-exp.md
@@ -10,6 +10,8 @@ nav_order: 50
 
 The Fedora CoreOS configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `fcos` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.6.0-experimental` and generates Ignition configs with version `3.5.0-experimental`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-flatcar-v1_0.md b/docs/config-flatcar-v1_0.md
@@ -8,6 +8,8 @@ nav_order: 99
 
 The Flatcar configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `flatcar` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.0.0` and generates Ignition configs with version `3.3.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-flatcar-v1_1.md b/docs/config-flatcar-v1_1.md
@@ -8,6 +8,8 @@ nav_order: 98
 
 The Flatcar configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `flatcar` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.1.0` and generates Ignition configs with version `3.4.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-flatcar-v1_2-exp.md b/docs/config-flatcar-v1_2-exp.md
@@ -10,6 +10,8 @@ nav_order: 100
 
 The Flatcar configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `flatcar` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.2.0-experimental` and generates Ignition configs with version `3.5.0-experimental`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-openshift-v4_10.md b/docs/config-openshift-v4_10.md
@@ -8,6 +8,8 @@ nav_order: 147
 
 The OpenShift configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `openshift` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `4.10.0` and generates Ignition configs with version `3.2.0`.
 * **metadata** (object): metadata about the generated MachineConfig resource. Respected when rendering to a MachineConfig, ignored when rendering directly to an Ignition config.

diff --git a/docs/config-openshift-v4_11.md b/docs/config-openshift-v4_11.md
@@ -8,6 +8,8 @@ nav_order: 146
 
 The OpenShift configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `openshift` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `4.11.0` and generates Ignition configs with version `3.2.0`.
 * **metadata** (object): metadata about the generated MachineConfig resource. Respected when rendering to a MachineConfig, ignored when rendering directly to an Ignition config.

diff --git a/docs/config-openshift-v4_12.md b/docs/config-openshift-v4_12.md
@@ -8,6 +8,8 @@ nav_order: 145
 
 The OpenShift configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `openshift` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `4.12.0` and generates Ignition configs with version `3.2.0`.
 * **metadata** (object): metadata about the generated MachineConfig resource. Respected when rendering to a MachineConfig, ignored when rendering directly to an Ignition config.

diff --git a/docs/config-openshift-v4_13.md b/docs/config-openshift-v4_13.md
@@ -8,6 +8,8 @@ nav_order: 144
 
 The OpenShift configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `openshift` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `4.13.0` and generates Ignition configs with version `3.2.0`.
 * **metadata** (object): metadata about the generated MachineConfig resource. Respected when rendering to a MachineConfig, ignored when rendering directly to an Ignition config.

diff --git a/docs/config-openshift-v4_14-exp.md b/docs/config-openshift-v4_14-exp.md
@@ -10,6 +10,8 @@ nav_order: 150
 
 The OpenShift configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `openshift` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `4.14.0-experimental` and generates Ignition configs with version `3.5.0-experimental`.
 * **metadata** (object): metadata about the generated MachineConfig resource. Respected when rendering to a MachineConfig, ignored when rendering directly to an Ignition config.

diff --git a/docs/config-openshift-v4_8.md b/docs/config-openshift-v4_8.md
@@ -8,6 +8,8 @@ nav_order: 149
 
 The OpenShift configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `openshift` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `4.8.0` and generates Ignition configs with version `3.2.0`.
 * **metadata** (object): metadata about the generated MachineConfig resource. Respected when rendering to a MachineConfig, ignored when rendering directly to an Ignition config.

diff --git a/docs/config-openshift-v4_9.md b/docs/config-openshift-v4_9.md
@@ -8,6 +8,8 @@ nav_order: 148
 
 The OpenShift configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `openshift` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `4.9.0` and generates Ignition configs with version `3.2.0`.
 * **metadata** (object): metadata about the generated MachineConfig resource. Respected when rendering to a MachineConfig, ignored when rendering directly to an Ignition config.

diff --git a/docs/config-r4e-v1_0.md b/docs/config-r4e-v1_0.md
@@ -8,6 +8,8 @@ nav_order: 199
 
 The RHEL for Edge configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `r4e` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.0.0` and generates Ignition configs with version `3.3.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-r4e-v1_1.md b/docs/config-r4e-v1_1.md
@@ -8,6 +8,8 @@ nav_order: 198
 
 The RHEL for Edge configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `r4e` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.1.0` and generates Ignition configs with version `3.4.0`.
 * **_ignition_** (object): metadata about the configuration itself.

diff --git a/docs/config-r4e-v1_2-exp.md b/docs/config-r4e-v1_2-exp.md
@@ -10,6 +10,8 @@ nav_order: 200
 
 The RHEL for Edge configuration is a YAML document conforming to the following specification, with **_italicized_** entries being optional:
 
+<div id="spec-docs"></div>
+
 * **variant** (string): used to differentiate configs for different operating systems. Must be `r4e` for this specification.
 * **version** (string): the semantic version of the spec for this document. This document is for version `1.2.0-experimental` and generates Ignition configs with version `3.5.0-experimental`.
 * **_ignition_** (object): metadata about the configuration itself.