@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 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
- # Temporary Holding Version
1
+ # vite-plugin-blog
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/@binarynoir/vite-plugin-blog.svg)](https://www.npmjs.com/package/@binarynoir/vite-plugin-blog)
4
+ [![CI](https://github.com/binarynoir/vite-plugin-blog/actions/workflows/ci.yml/badge.svg)](https://github.com/binarynoir/vite-plugin-blog/actions/workflows/ci.yml)
5
+ [![license](https://img.shields.io/npm/l/@binarynoir/vite-plugin-blog.svg)](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
+ [![Support me on Buy Me a Coffee](https://img.shields.io/badge/Support%20me-Buy%20Me%20a%20Coffee-orange?style=for-the-badge&logo=buy-me-a-coffee)](https://buymeacoffee.com/binarynoir)
12
+ [![Support me on Ko-fi](https://img.shields.io/badge/Support%20me-Ko--fi-blue?style=for-the-badge&logo=ko-fi)](https://ko-fi.com/binarynoir)
13
+ [![More tools](https://img.shields.io/badge/Website-binarynoir.tech-8c8c8c?style=for-the-badge)](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" {}