more work on docs

2023-05-12 18:23:55 -07:00 · 2023-05-12 18:23:55 -07:00 · 553316eb50
commit 553316eb50
parent b84727bd3f
18 changed files with 761 additions and 211 deletions
--- a/config.yaml
+++ b/config.yaml
@ -93,3 +93,12 @@ output:
 markdown:
  # 
  base_url: http://localhost:8000
+
+  # 
+  custom_elements:
+    tag_names:
+    - svg-icon
+    - outline-inline
+    attribute_names:
+    - icon
+    - content-root
--- a/docs/_assets/base.css
+++ b/docs/_assets/base.css
@ -70,45 +70,45 @@ outline-button {
 	display: block;
 }

-:is(#outline-inline, #outline-panel) h2 {
+#outline-panel h2 {
 	margin-block: 1rem;
 	margin-inline: 1rem;
 	padding: 0;
 	font-size: 1.4rem;
 }

-:is(#outline-inline, #outline-panel) ol {
+#outline-panel ol {
 	list-style: none;
 	padding: 0;
 }

-:is(#outline-inline, #outline-panel) li[data-depth='h1'] {
+#outline-panel li[data-depth='h1'] {
 	font-size: 1.2rem;
 	font-weight: 700;
 	margin-inline-start: 1rem;
 }

-:is(#outline-inline, #outline-panel) li[data-depth='h2'] {
+#outline-panel li[data-depth='h2'] {
 	font-size: 1.1rem;
 	font-weight: 600;
 	margin-inline-start: 2rem;
 }

-:is(#outline-inline, #outline-panel) li[data-depth='h3'] {
+#outline-panel li[data-depth='h3'] {
 	margin-inline-start: 3rem;
 }

-:is(#outline-inline, #outline-panel) li[data-depth='h4'] {
+#outline-panel li[data-depth='h4'] {
 	font-size: 0.9rem;
 	margin-inline-start: 4rem;
 }

-:is(#outline-inline, #outline-panel) li[data-depth='h5'] {
+#outline-panel li[data-depth='h5'] {
 	font-size: 0.9rem;
 	margin-inline-start: 5rem;
 }

-:is(#outline-inline, #outline-panel) li[data-depth='h6'] {
+#outline-panel li[data-depth='h6'] {
 	font-size: 0.9rem;
 	margin-inline-start: 6rem;
 }
