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/modules/schematize/config/site/reference_map/schema.json
Type: object

JSON Schema

Definition

{
  "$id": "https://platen.io/modules/schematize/config/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/modules/schematize/config/site/reference_map/",
  "patternProperties": {
    "^[^sref].*$": {
      "$ref": "https://platen.io/modules/schematize/config/site/reference_map/schema.json",
      "description": "Defines a nested schema reference map\n\nhttps://platen.io/modules/schematize/config/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/modules/schematize/config/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/modules/schematize/config/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`)

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

JSON Schema

Postfix Markdown (sref_suffix)

Base URL (sref_base)

Pattern Properties

Schematize Reference Map (pattern-not-builtin)

Postfix Markdown (`sref_suffix`)

Base URL (`sref_base`)

Schematize Reference Map (`pattern-not-builtin`)