@lvl99dotcom/edaha.md 0.1.0 → 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 +183 -183
- package/README.md +7 -252
- package/dist/cli/index.d.ts +36 -6
- package/dist/cli/index.js +48 -9
- package/dist/embeds/blocks/index.d.ts +59 -0
- package/dist/embeds/blocks/index.js +103 -0
- package/dist/embeds/index.d.ts +122 -19
- package/dist/embeds/index.js +381 -41
- package/dist/embeds/types/index.d.ts +111 -8
- package/dist/generator/article/index.d.ts +52 -12
- package/dist/generator/article/index.js +94 -26
- package/dist/generator/build/index.d.ts +55 -23
- package/dist/generator/build/index.js +151 -81
- package/dist/generator/config/index.d.ts +45 -8
- package/dist/generator/config/index.js +152 -30
- package/dist/generator/configFile/index.d.ts +58 -0
- package/dist/generator/configFile/index.js +122 -0
- package/dist/generator/fields/index.d.ts +93 -0
- package/dist/generator/fields/index.js +186 -0
- package/dist/generator/format/index.d.ts +40 -0
- package/dist/generator/format/index.js +75 -0
- package/dist/generator/lists/index.d.ts +3 -3
- package/dist/generator/lists/index.js +9 -8
- package/dist/generator/markdown/index.d.ts +8 -3
- package/dist/generator/markdown/index.js +11 -4
- package/dist/generator/metadata/index.d.ts +150 -0
- package/dist/generator/metadata/index.js +361 -0
- package/dist/generator/metadataGroups/index.d.ts +45 -0
- package/dist/generator/metadataGroups/index.js +169 -0
- package/dist/generator/templates/index.d.ts +35 -3
- package/dist/generator/templates/index.js +72 -6
- package/dist/generator/types/index.d.ts +43 -18
- package/dist/generator/urls/index.d.ts +18 -8
- package/dist/generator/urls/index.js +22 -12
- package/dist/index.d.ts +5 -7
- package/dist/index.js +6 -7
- package/package.json +18 -47
- package/theme/static/{site.css → base.css} +132 -24
- package/theme/templates/article/list.njk +6 -6
- package/theme/templates/article/single.njk +13 -7
- package/theme/templates/layouts/html.njk +54 -32
- package/theme/templates/layouts/rssfeed.njk +7 -7
- package/theme/templates/page/home.njk +2 -7
- package/theme/templates/page/single.njk +2 -2
- package/dist/client/assets/index-BbKEbPS8.css +0 -1
- package/dist/client/assets/index-DtG7vi1d.js +0 -559
- package/dist/client/index.html +0 -13
- package/dist/editor/index.d.ts +0 -62
- package/dist/editor/index.js +0 -102
- package/dist/embeds/bandcamp/index.d.ts +0 -9
- package/dist/embeds/bandcamp/index.js +0 -28
- package/dist/embeds/youtube/index.d.ts +0 -17
- package/dist/embeds/youtube/index.js +0 -48
- package/dist/server/app/index.d.ts +0 -39
- package/dist/server/app/index.js +0 -138
- package/dist/server/convert/index.d.ts +0 -25
- package/dist/server/convert/index.js +0 -125
- package/dist/server/store/index.d.ts +0 -148
- package/dist/server/store/index.js +0 -411
- package/dist/server/types/index.d.ts +0 -76
- package/dist/server/types/index.js +0 -1
|
@@ -1,4 +1,11 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { type MetadataValidator } from "../metadata/index.ts";
|
|
2
|
+
import type { ArticleStatus, TemplateDataArticle, TemplateDataAuthor, TemplateDataSite, TemplateDataTag } from "../types/index.ts";
|
|
3
|
+
/** Formats an article's config header can be written in */
|
|
4
|
+
export declare const HEADER_FORMATS: readonly ["yaml", "yml", "json"];
|
|
5
|
+
/** A format an article's config header can be written in */
|
|
6
|
+
export type HeaderFormat = (typeof HEADER_FORMATS)[number];
|
|
7
|
+
/** The format articles' config headers are written in by default */
|
|
8
|
+
export declare const DEFAULT_HEADER_FORMAT: HeaderFormat;
|
|
2
9
|
/** The `<!-- readmore -->` shortcode */
|
|
3
10
|
export declare const READMORE: RegExp;
|
|
4
11
|
/** Excerpts without a readmore shortcode or config are cropped to this many characters */
|
|
@@ -21,7 +28,8 @@ export interface ArticleConfig {
|
|
|
21
28
|
type: string;
|
|
22
29
|
status: ArticleStatus;
|
|
23
30
|
date: string;
|
|
24
|
-
author
|
|
31
|
+
/** The article's author, or `false` for none (undefined uses its type's or the website's default) */
|
|
32
|
+
author?: AuthorConfig | false | undefined;
|
|
25
33
|
title?: string | undefined;
|
|
26
34
|
template?: string | undefined;
|
|
27
35
|
excerpt?: string | undefined;
|
|
@@ -30,13 +38,23 @@ export interface ArticleConfig {
|
|
|
30
38
|
tags: string[];
|
|
31
39
|
}
|
|
32
40
|
/**
|
|
33
|
-
*
|
|
41
|
+
* The format of an article's config header, or DEFAULT_HEADER_FORMAT if it has none.
|
|
34
42
|
*
|
|
35
43
|
* @example
|
|
36
|
-
*
|
|
44
|
+
* headerFormat("<!--json\n{}\n-->\n# Hi"); // "json"
|
|
45
|
+
*/
|
|
46
|
+
export declare const headerFormat: (source: string) => HeaderFormat;
|
|
47
|
+
/**
|
|
48
|
+
* Split an article's source into its parsed config header (empty if there is none), the header's format and its
|
|
49
|
+
* markdown content. The header is YAML (`<!--yaml` or `<!--yml`) or JSON (`<!--json`). Throws if it can't be read.
|
|
50
|
+
*
|
|
51
|
+
* @example
|
|
52
|
+
* splitArticle("<!--yaml\ndate: 2026-10-19\n-->\n# Hi"); // { header: { date: "2026-10-19" }, format: "yaml", content: "\n# Hi" }
|
|
53
|
+
* splitArticle('<!--json\n{ "date": "2026-10-19" }\n-->\n# Hi'); // { header: { date: "2026-10-19" }, format: "json", content: "\n# Hi" }
|
|
37
54
|
*/
|
|
38
55
|
export declare const splitArticle: (source: string) => {
|
|
39
56
|
header: unknown;
|
|
57
|
+
format: HeaderFormat;
|
|
40
58
|
content: string;
|
|
41
59
|
};
|
|
42
60
|
/**
|
|
@@ -59,7 +77,8 @@ export interface ArticleContent {
|
|
|
59
77
|
beforeReadmore: string | undefined;
|
|
60
78
|
}
|
|
61
79
|
/**
|
|
62
|
-
* Split article markdown into its title heading, body and the part before `<!-- readmore -->`.
|
|
80
|
+
* Split article markdown into its title heading, body and the part before `<!-- readmore -->`. Raw blocks become HTML
|
|
81
|
+
* that shows their content as it is (see rawHtml) first, so nothing inside them is read as a title or shortcode.
|
|
63
82
|
*
|
|
64
83
|
* @example
|
|
65
84
|
* splitContent("# Hi\n\nIntro <!-- readmore -->rest"); // { heading: "Hi", body: "\nIntro rest", beforeReadmore: "\nIntro" }
|
|
@@ -67,8 +86,8 @@ export interface ArticleContent {
|
|
|
67
86
|
export declare const splitContent: (content: string) => ArticleContent;
|
|
68
87
|
/** Where an article is and how to render its parts */
|
|
69
88
|
export interface ArticleContext {
|
|
70
|
-
/** The
|
|
71
|
-
|
|
89
|
+
/** The website the article belongs to */
|
|
90
|
+
site: TemplateDataSite;
|
|
72
91
|
/** The article's folder on disk */
|
|
73
92
|
dir: string;
|
|
74
93
|
/** The article's slug (its folder name) */
|
|
@@ -79,20 +98,41 @@ export interface ArticleContext {
|
|
|
79
98
|
typeUrl: string;
|
|
80
99
|
/** Where the article is, for errors and warnings */
|
|
81
100
|
source: string;
|
|
82
|
-
/** Replace embed blocks in markdown with HTML */
|
|
83
|
-
replaceEmbeds(markdown: string): Promise<string>;
|
|
101
|
+
/** Replace embed blocks in markdown with HTML, for the article's body or its excerpt */
|
|
102
|
+
replaceEmbeds(markdown: string, part: "body" | "excerpt"): Promise<string>;
|
|
84
103
|
/** Render markdown to HTML, resolving relative URLs against a folder URL */
|
|
85
104
|
renderMarkdown(markdown: string, baseUrl: string): string;
|
|
105
|
+
/** The article's custom metadata fields, to validate its values and give them to templates. Default: none */
|
|
106
|
+
metadata?: MetadataContext | undefined;
|
|
107
|
+
}
|
|
108
|
+
/** What an article's custom metadata is read with */
|
|
109
|
+
export interface MetadataContext {
|
|
110
|
+
validator: MetadataValidator;
|
|
111
|
+
/** The custom fields the article's type uses */
|
|
112
|
+
keys: string[];
|
|
113
|
+
/** The type's plural label, for warnings, e.g. "News" */
|
|
114
|
+
typeLabel: string;
|
|
115
|
+
/** Report a problem with the article's metadata (they are warnings for the build) */
|
|
116
|
+
warn(message: string): void;
|
|
86
117
|
}
|
|
87
118
|
/**
|
|
88
|
-
*
|
|
119
|
+
* An article's author: its own, or `false` for none; without one, its type's default (or `false` for none); without
|
|
120
|
+
* that, the website's default (the config file's `author`, or the website's name; undefined when it is `false`).
|
|
121
|
+
*
|
|
122
|
+
* @example
|
|
123
|
+
* articleAuthor(undefined, { name: "Docs team" }, { name: "Matt" }); // { name: "Docs team" }
|
|
124
|
+
* articleAuthor(false, undefined, { name: "Matt" }); // undefined
|
|
125
|
+
*/
|
|
126
|
+
export declare const articleAuthor: (own: AuthorConfig | false | undefined, typeDefault: AuthorConfig | false | undefined, siteDefault: AuthorConfig | undefined) => AuthorConfig | undefined;
|
|
127
|
+
/**
|
|
128
|
+
* Build an author's template data.
|
|
89
129
|
*
|
|
90
130
|
* @param typeUrl - the URL of the article type, which its author lists are under
|
|
91
131
|
*
|
|
92
132
|
* @example
|
|
93
|
-
* authorData({ name: "
|
|
133
|
+
* authorData({ name: "LiveCanvas" }, "/news/"); // { name: "LiveCanvas", slug: "livecanvas", listUrl: "/news/authors/livecanvas/" }
|
|
94
134
|
*/
|
|
95
|
-
export declare const authorData: (
|
|
135
|
+
export declare const authorData: ({ name, email, url }: AuthorConfig, typeUrl: string) => TemplateDataAuthor;
|
|
96
136
|
/**
|
|
97
137
|
* Build a tag's template data.
|
|
98
138
|
*
|
|
@@ -2,10 +2,15 @@ import { stat } from "node:fs/promises";
|
|
|
2
2
|
import { basename, join } from "node:path";
|
|
3
3
|
import mime from "mime-types";
|
|
4
4
|
import { parse } from "yaml";
|
|
5
|
-
import { formatBytes, isRelativeUrl, stripHtml, cropText, escapeHtml, } from "../format/index.js";
|
|
5
|
+
import { maskCode, rawHtml, replaceRawBlocks, formatBytes, isRelativeUrl, stripHtml, cropText, escapeHtml, } from "../format/index.js";
|
|
6
6
|
import { isSlug, slugify } from "../slug/index.js";
|
|
7
|
-
|
|
8
|
-
|
|
7
|
+
import { articleMetadata, templateMetadata, } from "../metadata/index.js";
|
|
8
|
+
/** Formats an article's config header can be written in */
|
|
9
|
+
export const HEADER_FORMATS = ["yaml", "yml", "json"];
|
|
10
|
+
/** The format articles' config headers are written in by default */
|
|
11
|
+
export const DEFAULT_HEADER_FORMAT = "yaml";
|
|
12
|
+
/** The config header at the start of an article: `<!--yaml ... -->`, `<!--yml ... -->` or `<!--json ... -->` */
|
|
13
|
+
const HEADER = /^\s*<!--(yaml|yml|json)[ \t]*\r?\n([\s\S]*?)-->/;
|
|
9
14
|
/** The `<!-- readmore -->` shortcode */
|
|
10
15
|
export const READMORE = /<!--\s*readmore\s*-->/;
|
|
11
16
|
/** A leading `# Title` line (only blank lines before it) */
|
|
@@ -16,17 +21,42 @@ const ANY_H1 = /^#[ \t]+(.+?)[ \t#]*$/m;
|
|
|
16
21
|
export const EXCERPT_LENGTH = 200;
|
|
17
22
|
const STATUSES = ["published", "draft", "unlisted"];
|
|
18
23
|
/**
|
|
19
|
-
*
|
|
24
|
+
* The format of an article's config header, or DEFAULT_HEADER_FORMAT if it has none.
|
|
20
25
|
*
|
|
21
26
|
* @example
|
|
22
|
-
*
|
|
27
|
+
* headerFormat("<!--json\n{}\n-->\n# Hi"); // "json"
|
|
28
|
+
*/
|
|
29
|
+
export const headerFormat = (source) => HEADER.exec(source)?.[1] ??
|
|
30
|
+
DEFAULT_HEADER_FORMAT;
|
|
31
|
+
/**
|
|
32
|
+
* Split an article's source into its parsed config header (empty if there is none), the header's format and its
|
|
33
|
+
* markdown content. The header is YAML (`<!--yaml` or `<!--yml`) or JSON (`<!--json`). Throws if it can't be read.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* splitArticle("<!--yaml\ndate: 2026-10-19\n-->\n# Hi"); // { header: { date: "2026-10-19" }, format: "yaml", content: "\n# Hi" }
|
|
37
|
+
* splitArticle('<!--json\n{ "date": "2026-10-19" }\n-->\n# Hi'); // { header: { date: "2026-10-19" }, format: "json", content: "\n# Hi" }
|
|
23
38
|
*/
|
|
24
39
|
export const splitArticle = (source) => {
|
|
25
40
|
const match = HEADER.exec(source);
|
|
26
41
|
if (!match)
|
|
27
|
-
return { header: {}, content: source };
|
|
42
|
+
return { header: {}, format: DEFAULT_HEADER_FORMAT, content: source };
|
|
43
|
+
const format = match[1];
|
|
44
|
+
const text = match[2];
|
|
45
|
+
let header;
|
|
46
|
+
try {
|
|
47
|
+
header =
|
|
48
|
+
format === "json"
|
|
49
|
+
? text.trim()
|
|
50
|
+
? JSON.parse(text)
|
|
51
|
+
: null
|
|
52
|
+
: parse(text);
|
|
53
|
+
}
|
|
54
|
+
catch (error) {
|
|
55
|
+
throw new Error(`the ${format} config header can't be read: ${error.message}`, { cause: error });
|
|
56
|
+
}
|
|
28
57
|
return {
|
|
29
|
-
header:
|
|
58
|
+
header: header ?? {},
|
|
59
|
+
format,
|
|
30
60
|
content: source.slice(match[0].length),
|
|
31
61
|
};
|
|
32
62
|
};
|
|
@@ -73,7 +103,9 @@ export const parseArticleConfig = (header, folderType, source) => {
|
|
|
73
103
|
fail(source, `"date" must be an ISO 8601 timestamp`);
|
|
74
104
|
const date = new Date(rawDate).toISOString();
|
|
75
105
|
let author;
|
|
76
|
-
if (
|
|
106
|
+
if (data.author === false)
|
|
107
|
+
author = false;
|
|
108
|
+
else if (typeof data.author === "string")
|
|
77
109
|
author = { name: data.author.trim() };
|
|
78
110
|
else if (data.author !== undefined && data.author !== null) {
|
|
79
111
|
const fields = asMap(data.author, source, `"author"`);
|
|
@@ -117,39 +149,57 @@ export const parseArticleConfig = (header, folderType, source) => {
|
|
|
117
149
|
};
|
|
118
150
|
};
|
|
119
151
|
/**
|
|
120
|
-
* Split article markdown into its title heading, body and the part before `<!-- readmore -->`.
|
|
152
|
+
* Split article markdown into its title heading, body and the part before `<!-- readmore -->`. Raw blocks become HTML
|
|
153
|
+
* that shows their content as it is (see rawHtml) first, so nothing inside them is read as a title or shortcode.
|
|
121
154
|
*
|
|
122
155
|
* @example
|
|
123
156
|
* splitContent("# Hi\n\nIntro <!-- readmore -->rest"); // { heading: "Hi", body: "\nIntro rest", beforeReadmore: "\nIntro" }
|
|
124
157
|
*/
|
|
125
158
|
export const splitContent = (content) => {
|
|
126
|
-
const
|
|
127
|
-
const
|
|
128
|
-
const
|
|
159
|
+
const markdown = replaceRawBlocks(content, rawHtml);
|
|
160
|
+
const heading = ANY_H1.exec(markdown)?.[1];
|
|
161
|
+
const withoutTitle = markdown.replace(LEADING_H1, "");
|
|
162
|
+
// The first break outside code (code may show the shortcode itself)
|
|
163
|
+
const readmore = READMORE.exec(maskCode(withoutTitle));
|
|
164
|
+
if (!readmore)
|
|
165
|
+
return { heading, body: withoutTitle.trim(), beforeReadmore: undefined };
|
|
166
|
+
const before = withoutTitle.slice(0, readmore.index);
|
|
129
167
|
return {
|
|
130
168
|
heading,
|
|
131
|
-
body: withoutTitle.
|
|
132
|
-
beforeReadmore:
|
|
133
|
-
? withoutTitle.slice(0, readmore.index).trim()
|
|
134
|
-
: undefined,
|
|
169
|
+
body: (before + withoutTitle.slice(readmore.index + readmore[0].length)).trim(),
|
|
170
|
+
beforeReadmore: before.trim(),
|
|
135
171
|
};
|
|
136
172
|
};
|
|
137
173
|
/**
|
|
138
|
-
*
|
|
174
|
+
* An article's author: its own, or `false` for none; without one, its type's default (or `false` for none); without
|
|
175
|
+
* that, the website's default (the config file's `author`, or the website's name; undefined when it is `false`).
|
|
176
|
+
*
|
|
177
|
+
* @example
|
|
178
|
+
* articleAuthor(undefined, { name: "Docs team" }, { name: "Matt" }); // { name: "Docs team" }
|
|
179
|
+
* articleAuthor(false, undefined, { name: "Matt" }); // undefined
|
|
180
|
+
*/
|
|
181
|
+
export const articleAuthor = (own, typeDefault, siteDefault) => {
|
|
182
|
+
if (own !== undefined)
|
|
183
|
+
return own || undefined;
|
|
184
|
+
if (typeDefault !== undefined)
|
|
185
|
+
return typeDefault || undefined;
|
|
186
|
+
return siteDefault;
|
|
187
|
+
};
|
|
188
|
+
/**
|
|
189
|
+
* Build an author's template data.
|
|
139
190
|
*
|
|
140
191
|
* @param typeUrl - the URL of the article type, which its author lists are under
|
|
141
192
|
*
|
|
142
193
|
* @example
|
|
143
|
-
* authorData({ name: "
|
|
194
|
+
* authorData({ name: "LiveCanvas" }, "/news/"); // { name: "LiveCanvas", slug: "livecanvas", listUrl: "/news/authors/livecanvas/" }
|
|
144
195
|
*/
|
|
145
|
-
export const authorData = (
|
|
146
|
-
const name = author?.name ?? blogName;
|
|
196
|
+
export const authorData = ({ name, email, url }, typeUrl) => {
|
|
147
197
|
const slug = slugify(name);
|
|
148
198
|
return {
|
|
149
199
|
name,
|
|
150
200
|
slug,
|
|
151
|
-
email
|
|
152
|
-
url
|
|
201
|
+
email,
|
|
202
|
+
url,
|
|
153
203
|
listUrl: `${typeUrl}authors/${slug}/`,
|
|
154
204
|
};
|
|
155
205
|
};
|
|
@@ -210,7 +260,14 @@ const attachmentData = async (attachment, articleUrl, context) => {
|
|
|
210
260
|
* await loadArticle(source, "article", context);
|
|
211
261
|
*/
|
|
212
262
|
export const loadArticle = async (source, type, context) => {
|
|
213
|
-
|
|
263
|
+
let split;
|
|
264
|
+
try {
|
|
265
|
+
split = splitArticle(source);
|
|
266
|
+
}
|
|
267
|
+
catch (error) {
|
|
268
|
+
return fail(context.source, error.message);
|
|
269
|
+
}
|
|
270
|
+
const { header, content } = split;
|
|
214
271
|
const config = parseArticleConfig(header, type, context.source);
|
|
215
272
|
if (config.status === "draft")
|
|
216
273
|
return undefined;
|
|
@@ -219,8 +276,18 @@ export const loadArticle = async (source, type, context) => {
|
|
|
219
276
|
parts.heading ??
|
|
220
277
|
fail(context.source, `needs a "title" in its config or a "# Title" heading`);
|
|
221
278
|
const url = context.url;
|
|
279
|
+
const author = articleAuthor(config.author, context.site.types[type]?.author, context.site.author);
|
|
280
|
+
// Custom metadata: problems are reported, and values with errors are left out
|
|
281
|
+
let meta = {};
|
|
282
|
+
if (context.metadata) {
|
|
283
|
+
const { validator, keys, typeLabel, warn } = context.metadata;
|
|
284
|
+
const metadata = articleMetadata(header, keys, validator, typeLabel);
|
|
285
|
+
for (const { path, message } of metadata.problems)
|
|
286
|
+
warn(`${context.source}: "${path}" ${message}`);
|
|
287
|
+
meta = templateMetadata(metadata, validator.definitions, url);
|
|
288
|
+
}
|
|
222
289
|
const body = parts.body;
|
|
223
|
-
const bodyHtml = context.renderMarkdown(await context.replaceEmbeds(body), url);
|
|
290
|
+
const bodyHtml = context.renderMarkdown(await context.replaceEmbeds(body, "body"), url);
|
|
224
291
|
const bodyText = stripHtml(bodyHtml);
|
|
225
292
|
const excerptSource = config.excerpt ?? parts.beforeReadmore;
|
|
226
293
|
let excerpt;
|
|
@@ -231,7 +298,7 @@ export const loadArticle = async (source, type, context) => {
|
|
|
231
298
|
}
|
|
232
299
|
else {
|
|
233
300
|
excerpt = excerptSource;
|
|
234
|
-
excerptHtml = context.renderMarkdown(await context.replaceEmbeds(excerptSource), url);
|
|
301
|
+
excerptHtml = context.renderMarkdown(await context.replaceEmbeds(excerptSource, "excerpt"), url);
|
|
235
302
|
}
|
|
236
303
|
return {
|
|
237
304
|
type,
|
|
@@ -241,7 +308,7 @@ export const loadArticle = async (source, type, context) => {
|
|
|
241
308
|
template: config.template ?? "single",
|
|
242
309
|
url,
|
|
243
310
|
title,
|
|
244
|
-
author: authorData(
|
|
311
|
+
author: author && authorData(author, context.typeUrl),
|
|
245
312
|
thumbnail: config.thumbnail
|
|
246
313
|
? (await resolveFile(config.thumbnail, url, context)).url
|
|
247
314
|
: undefined,
|
|
@@ -253,5 +320,6 @@ export const loadArticle = async (source, type, context) => {
|
|
|
253
320
|
bodyText,
|
|
254
321
|
bodyHtml,
|
|
255
322
|
attachments: await Promise.all(config.attachments.map((attachment) => attachmentData(attachment, url, context))),
|
|
323
|
+
meta,
|
|
256
324
|
};
|
|
257
325
|
};
|
|
@@ -1,29 +1,35 @@
|
|
|
1
|
-
import { type
|
|
2
|
-
import { type ArticleTypeConfig, type
|
|
3
|
-
import type { Logger, TemplateDataArticle,
|
|
1
|
+
import { type EmbedPlugin } from "../../embeds/index.ts";
|
|
2
|
+
import { type ArticleTypeConfig, type EdahaConfig } from "../config/index.ts";
|
|
3
|
+
import type { Logger, TemplateData, TemplateDataArticle, TemplateDataList, TemplateDataSite } from "../types/index.ts";
|
|
4
4
|
export { RESERVED_TYPES } from "../config/index.ts";
|
|
5
|
-
/** Used for feeds when neither `SITE_URL` nor `siteUrl` in config
|
|
5
|
+
/** Used for feeds when neither `SITE_URL` nor `siteUrl` in the config file is set */
|
|
6
6
|
export declare const DEFAULT_SITE_URL = "http://localhost";
|
|
7
|
-
/** Options for building the
|
|
7
|
+
/** Options for building the site */
|
|
8
8
|
export interface BuildOptions {
|
|
9
|
-
/**
|
|
10
|
-
|
|
9
|
+
/**
|
|
10
|
+
* The folder to look for a config file in, before the nearest package.json's folder (see findConfigFile). Default:
|
|
11
|
+
* the current folder. The site folder is the config file's folder: it holds the articles folder (`articlesDir`), and
|
|
12
|
+
* optionally the templates and static files folders (`templatesDir` and `staticDir`).
|
|
13
|
+
*/
|
|
14
|
+
siteDir?: string | undefined;
|
|
15
|
+
/** The config file to use instead of looking for one */
|
|
16
|
+
configFile?: string | undefined;
|
|
11
17
|
/** The default theme folder (holds templates/ and static/) that the site's own files override. Default: THEME_DIR */
|
|
12
18
|
themeDir?: string;
|
|
13
|
-
/** The website's absolute URL, for feeds. Defaults to `siteUrl` in config
|
|
19
|
+
/** The website's absolute URL, for feeds. Defaults to `siteUrl` in the config file, then DEFAULT_SITE_URL with a warning. */
|
|
14
20
|
siteUrl?: string | undefined;
|
|
15
21
|
/** Where warnings go (defaults to console) */
|
|
16
22
|
logger?: Logger;
|
|
17
23
|
/** Fetches extra data for embeds (defaults to the global fetch) */
|
|
18
24
|
fetch?: typeof fetch;
|
|
19
|
-
/** Embed
|
|
20
|
-
|
|
25
|
+
/** Embed plugins added after the config file's `plugins` (a key in both uses the config file's). Default: none */
|
|
26
|
+
plugins?: readonly EmbedPlugin[];
|
|
21
27
|
}
|
|
22
28
|
/** What a build produced */
|
|
23
29
|
export interface BuildResult {
|
|
24
30
|
/** The absolute output directory */
|
|
25
31
|
outputDir: string;
|
|
26
|
-
/** The absolute folder the files were copied to, if config
|
|
32
|
+
/** The absolute folder the files were copied to, if the config file sets `publishDir` */
|
|
27
33
|
publishDir: string | undefined;
|
|
28
34
|
/** Rendered articles (published and unlisted) */
|
|
29
35
|
articles: TemplateDataArticle[];
|
|
@@ -31,19 +37,22 @@ export interface BuildResult {
|
|
|
31
37
|
files: string[];
|
|
32
38
|
}
|
|
33
39
|
/**
|
|
34
|
-
* Resolve `outputDir` from config
|
|
35
|
-
* emptied on every build.
|
|
40
|
+
* Resolve `outputDir` from the config file: a folder inside the site folder, apart from its source folders (the
|
|
41
|
+
* articles, templates and static files folders), as it is emptied on every build.
|
|
42
|
+
*
|
|
43
|
+
* @param sources - the source folders, relative to the site folder (default: the default ones)
|
|
36
44
|
*
|
|
37
45
|
* @example
|
|
38
|
-
* resolveOutputDir("/site", "
|
|
46
|
+
* resolveOutputDir("/site", "build"); // "/site/build"
|
|
47
|
+
* resolveOutputDir("/site", "site/build", ["site/content", "site/templates", "site/static"]); // "/site/site/build"
|
|
39
48
|
*/
|
|
40
|
-
export declare const resolveOutputDir: (siteDir: string, folder: string) => string;
|
|
49
|
+
export declare const resolveOutputDir: (siteDir: string, folder: string, sources?: readonly string[]) => string;
|
|
41
50
|
/**
|
|
42
|
-
* Resolve `publishDir` from config
|
|
51
|
+
* Resolve `publishDir` from the config file, relative to the site folder: any folder apart from the site folder, e.g.
|
|
43
52
|
* another app's build folder.
|
|
44
53
|
*
|
|
45
54
|
* @example
|
|
46
|
-
* resolvePublishDir("/work/
|
|
55
|
+
* resolvePublishDir("/work/site", "../app/dist"); // "/work/app/dist"
|
|
47
56
|
*/
|
|
48
57
|
export declare const resolvePublishDir: (siteDir: string, folder: string) => string;
|
|
49
58
|
/**
|
|
@@ -56,22 +65,45 @@ export declare const resolvePublishDir: (siteDir: string, folder: string) => str
|
|
|
56
65
|
*/
|
|
57
66
|
export declare const staticFiles: (dirs: string[]) => Promise<Map<string, string>>;
|
|
58
67
|
/**
|
|
59
|
-
* The
|
|
68
|
+
* The website's template data: its name, description, absolute URL and home URL, default author, and each article
|
|
69
|
+
* type's settings and URL.
|
|
60
70
|
*
|
|
61
71
|
* @param typeConfigs - the article types' settings (configured ones, plus defaults for any others)
|
|
72
|
+
* @param url - the website's absolute URL (a trailing slash is removed)
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* siteData(config, config.types, "https://example.com").types.news.url; // "/news/"
|
|
76
|
+
*/
|
|
77
|
+
export declare const siteData: (config: EdahaConfig, typeConfigs: Record<string, ArticleTypeConfig>, url: string) => TemplateDataSite;
|
|
78
|
+
/**
|
|
79
|
+
* The template data for an article's page, with its type's list for an index article.
|
|
80
|
+
*
|
|
81
|
+
* @example
|
|
82
|
+
* articlePageData(site, article); // { site, type: "news", isArticle: true, isList: false, article }
|
|
83
|
+
*/
|
|
84
|
+
export declare const articlePageData: (site: TemplateDataSite, article: TemplateDataArticle, list?: TemplateDataList) => TemplateData;
|
|
85
|
+
/**
|
|
86
|
+
* The template data for a list's page or feed.
|
|
87
|
+
*
|
|
88
|
+
* @example
|
|
89
|
+
* listPageData(site, list); // { site, type: "news", isArticle: false, isList: true, list }
|
|
90
|
+
*/
|
|
91
|
+
export declare const listPageData: (site: TemplateDataSite, list: TemplateDataList) => TemplateData;
|
|
92
|
+
/**
|
|
93
|
+
* The embed plugins to build with: the config file's, then the given ones whose keys the config file doesn't use.
|
|
62
94
|
*
|
|
63
95
|
* @example
|
|
64
|
-
*
|
|
96
|
+
* withPlugins([youtube], [youtube2, mermaidjs]); // [youtube, mermaidjs]
|
|
65
97
|
*/
|
|
66
|
-
export declare const
|
|
98
|
+
export declare const withPlugins: (configPlugins: readonly EmbedPlugin[], plugins?: readonly EmbedPlugin[]) => EmbedPlugin[];
|
|
67
99
|
/**
|
|
68
|
-
* Build the
|
|
100
|
+
* Build the site: render every published and unlisted article with its assets, then each type's paginated list and
|
|
69
101
|
* RSS feed, and its tag and author lists, and copy the static files (the theme's, overridden by the site's `static/`)
|
|
70
102
|
* as they are. Files are written to `outputDir` (emptied first). If `publishDir` is set, they are then copied into it
|
|
71
103
|
* (the website's root): the files published by the previous build are removed from it first, and the build stops if a
|
|
72
104
|
* file is already there.
|
|
73
105
|
*
|
|
74
106
|
* @example
|
|
75
|
-
* await
|
|
107
|
+
* await buildSite({ siteDir: "my-site", siteUrl: "https://example.com" });
|
|
76
108
|
*/
|
|
77
|
-
export declare const
|
|
109
|
+
export declare const buildSite: (options: BuildOptions) => Promise<BuildResult>;
|