Config

Table of contents

• Types of config
• Specifying config
• Config JSON
• docset
• docset.url_prefix
• docset.filters
• docset.editions
• docset.index_patterns
• rendering
• rendering.plugins

Types of config

Rendering config:

• Which plugins should be used?
• ...and with what options?
• ...and in which order?

Docset config:

• Given a file tree (from a dir or a zip file), which files should be considered Docs?
• How are the "index" docs determined? index.md? _DIRNAME.md?
• When rendering a website from this docset, what should the URL prefix be for the
  link rel="canonical" element?
• Should the Markdown be filtered to a publication-ready subset, indicated by adding a custom marker to your code underneath the prod-ready subset, e.g.
  <!--🟩🟩🟩 ^ prod 🟩🟩🟩-->?

Specifying config

Specify config by doing at most one of the following:

Config JSON

Example:

{
    "docset": {
        "url_prefix": "https://example.org/foo/",
        "filters": {},
        "editions": [
            {
                "name": "prod",
                "default": true,
                "filters": {
                    "only_include_content_above_this_marker": "\n<!--🟩🟩🟩 ^ prod 🟩🟩🟩-->\n"
                }
            },
            {
                "name": "draft",
                "filters": {}
            }
        ],
        "index_patterns": ["_DIRNAME.md", "index.md", "landing.md"]
    },
    "rendering": {
        "plugins": [
            "foo",
            ["bar", {"some_option_for_bar": 123}]
        ]
    }
}

docset

type DocsetConfig = {
    url_prefix?: string,
    filters?: FiltersConfig,
    editions?: EditionConfig[],
    index_patterns?: string[],
}

docset.url_prefix

e.g. "https://example.org/foo/"

docset.filters

type FiltersConfig = {
    only_include_content_above_this_marker: string,
    only_include_paths_matching_these_globs: string[],
    also_exclude_paths_matching_these_globs: string[],
}

docset.editions

type EditionConfig = {
    name: string,
    default?: bool,
    filters?: FiltersConfig,
}

docset.index_patterns

e.g.

{
    "docset": {
        "index_patterns": ["_DIRNAME.md", "index.md", "landing.md"]
    }
}

When searching for a file to represent a dir as that dir's index, the patterns in this list are attempted in the order that they are specified.

_DIRNAME.md is a special case that means "_" + name_of_dir.toUpperCase() + ".md":js

rendering

type RenderingConfig = {
    plugins?: PluginConfig[]
}
type PluginConfig = (
    string |    // e.g. "some-plugin"
    array       // e.g. ["some-plugin", {...plugin config...}]
);

rendering.plugins

e.g.

{
    "rendering": {
        "plugins": [
            "foo",
            ["bar", {"some_option_for_bar": 123}]
        ]
    }
}