Skip to content

Commit a280eae

Browse files
pivaldipivaldi
committed
Initial commit
0 parents  commit a280eae

34 files changed

Lines changed: 4929 additions & 0 deletions

‎.changeset/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Changesets
2+
3+
Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
4+
with multi-package repos, or single-package repos to help you version and publish your code. You can
5+
find the full documentation for it [in our repository](https://github.com/changesets/changesets)
6+
7+
We have a quick list of common questions to get you started engaging with this project in
8+
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

‎.changeset/config.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
3+
"changelog": "@changesets/cli/changelog",
4+
"commit": false,
5+
"fixed": [],
6+
"linked": [],
7+
"access": "restricted",
8+
"baseBranch": "main",
9+
"updateInternalDependencies": "patch",
10+
"ignore": []
11+
}

‎.claude/settings.local.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(npm test)",
5+
"WebSearch",
6+
"Bash(find:*)"
7+
]
8+
}
9+
}

‎.github/workflows/ci.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
test:
9+
runs-on: ubuntu-latest
10+
strategy:
11+
matrix:
12+
node: [18, 20, 22]
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- uses: actions/setup-node@v4
17+
with:
18+
node-version: ${{ matrix.node }}
19+
cache: npm
20+
21+
- run: npm ci
22+
- run: npm test

‎.github/workflows/release.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches: [master]
6+
7+
permissions:
8+
contents: write
9+
pull-requests: write
10+
11+
jobs:
12+
release:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- uses: actions/setup-node@v4
18+
with:
19+
node-version: 20
20+
registry-url: https://registry.npmjs.org
21+
cache: npm
22+
23+
- run: npm ci
24+
25+
- name: Create Release PR or Publish
26+
uses: changesets/action@v1
27+
with:
28+
version: npm run version-packages
29+
publish: npm run release
30+
env:
31+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
32+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Node.js
2+
node_modules/
3+
npm-debug.log*
4+
yarn-debug.log*
5+
yarn-error.log*
6+
7+
# Package manager locks (keep package-lock.json for consistency)
8+
# Uncomment if using yarn: yarn.lock
9+
10+
# Testing
11+
coverage/
12+
.nyc_output/
13+
14+
# Build output
15+
dist/
16+
build/
17+
18+
# IDE
19+
.vscode/
20+
.idea/
21+
*.swp
22+
*.swo
23+
*~
24+
25+
# OS
26+
.DS_Store
27+
Thumbs.db
28+
29+
# Temporary files
30+
*.tmp
31+
*.log

