@binarynoir/vite-plugin-blog 0.0.0-stage → 0.2.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 +224 -2
- package/client.d.ts +27 -0
- package/dist/index.cjs +1199 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +232 -0
- package/dist/index.d.ts +232 -0
- package/dist/index.js +1163 -0
- package/dist/index.js.map +1 -0
- package/package.json +90 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
import { Plugin } from 'vite';
|
|
2
|
+
import { MarkdownIt } from 'markdown-it';
|
|
3
|
+
|
|
4
|
+
/** A tag a post may use, from the `tags` option or `tags.yml`. */
|
|
5
|
+
interface TagInfo {
|
|
6
|
+
name: string;
|
|
7
|
+
description?: string;
|
|
8
|
+
}
|
|
9
|
+
/** A post's author, from the `authors` option or `authors.yml`. */
|
|
10
|
+
interface AuthorInfo {
|
|
11
|
+
name: string;
|
|
12
|
+
url?: string;
|
|
13
|
+
}
|
|
14
|
+
/** A `##` or `###` heading, for a table of contents. */
|
|
15
|
+
interface TocEntry {
|
|
16
|
+
level: 2 | 3;
|
|
17
|
+
id: string;
|
|
18
|
+
/** The heading as plain text. */
|
|
19
|
+
text: string;
|
|
20
|
+
}
|
|
21
|
+
/** A post as read from its Markdown file, before rendering. */
|
|
22
|
+
interface PostSource {
|
|
23
|
+
/** From the folder (`posts/vpn-leaks/index.md`) or file name (`posts/vpn-leaks.md`). */
|
|
24
|
+
slug: string;
|
|
25
|
+
/** Absolute path of the Markdown file. */
|
|
26
|
+
file: string;
|
|
27
|
+
/** Front matter, as written. */
|
|
28
|
+
data: Record<string, unknown>;
|
|
29
|
+
/** Markdown after the front matter. */
|
|
30
|
+
content: string;
|
|
31
|
+
}
|
|
32
|
+
/** A rendered post. */
|
|
33
|
+
interface Post {
|
|
34
|
+
slug: string;
|
|
35
|
+
/** Path on the site, with Vite's `base`: `/blog/vpn-leaks/`. */
|
|
36
|
+
url: string;
|
|
37
|
+
/** Absolute URL, when the `site` option is set. */
|
|
38
|
+
canonical?: string;
|
|
39
|
+
file: string;
|
|
40
|
+
title: string;
|
|
41
|
+
description: string;
|
|
42
|
+
date: Date;
|
|
43
|
+
/** Whether the front matter gave a time, so a date alone is never shown with "12:00 AM". */
|
|
44
|
+
dateHasTime: boolean;
|
|
45
|
+
updated?: Date;
|
|
46
|
+
tags: string[];
|
|
47
|
+
authors: AuthorInfo[];
|
|
48
|
+
draft: boolean;
|
|
49
|
+
/** Dated after the build's `now`. Only built with `preview`. */
|
|
50
|
+
scheduled: boolean;
|
|
51
|
+
featured: boolean;
|
|
52
|
+
series?: string;
|
|
53
|
+
/** The cover image's URL, as the page should reference it. */
|
|
54
|
+
cover?: string;
|
|
55
|
+
/** Front matter, as written, including fields this plugin doesn't know (`tools`, `discuss`). */
|
|
56
|
+
data: Record<string, unknown>;
|
|
57
|
+
/** The article body as HTML. */
|
|
58
|
+
html: string;
|
|
59
|
+
toc: TocEntry[];
|
|
60
|
+
readingMinutes: number;
|
|
61
|
+
words: number;
|
|
62
|
+
}
|
|
63
|
+
/** Context a directive renders with. */
|
|
64
|
+
interface DirectiveContext {
|
|
65
|
+
/** Everything after the directive's name on its opening line, trimmed. */
|
|
66
|
+
args: string;
|
|
67
|
+
/** A container's body, rendered to HTML. `''` for a leaf directive. */
|
|
68
|
+
body: string;
|
|
69
|
+
post: PostSource;
|
|
70
|
+
md: MarkdownIt;
|
|
71
|
+
/** Fails the build (or shows the error page in dev), naming the post. */
|
|
72
|
+
error(message: string): void;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* A `:::` block. A **leaf** directive is one line (`::: tool check example.com`).
|
|
76
|
+
* A **container** wraps Markdown until a line holding only `:::`.
|
|
77
|
+
*/
|
|
78
|
+
interface Directive {
|
|
79
|
+
kind: "leaf" | "container";
|
|
80
|
+
render(context: DirectiveContext): string;
|
|
81
|
+
}
|
|
82
|
+
/** The blog's index (`/blog/`) or one tag's page (`/blog/tag/dns/`). */
|
|
83
|
+
interface ListPage {
|
|
84
|
+
kind: "index" | "tag";
|
|
85
|
+
/** Path on the site, with Vite's `base`: `/blog/tag/dns/`. */
|
|
86
|
+
url: string;
|
|
87
|
+
/** Absolute URL, when the `site` option is set. */
|
|
88
|
+
canonical?: string;
|
|
89
|
+
title: string;
|
|
90
|
+
description: string;
|
|
91
|
+
/** The tag id, on a tag page. */
|
|
92
|
+
tag?: string;
|
|
93
|
+
/** The page's posts, newest first. */
|
|
94
|
+
posts: Post[];
|
|
95
|
+
}
|
|
96
|
+
/** Helpers passed to the page renderers. */
|
|
97
|
+
interface RenderHelpers {
|
|
98
|
+
/** The blog index's path: `/blog/`. */
|
|
99
|
+
indexUrl: string;
|
|
100
|
+
/** A tag page's path: `/blog/tag/dns/`. Tags without published posts have no page. */
|
|
101
|
+
tagUrl: (tag: string) => string;
|
|
102
|
+
/** Tags with at least one published post, by id, in `tags.yml` order. */
|
|
103
|
+
usedTags: string[];
|
|
104
|
+
/** The default `<head>` tags for the index or a tag page. */
|
|
105
|
+
renderListHead: (page: ListPage) => string;
|
|
106
|
+
/** The default markup for the index or a tag page. */
|
|
107
|
+
renderList: (page: ListPage) => string;
|
|
108
|
+
escapeHtml: (value: string) => string;
|
|
109
|
+
/** A post's date for readers, in the blog's locale and time zone. */
|
|
110
|
+
formatDate: (date: Date, hasTime?: boolean) => string;
|
|
111
|
+
/** A `<time datetime>` value. */
|
|
112
|
+
dateAttribute: (date: Date, hasTime?: boolean) => string;
|
|
113
|
+
/** A `<nav>` list of the headings, or `''` when there are fewer than two. */
|
|
114
|
+
renderToc: (toc: TocEntry[]) => string;
|
|
115
|
+
/** The default `<head>` tags for a post. */
|
|
116
|
+
renderHead: (post: Post) => string;
|
|
117
|
+
/** The default article markup for a post. */
|
|
118
|
+
renderArticle: (post: Post) => string;
|
|
119
|
+
tags: Record<string, TagInfo>;
|
|
120
|
+
/** Every published post, newest first. */
|
|
121
|
+
posts: Post[];
|
|
122
|
+
}
|
|
123
|
+
/** One problem with a post, reported by file. */
|
|
124
|
+
interface BlogIssue {
|
|
125
|
+
file: string;
|
|
126
|
+
message: string;
|
|
127
|
+
}
|
|
128
|
+
interface BlogOptions {
|
|
129
|
+
/**
|
|
130
|
+
* The content folder. It holds `posts/` (one folder or `.md` file per post),
|
|
131
|
+
* and optionally `tags.yml` and `authors.yml`. Relative to Vite's `root`.
|
|
132
|
+
*/
|
|
133
|
+
dir: string;
|
|
134
|
+
/** Where the blog lives on the site. Default `/blog/`. */
|
|
135
|
+
base?: string;
|
|
136
|
+
/** The site's origin, `https://example.com`, for canonical URLs and Open Graph tags. */
|
|
137
|
+
site?: string;
|
|
138
|
+
/**
|
|
139
|
+
* The HTML page shell for posts, relative to Vite's `root`. It must contain
|
|
140
|
+
* `<!--blog:content-->`, and may contain `<!--blog:head-->` (otherwise the
|
|
141
|
+
* head tags go before `</head>`). Scripts and styles in it are bundled by
|
|
142
|
+
* Vite as in any other page.
|
|
143
|
+
*/
|
|
144
|
+
template: string;
|
|
145
|
+
/** Include drafts and scheduled posts, with `noindex`. Default `false`. */
|
|
146
|
+
preview?: boolean;
|
|
147
|
+
/** What "now" is when deciding whether a post is scheduled. Default: the build's start. */
|
|
148
|
+
now?: Date;
|
|
149
|
+
/** IANA time zone for dates without an offset, and for showing dates. Default `UTC`. */
|
|
150
|
+
timeZone?: string;
|
|
151
|
+
/** For showing dates. Default `en-US`. */
|
|
152
|
+
locale?: string;
|
|
153
|
+
/** Default 230. */
|
|
154
|
+
wordsPerMinute?: number;
|
|
155
|
+
/** Added after the post title in `<title>`: `" · Example"`. Default `''`. */
|
|
156
|
+
titleSuffix?: string;
|
|
157
|
+
/** The blog index's heading and description. Default `{ title: "Blog", description: "" }`. */
|
|
158
|
+
index?: {
|
|
159
|
+
title?: string;
|
|
160
|
+
description?: string;
|
|
161
|
+
};
|
|
162
|
+
/** Write a page per tag at `{base}tag/{tag}/`. Default `true`. */
|
|
163
|
+
tagPages?: boolean;
|
|
164
|
+
/** Front matter limits. */
|
|
165
|
+
limits?: {
|
|
166
|
+
/** Longest title, in characters. Default 70. */
|
|
167
|
+
title?: number;
|
|
168
|
+
/** Longest description, in characters. Default 160. */
|
|
169
|
+
description?: number;
|
|
170
|
+
/** Fewest tags a post may have. Default 0. */
|
|
171
|
+
minTags?: number;
|
|
172
|
+
/** Most tags a post may have. Default no limit. */
|
|
173
|
+
maxTags?: number;
|
|
174
|
+
};
|
|
175
|
+
/**
|
|
176
|
+
* The only tags posts may use. Defaults to `tags.yml` in `dir`; without it,
|
|
177
|
+
* any tag is allowed.
|
|
178
|
+
*/
|
|
179
|
+
tags?: Record<string, TagInfo>;
|
|
180
|
+
/** Known authors, by id. Defaults to `authors.yml` in `dir`. */
|
|
181
|
+
authors?: Record<string, AuthorInfo>;
|
|
182
|
+
/** `:::` directives. `note`, `tip` and `warning` callouts are built in; a directive here with the same name replaces one. */
|
|
183
|
+
directives?: Record<string, Directive>;
|
|
184
|
+
/** Code highlighting with Shiki, or `false` for plain `<pre>`. */
|
|
185
|
+
highlight?: false | {
|
|
186
|
+
/** Default `{ light: "github-light", dark: "github-dark" }`. */
|
|
187
|
+
themes?: {
|
|
188
|
+
light: string;
|
|
189
|
+
dark: string;
|
|
190
|
+
};
|
|
191
|
+
/** Prefix for the generated color classes. Default `sk-`. */
|
|
192
|
+
classPrefix?: string;
|
|
193
|
+
};
|
|
194
|
+
/** Change the markdown-it instance: add plugins, rules or options. */
|
|
195
|
+
markdown?: (md: MarkdownIt) => void;
|
|
196
|
+
/**
|
|
197
|
+
* Whether a link to a site page outside the blog points at a real page. Links
|
|
198
|
+
* between posts are always checked. Without this, other links aren't.
|
|
199
|
+
*/
|
|
200
|
+
isKnownPath?: (path: string) => boolean;
|
|
201
|
+
/** Extra checks for a post. Return messages to fail the build. */
|
|
202
|
+
validate?: (post: Post) => string[] | void;
|
|
203
|
+
/** Replace the default markup. */
|
|
204
|
+
render?: {
|
|
205
|
+
/** Tags for `<!--blog:head-->`. */
|
|
206
|
+
head?: (post: Post, helpers: RenderHelpers) => string;
|
|
207
|
+
/** Markup for `<!--blog:content-->`. */
|
|
208
|
+
article?: (post: Post, helpers: RenderHelpers) => string;
|
|
209
|
+
/** Head tags for the index and tag pages. */
|
|
210
|
+
listHead?: (page: ListPage, helpers: RenderHelpers) => string;
|
|
211
|
+
/** Markup for the index and tag pages. */
|
|
212
|
+
list?: (page: ListPage, helpers: RenderHelpers) => string;
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/**
|
|
217
|
+
* A static Markdown blog for a Vite site. Each post becomes an HTML page,
|
|
218
|
+
* built from the site's own page shell, so the site's scripts, styles and
|
|
219
|
+
* `transformIndexHtml` plugins apply to posts like to any other page.
|
|
220
|
+
*/
|
|
221
|
+
declare function blog(userOptions: BlogOptions): Plugin;
|
|
222
|
+
|
|
223
|
+
/** `::: note`, `::: tip` and `::: warning`, with an optional title after the name. */
|
|
224
|
+
declare const BUILT_IN_DIRECTIVES: Record<string, Directive>;
|
|
225
|
+
|
|
226
|
+
/** Escapes the characters that are special in HTML text and attribute values. */
|
|
227
|
+
declare function escapeHtml(value: string): string;
|
|
228
|
+
/** Lowercase words joined by hyphens: "Is your VPN working?" is `is-your-vpn-working`. */
|
|
229
|
+
declare function slugify(text: string): string;
|
|
230
|
+
|
|
231
|
+
export { BUILT_IN_DIRECTIVES, blog, blog as default, escapeHtml, slugify };
|
|
232
|
+
export type { AuthorInfo, BlogIssue, BlogOptions, Directive, DirectiveContext, ListPage, Post, PostSource, RenderHelpers, TagInfo, TocEntry };
|