# Plugins > Turn Docsy's optional scripts on or off and load your own from site configuration, no layout overrides needed. --- LLMS index: [llms.txt](/llms.txt) --- Docsy loads some of its optional JavaScript features, and any script you add, as **plugins**: entries under `params.docsy.plugins` in your site configuration. ## Configure Docsy's plugins | Plugin | What it does | Default | Loads on | Docs | | ----------------- | ------------------------------------------ | --------------------------------------- | --------------------------------------------------- | ------------------------------ | | `click-to-copy` | Adds a copy button to code blocks | On (off under Prism, which has its own) | Every page | [Copy to clipboard][] | | `tabpane-persist` | Remembers the selected tab across pages | On | Every page ([why](#page-flags-in-included-content)) | [`tabpane`][] | | `markmap` | Renders `markmap` code blocks as mind maps | Off | Pages with a `markmap` code block | [Activating MarkMap support][] | To turn a plugin off, set its entry to `false`:

[params.docsy.plugins]
click-to-copy = false

params:
  docsy:
    plugins:
      click-to-copy: false

{
  "params": {
    "docsy": {
      "plugins": { "click-to-copy": false }
    }
  }
}

## Configuration reference Docsy's own plugins are declared in the theme's [`hugo.yaml`][theme-defaults]; your entries merge over them by name and field ([Configuration § Theme defaults][config-merge]). Each entry's fields, types, and defaults: ```yaml # Schema of `params.docsy`, the namespace Docsy reserves for theme settings. type: map keys: plugins: type: map # keyed by plugin name; a scalar false turns an entry off key: pattern: ^[a-z0-9_-]+$ reservedSuffix: _docsy-shim entry: enable: { type: bool, default: true } defer: { type: bool, default: false } # adds `defer` to the script tag pageGate: { type: string, default: '' } # a .Page.Store flag; '' = none weight: { type: int, default: 0 } # emission order, ascending, then name options: { type: map, default: {} } # reaches the module as @params ``` - `{}` in place of an entry keeps every default. - `enable` is off for `false`, `"false"`, and `0`, and on for any other value; `defer` is on for `true`, `"true"`, and `1`, and off for any other value. The string forms exist for [environment overrides][config-env]. ### Warnings Every registry shape warning carries the id `docsy-config` (to silence one, see [Configuration § Configuration warnings][config-warnings]): - An unknown field or a non-map `options` is ignored and the rest of the entry applies. - A name the schema's pattern rejects or that ends in its reserved suffix, or a scalar entry other than a false spelling, drops the whole entry. - A `params.docsy` or `params.docsy.plugins` that is not a map empties the registry, Docsy's own plugins and their deprecated aliases included. `plugins: {}` keeps them; a valueless `plugins:` is null and drops them. - An enabled name with no script file ([Plugin files](#plugin-files)) is a different fault: it warns `docsy-plugin-missing`, gated or not (a disabled entry is never looked up). ## Add a custom script For a script that should load at the end of every page, register it as a plugin; for markup in ``, inline snippets, or third-party tags, use the [head and body hooks][] instead. 1. Save the script as `assets/js/plugins/`_`NAME`_`.js`, with _`NAME`_ in lowercase. 2. Register it under `params.docsy.plugins` ([configuration reference](#configuration-reference)):

[params.docsy.plugins]
NAME = {}

params:
  docsy:
    plugins:
      NAME: {}

{
  "params": {
    "docsy": {
      "plugins": { "NAME": {} }
    }
  }
}

### Plugin files A plugin is one to three files. A project file shadows the theme's of the same name, which is how you replace one of Docsy's plugins or its companions. | File | Contract | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `assets/js/plugins/`_`NAME`_`.js` | Required. Built on its own with [`js.Build`][]; `options` reach it as [`@params`][]. | | `layouts/_partials/scripts/plugins/`_`NAME`_`.html` | Optional companion partial for vendored libraries, markup, or configuration; receives `(dict "Page" PAGE "Plugin" ENTRY)`. | | `assets/scss/plugins/`_`NAME`_`.scss` | Optional companion stylesheet, through the Sass pipeline. | Companions emit before the script ([why][design-ordering]). Script and stylesheet tags carry [subresource integrity][SRI] in every environment. Entry keys reach templates and plugin scripts lowercase: `.Plugin.pagegate`, `params.apikey` ([Configuration § Key spelling][config-keys]). ### Security - Never pipe `.Plugin.options` through `safeHTML`, `safeJS`, or `safeURL` in a companion partial: options are site-configured strings, and Hugo's contextual autoescaping is the defense. - In a plugin script, options are values, not markup: set them through DOM and CSSOM properties, never by building HTML or stylesheet text around them (an option interpolated into a `