@ -116,7 +116,6 @@ outline-button {
@media print {
 	color-scheme-toggle-button,
 	outline-button,
-	#outline-inline,
 	#outline-panel {
 		display: hidden !important;
 	}
@ -136,6 +135,7 @@ body[data-color-transition-enabled],
 body[data-color-transition-enabled] :is(
 	[data-bg-transition]:not([data-color-transition]):not([data-border-transition]),
 	button,
+	.markdown-example-output
 ) {
 	transition: background linear .5s;
 }
@ -214,20 +214,27 @@ body[data-color-transition-enabled] :is(
 }

 /* Fill and Stroke */
-body[data-color-transition-enabled] svg [fill^='var('][stroke^='var(']:not([fill^='var('][stroke^='var('] *) {
+body[data-color-transition-enabled] svg :is(
+	[fill^='var('][stroke^='var(']:not([fill^='var('][stroke^='var('] *),
+	[style*='fill:'][style*='stroke:']:not([style*='fill:'][style*='stroke:'] *)
+) {
 	transition:
 		fill linear .5s,
 		stroke linear .5s;
 }

 /* Fill Only */
-body[data-color-transition-enabled] svg [fill^='var(']:not([stroke^='var(']):not([fill^='var('] *) {
+body[data-color-transition-enabled] svg :is(
+	[fill^='var(']:not([stroke^='var(']):not([fill^='var('] *),
+	[style*='fill:']:not([style*='stroke:']):not([style*='fill:'] *)
+) {
 	transition: fill linear .5s;
 }

 /* Stroke Only */
 body[data-color-transition-enabled] :is(
 	svg [stroke^='var(']:not([fill^='var(']):not([stroke^='var('] *),
+	svg [style*='stroke:']:not([style*='fill:']):not([style*='stroke:'] *)
 	svg.icon
 ) {
 	transition: stroke linear .5s;
@ -252,6 +259,12 @@ body[data-color-transition-enabled] :is(
 	z-index: 1;
 }

+@media screen and (min-width: 60rem) {
+	#root {
+		padding-inline: 2rem;
+	}
+}
+
@media print {
 	#root {
 		padding-block: 0.5rem;
@ -652,6 +665,23 @@ a.local-ref {
 	font-style: italic;
 }

+.markdown-example-output {
+	padding: 1rem;
+	margin-block-start: 0;
+	margin-block-end: 1.5rem;
+	margin-inline: 1rem;
+	border-radius: 1rem;
+	background: var(--theme-bg-light);
+}
+
+.markdown-example-output > :first-child {
+	margin-block-start: 0;
+}
+
+.markdown-example-output > :last-child {
+	margin-block-end: 0;
+}
+
 blockquote {
 	margin-block: 2rem;
 	margin-inline: 1rem;
@ -850,6 +880,33 @@ a.heading-anchor {



+nav[aria-label="breadcrumbs"] {
+	/*  */
+}
+
+nav[aria-label="breadcrumbs"] ol {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	display: flex;
+}
+
+nav[aria-label="breadcrumbs"] li {
+	padding: 0.25rem;
+}
+
+
+
+
+
+
+
+
+
+
+
+
+



@ -1136,10 +1193,14 @@ body .katex-display {
 	margin: 2rem;
 }

-body .katex-display > .katex {
+body figure.align-left .katex-display > .katex {
 	text-align: left;
 }

+body figure.align-right .katex-display > .katex {
+	text-align: right;
+}
+
 :not(.katex-display) > .katex {
 	font-size: inherit;
 	margin-inline: 0.5rem;
--- a/docs/color-themes/index.md
+++ b/docs/color-themes/index.md
@ -3,9 +3,11 @@ title: Color Themes | doc-utils
 layout: main.html
 ---

+///
 [doc-utils](index.html)
+///

-# Color Themes {#-}
+# Color Themes {#/}

 _todo_

--- a/docs/color-themes/preview.md
+++ b/docs/color-themes/preview.md
@ -3,7 +3,10 @@ title: Preview Color Themes | doc-utils
 layout: preview-color-themes.html
 ---

-[doc-utils](index.html) / [color-themes](color-themes/index.html)
+///
+[doc-utils](index.html)
+[color-themes](color-themes/index.html)
+///

 # Sample Content

@ -37,18 +40,18 @@ Ut cursus erat id iaculis molestie. Praesent rhoncus rhoncus vehicula. Suspendis
 Etiam tempus id purus accumsan congue. Mauris et egestas nunc. Sed eu enim nunc. Etiam maximus dui molestie, sagittis neque non, tincidunt ligula. Fusce fermentum metus massa, nec convallis urna viverra sit amet. Ut libero ex, venenatis ut semper sed, fermentum sed massa. Ut gravida ligula diam, non vehicula orci porttitor quis. Vivamus porta, risus nec egestas imperdiet, sem tellus congue mi, eget molestie tellus mauris et arcu. Suspendisse sit amet rhoncus lectus. In [lorem lorem](#), varius id est sed, maximus eleifend augue. Ut scelerisque nunc et commodo varius. Nam quis turpis ac metus suscipit dictum. Duis ut elit vel neque pretium mattis. Curabitur vehicula a dolor ac condimentum. Aenean sit amet ultricies nibh. Nunc id massa ac augue ultricies consequat.

 ```pikchr "_fig. 2: Input/Output diagram for markdown2html and docs2website_"
-MD:     box wid 1.2 ht 0.5 "Markdown"
-HTML:   box same at 2.5 east of MD "HTML Fragments"
-COLOR:  box same at 0.75 north of HTML "Color Themes"
-ASSET:  box same at 0.75 south of HTML "Static Assets"
-WEB:    box same at 2 east of HTML "Static Website"
+MD:     box wid 1.2 ht 0.5 "Markdown" fill yellow color yellow
+HTML:   box same at 2.5 east of MD "HTML Fragments" fill blue color blue
+COLOR:  box same at 0.75 north of HTML "Color Themes" fill blue color blue
+ASSET:  box same at 0.75 south of HTML "Static Assets" fill blue color blue
+WEB:    box same at 2 east of HTML "Static Website" fill green color green

 arrow from MD .e to HTML .w \
-  "markdown2html" italic aligned above small
+  "markdown2html" italic aligned above small color blue

-arrow from COLOR .e to WEB .nw
-arrow from HTML .e to WEB .w
-arrow from ASSET .e to WEB .sw
+arrow from COLOR .e to WEB .nw color green
+arrow from HTML .e to WEB .w color green
+arrow from ASSET .e to WEB .sw color green
 ```

 In et ipsum laoreet, lobortis turpis eget, hendrerit elit. Ut vehicula magna nec elementum consectetur. Nam luctus tellus sit amet odio maximus ultrices. Donec vulputate magna nisi. Morbi euismod velit et dolor posuere, a [aliquet quam sodales](#). Pellentesque luctus eleifend ex sed vestibulum. Fusce sed rutrum ante. Pellentesque id justo lobortis, sollicitudin velit ut, porttitor magna. Mauris eu lorem congue, pellentesque purus et, eleifend velit. Nulla facilisi.
@ -59,8 +62,6 @@ Suspendisse sapien libero, facilisis sit amet ex sed, hendrerit rhoncus turpis.

 ```katex "_fig. 3: Math! D:_"
 {(ax + by + x)^2 \over {a^2 + b^2}} = (x - f_1)^2 + (y - f_2)^2
-\\\mathstrut\\
-\KaTeX
 ```


--- a/docs/color-themes/schema/v1.yaml
+++ b/docs/color-themes/schema/v1.yaml
@ -217,34 +217,70 @@ properties:
      chart_guideline:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_0:
+      chart_shape_red_fill:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_1:
+      chart_shape_red_line:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_2:
+      chart_shape_orange_fill:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_3:
+      chart_shape_orange_line:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_4:
+      chart_shape_yellow_fill:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_5:
+      chart_shape_yellow_line:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_6:
+      chart_shape_green_fill:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_7:
+      chart_shape_green_line:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_8:
+      chart_shape_teal_fill:
        $ref: "#/definitions/css_color"
        # todo: description
-      chart_data_9:
+      chart_shape_teal_line:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_pink_fill:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_pink_line:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_purple_fill:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_purple_line:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_blue_fill:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_blue_line:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_indigo_fill:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_indigo_line:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_magenta_fill:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_magenta_line:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_brown_fill:
+        $ref: "#/definitions/css_color"
+        # todo: description
+      chart_shape_brown_line:
        $ref: "#/definitions/css_color"
        # todo: description

@ -317,38 +353,36 @@ properties:
        # todo: description
 definitions:
  css_color:
-    title: CSS Color
-    $comment: 'todo: other color function formats, like hsl'
    oneOf:
+      # Hex Colors
      - type: string
-        title: Hex Colors
        format: regex
        pattern: ^(#[0-9a-fA-F]{3}(?:[0-9a-fA-F]{3}(?:[0-9a-fA-F]{2})?)?)$
        examples:
          - "#000"
          - "#ff0000"
          - "#ffccaa88"
+      # RGB Colors
      - type: string
-        title: RGB Colors
        format: regex
        pattern: ^(rgb\(\s*([0-9]{1,3})\s*,\s*([0-9]{1,3})\s*,\s*([0-9]{1,3})\s*\))$
        examples:
          - rgb(10, 70, 130)
+      # RGBA Colors
      - type: string
-        title: RGBA Colors
        format: regex
        pattern: ^(rgba\(\s*([0-9]{1,3})\s*,\s*([0-9]{1,3})\s*,\s*([0-9]{1,3})\s*,\s*([01]|[01]?\.[0-9]{1,3})\s*\))$
        examples:
          - rgba(10, 70, 130, 0.5)
      # todo: other color function formats, like hsl
+      # transparent
      - type: string
-        title: transparent Keyword
        const: transparent
+      # currentcolor
      - type: string
-        title: currentcolor Keyword
        const: currentcolor
+      # Named Colors: CSS Level 1
      - type: string
-        title: 'Named Colors: CSS Level 1'
        enum:
          - black
          - silver
@ -366,147 +400,18 @@ definitions:
          - blue
          - teal
          - aqua
+      # Named Colors: CSS Level 2
      - type: string
-        title: 'Named Colors: CSS Level 2'
        enum:
          - orange
+      # Named Colors: CSS Level 3
      - type: string
-        title: 'Named Colors: CSS Level 3'
        enum:
          - aliceblue
          - antiquewhite
-          - aquamarine
-          - azure
-          - beige
-          - bisque
-          - blanchedalmond
-          - blueviolet
-          - brown
-          - burlywood
-          - cadetblue
-          - chartreuse
-          - chocolate
-          - coral
-          - cornflowerblue
-          - cornsilk
-          - crimson
-          - cyan
-          - aqua
-          - darkblue
-          - darkcyan
-          - darkgoldenrod
-          - darkgray
-          - darkgreen
-          - darkgrey
-          - darkkhaki
-          - darkmagenta
-          - darkolivegreen
-          - darkorange
-          - darkorchid
-          - darkred
-          - darksalmon
-          - darkseagreen
-          - darkslateblue
-          - darkslategray
-          - darkslategrey
-          - darkturquoise
-          - darkviolet
-          - deeppink
-          - deepskyblue
-          - dimgray
-          - dimgrey
-          - dodgerblue
-          - firebrick
-          - floralwhite
-          - forestgreen
-          - gainsboro
-          - ghostwhite
-          - gold
-          - goldenrod
-          - greenyellow
-          - grey
-          - honeydew
-          - hotpink
-          - indianred
-          - indigo
-          - ivory
-          - khaki
-          - lavender
-          - lavenderblush
-          - lawngreen
-          - lemonchiffon
-          - lightblue
-          - lightcoral
-          - lightcyan
-          - lightgoldenrodyellow
-          - lightgray
-          - lightgreen
-          - lightgrey
-          - lightpink
-          - lightsalmon
-          - lightseagreen
-          - lightskyblue
-          - lightslategray
-          - lightslategrey
-          - lightsteelblue
-          - lightyellow
-          - limegreen
-          - linen
-          - magenta
-          - fuchsia
-          - mediumaquamarine
-          - mediumblue
-          - mediumorchid
-          - mediumpurple
-          - mediumseagreen
-          - mediumslateblue
-          - mediumspringgreen
-          - mediumturquoise
-          - mediumvioletred
-          - midnightblue
-          - mintcream
-          - mistyrose
-          - moccasin
-          - navajowhite
-          - oldlace
-          - olivedrab
-          - orangered
-          - orchid
-          - palegoldenrod
-          - palegreen
-          - paleturquoise
-          - palevioletred
-          - papayawhip
-          - peachpuff
-          - peru
-          - pink
-          - plum
-          - powderblue
-          - rosybrown
-          - royalblue
-          - saddlebrown
-          - salmon
-          - sandybrown
-          - seagreen
-          - seashell
-          - sienna
-          - skyblue
-          - slateblue
-          - slategray
-          - slategrey
-          - snow
-          - springgreen
-          - steelblue
-          - tan
-          - thistle
-          - tomato
-          - transparent
-          - turquoise
-          - violet
-          - wheat
-          - whitesmoke
-          - yellowgreen
+          # todo: fill in the rest of level3 colors...
+          # see: https://developer.mozilla.org/en-US/docs/Web/CSS/named-color
+      # Named Colors: CSS Level 4
      - type: string
-        title: 'Named Colors: CSS Level 4'
        enum:
          - rebeccapurple
--- a/docs/docs2website/building-from-source.md
+++ b/docs/docs2website/building-from-source.md
@ -3,8 +3,64 @@ title: Building From Source | docs2website
 layout: main.html
 ---

-[doc-utils](index.html) / [docs2website](docs2website/index.html)
+///
+[doc-utils](index.html)
+[docs2website](docs2website/index.html)
+///

-# Building From Source {#-}
+# Building From Source {#/}

 _todo_
+
+## Clone the repo
+
+```bash:samp
+git clone https://gitea.jbrumond.me/doc-utils/docs2website
+Cloning into 'docs2website'...
+remote: Enumerating objects: 25, done.
+remote: Counting objects: 100% (25/25), done.
+remote: Compressing objects: 100% (19/19), done.
+remote: Total 25 (delta 1), reused 0 (delta 0), pack-reused 0
+Receiving objects: 100% (25/25), 53.92 KiB | 7.70 MiB/s, done.
+Resolving deltas: 100% (1/1), done.
+```
+
+
+
+## Install dependencies
+
+First, you'll need to create an npm config file in the project to refer to correct registry for the @doc-utils scope
+
+```bash
+echo '@doc-utils:registry=https://gitea.jbrumond.me/api/packages/doc-utils/npm/' >> ./.npmrc
+```
+
+Then you can install with npm as normal
+
+```bash:samp
+npm install
+added 239 packages, and audited 240 packages in 5s
+
+17 packages are looking for funding
+  run `npm fund` for details
+
+found 0 vulnerabilities
+```
+
+
+
+## Build
+
+```bash:samp
+npm run tsc
+> @doc-utils/docs2website@0.1.0 tsc
+> tsc
+```
+
+
+
+## Setup PATH for CLI use
+
+The `docs2website` command can be found in the `./bin` directory.
+
+You can link to this file in a directory in your `PATH`, or add that directory to your `PATH`.
--- a/docs/docs2website/command-line-use.md
+++ b/docs/docs2website/command-line-use.md
--- a/docs/docs2website/configuration.md
+++ b/docs/docs2website/configuration.md
@ -3,8 +3,107 @@ title: Configuration | docs2website
 layout: main.html
 ---

-[doc-utils](index.html) / [docs2website](docs2website/index.html)
+///
+[doc-utils](index.html)
+[docs2website](docs2website/index.html)
+///

-# Configuration {#-}
+
+# Configuration {#/}

 _todo_
+
+## Sample Configuration File
+
+```yaml
+# Input Configuration (where your documents are)
+input:
+  # The root directory for where to find input file. All other
+  # input paths are relative to this, and must be under this
+  root: ./docs
+
+  # Files identified in this section are copied over to the
+  # output directory unprocessed
+  raw:
+  - ./**/*.{png,jpg,jpeg,gif}
+
+  # Files in this section will be processed as mustache templates,
+  # but will receive no other processing
+  text:
+  - ./**/*.{css,html,js,txt}
+
+  # Files to be parsed as markdown (optionally with front matter)
+  # and rendered to HTML pages
+  markdown:
+  - ./**/*.md
+
+  # Files to be parsed as JSON Schema definitions and rendered
+  # to HTML documentation. Additionally, the original JSON / Yaml
+  # file will also be copied to the output directory
+  schema+json:
+  - ./**/*.schema.json
+  schema+yaml:
+  - ./**/*.schema.{yaml,yml}
+
+  # Files to be parsed as OpenAPI V3 specifications and rendered
+  # to HTML documentation. Additionally, the original JSON / Yaml
+  # file will also be copied to the output directory
+  openapi+json:
+  - ./**/*.openapi.json
+  openapi+yaml:
+  - ./**/*.openapi.{yaml,yml}
+
+# Template Configuration (used by mustache to actually render pages)
+templates:
+  # Root directory where layout files are stored
+  layouts: ./layouts
+
+  # Root directory where partial files are stored
+  partials: ./partials
+
+  # Overrides the opening/closing tags used in mustache template rendering
+  tags: [ '{{', '}}' ]
+
+  # (Optional) whitelist of environment variables to be made accessible
+  # under `env` when processing templates
+  env:
+  - EXAMPLE_ENVIRONMENT_VARIABLE
+  - FOO_BAR_BAZ
+
+# Output Configuration (where to put your website)
+output:
+  # The root directory to output your website at. The path of an
+  # input file relative to $.input.root will match (aside from file
+  # extension) the path of the output file relative to $.output.root
+  root: ./www
+
+  # Any input types listed here will have their raw input files copied
+  # into the output directory (in addition to creating the new, processed
+  # output files)
+  include_inputs:
+  - schema+json
+  - schema+yaml
+  - openapi+json
+  - openapi+yaml
+
+  # When writing either a JSON or Yaml file, if this flag is set to true,
+  # the file will be converted to the other format so both formats are
+  # included in the output
+  include_yaml_and_json: true
+
+  # If set to true, intermediate markdown files that are generated from
+  # other input sources will also be written to the output directory. For
+  # example, a JSON Schema file goes through two transform steps, e.g.
+  # 
+  #   "schema.json" => "schema.md" => "schema.html"
+  # 
+  # Typically, those intermediate markdown files are not written anywhere,
+  # only passed from one step to the other, unless this flag is set.
+  include_intermediate_markdown: false
+
+# Markdown-to-HTML Configuration
+markdown:
+  # 
+```
+
+
--- a/docs/docs2website/index.md
+++ b/docs/docs2website/index.md
@ -3,13 +3,15 @@ title: docs2website
 layout: main.html
 ---

+///
 [doc-utils](index.html)
+///

-# docs2website {#-}
+# docs2website {#/}

 _todo_

- Source Code: <https://gitea.jbrumond.me/doc-utils/docs2website>
+- [Source Code {:external-link:}](https://gitea.jbrumond.me/doc-utils/docs2website)
 - [Building From Source](docs2website/building-from-source.html)
 - [Configuration](docs2website/configuration.html)
 - [Preview Built-in Color Themes](color-themes/preview.html)
--- a/docs/docs2website/programatic-use.md
+++ b/docs/docs2website/programatic-use.md
--- a/docs/index.md
+++ b/docs/index.md
@ -3,7 +3,7 @@ title: doc-utils
 layout: main.html
 ---

-# doc-utils {#-}
+# doc-utils {#/}

 Documentation for the doc-utils projects.

@ -12,8 +12,22 @@ Documentation for the doc-utils projects.
 - [docs2website] - Static site generator based on an extended form of Markdown
 - [color-themes] - Directory of color themes, along with the definition for the color theme format
 - [markdown2html] - Convert Markdown documents to HTML documents
- [openapi2markdown] - Convert OpenAPI Specification files to Markdown documents
- [jsonschema2markdown] - Convert JSON Schema files to Markdown documents
+- Convert various other files to Markdown documents:
+  - JSON Schemas: [jsonschema2markdown]
+  - OpenAPI Specifications: [openapi2markdown]
+  <!-- - AsyncAPI Specifications: [asyncapi2markdown] -->
+  - CycloneDX SBOMs: [cyclonedxsbom2markdown]
+  <!-- - SPDX SBOMs: [spdxsbom2markdown] -->
+  <!-- - Linked Data Contexts: [ld2markdown] -->
+  <!-- - XSD Schemas: [xsdschema2markdown] -->
+  <!-- - Avro Schemas: [avroschema2markdown] -->
+  <!-- - TypeScript: [ts2markdown] -->
+
+
+
+## Markdown Format
+
+See [Markdown Format]



@ -23,10 +37,11 @@ The [docs2website] project is a static site generator primarily focused on techn

 The [color-themes] project contains the directory of all of the built-in color themes that come with [docs2website], and is where the JSON Schema and TypeScript definitions for those color themes are located.

-The remaining projects each are responsible for converting one document format into another; [markdown2html] is an extension layer on top of [Marked] that is responsible for rendering Markdown to HTML, and the others all convert various formats into Markdown.
+The remaining projects each are responsible for converting one document format into another; [markdown2html] is an extension layer on top of [Marked {:external-link:}](https://marked.js.org/) that is responsible for rendering Markdown to HTML, and the others all convert various formats into Markdown.

 ```pikchr "_fig. 1: Diagram showing the architecture of the doc-utils projects and the flow from one step/project to another_"
-JSCH:   box "JSON Schema" wid 150% ht 65%
+JSCH:   box "JSON Schema" wid 150% ht 65% \
+          fill indigo color indigo

 OAPI:   box "OpenAPI Spec" same \
          at 0.75 south of JSCH
@ -42,59 +57,66 @@ ETC:    box "Etc..." same \
          dashed

 MD:     box "Markdown" same as JSCH \
-          at 2.5 east of CSBOM
+          at 2.5 east of CSBOM \
+          color yellow fill yellow

 HTML:   box "HTML Fragments" same \
          at 2.5 east of MD

 COLOR:  box "Color Themes" same \
-          at 0.75 north of HTML
+          at 0.75 north of HTML \
+          fill purple color purple

 ASSET:  box "Static Assets" same \
-          at 0.75 south of HTML
+          at 0.75 south of HTML \
+          fill blue color blue

 WEB:    box "Static Website" same \
-          at 1.5 east of HTML
+          at 1.5 east of HTML \
+          fill green color green

 SITE:   box ht (COLOR.n.y-ASSET.s.y)+0.5 wid COLOR.wid+WEB.wid+0.75 \
          at (HTML.x+0.75,HTML.y) \
-          dashed \
+          dashed color green \
          behind HTML

 text "docs2website" italic small above at SITE.s

-arrow from JSCH .e to MD .nw \
-  "jsonschema2markdown" italic aligned above small
+arrow from JSCH .e to 0.1 east of MD .nw \
+  "jsonschema2markdown" italic aligned above small \
+  color indigo

 arrow from OAPI .e to 0.1 above MD .w \
-  "openapi2markdown" italic aligned above small
+  "openapi2markdown" italic aligned above small \
+  color indigo

 arrow from CSBOM .e to MD .w \
-  "cyclonedxsbom2markdown" italic aligned above small
+  "cyclonedxsbom2markdown" italic aligned above small \
+  color indigo

 arrow from LD .e to 0.1 below MD .w \
-  "ldcontext2markdown" italic aligned above small
+  "ldcontext2markdown" italic aligned above small \
+  color indigo

-arrow from ETC .e to MD .sw dashed
+arrow from ETC .e to 0.1 east of MD .sw dashed \
+  color indigo

 arrow from MD .e to HTML .w \
-  "markdown2html" italic aligned above small
+  "markdown2html" italic aligned above small \
+  color yellow

-arrow from COLOR .e to WEB .nw
+arrow from COLOR .e to 0.1 east of WEB .nw \
+  color green

-arrow from HTML .e to WEB .w
+arrow from HTML .e to WEB .w \
+  color green

-arrow from ASSET .e to WEB .sw
+arrow from ASSET .e to 0.1 east of WEB .sw \
+  color green
 ```



-## Markdown Format
-
-See [Markdown Format]
-
-
-


 <!-- Link Details -->
@ -104,5 +126,11 @@ See [Markdown Format]
 [markdown2html]: markdown2html/index.html
 [openapi2markdown]: openapi2markdown/index.html
 [jsonschema2markdown]: jsonschema2markdown/index.html
-[Markdown Format]: markdown-format.html
-[Marked]: https://marked.js.org/
+[asyncapi2markdown]: asyncapi2markdown/index.html
+[cyclonedxsbom2markdown]: cyclonedxsbom2markdown/index.html
+[spdxsbom2markdown]: spdxsbom2markdown/index.html
+[ld2markdown]: ld2markdown/index.html
+[xsdschema2markdown]: xsdschema2markdown/index.html
+[avroschema2markdown]: avroschema2markdown/index.html
+[ts2markdown]: ts2markdown/index.html
+[Markdown Format]: markdown2html/markdown-format.html
--- a/docs/jsonschema2markdown/building-from-source.md
+++ b/docs/jsonschema2markdown/building-from-source.md
--- a/docs/jsonschema2markdown/command-line-use.md
+++ b/docs/jsonschema2markdown/command-line-use.md
--- a/docs/jsonschema2markdown/index.md
+++ b/docs/jsonschema2markdown/index.md
--- a/docs/jsonschema2markdown/programatic-use.md
+++ b/docs/jsonschema2markdown/programatic-use.md
--- a/docs/markdown2html/building-from-source.md
+++ b/docs/markdown2html/building-from-source.md
@ -0,0 +1,66 @@
+---
+title: Building From Source | markdown2html
+layout: main.html
+---
+
+///
+[doc-utils](index.html)
+[markdown2html](markdown2html/index.html)
+///
+
+# Building From Source {#/}
+
+_todo_
+
+## Clone the repo
+
+```bash:samp
+git clone https://gitea.jbrumond.me/doc-utils/markdown2html
+Cloning into 'markdown2html'...
+remote: Enumerating objects: 286, done.
+remote: Counting objects: 100% (286/286), done.
+remote: Compressing objects: 100% (275/275), done.
+remote: Total 286 (delta 99), reused 127 (delta 4), pack-reused 0
+Receiving objects: 100% (286/286), 2.42 MiB | 19.48 MiB/s, done.
+Resolving deltas: 100% (99/99), done.
+```
+
+
+
+## Install dependencies
+
+First, you'll need to create an npm config file in the project to refer to correct registry for the @doc-utils scope
+
+```bash
+echo '@doc-utils:registry=https://gitea.jbrumond.me/api/packages/doc-utils/npm/' >> ./.npmrc
+```
+
+Then you can install with npm as normal
+
+```bash:samp
+npm install
+added 197 packages, and audited 198 packages in 5s
+
+5 packages are looking for funding
+  run `npm fund` for details
+
+found 0 vulnerabilities
+```
+
+
+
+## Build
+
+```bash:samp
+npm run tsc
+> @doc-utils/markdown2html@0.1.13 tsc
+> tsc
+```
+
+
+
+## Setup PATH for CLI use
+
+The `markdown2html` command can be found in the `./bin` directory.
+
+You can link to this file in a directory in your `PATH`, or add that directory to your `PATH`.
--- a/docs/markdown2html/index.md
+++ b/docs/markdown2html/index.md
@ -0,0 +1,18 @@
+---
+title: markdown2html | doc-utils
+layout: main.html
+---
+
+///
+[doc-utils](index.html)
+///
+
+# markdown2html {#/}
+
+_todo_
+
+- [Source Code {:external-link:}](https://gitea.jbrumond.me/doc-utils/markdown2html)
+- [Building From Source](markdown2html/building-from-source.html)
+- [Configuration](markdown2html/configuration.html)
+- [Markdown Format](markdown2html/markdown-format.html)
+
--- a/docs/markdown2html/markdown-format.md
+++ b/docs/markdown2html/markdown-format.md
@ -0,0 +1,303 @@
+---
+title: Markdown Format | markdown2html | doc-utils
+layout: main.html
+---
+
+///
+[doc-utils](index.html)
+[markdown2html](markdown2html/index.html)
+///
+
+# Markdown Format {#/}
+
+This document describes the extensions added on top of [Marked {:external-link:}](https://marked.js.org/) by [markdown2html].
+
+<outline-inline content-root="#root > main"></outline-inline>
+
+
+
+
+## KaTeX
+
+Math typesetting can be done using [KaTeX {:external-link:}](https://katex.org/), wrapped in a back-tick-fenced block.
+
+````md
+```katex "_fig. 1: an example math block_"
+a^2 + b^2 = c^2
+```
+````
+
+!!! {.markdown-example-output}
+```katex "_fig. 1: an example math block_"
+a^2 + b^2 = c^2
+```
+!!!
+
+Inline expressions can also be wrapped in `$`, for example:
+
+```md
+$x$ to the second power is written as $x^2$
+```
+
+!!! {.markdown-example-output}
+$x$ to the second power is written as $x^2$
+!!!
+
+
+
+
+
+## Prism Highlighting
+
+[Prism {:external-link:}](https://prismjs.com/) is used to provide syntax highlighting for 290+ languages.
+
+Highlighted code blocks can be displayed in the usual way using a fenced block:
+
+````md
+```ts "_fig. 2: some example TypeScript code_"
+function say_hello() {
+  console.log('Hello, World!');
+}
+```
+````
+
+!!! {.markdown-example-output}
+```ts "_fig. 2: some example TypeScript code_"
+function say_hello() {
+  console.log('Hello, World!');
+}
+```
+!!!
+
+As is done throughout this document to show examples, you can also nest code blocks by adding additional back-ticks to the outer levels. For example, the sample above is created like this:
+
+`````md
+````md
+```ts "_fig. 2: some example TypeScript code_"
+function say_hello() {
+  console.log('Hello, World!');
+}
+```
+````
+`````
+
+
+
+
+## Feather Icons
+
+[Feather Icons {:external-link:}](https://feathericons.com/) can be rendered using tokens that look like `{:icon-name:}`.
+
+```md
+{:feather:} {:external-link:} {:alert-triangle:}
+```
+
+!!! {.markdown-example-output}
+{:feather:} {:external-link:} {:alert-triangle:}
+!!!
+
+
+
+
+## Highlighting
+
+Text can be highlighted with the [`<mark>` tag {:external-link:}](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark) by wrapping it in double equals signs (`==`):
+
+```md
+This is some ==highlighted text==.
+```
+
+!!! {.markdown-example-output}
+This is some ==highlighted text==.
+!!!
+
+
+
+
+
+
+
+## Pikchr Diagrams
+
+[Pikchr {:external-link:}](https://pikchr.org/home/doc/trunk/homepage.md) can be used to render diagrams, which is also written using fenced blocks.
+
+````md
+```pikchr "_fig. 6: an example diagram rendered with Pikchr, based on the docs2website flow_"
+MD:     box wid 1.2 ht 0.5 "Markdown"
+HTML:   box same at 2.5 east of MD "HTML Fragments"
+COLOR:  box same at 0.75 north of HTML "Color Themes"
+ASSET:  box same at 0.75 south of HTML "Static Assets"
+WEB:    box same at 2 east of HTML "Static Website" fill green color green
+
+arrow from MD .e to HTML .w \
+  "markdown2html" italic aligned above small
+
+arrow from COLOR .e to WEB .nw color green
+arrow from HTML .e to WEB .w color green
+arrow from ASSET .e to WEB .sw color green
+```
+````
+
+!!! {.markdown-example-output}
+```pikchr "_fig. 6: an example diagram rendered with Pikchr, based on the docs2website flow_"
+MD:     box wid 1.2 ht 0.5 "Markdown"
+HTML:   box same at 2.5 east of MD "HTML Fragments"
+COLOR:  box same at 0.75 north of HTML "Color Themes"
+ASSET:  box same at 0.75 south of HTML "Static Assets"
+WEB:    box same at 2 east of HTML "Static Website" fill green color green
+
+arrow from MD .e to HTML .w \
+  "markdown2html" italic aligned above small
+
+arrow from COLOR .e to WEB .nw color green
+arrow from HTML .e to WEB .w color green
+arrow from ASSET .e to WEB .sw color green
+```
+!!!
+
+The following color names are mapped to CSS variables to enable theming:
+
+- red $\mapsto$ `--theme-chart-shape-red-fill` and `--theme-chart-shape-red-line`
+- orange $\mapsto$ `--theme-chart-shape-orange-fill` and `--theme-chart-shape-orange-line`
+- yellow $\mapsto$ `--theme-chart-shape-yellow-fill` and `--theme-chart-shape-yellow-line`
+- green $\mapsto$ `--theme-chart-shape-green-fill` and `--theme-chart-shape-green-line`
+- teal $\mapsto$ `--theme-chart-shape-teal-fill` and `--theme-chart-shape-teal-line`
+- pink $\mapsto$ `--theme-chart-shape-pink-fill` and `--theme-chart-shape-pink-line`
+- purple $\mapsto$ `--theme-chart-shape-purple-fill` and `--theme-chart-shape-purple-line`
+- blue $\mapsto$ `--theme-chart-shape-blue-fill` and `--theme-chart-shape-blue-line`
+- indigo $\mapsto$ `--theme-chart-shape-indigo-fill` and `--theme-chart-shape-indigo-line`
+- magenta $\mapsto$ `--theme-chart-shape-magenta-fill` and `--theme-chart-shape-magenta-line`
+- brown $\mapsto$ `--theme-chart-shape-brown-fill` and `--theme-chart-shape-brown-line`
+- black $\mapsto$ `--theme-text-body`, `--theme-bg-heavy`, and `--theme-line`
+
+
+
+
+## nomnoml Diagrams
+
+_todo_
+
+
+
+
+
+## Bytefield Diagrams
+
+_todo_
+
+
+
+
+
+## QR Codes
+
+_todo_
+
+
+
+
+## Footnotes
+
+_todo_
+
+
+
+
+## Vega Charts
+
+_todo_
+
+
+
+
+
+## Breadcrumb Navigation
+
+_todo_
+
+```md
+///
+[Foo](#foo)
+[Bar](#bar)
+[Baz](#baz)
+///
+```
+
+!!! {.markdown-example-output}
+///
+[Foo](#foo)
+[Bar](#bar)
+[Baz](#baz)
+///
+!!!
+
+
+
+
+
+
+## Sample Output
+
+Fenced blocks with the `samp` "language" tag output contents in a [`<samp>` {:external-link:}](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp) tag rather than the typical `<code>` tag, to more semantically markup output examples from code.
+
+````md
+```samp "_fig. 4: some sample output, rendered with a &lt;samp> tag_"
+This is some sample output
+```
+````
+
+!!! {.markdown-example-output}
+```samp "_fig. 4: some sample output, rendered with a &lt;samp> tag_"
+This is some sample output
+```
+!!!
+
+A combination `bash:samp` fenced block can be used to include shell commands followed by sample output:
+
+````md
+```bash:samp "_fig. 5: a combination bash:samp block that outputs a &lt;code> and &lt;samp> together_"
+echo 'This is some sample output' && \
+  echo 'This is another line of sample output'
+This is some sample output
+This is another line of sample output
+```
+````
+
+!!! {.markdown-example-output}
+```bash:samp "_fig. 5: a combination bash:samp block that outputs a &lt;code> and &lt;samp> together_"
+echo 'This is some sample output' && \
+  echo 'This is another line of sample output'
+This is some sample output
+This is another line of sample output
+```
+!!!
+
+
+
+
+
+## Attribute Annotations
+
+Some markdown elements allow for attributes to be appended in a curly-brace (`{ }`) wrapped block.
+
+The braces contain a space-delimeted list attributes to assign to the rendered attribute, identified as either:
+
+- An `id` attribute, prefixed by a `#` character,
+- A `class` attribute value, prefixed by `.` character,
+- Or, another, named attribute prefixed by a `:` character
+
+```md
+# Heading {#new-id .some .class .names :data-foo=bar}
+```
+
+
+
+
+
+
+
+
+
+[docs2website]: docs2website/index.html
+[markdown2html]: markdown2html/index.html
+