README.md

dyy ~ Document Your YAML

A Go program that generates beautiful HTML docs for YAML configs with a side-by-side layout. Makes it easier for programmers to document the YAML and easier for users to understand that YAML.

Full working example: https://mlrd.tech/docs/v0-beta/config/table/

Usage

$ go run main.go config.yaml docs.md > partial.md

YAML comment "# Foo" matches Markdown docs header "# Foo". YAML comments that end with {xyz} get a <a name="xyz"> anchor so https://.../#xyz works, too.

Top-level YAML sections must be separated by an empty line, like:

section1: # First {premiere}
  foo: "..."

section2: # Second {deuxieme}
  bar: 0

With Hugo, requires HTML rendering in Markdown:

markup:
  goldmark:
    renderer:
      unsafe: true

Example

mlrd docs use Hugo, so this requires assets, shortcodes, and partials.

Assets:

• table-config-v0-beta.yaml - YAML config file
• table-config-v0-beta.md - Docs
• _custom.scss - dyy.css (and other custom CSS)

Programmers edit the YAML and Markdown docs (and sometimes the CSS); the reset is auto-generated with dyy and live-reloaded with Hugo.

Content: table.md

Since Hugo content cannot include partials, a shortcut is needed:

Shortcode: table-config.md

That shortcode includes the HTML/Markdown partial that dyy generates:

Partial: table-config-v0-beta.md

Compile the assets to generate the partial:

go run main.go \
  ../website/docs/assets/table-config-v0-beta.yaml \
  ../website/docs/assets/table-config-v0-beta.md \
> ../website/docs/layouts/partials/table-config-v0-beta.md

Result: nicely presented, documented YAML config file. Now whether or not anyone actually reads the docs...