more work on docs

2023-05-12 18:23:55 -07:00
parent b84727bd3f
commit 553316eb50
18 changed files with 761 additions and 211 deletions
--- 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
+