From 9391a4271871b5e37567f15bb289e64200e81432 Mon Sep 17 00:00:00 2001 From: James Brumond Date: Sat, 13 May 2023 20:30:29 -0700 Subject: [PATCH] more docs --- docs/_assets/base.css | 9 + docs/color-themes/index.md | 6 +- docs/color-themes/preview.md | 8 +- docs/color-themes/schema/v1.yaml | 248 ++++++++++++++++++-------- docs/docs2website/command-line-use.md | 19 ++ docs/docs2website/index.md | 11 +- docs/docs2website/programatic-use.md | 23 +++ docs/markdown2html/index.md | 2 +- layouts/main.html | 2 + layouts/preview-color-themes.html | 2 + partials/breadcrumb.html | 9 + 11 files changed, 251 insertions(+), 88 deletions(-) create mode 100644 partials/breadcrumb.html diff --git a/docs/_assets/base.css b/docs/_assets/base.css index df2f737..4479852 100644 --- a/docs/_assets/base.css +++ b/docs/_assets/base.css @@ -257,6 +257,8 @@ body[data-color-transition-enabled] :is( padding: 1rem; padding-block-end: 5rem; z-index: 1; + max-width: 100rem; + margin-inline: auto; } @media screen and (min-width: 60rem) { @@ -895,6 +897,13 @@ nav[aria-label="breadcrumbs"] li { padding: 0.25rem; } +nav[aria-label="breadcrumbs"] li:not(:first-of-type) ::before { + display: inline-block; + content: '/'; + padding-inline-end: 0.25rem; + color: var(--theme-text-body); +} + diff --git a/docs/color-themes/index.md b/docs/color-themes/index.md index 6bc970f..5dc9b2d 100644 --- a/docs/color-themes/index.md +++ b/docs/color-themes/index.md @@ -11,6 +11,10 @@ layout: main.html _todo_ -[Preview Color Themes](color-themes/preview.html) +- [Preview Color Themes](color-themes/preview.html) +## JSON Schema +- [HTML Webpage](color-themes/schema/v1.html) +- [JSON](color-themes/schema/v1.json) +- [Yaml](color-themes/schema/v1.yaml) diff --git a/docs/color-themes/preview.md b/docs/color-themes/preview.md index ef4b584..e7f50f4 100644 --- a/docs/color-themes/preview.md +++ b/docs/color-themes/preview.md @@ -1,13 +1,11 @@ --- title: Preview Color Themes | doc-utils layout: preview-color-themes.html +breadcrumb: +- '[doc-utils](index.html)' +- '[color-themes](color-themes/index.html)' --- -/// -[doc-utils](index.html) -[color-themes](color-themes/index.html) -/// - # Sample Content Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec ultricies odio. Praesent vitae urna placerat, pellentesque nibh auctor, gravida orci. Mauris nisi dui, pharetra id nisi quis, placerat vehicula nisl. Sed non enim sit amet diam venenatis suscipit. Proin sit amet fringilla dui, nec volutpat tellus. Suspendisse id sodales turpis, suscipit congue felis. Ut sed sodales lorem. Pellentesque vel felis et ipsum gravida tempus ut eget tellus. Ut elementum elementum tristique. Etiam accumsan ultrices mauris, mollis pellentesque ante efficitur in. Quisque non neque porttitor, tincidunt arcu porttitor, tincidunt turpis. Nullam eu ultrices ex, vitae hendrerit ipsum. diff --git a/docs/color-themes/schema/v1.yaml b/docs/color-themes/schema/v1.yaml index 0f070ae..3c389d7 100644 --- a/docs/color-themes/schema/v1.yaml +++ b/docs/color-themes/schema/v1.yaml @@ -1,33 +1,28 @@ +--- +title: Color Theme Schema | doc-utils +layout: main.html +breadcrumb: +- '[doc-utils](index.html)' +- '[color-themes](color-themes/index.html)' +--- $schema: http://json-schema.org/draft-07/schema -$id: https://gitea.jbrumond.me/minimal/docs/raw/branch/master/json-schema/color-theme/v1.json +$id: https://gitea.jbrumond.me/doc-utils/color-themes/v1.json type: object +title: Color Theme +required: +- name +- colors properties: name: type: string description: > - The name of the color theme as it should be displayed to a user - labels: - type: array - description: > - The labels field allows for categorizing color themes into high-level groupings - like "light", "dark", or "high_contrast". This is purely meta-information that is - intended to be used by applications to display color theme options with groupings - or other indicators to the user in configuration interfaces - items: - type: string - enum: - - light - - dark - - high_contrast - - low_contrast - - monochrome - - greyscale - - protanopia_safe - - deuteranopia_safe - - tritanopia_safe + The name of the color theme as it is displayed in web UI. Must match the file + name of the theme file, e.g. a theme called "example-theme" should be located + in a file called "example-theme.theme.json" colors: type: object - description: Contains the color values that will be used to populate CSS variables + description: Contains the values that will be used to populate the CSS variables + controlling the UI theme properties: # Content Background Colors bg_main: @@ -217,70 +212,34 @@ properties: chart_guideline: $ref: "#/definitions/css_color" # todo: description - chart_shape_red_fill: + chart_data_0: $ref: "#/definitions/css_color" # todo: description - chart_shape_red_line: + chart_data_1: $ref: "#/definitions/css_color" # todo: description - chart_shape_orange_fill: + chart_data_2: $ref: "#/definitions/css_color" # todo: description - chart_shape_orange_line: + chart_data_3: $ref: "#/definitions/css_color" # todo: description - chart_shape_yellow_fill: + chart_data_4: $ref: "#/definitions/css_color" # todo: description - chart_shape_yellow_line: + chart_data_5: $ref: "#/definitions/css_color" # todo: description - chart_shape_green_fill: + chart_data_6: $ref: "#/definitions/css_color" # todo: description - chart_shape_green_line: + chart_data_7: $ref: "#/definitions/css_color" # todo: description - chart_shape_teal_fill: + chart_data_8: $ref: "#/definitions/css_color" # todo: description - 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: + chart_data_9: $ref: "#/definitions/css_color" # todo: description @@ -353,36 +312,38 @@ 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 @@ -400,18 +361,147 @@ 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 - # 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 + - 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 - type: string + title: 'Named Colors: CSS Level 4' enum: - rebeccapurple diff --git a/docs/docs2website/command-line-use.md b/docs/docs2website/command-line-use.md index e69de29..01e8398 100644 --- a/docs/docs2website/command-line-use.md +++ b/docs/docs2website/command-line-use.md @@ -0,0 +1,19 @@ +--- +title: Command Line Use | docs2website +layout: main.html +--- + +/// +[doc-utils](index.html) +[docs2website](docs2website/index.html) +/// + +# Command Line Use {#/} + +Command line use is very straight-forward, as there is only one valid way to call the command: + +```bash +docs2website +``` + +The `` parameter should refer to a file containing [the configuration](docs2website/configuration.html) to build with. diff --git a/docs/docs2website/index.md b/docs/docs2website/index.md index 77553e5..8ae4ed6 100644 --- a/docs/docs2website/index.md +++ b/docs/docs2website/index.md @@ -9,9 +9,16 @@ layout: main.html # docs2website {#/} -_todo_ +The [docs2website] project is a static site generator primarily focused on technical writing and documentation. -- [Source Code {:external-link:}](https://gitea.jbrumond.me/doc-utils/docs2website) - [Building From Source](docs2website/building-from-source.html) - [Configuration](docs2website/configuration.html) +- [Command Line Use](docs2website/command-line-use.html) +- [Programatic Use](docs2website/programatic-use.html) - [Preview Built-in Color Themes](color-themes/preview.html) +- [Source Code {:external-link:}](https://gitea.jbrumond.me/doc-utils/docs2website) + + + + +[docs2website]: docs2website/index.html diff --git a/docs/docs2website/programatic-use.md b/docs/docs2website/programatic-use.md index e69de29..545dd68 100644 --- a/docs/docs2website/programatic-use.md +++ b/docs/docs2website/programatic-use.md @@ -0,0 +1,23 @@ +--- +title: Programatic Use | docs2website +layout: main.html +--- + +/// +[doc-utils](index.html) +[docs2website](docs2website/index.html) +/// + +# Programatic Use {#/} + +_todo_ + +```ts +import { read_config, build_docs_project } from '@doc-utils/docs2website'; + +// Read and validate a configuration file +const config = await read_config('path/to/config.yaml'); + +// Build a project with the given configuration +await build_docs_project(config); +``` diff --git a/docs/markdown2html/index.md b/docs/markdown2html/index.md index 29f0604..5c4f5b5 100644 --- a/docs/markdown2html/index.md +++ b/docs/markdown2html/index.md @@ -13,6 +13,6 @@ _todo_ - [Source Code {:external-link:}](https://gitea.jbrumond.me/doc-utils/markdown2html) - [Building From Source](markdown2html/building-from-source.html) -- [Configuration](markdown2html/configuration.html) +- [Command Line Use](markdown2html/command-line-use.html) - [Markdown Format](markdown2html/markdown-format.html) diff --git a/layouts/main.html b/layouts/main.html index 2ee0f90..a22a077 100644 --- a/layouts/main.html +++ b/layouts/main.html @@ -19,6 +19,8 @@ {{/ page.outline_button }}
+{{> breadcrumb.html }} +
{{> .content }}
diff --git a/layouts/preview-color-themes.html b/layouts/preview-color-themes.html index da73caf..5b80337 100644 --- a/layouts/preview-color-themes.html +++ b/layouts/preview-color-themes.html @@ -117,6 +117,8 @@
+{{> breadcrumb.html }} +
{{> .content }}
diff --git a/partials/breadcrumb.html b/partials/breadcrumb.html new file mode 100644 index 0000000..bdfa705 --- /dev/null +++ b/partials/breadcrumb.html @@ -0,0 +1,9 @@ +{{# page.breadcrumb.length }} + +{{/ page.breadcrumb.length }} \ No newline at end of file