Schematize Reference Maps

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.

Metadata

ID

https://platen.io/schemas/schematize/site/reference_map/schema.json

Type

object

JSON Schema

Definition
{
  "$id": "https://platen.io/schemas/schematize/site/reference_map/schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Defines a map of reference targets for schematized documentation.\n\nhttps://platen.io/schemas/schematize/site/reference_map/",
  "patternProperties": {
    "^[^sref].*$": {
      "$ref": "https://platen.io/schemas/schematize/site/reference_map/schema.json",
      "description": "Defines a nested schema reference map\n\nhttps://platen.io/schemas/schematize/site/reference_map/#^[^sref].*$",
      "title": "Nested Schema Reference Map"
    }
  },
  "properties": {
    "sref_base": {
      "description": "The base URL to prefix sref values with for this target.\n\nhttps://platen.io/schemas/schematize/site/reference_map/#sref_base",
      "title": "Base URL",
      "type": "string"
    },
    "sref_suffix": {
      "description": "Markdown text to add after input text when rendering an sref shortcode\n\nhttps://platen.io/schemas/schematize/site/reference_map/#sref_suffix",
      "title": "Postfix Markdown",
      "type": "string"
    }
  },
  "title": "Schematize Reference Map",
  "type": "object"
}

Postfix Markdown (sref_suffix)

Specifies Markdown text to add after input text when rendering an sref shortcode.

Metadata

Type

string

Base URL (sref_base)

Specifies the base URL to prefix sref values with for this target. Leaf nodes in the map (ones that don’t define a nested map) must define this value or they can’t be used to reference external documentation.

Metadata

Type

string

Pattern Properties

Schematize Reference Map (pattern-not-builtin)

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