Wagtail Shiki is based on Wagtail Code Block.
Wagtail Code Block is a syntax highlighter block for source code for the Wagtail CMS. It features real-time highlighting in the Wagtail editor, the front end, line numbering, and support for PrismJS themes.
Wagtail Shiki uses the Shiki library instead of PrismJS library both in Wagtail Admin and the website. Required files for Shiki are loaded on demand using esm.run.
Additionally, Wagtail Shiki provides text decoration functions (underlining, borders, and more, extensible with CSS styles) within the syntax highlighting.
You can set each themes for light and dark modes.
pip install wagtail-shiki
And add wagtail_shiki to INSTALLED_APPS in mysite/settings/base.py.
INSTALLED_APPS = [
"home",
"search",
"wagtail.contrib.forms",
"wagtail.contrib.redirects",
"wagtail.embeds",
"wagtail.sites",
"wagtail.users",
#... other packages
"wagtail_shiki", # <- add this.
]
Install new wagtail for trial run.
mkdir mysite
python -m venv mysite/env
source mysite/env/bin/activate
pip install wagtail
wagtail start mysite mysite
cd mysite
pip install -r requirements.txt
pip install wagtail-shiki
Edit files bellow:
mysite/settings/base.py
INSTALLED_APPS = [
#... other packages
"wagtail_shiki", # <- add this.
]
home/models.py
from wagtail.blocks import TextBlock
from wagtail.fields import StreamField
from wagtail.models import Page
from wagtail.admin.panels import FieldPanel
from wagtail_shiki.blocks import CodeBlock
class HomePage(Page):
body = StreamField([
("heading", TextBlock()),
("code", CodeBlock(label='Code')),
], blank=True)
content_panels = Page.content_panels + [
FieldPanel("body"),
]
home/templates/home/home_page.html
...
{% load wagtailcore_tags wagtailimages_tags %}
...
<!-- {% include 'home/welcome_page.html' %} -->
{% include_block page.body %}
...
run:
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver
After the server starts, go to http://127.0.0.1:8000/admin" .
Clicking the "+" Add button in the body section, and click "Code" to add a code block.
Then you can edit the code block.
If true, line numbers will be displayed.
You can set the starting line number by inputting "Start number" field in the code block editing screen.
If true, copy to clipboard button will be displayed.
The theme for light mode.
Please refer to https://shiki.matsu.io/themes for a list of available themes.
Samples of each theme are provided at the end of this document.
The theme for dark mode.If this is not set, it will map the light theme to the dark theme.
As a result, the same theme will be assigned to light mode and dark mode.
If true, the decoration of the leading spaces will be skipped to show.
If true, the decoration of the front side leading spaces will be deleted.
If true, the decoration of the rear side leading spaces will be deleted.
If true, the "Highlight Words" field(uneditable) will be shown.
This is only for debugging.
The prefix for the CSS class name for decorations.
This parameter and the following "-" will be prepended to the value of the "value" key in "WAGS_DECORATION_OPTIONS" and used as a CSS class.
default = [
{
'value': 'underline-red',
'text': 'underline red',
'style': 'text-decoration: red underline;'
},
{
'value': 'underline-blue',
'text': 'underline blue',
'style': 'text-decoration: blue underline;'
},
{
'value': 'underline-green',
'text': 'underline green',
'style': 'text-decoration: green underline;'
},
{
'value': 'underline-yellow',
'text': 'underline yellow',
'style': 'text-decoration: yellow underline;'
},
{
'value': 'wavyunderline-red',
'text': 'wavy underline red',
'style': 'text-decoration: red wavy underline;'
},
{
'value': 'wavyunderline-blue',
'text': 'wavy underline blue',
'style': 'text-decoration: blue wavy underline;'
},
{
'value': 'wavyunderline-green',
'text': 'wavy underline green',
'style': 'text-decoration: green wavy underline;'
},
{
'value': 'wavyunderline-yellow',
'text': 'wavy underline yellow',
'style': 'text-decoration: red wavy underline;'
},
{
'value': 'dashedborder-red',
'text': 'dashed border red',
'style': 'border: dashed red; border-width: 1px; border-radius: 3px; padding: 0px;'
},
{
'value': 'dashedborder-blue',
'text': 'dashed border blue',
'style': 'border: dashed blue; border-width: 1px; border-radius: 3px; padding: 0px;'
},
{
'value': 'dashedborder-green',
'text': 'dashed border green',
'style': 'border: dashed green; border-width: 1px; border-radius: 3px; padding: 0px;'
},
{
'value': 'dashedborder-yellow',
'text': 'dashed border yellow',
'style': 'border: dashed yellow; border-width: 1px; border-radius: 3px; padding: 0px;'
},
{
'value': '',
'text': 'Remove decoration(s)',
'style': ''
}
]
<, >, ', ", & in the string of each value of keys 'value', 'text' and 'style' are removeed.{'value': '', 'text': 'Remove decoration(s)', 'style': ''} is for Remove decoration(s).Some utility functions for creating CSS styles are provided in the module to ease the creation of decoration options in basy.py.
To use these functions, import them from the module:
from wagtail_shiki.settings import (
css_style_underline as underline,
css_style_dashedborder as dashedborder,
css_style_bg_colored as bg_colored,
)
And then use it like following:
WAGS_DECORATION_OPTIONS = [
...
{'value': 'underline-red', 'text': 'underline red', 'style': underline('red')},
...
{'value': 'wavyunderline-red', 'text': 'wavy underline red', 'style': underline('red', 'wavy')},
...
{'value': 'dashedborder-red', 'text': 'dashed border red', 'style': dashedborder('red')},
...
{'value': 'bg_colored-red', 'text': 'ba-colored', 'style': bg_colored('red')},
...
]
It will expanded to:
WAGS_DECORATION_OPTIONS = [
...
{'value': 'underline-red', 'text': 'underline red', 'style': 'text-decoration: red underline;'},
...
{'value': 'wavyunderline-red', 'text': 'wavy underline red', 'style': 'text-decoration: red wavy underline;'},
...
{'value': 'dashedborder-red', 'text': 'dashed border red', 'style': 'border: dashed red; border-width: 1px; border-radius: 3px; padding: 0px;'},
...
{'value': 'bg_colored-red', 'text': 'ba-colored', 'style': 'background-color: red;'},
...
]
Not only color names, you can also use color specifications that are generally available in style sheets, such as '#00a400', 'rgb(214, 122, 127)' for these utility functions.
Add new options to WAGS_DECORATION_OPTIONS in your Django settings and add CSS styles for the new options.
If you want to add orange under line decoration, add the following option to WAGS_DECORATION_OPTIONS in your Django settings.(class name is for example)
WAGS_DECORATION_OPTIONS = [
...
{'value': 'underline-orange', 'text': 'underline orange', 'style': underline('orange')},
...
]
[!NOTE] WAGS_DECORATION_OPTIONS overrides the default settings, if you want to keep them, you have to add default settings along with your custom settings.
from wagtail_shiki.settings import (
css_style_underline as underline,
css_style_dashedborder as dashedborder,
css_style_bg_colored as bg_colored,
)
WAGS_DECORATION_OPTIONS = [
{
'value': 'underline-red',
'text': 'underline red',
'style': underline('red')
},
{
'value': 'underline-blue',
'text': 'underline blue',
'style': underline('blue')
},
{
'value': 'underline-green',
'text': 'underline green',
'style': underline('green')
},
{
'value': 'underline-yellow',
'text': 'underline yellow',
'style': underline('yellow')
},
{
'value': 'wavyunderline-red',
'text': 'wavy underline red',
'style': underline('red', 'wavy')
},
{
'value': 'wavyunderline-blue',
'text': 'wavy underline blue',
'style': underline('blue', 'wavy')
},
{
'value': 'wavyunderline-green',
'text': 'wavy underline green',
'style': underline('green', 'wavy')
},
{
'value': 'wavyunderline-yellow',
'text': 'wavy underline yellow',
'style': underline('yellow', 'wavy')},
{
'value': 'dashedborder-red',
'text': 'dashed border red',
'style': dashedborder('red')
},
{
'value': 'dashedborder-blue',
'text': 'dashed border blue',
'style': dashedborder('blue')
},
{
'value': 'dashedborder-green',
'text': 'dashed border green',
'style': dashedborder('green')
},
{
'value': 'dashedborder-yellow',
'text': 'dashed border yellow',
'style': dashedborder('yellow')
},
{
'value': '',
'text': 'Remove decoration(s)',
'style': ''
}
]
Specifies the initial Language for new added code block.
If this value is not specified or the specified value does not exist in WAGS_LANGUAGES or the default selection list, Plain Text ('text') will be selected.
A list of languages to enable. Don't add 'ansi'(Ansi) and 'text'(Plain Text) here.
They are automatically enabled.
default= (
("bash", "Bash/Shell"),
("css", "CSS"),
("diff", "diff"),
('jinja', 'Django/Jinja'),
("html", "HTML"),
("javascript", "Javascript"),
("json", "JSON"),
("python", "Python"),
("scss", "SCSS"),
("yaml", "YAML"),
)
Please refer to https://shiki.matsu.io/languages for a list of available languages.
Here's how to use this block in the editing screen of the admin site.
Open the pull-down selector box in the Language field and select the language to use for syntax highlighting.
Check the "Show line numbers" checkbox to show line numbers.
If you need to specify the starting line number, please enter it here. If this field is blank, start from line number "1".
If you want to display the file name, title, etc., enter it here. If nothing is entered, the title block will not be displayed. For design customization of title block, see here.
Enter the code text here that you want to apply syntax highlighting to.
Select the range you want to decorate in the preview box of syntax highlighting, click the right button of the mouse, select decoration (or remove), and press the "OK" button to apply.
Click the "Cancel" button to cancel the operation.
A pop-up menu will be displayed when both the start and end points of the selection are in the same preview box and you right-click inside that preview box.
The menu does not appear if the selection includes the outside of the preview box, or if you right-click outside of the preview box which the range was selected.
The title block stylesheet is separated from wagtail-shiki.css and placed under the title-block subdirectory.title-block.css is loaded by default.
Example style sheets for customization are placed in the same directory. title-block-default.css has the same content as title-block.css in the initial.
You can set the example stylesheet by renaming files to title-block.css or rewrite the file name in the @import statement, top of wagtail_shiki/static/wagtail_shiki/css/wagtail-shiki.css file.
Of course, you can also set your own style sheet.
| andromeeda | aurora-x | ayu-dark |
| catppuccin-frappe | catppuccin-latte | catppuccin-macchiato |
| catppuccin-mocha | dark-plus | dracula |
| dracula-soft | everforest-dark | everforest-light |
| github-dark | github-dark-default | github-dark-dimmed |
| github-dark-high-contrast | github-light | github-light-default |
| github-light-high-contrast | gruvbox-dark-hard | gruvbox-dark-medium |
| gruvbox-dark-soft | gruvbox-light-hard | gruvbox-light-medium |
| gruvbox-light-soft | houston | kanagawa-dragon |
| kanagawa-lotus | kanagawa-wave | laserwave |
| light-plus | material-theme | material-theme-darker |
| material-theme-lighter | material-theme-ocean | material-theme-palenight |
| min-dark | min-light | monokai |
| night-owl | nord | one-dark-pro |
| one-light | plastic | poimandres |
| red | rose-pine | rose-pine-dawn |
| rose-pine-moon | slack-dark | slack-ochin |
| snazzy-light | solarized-dark | solarized-light |
| synthwave-84 | tokyo-night | vesper |
| vitesse-black | vitesse-dark | vitesse-light |
FAQs
Add a code block to StreamField of Wagtail with Shiki Syntax highlighter.
We found that wagtail-shiki demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.