diff --git a/config.yaml b/config.yaml index 85b31b3..4f4adb3 100644 --- a/config.yaml +++ b/config.yaml @@ -28,6 +28,7 @@ input: - ./**/*.schema.json schema+yaml: - ./**/*.schema.{yaml,yml} + - ./color-themes/schema/*.yaml # Files to be parsed as OpenAPI V3 specifications and rendered # to HTML documentation. Additionally, the original JSON / Yaml diff --git a/docs/_assets/color-theme-preview.css b/docs/_assets/color-theme-preview.css new file mode 100644 index 0000000..ec7b1bc --- /dev/null +++ b/docs/_assets/color-theme-preview.css @@ -0,0 +1,19 @@ + +header { + margin: 1rem; + padding-block: 1rem; + padding-inline: 2rem; + border: 0.1rem solid var(--theme-line); +} + + + +/* todo: is there an easy way to generate this? */ + +body[data-color-theme='Minimal Dark'] { + {{> .themes/Minimal Dark }} +} + +body[data-color-theme='Minimal Light'] { + {{> .themes/Minimal Light }} +} diff --git a/docs/color-themes/index.md b/docs/color-themes/index.md index c5acb7d..381e8da 100644 --- a/docs/color-themes/index.md +++ b/docs/color-themes/index.md @@ -3,8 +3,12 @@ title: Color Themes | doc-utils layout: main.html --- +[doc-utils](index.html) + # Color Themes {#-} - +_todo_ + +[Preview Color Themes](color-themes/preview.html) diff --git a/docs/color-themes/preview.md b/docs/color-themes/preview.md new file mode 100644 index 0000000..09e9cfe --- /dev/null +++ b/docs/color-themes/preview.md @@ -0,0 +1,78 @@ +--- +title: Preview Color Themes | doc-utils +layout: preview-color-themes.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. + +```ts "_fig. 1: How to say hello in TypeScript_" +// hello.ts +let people_seen = 0; + +export function say_hello(say_to: string) { + console.log(`Hello, ${say_to}!`); + people_seen++; +} + + +// main.ts +import { say_hello } from './hello'; + +say_hello('Alice'); +say_hello('Bob'); +say_hello('Charlie'); +say_hello('Dave'); + +console.log(`We said hello to ${people_seen} people`); +``` + +Ut cursus erat id iaculis molestie. Praesent rhoncus rhoncus vehicula. Suspendisse non cursus ante. Donec finibus nec nulla vitae ultrices. Duis vel erat in orci feugiat varius vel tempor sem. Duis ornare eget urna vel ultrices. Ut [gravida scelerisque](#) ante. Etiam ultrices ex sit amet est convallis interdum. Sed augue est, consectetur ut scelerisque nec, fringilla eget sem. Mauris suscipit vestibulum tortor et rhoncus. Aliquam pretium enim a lacus efficitur, sed ornare tellus auctor. Nunc a tristique ligula. + +## An Interesting Sub-Section + +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" + +arrow from MD .e to HTML .w \ + "markdown2html" italic aligned above small + +arrow from COLOR .e to WEB .nw +arrow from HTML .e to WEB .w +arrow from ASSET .e to WEB .sw +``` + +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. + +### An Even More Interesting Sub-Sub-Section + +Suspendisse sapien libero, facilisis sit amet ex sed, hendrerit rhoncus turpis. Fusce blandit arcu et justo molestie, ac porttitor metus vestibulum. Proin posuere dui eu euismod molestie. In sed purus nec nibh auctor efficitur. Vestibulum vehicula, augue elementum lobortis egestas, justo erat dictum urna, quis placerat dolor eros nec ex. Sed vulputate eros eget dolor tincidunt aliquam. Vestibulum rhoncus odio magna, non mollis ipsum tristique ut. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Fusce pretium lorem justo, vel cursus quam gravida eget. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Vestibulum ullamcorper justo eu leo aliquam, id dictum mauris sollicitudin. Ut in tincidunt velit. Nam id auctor justo. + +```katex "_fig. 3: Math! D:_" +{(ax + by + x)^2 \over {a^2 + b^2}} = (x - f_1)^2 + (y - f_2)^2 +\\\mathstrut\\ +\KaTeX +``` + + + +## Donec quis laoreet nisl, vel + +Aliquam lacinia elementum velit in maximus. Maecenas et mi dapibus, vehicula augue sit amet, dapibus sapien. Aliquam sit amet rhoncus risus. Vestibulum pulvinar odio at maximus commodo. Quisque nec lectus non dui elementum sollicitudin. Integer purus risus, facilisis vitae magna sed, pellentesque suscipit libero. Duis commodo eu est eu cursus. Vivamus feugiat neque erat, nec mollis purus vulputate non. Integer consectetur purus urna, et molestie magna sollicitudin eget. + +Etiam scelerisque vitae lacus eu cursus. Mauris dictum, arcu vitae fermentum congue, turpis tellus tempus erat, eu egestas elit justo vitae velit. Nam mattis, magna vitae laoreet tincidunt, enim nibh scelerisque justo, ac fringilla mauris ipsum eget odio. Cras porta lacus et ipsum auctor venenatis. Maecenas nisi ante, interdum vehicula metus efficitur, vulputate semper elit. Aliquam ut convallis tortor. Phasellus eu dui vitae mi sagittis iaculis a sit amet massa. + +### Nulla mollis diam vel lectus + +Mauris vel erat id dui hendrerit pellentesque. Cras ac elit vehicula, volutpat magna sit amet, commodo purus. Fusce iaculis erat nec placerat laoreet. Ut pulvinar ac urna vitae porttitor. In iaculis quam nec nisi fermentum placerat. Etiam eu faucibus mauris. Mauris vulputate rutrum orci ac semper. Nam cursus tempor lorem, et accumsan ex semper elementum. Nulla fermentum eros odio, nec gravida tellus rutrum eget. Sed molestie dui ac convallis faucibus. Vestibulum commodo tortor non tincidunt tempus. Morbi ut tincidunt sem. Nunc tortor nibh, scelerisque nec lacus eget, tempor porttitor lacus. Nunc eros lorem, pharetra sed purus et, pharetra egestas ante. + +Aliquam erat volutpat. Aliquam erat volutpat. Nam blandit, est at viverra maximus, sem leo gravida ipsum, eget congue eros eros eu sapien. Nunc euismod nec lorem vel scelerisque. Curabitur eu porttitor velit, ac viverra ipsum. Integer id erat dignissim, ultrices mauris in, consequat quam. Nullam leo enim, ullamcorper ac est vitae, malesuada commodo purus. Suspendisse facilisis posuere cursus. Nam pharetra ultrices magna et molestie. diff --git a/docs/color-themes/schema/v1.yaml b/docs/color-themes/schema/v1.yaml new file mode 100644 index 0000000..3c9c3b2 --- /dev/null +++ b/docs/color-themes/schema/v1.yaml @@ -0,0 +1,381 @@ +$schema: http://json-schema.org/draft-07/schema +$id: https://gitea.jbrumond.me/minimal/docs/raw/branch/master/json-schema/color-theme/v1.json +type: object +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 + colors: + type: object + description: Contains the color values that will be used to populate CSS variables + properties: + # Content Background Colors + bg_main: + $ref: "#/definitions/css_color" + description: > + The primary background color applied to the page as a whole. Must have good contrast against + the main copy text colors text_heading, text_body, text_light, text_link, text_link_active, + and text_link_visited + bg_light: + $ref: "#/definitions/css_color" + description: > + A lighter background color applied to content panels; Should have a relatively low contrast against + the bg_main color, providing only a light accent. Must have good contrast against the main copy text + colors text_heading, text_body, text_light, text_link, text_link_active, and text_link_visited + bg_heavy: + $ref: "#/definitions/css_color" + description: > + A heavier background color applied to content panels; Should have a relatively higher contrast against + the bg_main color, directing attention to what is "important" or "primary" content inside of it. Must + have good contrast against the main copy text colors text_heading, text_body, text_light, text_link, + text_link_active, and text_link_visited + bg_popup_mask: + $ref: "#/definitions/css_color" + # todo: description + + # + line: + $ref: "#/definitions/css_color" + # todo: description + line_safe: + $ref: "#/definitions/css_color" + # todo: description + line_warn: + $ref: "#/definitions/css_color" + # todo: description + line_danger: + $ref: "#/definitions/css_color" + # todo: description + + # Main Content Text Colors + text_heading: + $ref: "#/definitions/css_color" + description: The color of heading text + text_body: + $ref: "#/definitions/css_color" + description: The color of main / normal body copy text + text_light: + $ref: "#/definitions/css_color" + # todo: description + text_safe: + $ref: "#/definitions/css_color" + # todo: description + text_warn: + $ref: "#/definitions/css_color" + # todo: description + text_danger: + $ref: "#/definitions/css_color" + # todo: description + text_link: + $ref: "#/definitions/css_color" + description: The default color of hyperlinks + text_link_active: + $ref: "#/definitions/css_color" + description: The color of hyperlinks that are currently active / selected + text_link_visited: + $ref: "#/definitions/css_color" + description: The color of hyperlinks that have been previously visited + + # QR Codes + bg_qrcode: + $ref: "#/definitions/css_color" + description: > + The background color (i.e. typically white) of rendered QR codes + stroke_qrcode: + $ref: "#/definitions/css_color" + description: > + The stroke color (i.e. typically black) of rendered QR codes + + # Text Highlighted with + text_highlight: + $ref: "#/definitions/css_color" + description: > + The color of text highlighted using the text tag (or by using ==text== + in markdown) + bg_text_highlight: + $ref: "#/definitions/css_color" + description: > + The background color of text highlighted using the text tag (or by using + ==text== in markdown) + + # User-Selected Text + text_selection: + $ref: "#/definitions/css_color" + description: The color of text that has been selected by the user + bg_text_selection: + $ref: "#/definitions/css_color" + description: The background color of text that has been selected by the user + + # Buttons + bg_button_primary: + $ref: "#/definitions/css_color" + description: > + The background color of "primary" buttons (typically major, positive actions, like "save" + or "publish") + bg_button_primary_hover: + $ref: "#/definitions/css_color" + description: > + The background color of "primary" buttons (typically major, positive actions, like "save" + or "publish") while the user is hovering over them + text_button_primary: + $ref: "#/definitions/css_color" + description: > + The text color of "primary" buttons (typically major, positive actions, like "save" or "publish") + bg_button_secondary: + $ref: "#/definitions/css_color" + description: > + The background color of "secondary" buttons (typically safe, unimpactful, or backward moving + actions, like "cancel" or "preview") + bg_button_secondary_hover: + $ref: "#/definitions/css_color" + description: > + The background color of "secondary" buttons (typically safe, unimpactful, or backward moving + actions, like "cancel" or "preview") while the user is hovering over them + text_button_secondary: + $ref: "#/definitions/css_color" + description: > + The text color of "secondary" buttons (typically safe, unimpactful, or backward moving actions, + like "cancel" or "preview") + + # Error Boxes / Alerts + bg_error_box: + $ref: "#/definitions/css_color" + # todo: description + border_error_box: + $ref: "#/definitions/css_color" + # todo: description + text_error_box: + $ref: "#/definitions/css_color" + # todo: description + + # Inputs / Forms + bg_input: + $ref: "#/definitions/css_color" + # todo: description + border_input: + $ref: "#/definitions/css_color" + # todo: description + border_input_invalid: + $ref: "#/definitions/css_color" + # todo: description + + # Activity / Result Indicators + icon_active_indicator: + $ref: "#/definitions/css_color" + # todo: description + icon_success_indicator: + $ref: "#/definitions/css_color" + # todo: description + icon_failure_indicator: + $ref: "#/definitions/css_color" + # todo: description + icon_warning_indicator: + $ref: "#/definitions/css_color" + # todo: description + + # Semantic Accent Colors + accent_info: + $ref: "#/definitions/css_color" + # todo: description + accent_highlight: + $ref: "#/definitions/css_color" + # todo: description + accent_warning: + $ref: "#/definitions/css_color" + # todo: description + accent_problem: + $ref: "#/definitions/css_color" + # todo: description + + # Charts + chart_axis: + $ref: "#/definitions/css_color" + # todo: description + chart_text: + $ref: "#/definitions/css_color" + # todo: description + chart_guideline: + $ref: "#/definitions/css_color" + # todo: description + chart_data_0: + $ref: "#/definitions/css_color" + # todo: description + chart_data_1: + $ref: "#/definitions/css_color" + # todo: description + chart_data_2: + $ref: "#/definitions/css_color" + # todo: description + chart_data_3: + $ref: "#/definitions/css_color" + # todo: description + chart_data_4: + $ref: "#/definitions/css_color" + # todo: description + chart_data_5: + $ref: "#/definitions/css_color" + # todo: description + chart_data_6: + $ref: "#/definitions/css_color" + # todo: description + chart_data_7: + $ref: "#/definitions/css_color" + # todo: description + chart_data_8: + $ref: "#/definitions/css_color" + # todo: description + chart_data_9: + $ref: "#/definitions/css_color" + # todo: description + + # Pre-Formatted / Syntax Highlighted Code Blocks + code_normal: + $ref: "#/definitions/css_color" + # todo: description + code_shadow: + $ref: "#/definitions/css_color" + # todo: description + code_background: + $ref: "#/definitions/css_color" + # todo: description + code_selection: + $ref: "#/definitions/css_color" + # todo: description + code_comment: + $ref: "#/definitions/css_color" + # todo: description + code_punc: + $ref: "#/definitions/css_color" + # todo: description + code_operator: + $ref: "#/definitions/css_color" + # todo: description + code_const_literal: + $ref: "#/definitions/css_color" + # todo: description + code_number_literal: + $ref: "#/definitions/css_color" + # todo: description + code_boolean_literal: + $ref: "#/definitions/css_color" + # todo: description + code_tag: + $ref: "#/definitions/css_color" + # todo: description + code_string: + $ref: "#/definitions/css_color" + # todo: description + code_keyword: + $ref: "#/definitions/css_color" + # todo: description + code_func_name: + $ref: "#/definitions/css_color" + # todo: description + code_class_name: + $ref: "#/definitions/css_color" + # todo: description + code_regex_important: + $ref: "#/definitions/css_color" + # todo: description + code_variable: + $ref: "#/definitions/css_color" + # todo: description + code_builtin: + $ref: "#/definitions/css_color" + # todo: description + code_attr_name: + $ref: "#/definitions/css_color" + # todo: description + code_gutter_divider: + $ref: "#/definitions/css_color" + # todo: description + code_line_number: + $ref: "#/definitions/css_color" + # todo: description + code_line_highlight: + $ref: "#/definitions/css_color" + # todo: description +definitions: + css_color: + oneOf: + # Hex Colors + - type: string + 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 + 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 + 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 + const: transparent + # currentcolor + - type: string + const: currentcolor + # Named Colors: CSS Level 1 + - type: string + enum: + - black + - silver + - gray + - white + - maroon + - red + - purple + - fuchsia + - green + - lime + - olive + - yellow + - navy + - blue + - teal + - aqua + # Named Colors: CSS Level 2 + - type: string + enum: + - orange + # Named Colors: CSS Level 3 + - type: string + 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 + - type: string + enum: + - rebeccapurple diff --git a/docs/docs2website/building-from-source.md b/docs/docs2website/building-from-source.md new file mode 100644 index 0000000..4f8c12c --- /dev/null +++ b/docs/docs2website/building-from-source.md @@ -0,0 +1,10 @@ +--- +title: Building From Source | docs2website +layout: main.html +--- + +[doc-utils](index.html) / [docs2website](docs2website/index.html) + +# Building From Source {#-} + +_todo_ diff --git a/docs/docs2website/configuration.md b/docs/docs2website/configuration.md new file mode 100644 index 0000000..e45c6e9 --- /dev/null +++ b/docs/docs2website/configuration.md @@ -0,0 +1,10 @@ +--- +title: Configuration | docs2website +layout: main.html +--- + +[doc-utils](index.html) / [docs2website](docs2website/index.html) + +# Configuration {#-} + +_todo_ diff --git a/docs/docs2website/index.md b/docs/docs2website/index.md new file mode 100644 index 0000000..265887f --- /dev/null +++ b/docs/docs2website/index.md @@ -0,0 +1,15 @@ +--- +title: docs2website +layout: main.html +--- + +[doc-utils](index.html) + +# docs2website {#-} + +_todo_ + +- Source Code: +- [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/index.md b/docs/index.md index 389c2ff..6b3a8cd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,19 @@ layout: main.html # doc-utils {#-} -Documentation for the `doc-utils` projects. +Documentation for the doc-utils projects. + +## 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 + + + +## High-Level Architecture The [docs2website] project is a static site generator primarily focused on technical writing and documentation. It is the main culmination of all of the other projects here, and is probably what you want if you're here to create a website of some kind. @@ -13,7 +25,7 @@ The [color-themes] project contains the directory of all of the built-in color t 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. -```pikchr +```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% OAPI: box "OpenAPI Spec" same \ @@ -26,9 +38,10 @@ LD: box "L-D Context" same \ at 0.75 south of CSBOM ETC: box "Etc..." same \ - at 0.75 south of LD + at 0.75 south of LD \ + dashed -MD: box "Markdown" same \ +MD: box "Markdown" same as JSCH \ at 2.5 east of CSBOM HTML: box "HTML Fragments" same \ @@ -62,7 +75,7 @@ arrow from CSBOM .e to MD .w \ arrow from LD .e to 0.1 below MD .w \ "ldcontext2markdown" italic aligned above small -arrow from ETC .e to MD .sw +arrow from ETC .e to MD .sw dashed arrow from MD .e to HTML .w \ "markdown2html" italic aligned above small @@ -76,16 +89,6 @@ arrow from ASSET .e to WEB .sw -## 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 - - - ## Markdown Format See [Markdown Format] @@ -96,10 +99,10 @@ See [Markdown Format] -[docs2website]: ./docs2website/index.html -[color-themes]: ./color-themes/index.html -[markdown2html]: ./markdown2html/index.html -[openapi2markdown]: ./openapi2markdown/index.html -[jsonschema2markdown]: ./jsonschema2markdown/index.html -[Markdown Format]: ./markdown-format.html +[docs2website]: docs2website/index.html +[color-themes]: color-themes/index.html +[markdown2html]: markdown2html/index.html +[openapi2markdown]: openapi2markdown/index.html +[jsonschema2markdown]: jsonschema2markdown/index.html +[Markdown Format]: markdown-format.html [Marked]: https://marked.js.org/ diff --git a/layouts/main.html b/layouts/main.html index 217f68d..2ee0f90 100644 --- a/layouts/main.html +++ b/layouts/main.html @@ -3,15 +3,15 @@ {{ page.title }} - - - - - + + + + + - + {{# page.outline_button }} diff --git a/layouts/preview-color-themes.html b/layouts/preview-color-themes.html new file mode 100644 index 0000000..da73caf --- /dev/null +++ b/layouts/preview-color-themes.html @@ -0,0 +1,131 @@ + + + + + {{ page.title }} + + + + + + + + + +
+

This page can be used to preview all of the built-in color themes.

+

Select a color theme to see the sample content below in that theme.

+ + + + + + +
+ +
+
+{{> .content }} +
+ + +
+ + + \ No newline at end of file