@lvl99dotcom/edaha.md 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.
Files changed (52) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +13 -2
  3. package/dist/cli/bin.d.ts +2 -0
  4. package/dist/cli/bin.js +9 -0
  5. package/dist/cli/index.d.ts +71 -0
  6. package/dist/cli/index.js +149 -0
  7. package/dist/embeds/blocks/index.d.ts +59 -0
  8. package/dist/embeds/blocks/index.js +103 -0
  9. package/dist/embeds/index.d.ts +143 -0
  10. package/dist/embeds/index.js +411 -0
  11. package/dist/embeds/types/index.d.ts +117 -0
  12. package/dist/embeds/types/index.js +1 -0
  13. package/dist/generator/article/index.d.ts +151 -0
  14. package/dist/generator/article/index.js +325 -0
  15. package/dist/generator/build/index.d.ts +109 -0
  16. package/dist/generator/build/index.js +363 -0
  17. package/dist/generator/config/index.d.ts +96 -0
  18. package/dist/generator/config/index.js +298 -0
  19. package/dist/generator/configFile/index.d.ts +58 -0
  20. package/dist/generator/configFile/index.js +122 -0
  21. package/dist/generator/fields/index.d.ts +93 -0
  22. package/dist/generator/fields/index.js +186 -0
  23. package/dist/generator/format/index.d.ts +92 -0
  24. package/dist/generator/format/index.js +177 -0
  25. package/dist/generator/lists/index.d.ts +63 -0
  26. package/dist/generator/lists/index.js +133 -0
  27. package/dist/generator/markdown/index.d.ts +25 -0
  28. package/dist/generator/markdown/index.js +62 -0
  29. package/dist/generator/metadata/index.d.ts +150 -0
  30. package/dist/generator/metadata/index.js +361 -0
  31. package/dist/generator/metadataGroups/index.d.ts +45 -0
  32. package/dist/generator/metadataGroups/index.js +169 -0
  33. package/dist/generator/slug/index.d.ts +26 -0
  34. package/dist/generator/slug/index.js +57 -0
  35. package/dist/generator/templates/index.d.ts +88 -0
  36. package/dist/generator/templates/index.js +175 -0
  37. package/dist/generator/types/index.d.ts +186 -0
  38. package/dist/generator/types/index.js +1 -0
  39. package/dist/generator/urls/index.d.ts +50 -0
  40. package/dist/generator/urls/index.js +77 -0
  41. package/dist/index.d.ts +8 -0
  42. package/dist/index.js +9 -0
  43. package/dist/theme/index.d.ts +8 -0
  44. package/dist/theme/index.js +9 -0
  45. package/package.json +64 -3
  46. package/theme/static/base.css +328 -0
  47. package/theme/templates/article/list.njk +69 -0
  48. package/theme/templates/article/single.njk +64 -0
  49. package/theme/templates/layouts/html.njk +72 -0
  50. package/theme/templates/layouts/rssfeed.njk +28 -0
  51. package/theme/templates/page/home.njk +16 -0
  52. package/theme/templates/page/single.njk +18 -0
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,151 @@
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;
9
+ /** The `<!-- readmore -->` shortcode */
10
+ export declare const READMORE: RegExp;
11
+ /** Excerpts without a readmore shortcode or config are cropped to this many characters */
12
+ export declare const EXCERPT_LENGTH = 200;
13
+ /** An attachment as written in an article's config */
14
+ export interface AttachmentConfig {
15
+ url: string;
16
+ thumbnail?: string | undefined;
17
+ mimeType?: string | undefined;
18
+ name?: string | undefined;
19
+ }
20
+ /** An author as written in an article's config */
21
+ export interface AuthorConfig {
22
+ name: string;
23
+ email?: string | undefined;
24
+ url?: string | undefined;
25
+ }
26
+ /** An article's validated config header */
27
+ export interface ArticleConfig {
28
+ type: string;
29
+ status: ArticleStatus;
30
+ date: string;
31
+ /** The article's author, or `false` for none (undefined uses its type's or the website's default) */
32
+ author?: AuthorConfig | false | undefined;
33
+ title?: string | undefined;
34
+ template?: string | undefined;
35
+ excerpt?: string | undefined;
36
+ thumbnail?: string | undefined;
37
+ attachments: AttachmentConfig[];
38
+ tags: string[];
39
+ }
40
+ /**
41
+ * The format of an article's config header, or DEFAULT_HEADER_FORMAT if it has none.
42
+ *
43
+ * @example
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" }
54
+ */
55
+ export declare const splitArticle: (source: string) => {
56
+ header: unknown;
57
+ format: HeaderFormat;
58
+ content: string;
59
+ };
60
+ /**
61
+ * Validate an article's config header and fill in defaults.
62
+ *
63
+ * @param folderType - the type folder the article is in
64
+ * @param source - where the article is, for errors
65
+ *
66
+ * @example
67
+ * parseArticleConfig({ date: "2026-10-19T09:54:00Z" }, "article", "article/hello");
68
+ */
69
+ export declare const parseArticleConfig: (header: unknown, folderType: string, source: string) => ArticleConfig;
70
+ /** The article's content split into its parts */
71
+ export interface ArticleContent {
72
+ /** The title from the first H1, if any */
73
+ heading: string | undefined;
74
+ /** The body markdown, without a leading H1 or the readmore shortcode */
75
+ body: string;
76
+ /** The markdown before the readmore shortcode, if there is one */
77
+ beforeReadmore: string | undefined;
78
+ }
79
+ /**
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.
82
+ *
83
+ * @example
84
+ * splitContent("# Hi\n\nIntro <!-- readmore -->rest"); // { heading: "Hi", body: "\nIntro rest", beforeReadmore: "\nIntro" }
85
+ */
86
+ export declare const splitContent: (content: string) => ArticleContent;
87
+ /** Where an article is and how to render its parts */
88
+ export interface ArticleContext {
89
+ /** The website the article belongs to */
90
+ site: TemplateDataSite;
91
+ /** The article's folder on disk */
92
+ dir: string;
93
+ /** The article's slug (its folder name) */
94
+ slug: string;
95
+ /** The article's URL, e.g. "/news/hello/" */
96
+ url: string;
97
+ /** The URL of the article type's front page, which its tag and author lists are under, e.g. "/news/" */
98
+ typeUrl: string;
99
+ /** Where the article is, for errors and warnings */
100
+ source: 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>;
103
+ /** Render markdown to HTML, resolving relative URLs against a folder URL */
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;
117
+ }
118
+ /**
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.
129
+ *
130
+ * @param typeUrl - the URL of the article type, which its author lists are under
131
+ *
132
+ * @example
133
+ * authorData({ name: "LiveCanvas" }, "/news/"); // { name: "LiveCanvas", slug: "livecanvas", listUrl: "/news/authors/livecanvas/" }
134
+ */
135
+ export declare const authorData: ({ name, email, url }: AuthorConfig, typeUrl: string) => TemplateDataAuthor;
136
+ /**
137
+ * Build a tag's template data.
138
+ *
139
+ * @param typeUrl - the URL of the article type, which its tag lists are under
140
+ *
141
+ * @example
142
+ * tagData("Release Notes", "/news/"); // { name: "Release Notes", slug: "release-notes", url: "/news/tags/release-notes/" }
143
+ */
144
+ export declare const tagData: (name: string, typeUrl: string) => TemplateDataTag;
145
+ /**
146
+ * Build an article's template data from its source. Returns undefined for drafts, which are not built.
147
+ *
148
+ * @example
149
+ * await loadArticle(source, "article", context);
150
+ */
151
+ export declare const loadArticle: (source: string, type: string, context: ArticleContext) => Promise<TemplateDataArticle | undefined>;
@@ -0,0 +1,325 @@
1
+ import { stat } from "node:fs/promises";
2
+ import { basename, join } from "node:path";
3
+ import mime from "mime-types";
4
+ import { parse } from "yaml";
5
+ import { maskCode, rawHtml, replaceRawBlocks, formatBytes, isRelativeUrl, stripHtml, cropText, escapeHtml, } from "../format/index.js";
6
+ import { isSlug, slugify } from "../slug/index.js";
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]*?)-->/;
14
+ /** The `<!-- readmore -->` shortcode */
15
+ export const READMORE = /<!--\s*readmore\s*-->/;
16
+ /** A leading `# Title` line (only blank lines before it) */
17
+ const LEADING_H1 = /^\s*#[ \t]+(.+?)[ \t#]*(?:\r?\n|$)/;
18
+ /** Any `# Title` line */
19
+ const ANY_H1 = /^#[ \t]+(.+?)[ \t#]*$/m;
20
+ /** Excerpts without a readmore shortcode or config are cropped to this many characters */
21
+ export const EXCERPT_LENGTH = 200;
22
+ const STATUSES = ["published", "draft", "unlisted"];
23
+ /**
24
+ * The format of an article's config header, or DEFAULT_HEADER_FORMAT if it has none.
25
+ *
26
+ * @example
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" }
38
+ */
39
+ export const splitArticle = (source) => {
40
+ const match = HEADER.exec(source);
41
+ if (!match)
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
+ }
57
+ return {
58
+ header: header ?? {},
59
+ format,
60
+ content: source.slice(match[0].length),
61
+ };
62
+ };
63
+ /** Throw a config error for an article */
64
+ const fail = (source, message) => {
65
+ throw new Error(`${source}: ${message}`);
66
+ };
67
+ /** Read an optional string field */
68
+ const optionalString = (data, field, source) => {
69
+ const value = data[field];
70
+ if (value === undefined || value === null)
71
+ return undefined;
72
+ if (typeof value !== "string" || value.trim() === "")
73
+ return fail(source, `"${field}" must be a non-empty string`);
74
+ return value.trim();
75
+ };
76
+ /** Check a value is a map */
77
+ const asMap = (value, source, what) => value && typeof value === "object" && !Array.isArray(value)
78
+ ? value
79
+ : fail(source, `${what} must be a map of fields`);
80
+ /**
81
+ * Validate an article's config header and fill in defaults.
82
+ *
83
+ * @param folderType - the type folder the article is in
84
+ * @param source - where the article is, for errors
85
+ *
86
+ * @example
87
+ * parseArticleConfig({ date: "2026-10-19T09:54:00Z" }, "article", "article/hello");
88
+ */
89
+ export const parseArticleConfig = (header, folderType, source) => {
90
+ const data = asMap(header, source, "the config header");
91
+ const type = optionalString(data, "type", source) ?? folderType;
92
+ if (type !== folderType)
93
+ fail(source, `type "${type}" doesn't match its folder "${folderType}"`);
94
+ const template = optionalString(data, "template", source);
95
+ if (template !== undefined && (!isSlug(template) || template === "list"))
96
+ fail(source, `"template" must be a template name like "single" (lowercase kebab-case, not "list")`);
97
+ const status = (optionalString(data, "status", source) ??
98
+ "published");
99
+ if (!STATUSES.includes(status))
100
+ fail(source, `"status" must be one of ${STATUSES.join(", ")}`);
101
+ const rawDate = data.date instanceof Date ? data.date.toISOString() : data.date;
102
+ if (typeof rawDate !== "string" || Number.isNaN(Date.parse(rawDate)))
103
+ fail(source, `"date" must be an ISO 8601 timestamp`);
104
+ const date = new Date(rawDate).toISOString();
105
+ let author;
106
+ if (data.author === false)
107
+ author = false;
108
+ else if (typeof data.author === "string")
109
+ author = { name: data.author.trim() };
110
+ else if (data.author !== undefined && data.author !== null) {
111
+ const fields = asMap(data.author, source, `"author"`);
112
+ author = {
113
+ name: optionalString(fields, "name", source) ??
114
+ fail(source, `"author.name" is required`),
115
+ email: optionalString(fields, "email", source),
116
+ url: optionalString(fields, "url", source),
117
+ };
118
+ }
119
+ if (author && !slugify(author.name))
120
+ fail(source, `"author" needs a name with letters or numbers`);
121
+ const attachmentList = data.attachments ?? [];
122
+ if (!Array.isArray(attachmentList))
123
+ fail(source, `"attachments" must be a list`);
124
+ const attachments = attachmentList.map((item, i) => {
125
+ const fields = asMap(item, source, `attachment ${i + 1}`);
126
+ return {
127
+ url: optionalString(fields, "url", source) ??
128
+ fail(source, `attachment ${i + 1} needs a "url"`),
129
+ thumbnail: optionalString(fields, "thumbnail", source),
130
+ mimeType: optionalString(fields, "mimeType", source),
131
+ name: optionalString(fields, "name", source),
132
+ };
133
+ });
134
+ const tagList = data.tags ?? [];
135
+ if (!Array.isArray(tagList) ||
136
+ tagList.some((tag) => typeof tag !== "string" || !slugify(tag)))
137
+ fail(source, `"tags" must be a list of names`);
138
+ return {
139
+ type,
140
+ status,
141
+ date,
142
+ author,
143
+ title: optionalString(data, "title", source),
144
+ template,
145
+ excerpt: optionalString(data, "excerpt", source),
146
+ thumbnail: optionalString(data, "thumbnail", source),
147
+ attachments,
148
+ tags: tagList.map((tag) => tag.trim()),
149
+ };
150
+ };
151
+ /**
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.
154
+ *
155
+ * @example
156
+ * splitContent("# Hi\n\nIntro <!-- readmore -->rest"); // { heading: "Hi", body: "\nIntro rest", beforeReadmore: "\nIntro" }
157
+ */
158
+ export const splitContent = (content) => {
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);
167
+ return {
168
+ heading,
169
+ body: (before + withoutTitle.slice(readmore.index + readmore[0].length)).trim(),
170
+ beforeReadmore: before.trim(),
171
+ };
172
+ };
173
+ /**
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.
190
+ *
191
+ * @param typeUrl - the URL of the article type, which its author lists are under
192
+ *
193
+ * @example
194
+ * authorData({ name: "LiveCanvas" }, "/news/"); // { name: "LiveCanvas", slug: "livecanvas", listUrl: "/news/authors/livecanvas/" }
195
+ */
196
+ export const authorData = ({ name, email, url }, typeUrl) => {
197
+ const slug = slugify(name);
198
+ return {
199
+ name,
200
+ slug,
201
+ email,
202
+ url,
203
+ listUrl: `${typeUrl}authors/${slug}/`,
204
+ };
205
+ };
206
+ /**
207
+ * Build a tag's template data.
208
+ *
209
+ * @param typeUrl - the URL of the article type, which its tag lists are under
210
+ *
211
+ * @example
212
+ * tagData("Release Notes", "/news/"); // { name: "Release Notes", slug: "release-notes", url: "/news/tags/release-notes/" }
213
+ */
214
+ export const tagData = (name, typeUrl) => {
215
+ const slug = slugify(name);
216
+ return { name, slug, url: `${typeUrl}tags/${slug}/` };
217
+ };
218
+ /**
219
+ * Resolve a URL from an article's config: relative URLs must be files in the article's folder and become
220
+ * root-relative URLs. Returns the URL and, for local files, the file size.
221
+ */
222
+ const resolveFile = async (url, articleUrl, context) => {
223
+ if (!isRelativeUrl(url))
224
+ return { url };
225
+ const file = join(context.dir, decodeURIComponent(url.split(/[?#]/)[0]));
226
+ try {
227
+ const info = await stat(file);
228
+ if (!info.isFile())
229
+ throw new Error();
230
+ return { url: articleUrl + url, size: info.size };
231
+ }
232
+ catch {
233
+ return fail(context.source, `"${url}" was not found in the article's folder`);
234
+ }
235
+ };
236
+ /**
237
+ * Build an attachment's template data, filling in its name and mime type from the file name and its size from the file.
238
+ */
239
+ const attachmentData = async (attachment, articleUrl, context) => {
240
+ const file = await resolveFile(attachment.url, articleUrl, context);
241
+ const thumbnail = attachment.thumbnail
242
+ ? (await resolveFile(attachment.thumbnail, articleUrl, context)).url
243
+ : undefined;
244
+ const fileName = decodeURIComponent(basename(new URL(attachment.url, "file:///").pathname));
245
+ return {
246
+ name: attachment.name ?? fileName,
247
+ thumbnail,
248
+ url: file.url,
249
+ mimeType: attachment.mimeType ||
250
+ mime.lookup(fileName) ||
251
+ "application/octet-stream",
252
+ size: file.size,
253
+ sizeRelative: file.size === undefined ? undefined : formatBytes(file.size),
254
+ };
255
+ };
256
+ /**
257
+ * Build an article's template data from its source. Returns undefined for drafts, which are not built.
258
+ *
259
+ * @example
260
+ * await loadArticle(source, "article", context);
261
+ */
262
+ export const loadArticle = async (source, type, context) => {
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;
271
+ const config = parseArticleConfig(header, type, context.source);
272
+ if (config.status === "draft")
273
+ return undefined;
274
+ const parts = splitContent(content);
275
+ const title = config.title ??
276
+ parts.heading ??
277
+ fail(context.source, `needs a "title" in its config or a "# Title" heading`);
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
+ }
289
+ const body = parts.body;
290
+ const bodyHtml = context.renderMarkdown(await context.replaceEmbeds(body, "body"), url);
291
+ const bodyText = stripHtml(bodyHtml);
292
+ const excerptSource = config.excerpt ?? parts.beforeReadmore;
293
+ let excerpt;
294
+ let excerptHtml;
295
+ if (excerptSource === undefined) {
296
+ excerpt = cropText(bodyText, EXCERPT_LENGTH);
297
+ excerptHtml = `<p>${escapeHtml(excerpt)}</p>`;
298
+ }
299
+ else {
300
+ excerpt = excerptSource;
301
+ excerptHtml = context.renderMarkdown(await context.replaceEmbeds(excerptSource, "excerpt"), url);
302
+ }
303
+ return {
304
+ type,
305
+ status: config.status,
306
+ date: config.date,
307
+ slug: context.slug,
308
+ template: config.template ?? "single",
309
+ url,
310
+ title,
311
+ author: author && authorData(author, context.typeUrl),
312
+ thumbnail: config.thumbnail
313
+ ? (await resolveFile(config.thumbnail, url, context)).url
314
+ : undefined,
315
+ tags: config.tags.map((tag) => tagData(tag, context.typeUrl)),
316
+ excerpt,
317
+ excerptText: stripHtml(excerptHtml),
318
+ excerptHtml,
319
+ body,
320
+ bodyText,
321
+ bodyHtml,
322
+ attachments: await Promise.all(config.attachments.map((attachment) => attachmentData(attachment, url, context))),
323
+ meta,
324
+ };
325
+ };
@@ -0,0 +1,109 @@
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
+ export { RESERVED_TYPES } from "../config/index.ts";
5
+ /** Used for feeds when neither `SITE_URL` nor `siteUrl` in the config file is set */
6
+ export declare const DEFAULT_SITE_URL = "http://localhost";
7
+ /** Options for building the site */
8
+ export interface BuildOptions {
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;
17
+ /** The default theme folder (holds templates/ and static/) that the site's own files override. Default: THEME_DIR */
18
+ themeDir?: string;
19
+ /** The website's absolute URL, for feeds. Defaults to `siteUrl` in the config file, then DEFAULT_SITE_URL with a warning. */
20
+ siteUrl?: string | undefined;
21
+ /** Where warnings go (defaults to console) */
22
+ logger?: Logger;
23
+ /** Fetches extra data for embeds (defaults to the global fetch) */
24
+ fetch?: typeof fetch;
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[];
27
+ }
28
+ /** What a build produced */
29
+ export interface BuildResult {
30
+ /** The absolute output directory */
31
+ outputDir: string;
32
+ /** The absolute folder the files were copied to, if the config file sets `publishDir` */
33
+ publishDir: string | undefined;
34
+ /** Rendered articles (published and unlisted) */
35
+ articles: TemplateDataArticle[];
36
+ /** Files written, relative to the output directory (and the publish directory) */
37
+ files: string[];
38
+ }
39
+ /**
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)
44
+ *
45
+ * @example
46
+ * resolveOutputDir("/site", "build"); // "/site/build"
47
+ * resolveOutputDir("/site", "site/build", ["site/content", "site/templates", "site/static"]); // "/site/site/build"
48
+ */
49
+ export declare const resolveOutputDir: (siteDir: string, folder: string, sources?: readonly string[]) => string;
50
+ /**
51
+ * Resolve `publishDir` from the config file, relative to the site folder: any folder apart from the site folder, e.g.
52
+ * another app's build folder.
53
+ *
54
+ * @example
55
+ * resolvePublishDir("/work/site", "../app/dist"); // "/work/app/dist"
56
+ */
57
+ export declare const resolvePublishDir: (siteDir: string, folder: string) => string;
58
+ /**
59
+ * Map each static file's path to its source: the theme's files, overridden by the site's files with the same path.
60
+ *
61
+ * @param dirs - static folders, the overriding one last
62
+ *
63
+ * @example
64
+ * await staticFiles(["/theme/static", "/site/static"]); // Map { "site.css" => "/site/static/site.css", ... }
65
+ */
66
+ export declare const staticFiles: (dirs: string[]) => Promise<Map<string, string>>;
67
+ /**
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.
70
+ *
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.
94
+ *
95
+ * @example
96
+ * withPlugins([youtube], [youtube2, mermaidjs]); // [youtube, mermaidjs]
97
+ */
98
+ export declare const withPlugins: (configPlugins: readonly EmbedPlugin[], plugins?: readonly EmbedPlugin[]) => EmbedPlugin[];
99
+ /**
100
+ * Build the site: render every published and unlisted article with its assets, then each type's paginated list and
101
+ * RSS feed, and its tag and author lists, and copy the static files (the theme's, overridden by the site's `static/`)
102
+ * as they are. Files are written to `outputDir` (emptied first). If `publishDir` is set, they are then copied into it
103
+ * (the website's root): the files published by the previous build are removed from it first, and the build stops if a
104
+ * file is already there.
105
+ *
106
+ * @example
107
+ * await buildSite({ siteDir: "my-site", siteUrl: "https://example.com" });
108
+ */
109
+ export declare const buildSite: (options: BuildOptions) => Promise<BuildResult>;