137 lines
4.2 KiB
Markdown
137 lines
4.2 KiB
Markdown
---
|
|
title: doc-utils
|
|
layout: main.html
|
|
---
|
|
|
|
# doc-utils {#-}
|
|
|
|
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
|
|
- 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]
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
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 {: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% \
|
|
fill indigo color indigo
|
|
|
|
OAPI: box "OpenAPI Spec" same \
|
|
at 0.75 south of JSCH
|
|
|
|
CSBOM: box "CycloneDX SBOM" same \
|
|
at 0.75 south of OAPI
|
|
|
|
LD: box "L-D Context" same \
|
|
at 0.75 south of CSBOM
|
|
|
|
ETC: box "Etc..." same \
|
|
at 0.75 south of LD \
|
|
dashed
|
|
|
|
MD: box "Markdown" same as JSCH \
|
|
at 3 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 \
|
|
fill purple color purple
|
|
|
|
ASSET: box "Static Assets" same \
|
|
at 0.75 south of HTML \
|
|
fill blue color blue
|
|
|
|
WEB: box "Static Website" same \
|
|
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 color green \
|
|
behind HTML
|
|
|
|
text "docs2website" italic small above at SITE.s
|
|
|
|
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 \
|
|
color indigo
|
|
|
|
arrow from CSBOM .e to MD .w \
|
|
"cyclonedxsbom2markdown" italic aligned above small \
|
|
color indigo
|
|
|
|
arrow from LD .e to 0.1 below MD .w \
|
|
"ldcontext2markdown" italic aligned above small \
|
|
color indigo
|
|
|
|
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 \
|
|
color yellow
|
|
|
|
arrow from COLOR .e to 0.1 east of WEB .nw \
|
|
color green
|
|
|
|
arrow from HTML .e to WEB .w \
|
|
color green
|
|
|
|
arrow from ASSET .e to 0.1 east of WEB .sw \
|
|
color green
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
<!-- Link Details -->
|
|
|
|
[docs2website]: docs2website/index.html
|
|
[color-themes]: color-themes/index.html
|
|
[markdown2html]: markdown2html/index.html
|
|
[openapi2markdown]: openapi2markdown/index.html
|
|
[jsonschema2markdown]: jsonschema2markdown/index.html
|
|
[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
|