Opshell Docusaurus Admonitions

Overview

Version 0.1.3 by Opshell. Registers a custom Gutenberg block opshell/admonition that renders Docusaurus-inspired admonition (callout) boxes. Also provides automatic raw content conversion for ::: syntax used outside the block editor.

Admonition Types

Type	Icon	Default Title	CSS Class
note	Document icon (default)	Note	opshell-admonition--note
tip	Lightbulb icon	Tip	opshell-admonition--tip
info	Info circle icon	Info	opshell-admonition--info
warning	Warning triangle icon	Warning	opshell-admonition--warning
danger	Danger triangle icon	Danger	opshell-admonition--danger

Block Attributes

Attribute	Type	Default	Description
type	string	note	Admonition type: note, tip, info, warning, danger
title	string	""	Custom title (falls back to capitalized type name)

Features

1. Gutenberg Block

Registered as opshell/admonition with:

• Editor script at assets/js/editor.js
• Block style at assets/css/admonitions.css
• Editor style at assets/css/editor.css

2. Raw Content Conversion

Two regex-based conversion passes run on the_content filter at priority 8:

HTML block pattern: Converts ::: syntax wrapped in <p> tags:

<p>:::tip Custom title
Body content
:::</p>

Fenced block pattern: Converts standalone ::: fences:

:::warning
Warning body text
:::

3. Render Output

Each admonition renders as an <aside> element with:

• Badge icon (SVG inline)
• Title paragraph
• Body content broken into <p> elements

Output Structure

<aside class="wp-block-opshell-admonition opshell-admonition opshell-admonition--tip">
  <div class="opshell-admonition__badge" aria-hidden="true"><!-- SVG icon --></div>
  <div class="opshell-admonition__body">
    <p class="opshell-admonition__title">Tip</p>
    <p>Body content here</p>
  </div>
</aside>

CSS Architecture

File	Purpose
assets/css/admonitions.css	Frontend block styles
assets/css/editor.css	Block editor overrides

Styles are enqueued automatically when blocks are present or when ::: syntax is detected in post content.

On single-post pages, admonitions follow the centered article reading measure (720px maximum on wide screens and the available content width on smaller screens). The plugin uses the shared Opshell theme tokens: dark surfaces, --ops-border, and --ops-text. Type accents stay semantic without introducing a competing palette: note uses neutral secondary gray, tip uses Opshell green, info uses bright cyan (#00dbff), warning uses the theme warning amber, and danger uses the theme danger red. All types retain the shared dark Opshell surface, border, and text colors.

Usage

In the Block Editor: Search for "Admonition" or "Opshell" in the block inserter. Choose the type and optional custom title.

In Raw Markdown/Classic Editor: Use :::type Title syntax:

:::info[Important]
This is an important message with **formatting** support.
:::

Allowed types: note, tip, info, warning, danger.