@binarynoir/vite-plugin-blog 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +213 -2
- package/client.d.ts +27 -0
- package/dist/index.cjs +1077 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +197 -0
- package/dist/index.d.ts +197 -0
- package/dist/index.js +1041 -0
- package/dist/index.js.map +1 -0
- package/package.json +90 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BinaryNoir
|
|
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.
|
package/README.md
CHANGED
|
@@ -1,3 +1,214 @@
|
|
|
1
|
-
#
|
|
1
|
+
# vite-plugin-blog
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@binarynoir/vite-plugin-blog)
|
|
4
|
+
[](https://github.com/binarynoir/vite-plugin-blog/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
A static Markdown blog for any [Vite](https://vite.dev) site, without a second framework.
|
|
8
|
+
Each post becomes a plain HTML page built from your own page shell, so your header,
|
|
9
|
+
scripts, styles and `transformIndexHtml` plugins apply to posts like to every other page.
|
|
10
|
+
|
|
11
|
+
[](https://buymeacoffee.com/binarynoir)
|
|
12
|
+
[](https://ko-fi.com/binarynoir)
|
|
13
|
+
[](https://binarynoir.tech)
|
|
14
|
+
|
|
15
|
+
## What this does
|
|
16
|
+
|
|
17
|
+
- **Posts are HTML in the page source.** A post reads with no JavaScript.
|
|
18
|
+
- **Works under a strict Content Security Policy.** Code is highlighted with
|
|
19
|
+
[Shiki](https://shiki.style) at build time, and its colors are written as classes, not
|
|
20
|
+
`style` attributes, so `style-src 'self'` holds.
|
|
21
|
+
- **Checks every post.** The build fails, naming the file and line, on a missing or
|
|
22
|
+
too-long title or description, a bad date, a tag not in `tags.yml`, an image without alt
|
|
23
|
+
text or without a file, or a link to a post that doesn't exist (or is still a draft).
|
|
24
|
+
- **Drafts and scheduled posts.** `draft: true` and future dates stay out of the build,
|
|
25
|
+
unless `preview` is on. Then they get `noindex`.
|
|
26
|
+
- **`:::` directives.** `note`, `tip` and `warning` callouts are built in. Add your own,
|
|
27
|
+
such as a live widget inside a post.
|
|
28
|
+
- **Images** next to the post go through Vite (hashed and copied), with `width` and
|
|
29
|
+
`height` set so the page doesn't shift, and `loading="lazy"` after the first.
|
|
30
|
+
- **Live reload in dev**, with problems shown in Vite's error overlay.
|
|
31
|
+
- **`virtual:blog/posts`** lists published posts, for a "Latest posts" strip or links
|
|
32
|
+
from other pages.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npm install --save-dev @binarynoir/vite-plugin-blog
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Needs Node 22 or later and Vite 6, 7 or 8.
|
|
41
|
+
|
|
42
|
+
## Usage
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
content/
|
|
46
|
+
posts/
|
|
47
|
+
vpn-leaks/
|
|
48
|
+
index.md # served at /blog/vpn-leaks/
|
|
49
|
+
diagram.svg # images sit next to the post
|
|
50
|
+
short-post.md # served at /blog/short-post/
|
|
51
|
+
tags.yml # optional: the only tags allowed
|
|
52
|
+
authors.yml # optional
|
|
53
|
+
templates/
|
|
54
|
+
post.html # your page shell
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
// vite.config.ts
|
|
59
|
+
import { defineConfig } from "vite";
|
|
60
|
+
import { blog } from "@binarynoir/vite-plugin-blog";
|
|
61
|
+
|
|
62
|
+
export default defineConfig({
|
|
63
|
+
plugins: [
|
|
64
|
+
blog({
|
|
65
|
+
dir: "content",
|
|
66
|
+
template: "templates/post.html",
|
|
67
|
+
site: "https://example.com",
|
|
68
|
+
titleSuffix: " · Example",
|
|
69
|
+
preview: process.env.BLOG_PREVIEW === "1",
|
|
70
|
+
}),
|
|
71
|
+
],
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
The page shell is any HTML page with two markers. Use root paths (`/src/…`) in it: the
|
|
76
|
+
page is served from `/blog/{slug}/`. Leave out `<title>`; the plugin writes it.
|
|
77
|
+
|
|
78
|
+
```html
|
|
79
|
+
<!doctype html>
|
|
80
|
+
<html lang="en">
|
|
81
|
+
<head>
|
|
82
|
+
<meta charset="utf-8" />
|
|
83
|
+
<!--blog:head-->
|
|
84
|
+
</head>
|
|
85
|
+
<body>
|
|
86
|
+
<main><!--blog:content--></main>
|
|
87
|
+
<script type="module" src="/src/post.ts"></script>
|
|
88
|
+
</body>
|
|
89
|
+
</html>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
// src/post.ts
|
|
94
|
+
import "virtual:blog/code.css"; // the highlighting classes the posts use
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
For types, add `"@binarynoir/vite-plugin-blog/client"` to `types` in `tsconfig.json`.
|
|
98
|
+
|
|
99
|
+
### Front matter
|
|
100
|
+
|
|
101
|
+
```yaml
|
|
102
|
+
title: Is your VPN actually working? # required, 70 characters at most
|
|
103
|
+
description: The four leaks to test. # required, 160 characters at most
|
|
104
|
+
date: 2026-12-02 # required; a future date schedules the post
|
|
105
|
+
updated: 2026-12-10
|
|
106
|
+
tags: [vpn-privacy, homelab]
|
|
107
|
+
authors: [jane] # ids from authors.yml
|
|
108
|
+
series: building-it
|
|
109
|
+
cover: cover.png
|
|
110
|
+
featured: true
|
|
111
|
+
draft: false
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Fields the plugin doesn't know (`tools`, `discuss`) are kept in `post.data`, for your own
|
|
115
|
+
checks and markup.
|
|
116
|
+
|
|
117
|
+
### Light and dark code
|
|
118
|
+
|
|
119
|
+
Highlighting uses CSS `light-dark()`, so it follows the page's `color-scheme`. Set
|
|
120
|
+
`color-scheme: light dark` on `:root`, and `color-scheme: dark` or `light` when your
|
|
121
|
+
theme switch picks one.
|
|
122
|
+
|
|
123
|
+
## Options
|
|
124
|
+
|
|
125
|
+
| Option | Default | What it does |
|
|
126
|
+
| ---------------- | ------------- | -------------------------------------------------------------------- |
|
|
127
|
+
| `dir` | (required) | The content folder, relative to Vite's `root` or absolute |
|
|
128
|
+
| `template` | (required) | The page shell, relative to Vite's `root` |
|
|
129
|
+
| `base` | `/blog/` | Where the blog lives on the site |
|
|
130
|
+
| `site` | | The site's origin, for canonical URLs and Open Graph tags |
|
|
131
|
+
| `preview` | `false` | Also build drafts and scheduled posts, with `noindex` |
|
|
132
|
+
| `now` | build time | What "now" is when deciding whether a post is scheduled |
|
|
133
|
+
| `timeZone` | `UTC` | For dates without an offset, and for showing dates |
|
|
134
|
+
| `locale` | `en-US` | For showing dates |
|
|
135
|
+
| `wordsPerMinute` | `230` | For reading time |
|
|
136
|
+
| `titleSuffix` | `''` | Added after the post title in `<title>` |
|
|
137
|
+
| `limits` | | `{ title: 70, description: 160, minTags: 0, maxTags }` |
|
|
138
|
+
| `tags` | `tags.yml` | The only tags allowed; without either, any tag is |
|
|
139
|
+
| `authors` | `authors.yml` | Known authors, by id |
|
|
140
|
+
| `directives` | | Your own `:::` directives (below) |
|
|
141
|
+
| `highlight` | GitHub themes | `{ themes: { light, dark }, classPrefix }`, or `false` |
|
|
142
|
+
| `markdown` | | `(md) => void`: add markdown-it plugins |
|
|
143
|
+
| `isKnownPath` | | `(path) => boolean`: also check links to site pages outside the blog |
|
|
144
|
+
| `validate` | | `(post) => string[]`: your own checks; messages fail the build |
|
|
145
|
+
| `render` | | `{ head, article }`: replace the default markup (below) |
|
|
146
|
+
|
|
147
|
+
### Directives
|
|
148
|
+
|
|
149
|
+
A **leaf** directive is one line. A **container** wraps Markdown until a line holding
|
|
150
|
+
only `:::`, and can nest.
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
blog({
|
|
154
|
+
// ...
|
|
155
|
+
directives: {
|
|
156
|
+
tool: {
|
|
157
|
+
kind: "leaf",
|
|
158
|
+
render: ({ args, error, post }) => {
|
|
159
|
+
const [name, query] = args.split(/\s+/);
|
|
160
|
+
if (!name) error("needs a tool name");
|
|
161
|
+
return `<div class="tool" data-tool="${name}" data-q="${query ?? ""}"></div>`;
|
|
162
|
+
},
|
|
163
|
+
},
|
|
164
|
+
},
|
|
165
|
+
});
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
```md
|
|
169
|
+
::: tool check example.com
|
|
170
|
+
|
|
171
|
+
::: warning Before you start
|
|
172
|
+
Back up the zone file.
|
|
173
|
+
:::
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Your own markup
|
|
177
|
+
|
|
178
|
+
`render.article` and `render.head` get the post and a set of helpers: `escapeHtml`,
|
|
179
|
+
`formatDate`, `dateAttribute`, `renderToc`, `renderHead`, `renderArticle`, `tags` and
|
|
180
|
+
`posts` (every published post, newest first, for related posts or series links).
|
|
181
|
+
|
|
182
|
+
```ts
|
|
183
|
+
render: {
|
|
184
|
+
head: (post, h) => `${h.renderHead(post)}\n<meta property="og:site_name" content="Example">`,
|
|
185
|
+
article: (post, h) => `<article class="post"><h1>${h.escapeHtml(post.title)}</h1>
|
|
186
|
+
${h.renderToc(post.toc)}<div class="prose">${post.html}</div></article>`,
|
|
187
|
+
},
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The default article uses these classes: `post`, `post-header`, `post-description`,
|
|
191
|
+
`post-meta`, `post-tags`, `tag`, `toc`, `toc-title`, `toc-2`, `toc-3`, `prose`.
|
|
192
|
+
Inside posts: `heading-anchor`, `code-block`, `callout`, `callout-note`, `callout-tip`,
|
|
193
|
+
`callout-warning`, `callout-title`.
|
|
194
|
+
|
|
195
|
+
### `virtual:blog/posts`
|
|
196
|
+
|
|
197
|
+
```ts
|
|
198
|
+
import { posts } from "virtual:blog/posts";
|
|
199
|
+
|
|
200
|
+
for (const post of posts.slice(0, 3)) console.log(post.title, post.url, post.date);
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Each post has `slug`, `url`, `title`, `description`, `date`, `updated`, `tags`, `authors`,
|
|
204
|
+
`featured`, `series`, `readingMinutes` and `data` (the front matter).
|
|
205
|
+
|
|
206
|
+
## Releasing
|
|
207
|
+
|
|
208
|
+
Maintainers only. `npm run release:patch` (or `minor`, `major`) bumps the version, tags
|
|
209
|
+
and pushes. The tag runs `.github/workflows/release.yml`, which tests, builds and
|
|
210
|
+
publishes to npm with Trusted Publishing.
|
|
211
|
+
|
|
212
|
+
## License
|
|
213
|
+
|
|
214
|
+
[MIT](LICENSE)
|
package/client.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// Types for the plugin's virtual modules. Add to tsconfig "types":
|
|
2
|
+
// ["@binarynoir/vite-plugin-blog/client"], or reference it from a .d.ts file.
|
|
3
|
+
|
|
4
|
+
declare module "virtual:blog/posts" {
|
|
5
|
+
export interface BlogPostSummary {
|
|
6
|
+
slug: string;
|
|
7
|
+
/** `/blog/vpn-leaks/` */
|
|
8
|
+
url: string;
|
|
9
|
+
title: string;
|
|
10
|
+
description: string;
|
|
11
|
+
/** ISO 8601 */
|
|
12
|
+
date: string;
|
|
13
|
+
updated?: string;
|
|
14
|
+
tags: string[];
|
|
15
|
+
authors: { name: string; url?: string }[];
|
|
16
|
+
featured: boolean;
|
|
17
|
+
series?: string;
|
|
18
|
+
readingMinutes: number;
|
|
19
|
+
/** Front matter as written, including fields the plugin doesn't know. */
|
|
20
|
+
data: Record<string, unknown>;
|
|
21
|
+
}
|
|
22
|
+
/** Published posts, newest first. */
|
|
23
|
+
export const posts: BlogPostSummary[];
|
|
24
|
+
export default posts;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
declare module "virtual:blog/code.css" {}
|