Configuration

Site Configuration (config)

The Schematize module makes it easier to author and publish JSON schemas with documentation from YAML files. These settings effect the way the schemas are munged and how the documentation is rendered.

JSON Schema

Definition
{
  "$id": "https://platen.io/modules/schematize/config/site/config/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Settings and options for the Schematize module at the site level.\n\nhttps://platen.io/modules/schematize/config/site/config/",
  "properties": {
    "reference_map": {
      "$ref": "https://platen.io/modules/schematize/config/site/reference_map/schema.json"
    }
  },
  "title": "Site Configuration",
  "type": "object"
}

Schematize Reference Map (reference_map)

Schematize includes the sref shortcode and link renderer, which you can use to more easily reference documentation. An entry in the sref_map defines information for the shortcode and renderer to use when referencing external documentation.

The sref_base setting defines the base URL for the reference. The sref_suffix setting defines an optional automatic postix to add to the link text when using the shortcode and is ignored by the link renderer.

You can arbitrarily nest maps within each other to keep references from the same source but with different base URLs together in a usable way.

For example, you could define a map for Mozilla’s web documentation like this:

schematize:
  reference_map:
    mdn:
      sref_suffix: in the MDN documentation
      sref_base: https://developer.mozilla.org/docs
      css:
        sref_base: https://developer.mozilla.org/docs/Web/CSS

And then access it with in the link reference:

Checkout [sref:`text-decoration`] in the MDN documentation.

[sref:`text-decoration`]: mdn.css:text-decoration

Which turns into:

Checkout text-decoration in the MDN documentation.

For more information, see Schematize Reference Map

Edit this page