‎.npmignore‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Test files
2+
test/
3+
4+
# CI/CD
5+
.github/
6+
.changeset/
7+
8+
# Development files
9+
*.spec.js
10+
*.test.js
11+
12+
# Git
13+
.git/
14+
.gitignore
15+
16+
# IDE
17+
.vscode/
18+
.idea/
19+
20+
# Misc
21+
TODO.md
22+
CHANGELOG.md

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
This project uses Changesets to manage versions and release notes.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Philippe IVALDI
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
![CI](https://github.com/pivaldi/hexo-codapi/actions/workflows/ci.yml/badge.svg)
2+
![npm](https://img.shields.io/npm/v/hexo-codapi)
3+
![downloads](https://img.shields.io/npm/dm/hexo-codapi)
4+
![license](https://img.shields.io/npm/l/hexo-codapi)
5+
6+
# Hexo Codapi Plugin
7+
8+
Embed **live, executable code snippets** in your Hexo blog using
9+
[Codapi](https://codapi.org).
10+
11+
This plugin provides:
12+
13+
- A `{% codapi %}` **tag plugin** for author-friendly usage in Markdown
14+
- **Automatic, per-page injection** of Codapi JS/CSS (only on pages that need it)
15+
- Theme-agnostic integration (no theme edits required)
16+
17+
---
18+
19+
## Features
20+
21+
- Clean author syntax (`{% codapi %}`)
22+
- Outputs Codapi-compatible HTML (`<pre>` + `<codapi-snippet>`)
23+
- Injects assets **only on pages containing Codapi snippets**
24+
- Configurable defaults and CDN URLs
25+
- Works with any Hexo theme
26+
27+
---
28+
29+
## Installation
30+
31+
```bash
32+
npm install hexo-codapi
33+
```
34+
35+
### Hexo 8.x Users (Required)
36+
37+
If 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:
38+
39+
```javascript
40+
// scripts/load-codapi.js
41+
const plugin = require('hexo-codapi');
42+
plugin(hexo);
43+
```
44+
45+
This is due to a change in Hexo 8.x's plugin loading mechanism.
46+
47+
### Hexo 5.x - 7.x Users
48+
49+
For older Hexo versions, the plugin loads automatically - no additional setup needed.
50+
51+
Then rebuild:
52+
53+
```bash
54+
hexo clean && hexo generate
55+
```
56+
57+
---
58+
59+
## Usage
60+
61+
In any post or page:
62+
63+
```text
64+
{% codapi go basic %}
65+
println("Hello, Codapi!")
66+
{% endcodapi %}
67+
```
68+
69+
This renders an executable Go snippet powered by Codapi.
70+
71+
---
72+
73+
## Syntax
74+
75+
```text
76+
{% codapi <sandbox> <editor> [engine=...] [selector=...] %}
77+
<code>
78+
{% endcodapi %}
79+
```
80+
81+
### Parameters
82+
83+
| Parameter | Description | Default |
84+
| ---------- | ------------------------------------------ | ------- |
85+
| `sandbox` | Codapi sandbox (e.g. `go`, `js`, `bash`) | `go` |
86+
| `editor` | Editor UI (`basic`, `full`) | `basic` |
87+
| `engine` | Optional execution engine | *(none)* |
88+
| `selector` | Attach Codapi to an existing element | *(none)* |
89+
90+
### Examples
91+
92+
Basic Go:
93+
94+
```text
95+
{% codapi go %}
96+
println("Hello World")
97+
{% endcodapi %}
98+
```
99+
100+
JavaScript with browser engine:
101+
102+
```text
103+
{% codapi js basic engine=browser %}
104+
console.log("Hello from the browser")
105+
{% endcodapi %}
106+
```
107+
108+
---
109+
110+
## Configuration
111+
112+
Add to your Hexo `_config.yml`:
113+
114+
```yml
115+
codapi:
116+
version: 0.20.0
117+
default_sandbox: go
118+
default_editor: basic
119+
```
120+
121+
### Optional overrides
122+
123+
```yml
124+
codapi:
125+
js: https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.js
126+
css: https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.css
127+
priority: 10
128+
```
129+
130+
| Option | Description |
131+
| ------------ | ------------------------------------------ |
132+
| `version` | Codapi package version (used for CDN URLs) |
133+
| `js` / `css` | Override CDN URLs |
134+
| `priority` | Hexo filter priority (`after_render:html`) |
135+
136+
### Self-hosting Codapi assets
137+
138+
To self-host `snippet.js` and `snippet.css` instead of using the CDN:
139+
140+
1. **Download the assets** from the [Codapi releases](https://github.com/nalgeon/codapi/releases) or unpkg:
141+
```bash
142+
# Create assets directory in your Hexo source
143+
mkdir -p source/assets/codapi
144+
145+
# Download the files
146+
curl -o source/assets/codapi/snippet.js https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.js
147+
curl -o source/assets/codapi/snippet.css https://unpkg.com/@antonz/codapi@0.20.0/dist/snippet.css
148+
```
149+
150+
2. **Update your `_config.yml`** to point to the self-hosted files:
151+
```yml
152+
codapi:
153+
js: /assets/codapi/snippet.js
154+
css: /assets/codapi/snippet.css
155+
```
156+
157+
The plugin will inject these paths instead of CDN URLs. Hexo will automatically copy files from `source/assets/` to `public/assets/` during generation.
158+
159+
---
160+
161+
## How it works
162+
163+
1. `{% codapi %}` expands to:
164+
165+
```html
166+
<pre>...</pre>
167+
<codapi-snippet ...></codapi-snippet>
168+
```
169+
2. During `after_render:html`, the plugin:
170+
171+
* Detects `<codapi-snippet>` in the rendered page
172+
* Injects `snippet.css` into `<head>`
173+
* Injects `snippet.js` before `</body>`
174+
3. Pages without Codapi snippets remain untouched
175+
176+
This guarantees:
177+
178+
* No global JS/CSS bloat
179+
* Full theme compatibility
180+
181+
---
182+
183+
## Notes & Limitations
184+
185+
* Some Codapi sandboxes run fully in-browser; others require a Codapi server.
186+
* This plugin only handles **embedding**, not server configuration.
187+
* If your theme omits `</head>` or `</body>` (very rare), injection will be skipped safely.
188+
189+
---
190+
191+
## License
192+
193+
MIT
194+
195+
---
196+
197+
## Credits
198+
199+
* [Codapi](https://codapi.org) by Anton Zhiyanov
200+
* Hexo plugin API

0 commit comments

Comments
 (0)