Configuration

Three layers

Every display option is set up to three times: a plugin default, a field default, and a per-render override from the template. Each layer only changes what it names. So a site can turn line numbers on once in the plugin settings, leave them on for one field, and still switch them off for the single block where they read badly:

{{ entry.snippet.render({ lineNumbers: false }) }}

Plugin settings

Settings → Plugins → Kody.

The editor

Setting	Default
defaultLanguage	twig	The language a new Code field starts on
editorTheme	auto	auto (follows the OS), vs (light) or vs-dark
editorFontSize	14	8–32
editorMinRows	10	How many lines tall a field is before it grows to fit its content
editorMaxRows	40	The tallest a field grows before it scrolls. 0 never scrolls
editorLineNumbers	on
editorWordWrap	on
editorMinimap	off
autocomplete	on	Twig and Craft API completions in Twig fields only

Front-end rendering

Setting	Default
registerFrontendAssets	on	Kody's stylesheet. Turn off to ship your own
renderTheme	auto	auto (follows the visitor), light or dark
renderLineNumbers	off
renderCopyButton	on
renderShowLanguage	on	The language name in the caption
renderWrap	off	Soft-wrap instead of scrolling sideways
renderDedent	on	Strip the indentation every line shares
renderTrim	on	Drop blank leading and trailing lines
renderTabSize	4	0–16
renderMaxHeight	—	A CSS length, e.g. 30rem. Taller blocks scroll
cacheHighlighting	on	Cache highlighted HTML by content hash
highlightCacheDuration	0	Seconds. 0 uses Craft's default cache duration

Safety

Setting	Default
allowTwigRendering	off	Lets .eval() run a field's contents as Twig. See Usage

Field settings

Each Code field has its own settings:

• Language: Always the same language (fixed), or The author chooses (choose). With choose, Languages the author may choose narrows the picker. Leave it empty to offer every language.
• Default value and Placeholder.
• Minimum height and Maximum height, in lines. A maximum of 0 grows without limit.
• Theme, Font size, Line numbers, Word wrap, Minimap.
• Twig and Craft API autocomplete, for Twig fields.
• Refuse code that does not parse. This applies to Twig, which Craft parses without running anything, and to JSON, which either decodes or doesn't. Every other language saves as typed: a CSS field is allowed to hold half a rule while somebody is thinking.
• Character limit. 0 means none.
• Allow Twig rendering: the field's half of the .eval() switch.
• Render defaults for this field: Line numbers, Copy button, Show the language, Wrap long lines, Tab width and Maximum height.

config/kody.php

Copy vendor/justinholtweb/craft-kody/src/config.php to config/kody.php to set any plugin setting in code. It's multi-environment aware, like general.php:

return [
    '*' => [
        'renderLineNumbers' => true,
        'renderTheme' => 'dark',
        'allowTwigRendering' => false,
    ],
    'dev' => [
        'cacheHighlighting' => false,
    ],
];

Anything set here is locked in the control panel. That is usually the point: it makes a setting like allowTwigRendering something only a deploy can change.

Permissions

Kody adds three nested permissions under Kody:

• View snippets (kody:viewSnippets)
  • Create and edit snippets (kody:manageSnippets)
    • Delete snippets (kody:deleteSnippets)

Admins have all three. Rendering a snippet on the front end needs no permission.

Adding a language

Kody's registry fires Languages::EVENT_REGISTER_LANGUAGES, so a module can add a language or replace a bundled one:

use justinholtweb\kody\models\Language;
use justinholtweb\kody\services\Languages;
use yii\base\Event;

Event::on(Languages::class, Languages::EVENT_REGISTER_LANGUAGES, function($event) {
    $event->types['nunjucks'] = [
        'label' => 'Nunjucks',
        'monaco' => 'twig',
        'group' => Language::GROUP_TEMPLATING,
        'extensions' => ['njk'],
        'grammar' => 'twig',
    ];
});

monaco is the editor mode, and grammar names the server-side grammar to highlight with. A language with neither a grammar nor a generic keyword list still edits with Monaco's colours, but renders as plain text.

Styling

The whole palette is custom properties on .kody:

.kody {
    --kody-bg: #16181d;
    --kody-str: #8ddb8c;
    --kody-kwd: #ff7b72;
}

To write your own stylesheet, turn Include Kody's stylesheet off. The markup and class names stay the same, and the copy button keeps working. Token classes are k-com, k-str, k-num, k-kwd, k-bln, k-fun, k-cls, k-var, k-opr, k-pun, k-tag, k-atn, k-atv, k-sel, k-prp, k-del, k-flt, k-mta, k-esc, k-url, k-hdr, k-bld, k-ita, k-cod, k-dfa and k-dfr.