Embed live, executable code snippets in your Hexo blog using Codapi.
This plugin provides:
- A
{% codapi %}tag plugin for author-friendly usage in Markdown - Automatic, per-page injection of Codapi JS/CSS (only on pages that need it)
- Theme-agnostic integration (no theme edits required)
- Clean author syntax (
{% codapi %}) - Outputs Codapi-compatible HTML (
<pre>+<codapi-snippet>) - Injects assets only on pages containing Codapi snippets
- Configurable defaults and CDN URLs
- Works with any Hexo theme
npm install hexo-codapiIf you're using Hexo 8.0 or later, you need to explicitly load the plugin. Create a file scripts/load-codapi.js in your Hexo blog directory:
// scripts/load-codapi.js
const plugin = require('hexo-codapi');
plugin(hexo);This is due to a change in Hexo 8.x's plugin loading mechanism.
For older Hexo versions, the plugin loads automatically - no additional setup needed.
Then rebuild:
hexo clean && hexo generateIn any post or page:
{% codapi go basic %}
println("Hello, Codapi!")
{% endcodapi %}
This renders an executable Go snippet powered by Codapi.
{% codapi <sandbox> <editor> [engine=...] [selector=...] %}
<code>
{% endcodapi %}
| Parameter | Description | Default |
|---|---|---|
sandbox |
Codapi sandbox (e.g. go, js, bash) |
go |
editor |
Editor UI (basic, full) |
basic |
engine |
Optional execution engine | (none) |
selector |
Attach Codapi to an existing element | (none) |
Basic Go:
{% codapi go %}
println("Hello World")
{% endcodapi %}
JavaScript with browser engine:
{% codapi js basic engine=browser %}
console.log("Hello from the browser")
{% endcodapi %}
Add to your Hexo _config.yml:
codapi:
version: 0.20.0
default_sandbox: go
default_editor: basiccodapi:
js: https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.js
css: https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.css
priority: 10| Option | Description |
|---|---|
version |
Codapi package version (used for CDN URLs) |
js / css |
Override CDN URLs |
priority |
Hexo filter priority (after_render:html) |
To self-host snippet.js and snippet.css instead of using the CDN:
-
Download the assets from the Codapi releases or unpkg:
# Create assets directory in your Hexo source mkdir -p source/assets/codapi # Download the files curl -o source/assets/codapi/snippet.js https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.js curl -o source/assets/codapi/snippet.css https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.css
-
Update your
_config.ymlto point to the self-hosted files:codapi: js: /assets/codapi/snippet.js css: /assets/codapi/snippet.css
The plugin will inject these paths instead of CDN URLs. Hexo will automatically copy files from source/assets/ to public/assets/ during generation.
-
{% codapi %}expands to:<pre>...</pre> <codapi-snippet ...></codapi-snippet>
-
During
after_render:html, the plugin:- Detects
<codapi-snippet>in the rendered page - Injects
snippet.cssinto<head> - Injects
snippet.jsbefore</body>
- Detects
-
Pages without Codapi snippets remain untouched
This guarantees:
- No global JS/CSS bloat
- Full theme compatibility
- Some Codapi sandboxes run fully in-browser; others require a Codapi server.
- This plugin only handles embedding, not server configuration.
- If your theme omits
</head>or</body>(very rare), injection will be skipped safely.
MIT
- Codapi by Anton Zhiyanov
- Hexo plugin API