From 553316eb5095abcde622d6a5cd735402edf9a723 Mon Sep 17 00:00:00 2001 From: James Brumond Date: Fri, 12 May 2023 18:23:55 -0700 Subject: [PATCH] more work on docs --- config.yaml | 9 + docs/_assets/base.css | 85 ++++- docs/color-themes/index.md | 4 +- docs/color-themes/preview.md | 25 +- docs/color-themes/schema/v1.yaml | 209 ++++-------- docs/docs2website/building-from-source.md | 60 +++- .../command-line-use.md} | 0 docs/docs2website/configuration.md | 103 +++++- docs/docs2website/index.md | 6 +- docs/docs2website/programatic-use.md | 0 docs/index.md | 84 +++-- .../building-from-source.md | 0 docs/jsonschema2markdown/command-line-use.md | 0 docs/jsonschema2markdown/index.md | 0 docs/jsonschema2markdown/programatic-use.md | 0 docs/markdown2html/building-from-source.md | 66 ++++ docs/markdown2html/index.md | 18 ++ docs/markdown2html/markdown-format.md | 303 ++++++++++++++++++ 18 files changed, 761 insertions(+), 211 deletions(-) rename docs/{markdown-format.md => docs2website/command-line-use.md} (100%) create mode 100644 docs/docs2website/programatic-use.md create mode 100644 docs/jsonschema2markdown/building-from-source.md create mode 100644 docs/jsonschema2markdown/command-line-use.md create mode 100644 docs/jsonschema2markdown/index.md create mode 100644 docs/jsonschema2markdown/programatic-use.md create mode 100644 docs/markdown2html/building-from-source.md create mode 100644 docs/markdown2html/index.md create mode 100644 docs/markdown2html/markdown-format.md diff --git a/config.yaml b/config.yaml index 4f4adb3..b37d7dc 100644 --- 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 diff --git a/docs/_assets/base.css b/docs/_assets/base.css index 3ed7c40..df2f737 100644 --- 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; diff --git a/docs/color-themes/index.md b/docs/color-themes/index.md index 381e8da..6bc970f 100644 --- 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_ diff --git a/docs/color-themes/preview.md b/docs/color-themes/preview.md index 09e9cfe..ef4b584 100644 --- 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 ``` diff --git a/docs/color-themes/schema/v1.yaml b/docs/color-themes/schema/v1.yaml index 136ce99..0f070ae 100644 --- 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 diff --git a/docs/docs2website/building-from-source.md b/docs/docs2website/building-from-source.md index 4f8c12c..da7f724 100644 --- 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`. diff --git a/docs/markdown-format.md b/docs/docs2website/command-line-use.md similarity index 100% rename from docs/markdown-format.md rename to docs/docs2website/command-line-use.md diff --git a/docs/docs2website/configuration.md b/docs/docs2website/configuration.md index e45c6e9..a7d5b1b 100644 --- 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: + # +``` + + diff --git a/docs/docs2website/index.md b/docs/docs2website/index.md index 265887f..77553e5 100644 --- 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: +- [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) diff --git a/docs/docs2website/programatic-use.md b/docs/docs2website/programatic-use.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.md b/docs/index.md index 6b3a8cd..8241baa 100644 --- 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] + + - CycloneDX SBOMs: [cyclonedxsbom2markdown] + + + + + + + + +## 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] - - - @@ -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 diff --git a/docs/jsonschema2markdown/building-from-source.md b/docs/jsonschema2markdown/building-from-source.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/jsonschema2markdown/command-line-use.md b/docs/jsonschema2markdown/command-line-use.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/jsonschema2markdown/index.md b/docs/jsonschema2markdown/index.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/jsonschema2markdown/programatic-use.md b/docs/jsonschema2markdown/programatic-use.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/markdown2html/building-from-source.md b/docs/markdown2html/building-from-source.md new file mode 100644 index 0000000..a9a1391 --- /dev/null +++ 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`. diff --git a/docs/markdown2html/index.md b/docs/markdown2html/index.md new file mode 100644 index 0000000..29f0604 --- /dev/null +++ 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) + diff --git a/docs/markdown2html/markdown-format.md b/docs/markdown2html/markdown-format.md new file mode 100644 index 0000000..72ef912 --- /dev/null +++ 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]. + + + + + + +## 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 [`` 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 [`` {:external-link:}](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp) tag rather than the typical `` tag, to more semantically markup output examples from code. + +````md +```samp "_fig. 4: some sample output, rendered with a <samp> tag_" +This is some sample output +``` +```` + +!!! {.markdown-example-output} +```samp "_fig. 4: some sample output, rendered with a <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 <code> and <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 <code> and <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 +