@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
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
import { Ajv } from "ajv";
|
|
2
|
+
import { fullFormats } from "ajv-formats/dist/formats.js";
|
|
3
|
+
import { checkFieldExtensions, resolveFields } from "../fields/index.js";
|
|
4
|
+
import { isRelativeUrl } from "../format/index.js";
|
|
5
|
+
/** The kinds of field the editor can show for a metadata value (the key under `$edahaField` that configures it) */
|
|
6
|
+
export const FIELD_KINDS = [
|
|
7
|
+
"text",
|
|
8
|
+
"email",
|
|
9
|
+
"url",
|
|
10
|
+
"tel",
|
|
11
|
+
"color",
|
|
12
|
+
"date",
|
|
13
|
+
"time",
|
|
14
|
+
"datetime-local",
|
|
15
|
+
"number",
|
|
16
|
+
"range",
|
|
17
|
+
"textarea",
|
|
18
|
+
"select",
|
|
19
|
+
"checkbox",
|
|
20
|
+
"radio",
|
|
21
|
+
"file",
|
|
22
|
+
];
|
|
23
|
+
/** The settings every article has, which custom metadata can't use as keys */
|
|
24
|
+
export const CORE_FIELDS = [
|
|
25
|
+
"type",
|
|
26
|
+
"status",
|
|
27
|
+
"date",
|
|
28
|
+
"title",
|
|
29
|
+
"template",
|
|
30
|
+
"author",
|
|
31
|
+
"excerpt",
|
|
32
|
+
"thumbnail",
|
|
33
|
+
"attachments",
|
|
34
|
+
"tags",
|
|
35
|
+
];
|
|
36
|
+
/** Metadata keys: a letter or underscore, then letters, digits, underscores or hyphens */
|
|
37
|
+
const KEY = /^[A-Za-z_][\w-]*$/;
|
|
38
|
+
/** Check a value is a map (not a list), throwing an Error naming it if not */
|
|
39
|
+
const asMap = (value, what) => {
|
|
40
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
41
|
+
throw new Error(`${what} must be a map of settings`);
|
|
42
|
+
return value;
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* The kind of field an `$edahaField` configures.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* fieldKind({ title: "Image", file: { accept: "image/*" } }); // "file"
|
|
49
|
+
*/
|
|
50
|
+
export const fieldKind = (field) => FIELD_KINDS.find((kind) => kind in field);
|
|
51
|
+
/**
|
|
52
|
+
* Whether an `$edahaField` names a field kind (maps' and lists' may only set their group and labels).
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* hasFieldKind({ group: "files" }); // false
|
|
56
|
+
*/
|
|
57
|
+
export const hasFieldKind = (field) => Boolean(field &&
|
|
58
|
+
typeof field === "object" &&
|
|
59
|
+
FIELD_KINDS.some((kind) => kind in field));
|
|
60
|
+
/**
|
|
61
|
+
* A field kind's options, e.g. `{ accept: "image/*" }` for `{ file: { accept: "image/*" } }` (none for `true`).
|
|
62
|
+
*/
|
|
63
|
+
export const fieldOptions = (field) => {
|
|
64
|
+
const options = field[fieldKind(field)];
|
|
65
|
+
return options && typeof options === "object"
|
|
66
|
+
? options
|
|
67
|
+
: {};
|
|
68
|
+
};
|
|
69
|
+
/**
|
|
70
|
+
* Check a schema has editor fields: objects need properties, lists need items (or one field for the whole list), and
|
|
71
|
+
* every value has an `$edahaField` with exactly one field kind. Objects' and lists' own `$edahaField` may set only their
|
|
72
|
+
* group, labels and conditions. Default values and conditions are checked too (see checkFieldExtensions). Throws an Error naming the schema's path.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* checkFieldSchema({ type: "string", $edahaField: { text: true } }, "metadata.subtitle");
|
|
76
|
+
*/
|
|
77
|
+
export const checkFieldSchema = (schema, path) => {
|
|
78
|
+
const fields = asMap(schema, `"${path}"`);
|
|
79
|
+
if (fields.$edahaField !== undefined)
|
|
80
|
+
checkFieldExtensions(asMap(fields.$edahaField, `"${path}.$edahaField"`), `"${path}.$edahaField"`);
|
|
81
|
+
if (fields.type === "object") {
|
|
82
|
+
if (Array.isArray(fields.properties))
|
|
83
|
+
throw new Error(`"${path}.properties" must be a map of each property's name to its schema, not a list (remove the "-"s and put each schema under its property's name)`);
|
|
84
|
+
const properties = asMap(fields.properties, `"${path}.properties"`);
|
|
85
|
+
for (const [name, property] of Object.entries(properties))
|
|
86
|
+
checkFieldSchema(property, `${path}.properties.${name}`);
|
|
87
|
+
return;
|
|
88
|
+
}
|
|
89
|
+
// A list is edited item by item, unless one field edits it all (e.g. a select with `multiple`)
|
|
90
|
+
if (fields.type === "array" && !hasFieldKind(fields.$edahaField)) {
|
|
91
|
+
// A list of schemas describes each item in turn; the editor needs one schema for every item
|
|
92
|
+
if (Array.isArray(fields.items))
|
|
93
|
+
throw new Error(`"${path}.items" must be one schema for every item, not a list (remove the "-" before it)`);
|
|
94
|
+
checkFieldSchema(fields.items, `${path}.items`);
|
|
95
|
+
return;
|
|
96
|
+
}
|
|
97
|
+
const field = asMap(fields.$edahaField, `"${path}.$edahaField"`);
|
|
98
|
+
const kinds = FIELD_KINDS.filter((kind) => kind in field);
|
|
99
|
+
if (kinds.length !== 1)
|
|
100
|
+
throw new Error(`"${path}.$edahaField" must have exactly one field kind (${FIELD_KINDS.join(", ")}), not ${kinds.length ? kinds.join(" and ") : "none"}`);
|
|
101
|
+
};
|
|
102
|
+
/**
|
|
103
|
+
* An ajv instance for metadata schemas: every error reported, formats like `uri` and `email` checked, and `$edahaField`
|
|
104
|
+
* allowed beside JSON Schema's own keywords.
|
|
105
|
+
*/
|
|
106
|
+
export const createAjv = () => {
|
|
107
|
+
const ajv = new Ajv({ allErrors: true, strict: false, formats: fullFormats });
|
|
108
|
+
ajv.addKeyword({ keyword: "$edahaField", schemaType: "object" });
|
|
109
|
+
return ajv;
|
|
110
|
+
};
|
|
111
|
+
/**
|
|
112
|
+
* Read the config file's `metadata` setting: a map of keys to JSON Schemas with `$edahaField`s. Throws an Error if a
|
|
113
|
+
* key is a core field's name or isn't a usable name, or a schema has no editor fields or can't be compiled.
|
|
114
|
+
*
|
|
115
|
+
* @example
|
|
116
|
+
* parseMetadata({ featured: { type: "string", $edahaField: { file: { accept: "image/*" } } } });
|
|
117
|
+
*/
|
|
118
|
+
export const parseMetadata = (value) => {
|
|
119
|
+
if (value === undefined || value === null)
|
|
120
|
+
return {};
|
|
121
|
+
const definitions = asMap(value, '"metadata"');
|
|
122
|
+
const ajv = createAjv();
|
|
123
|
+
for (const [key, schema] of Object.entries(definitions)) {
|
|
124
|
+
if (CORE_FIELDS.includes(key))
|
|
125
|
+
throw new Error(`"metadata.${key}" can't be used: "${key}" is a core setting of every article`);
|
|
126
|
+
if (!KEY.test(key))
|
|
127
|
+
throw new Error(`"metadata.${key}" must start with a letter or "_" and have only letters, digits, "_" and "-"`);
|
|
128
|
+
checkFieldSchema(schema, `metadata.${key}`);
|
|
129
|
+
try {
|
|
130
|
+
ajv.compile(schema);
|
|
131
|
+
}
|
|
132
|
+
catch (error) {
|
|
133
|
+
throw new Error(`"metadata.${key}" isn't a valid JSON Schema: ${error.message}`, { cause: error });
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
return definitions;
|
|
137
|
+
};
|
|
138
|
+
/**
|
|
139
|
+
* The custom metadata fields an article type uses: those its `metadata` setting lists, none for `false`, or all when
|
|
140
|
+
* it has none.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* typeMetadataKeys({ featured: {...}, images: {...} }, ["featured"]); // ["featured"]
|
|
144
|
+
*/
|
|
145
|
+
export const typeMetadataKeys = (definitions, typeMetadata) => typeMetadata === undefined
|
|
146
|
+
? Object.keys(definitions)
|
|
147
|
+
: typeMetadata === false
|
|
148
|
+
? []
|
|
149
|
+
: typeMetadata;
|
|
150
|
+
/** JSON types in plain words, e.g. "a number" */
|
|
151
|
+
const TYPE_NAMES = {
|
|
152
|
+
string: "text",
|
|
153
|
+
number: "a number",
|
|
154
|
+
integer: "a whole number",
|
|
155
|
+
boolean: "yes or no",
|
|
156
|
+
array: "a list",
|
|
157
|
+
object: "a group of settings",
|
|
158
|
+
null: "empty",
|
|
159
|
+
};
|
|
160
|
+
/** Formats in plain words, e.g. "an email address" */
|
|
161
|
+
const FORMAT_NAMES = {
|
|
162
|
+
email: "an email address",
|
|
163
|
+
uri: "a full web address, e.g. https://example.com",
|
|
164
|
+
url: "a full web address, e.g. https://example.com",
|
|
165
|
+
"uri-reference": "a web address or path",
|
|
166
|
+
date: "a date, e.g. 2026-11-19",
|
|
167
|
+
time: "a time, e.g. 14:30:00",
|
|
168
|
+
"date-time": "a date and time, e.g. 2026-11-19T14:30:00Z",
|
|
169
|
+
hostname: "a host name, e.g. example.com",
|
|
170
|
+
ipv4: "an IPv4 address",
|
|
171
|
+
ipv6: "an IPv6 address",
|
|
172
|
+
uuid: "a UUID",
|
|
173
|
+
regex: "a regular expression",
|
|
174
|
+
};
|
|
175
|
+
/** "1 item" or "3 items" */
|
|
176
|
+
const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
|
|
177
|
+
/** A value in a message: text in quotes, anything else as written */
|
|
178
|
+
const quote = (value) => typeof value === "string" ? `"${value}"` : JSON.stringify(value);
|
|
179
|
+
/**
|
|
180
|
+
* Say what is wrong with a value in plain words, from an ajv error, e.g. "must be at most 10" or "must be an email
|
|
181
|
+
* address". Errors this doesn't know keep ajv's message.
|
|
182
|
+
*
|
|
183
|
+
* @example
|
|
184
|
+
* plainMessage({ keyword: "maximum", params: { limit: 10 }, ... }); // "must be at most 10"
|
|
185
|
+
*/
|
|
186
|
+
export const plainMessage = (error) => {
|
|
187
|
+
const params = error.params;
|
|
188
|
+
const limit = params.limit;
|
|
189
|
+
switch (error.keyword) {
|
|
190
|
+
case "type": {
|
|
191
|
+
const types = String(params.type).split(",");
|
|
192
|
+
// Schemas only compile with JSON's own types, which all have names
|
|
193
|
+
return `must be ${types.map((type) => TYPE_NAMES[type]).join(" or ")}`;
|
|
194
|
+
}
|
|
195
|
+
case "minimum":
|
|
196
|
+
return `must be at least ${limit}`;
|
|
197
|
+
case "maximum":
|
|
198
|
+
return `must be at most ${limit}`;
|
|
199
|
+
case "exclusiveMinimum":
|
|
200
|
+
return `must be more than ${limit}`;
|
|
201
|
+
case "exclusiveMaximum":
|
|
202
|
+
return `must be less than ${limit}`;
|
|
203
|
+
case "multipleOf":
|
|
204
|
+
return `must be a multiple of ${params.multipleOf}`;
|
|
205
|
+
case "minLength":
|
|
206
|
+
return limit === 1
|
|
207
|
+
? "can't be empty"
|
|
208
|
+
: `must be at least ${plural(limit, "character")}`;
|
|
209
|
+
case "maxLength":
|
|
210
|
+
return `must be at most ${plural(limit, "character")}`;
|
|
211
|
+
case "pattern":
|
|
212
|
+
return "isn't in the right form";
|
|
213
|
+
case "format":
|
|
214
|
+
return `must be ${FORMAT_NAMES[params.format] ?? `a valid ${params.format}`}`;
|
|
215
|
+
case "enum":
|
|
216
|
+
return `must be one of ${params.allowedValues.map(quote).join(", ")}`;
|
|
217
|
+
case "const":
|
|
218
|
+
return `must be ${quote(params.allowedValue)}`;
|
|
219
|
+
case "required":
|
|
220
|
+
return "is required";
|
|
221
|
+
case "minItems":
|
|
222
|
+
return `must have at least ${plural(limit, "item")}`;
|
|
223
|
+
case "maxItems":
|
|
224
|
+
return `can have at most ${plural(limit, "item")}`;
|
|
225
|
+
case "uniqueItems":
|
|
226
|
+
return "can't have the same item twice";
|
|
227
|
+
case "additionalProperties":
|
|
228
|
+
return "isn't a known setting";
|
|
229
|
+
default:
|
|
230
|
+
// ajv always describes its errors
|
|
231
|
+
return error.message;
|
|
232
|
+
}
|
|
233
|
+
};
|
|
234
|
+
/**
|
|
235
|
+
* An ajv error as a problem with a value, in plain words (see `plainMessage`). A missing or unknown property is a
|
|
236
|
+
* problem with that property, so its field shows it.
|
|
237
|
+
*/
|
|
238
|
+
const problem = (key, error) => {
|
|
239
|
+
const params = error.params;
|
|
240
|
+
const property = (params.missingProperty ?? params.additionalProperty);
|
|
241
|
+
return {
|
|
242
|
+
path: key + error.instancePath + (property ? `/${property}` : ""),
|
|
243
|
+
message: plainMessage(error),
|
|
244
|
+
level: "error",
|
|
245
|
+
};
|
|
246
|
+
};
|
|
247
|
+
/**
|
|
248
|
+
* Validates articles' custom metadata values against their schemas, compiling each schema once.
|
|
249
|
+
*
|
|
250
|
+
* @example
|
|
251
|
+
* const validator = new MetadataValidator(config.metadata);
|
|
252
|
+
* validator.validate("featured", 3); // [{ path: "featured", message: "must be string", level: "error" }]
|
|
253
|
+
*/
|
|
254
|
+
export class MetadataValidator {
|
|
255
|
+
ajv = createAjv();
|
|
256
|
+
compiled = new Map();
|
|
257
|
+
/** The custom metadata fields' schemas, by key */
|
|
258
|
+
definitions;
|
|
259
|
+
constructor(definitions) {
|
|
260
|
+
this.definitions = definitions;
|
|
261
|
+
}
|
|
262
|
+
/** The problems with a value of a custom metadata field (none if it's valid) */
|
|
263
|
+
validate(key, value) {
|
|
264
|
+
let validate = this.compiled.get(key);
|
|
265
|
+
if (!validate) {
|
|
266
|
+
validate = this.ajv.compile(this.definitions[key]);
|
|
267
|
+
this.compiled.set(key, validate);
|
|
268
|
+
}
|
|
269
|
+
if (validate(value))
|
|
270
|
+
return [];
|
|
271
|
+
// A value that isn't valid always has errors
|
|
272
|
+
return validate.errors.map((error) => problem(key, error));
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Read an article's custom metadata from its settings: fill in default values and leave out hidden fields' values (see
|
|
277
|
+
* resolveFields), validate the values of the fields its type uses, and warn about values of fields its type doesn't use
|
|
278
|
+
* and settings that aren't core or defined.
|
|
279
|
+
*
|
|
280
|
+
* @param typeLabel - the type's plural label, for warnings, e.g. "News"
|
|
281
|
+
*
|
|
282
|
+
* @example
|
|
283
|
+
* articleMetadata({ date, featured: "a.png", oops: 1 }, ["featured"], validator, "News");
|
|
284
|
+
* // { values: { featured: "a.png" }, problems: [{ path: "oops", message: "isn't a known setting", level: "warning" }] }
|
|
285
|
+
*/
|
|
286
|
+
export const articleMetadata = (settings, keys, validator, typeLabel) => {
|
|
287
|
+
const given = {};
|
|
288
|
+
/** Settings that aren't used */
|
|
289
|
+
const problems = [];
|
|
290
|
+
for (const [key, value] of Object.entries(settings)) {
|
|
291
|
+
if (CORE_FIELDS.includes(key))
|
|
292
|
+
continue;
|
|
293
|
+
if (keys.includes(key))
|
|
294
|
+
given[key] = value;
|
|
295
|
+
else
|
|
296
|
+
problems.push({
|
|
297
|
+
path: key,
|
|
298
|
+
message: key in validator.definitions
|
|
299
|
+
? `isn't used by ${typeLabel}`
|
|
300
|
+
: "isn't a known setting",
|
|
301
|
+
level: "warning",
|
|
302
|
+
});
|
|
303
|
+
}
|
|
304
|
+
const schemas = Object.fromEntries(keys.flatMap((key) => {
|
|
305
|
+
const schema = validator.definitions[key];
|
|
306
|
+
return schema ? [[key, schema]] : [];
|
|
307
|
+
}));
|
|
308
|
+
const { values } = resolveFields(schemas, given);
|
|
309
|
+
const errors = Object.entries(values).flatMap(([key, value]) => validator.validate(key, value));
|
|
310
|
+
return { values, problems: [...errors, ...problems] };
|
|
311
|
+
};
|
|
312
|
+
/**
|
|
313
|
+
* Make a value's file fields' relative file names into paths on the website (like `thumbnail`), following its
|
|
314
|
+
* schema's objects and lists.
|
|
315
|
+
*
|
|
316
|
+
* @example
|
|
317
|
+
* resolveFileFields({ $edahaField: { file: true } }, "photo.png", "/news/hello/"); // "/news/hello/photo.png"
|
|
318
|
+
*/
|
|
319
|
+
export const resolveFileFields = (schema, value, articleUrl) => {
|
|
320
|
+
if (Array.isArray(value) && schema.items)
|
|
321
|
+
return value.map((item) => resolveFileFields(schema.items, item, articleUrl));
|
|
322
|
+
if (value && typeof value === "object" && schema.properties)
|
|
323
|
+
return Object.fromEntries(Object.entries(value).map(([name, item]) => {
|
|
324
|
+
const property = schema.properties?.[name];
|
|
325
|
+
return [
|
|
326
|
+
name,
|
|
327
|
+
property ? resolveFileFields(property, item, articleUrl) : item,
|
|
328
|
+
];
|
|
329
|
+
}));
|
|
330
|
+
return typeof value === "string" &&
|
|
331
|
+
schema.$edahaField &&
|
|
332
|
+
"file" in schema.$edahaField &&
|
|
333
|
+
isRelativeUrl(value)
|
|
334
|
+
? articleUrl + value
|
|
335
|
+
: value;
|
|
336
|
+
};
|
|
337
|
+
/**
|
|
338
|
+
* An article's custom metadata for templates (`article.meta`): its type's valid values, with file fields as paths on
|
|
339
|
+
* the website. Values with errors are left out.
|
|
340
|
+
*/
|
|
341
|
+
export const templateMetadata = (metadata, definitions, articleUrl) => {
|
|
342
|
+
const invalid = new Set(metadata.problems
|
|
343
|
+
.filter((problem) => problem.level === "error")
|
|
344
|
+
.map((problem) => problem.path.split("/")[0]));
|
|
345
|
+
return Object.fromEntries(Object.entries(metadata.values)
|
|
346
|
+
.filter(([key]) => !invalid.has(key))
|
|
347
|
+
.map(([key, value]) => [
|
|
348
|
+
key,
|
|
349
|
+
resolveFileFields(definitions[key], value, articleUrl),
|
|
350
|
+
]));
|
|
351
|
+
};
|
|
352
|
+
/** Check a map key is used only for keys listed, for the type's `metadata` setting */
|
|
353
|
+
export const parseTypeMetadata = (value, what) => {
|
|
354
|
+
if (value === undefined || value === null)
|
|
355
|
+
return undefined;
|
|
356
|
+
if (value === false)
|
|
357
|
+
return false;
|
|
358
|
+
if (!Array.isArray(value) || value.some((key) => typeof key !== "string"))
|
|
359
|
+
throw new Error(`${what} must be a list of metadata keys, or false for none`);
|
|
360
|
+
return value;
|
|
361
|
+
};
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type { MetadataDefinitions } from "../metadata/index.ts";
|
|
2
|
+
/** A group of settings in the editor, as the config file's `metadataGroups` defines it */
|
|
3
|
+
export interface MetadataGroupConfig {
|
|
4
|
+
/** The group's heading */
|
|
5
|
+
title: string;
|
|
6
|
+
/** Shown above the group's fields */
|
|
7
|
+
description?: string | undefined;
|
|
8
|
+
/** The group it comes after (by default, groups go at the end) */
|
|
9
|
+
after?: string | undefined;
|
|
10
|
+
/** Whether the group starts open. Default: false */
|
|
11
|
+
openedByDefault: boolean;
|
|
12
|
+
}
|
|
13
|
+
/** A group of settings in the editor: its heading, and its fields' keys in order */
|
|
14
|
+
export interface MetadataGroup {
|
|
15
|
+
key: string;
|
|
16
|
+
title: string;
|
|
17
|
+
description?: string | undefined;
|
|
18
|
+
openedByDefault: boolean;
|
|
19
|
+
/** Its core and custom fields' keys, in order ("uploaded" is the article folder's files) */
|
|
20
|
+
fields: string[];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* The editor's own groups, in order, with their core settings. "slug" and "uploaded" (the files in the article's
|
|
24
|
+
* folder) aren't settings, but have their place too. Custom fields without a group go in "custom".
|
|
25
|
+
*/
|
|
26
|
+
export declare const BUILT_IN_GROUPS: readonly MetadataGroup[];
|
|
27
|
+
/**
|
|
28
|
+
* Read the config file's `metadataGroups` setting: groups of settings for the editor, by key. Throws an Error if a key
|
|
29
|
+
* is a built-in group's or isn't usable, or a group's settings aren't valid.
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* parseMetadataGroups({ seo: { title: "SEO", after: "info", openedByDefault: true } });
|
|
33
|
+
*/
|
|
34
|
+
export declare const parseMetadataGroups: (value: unknown) => Record<string, MetadataGroupConfig>;
|
|
35
|
+
/**
|
|
36
|
+
* The editor's groups of settings in order, each with its fields in order: the built-in groups (and the custom groups,
|
|
37
|
+
* placed after the group they name or at the end), with every custom field in its group (after the field it names, or
|
|
38
|
+
* at the group's end). Throws an Error if a field's group doesn't exist, or a field or group names one to follow that
|
|
39
|
+
* isn't there.
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* metadataLayout({ hero: { $edahaField: { group: { key: "files", after: "thumbnail" }, file: true } } }, {});
|
|
43
|
+
* // [..., { key: "files", fields: ["thumbnail", "hero", "attachments", "uploaded"], ... }, ...]
|
|
44
|
+
*/
|
|
45
|
+
export declare const metadataLayout: (definitions: MetadataDefinitions, groups: Record<string, MetadataGroupConfig>) => MetadataGroup[];
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The editor's own groups, in order, with their core settings. "slug" and "uploaded" (the files in the article's
|
|
3
|
+
* folder) aren't settings, but have their place too. Custom fields without a group go in "custom".
|
|
4
|
+
*/
|
|
5
|
+
export const BUILT_IN_GROUPS = [
|
|
6
|
+
{
|
|
7
|
+
key: "info",
|
|
8
|
+
title: "Info",
|
|
9
|
+
openedByDefault: true,
|
|
10
|
+
fields: ["type", "status", "slug", "date", "author"],
|
|
11
|
+
},
|
|
12
|
+
{
|
|
13
|
+
key: "categorise",
|
|
14
|
+
title: "Categorise",
|
|
15
|
+
openedByDefault: false,
|
|
16
|
+
fields: ["tags"],
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
key: "customise",
|
|
20
|
+
title: "Customise",
|
|
21
|
+
openedByDefault: true,
|
|
22
|
+
fields: ["excerpt", "template"],
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
key: "files",
|
|
26
|
+
title: "Files",
|
|
27
|
+
openedByDefault: true,
|
|
28
|
+
fields: ["thumbnail", "attachments", "uploaded"],
|
|
29
|
+
},
|
|
30
|
+
{ key: "custom", title: "Custom", openedByDefault: false, fields: [] },
|
|
31
|
+
];
|
|
32
|
+
/** The settings a custom group can have */
|
|
33
|
+
const GROUP_KEYS = ["title", "description", "after", "openedByDefault"];
|
|
34
|
+
/** Group keys: a letter, then letters, digits, "_" or "-" */
|
|
35
|
+
const KEY = /^[A-Za-z][\w-]*$/;
|
|
36
|
+
/** Check a value is a map (not a list), throwing an Error naming it if not */
|
|
37
|
+
const asMap = (value, what) => {
|
|
38
|
+
if (!value || typeof value !== "object" || Array.isArray(value))
|
|
39
|
+
throw new Error(`${what} must be a map of settings`);
|
|
40
|
+
return value;
|
|
41
|
+
};
|
|
42
|
+
/** Read an optional text setting, throwing an Error naming it if it isn't text */
|
|
43
|
+
const optionalText = (value, what) => {
|
|
44
|
+
if (value === undefined || value === null)
|
|
45
|
+
return undefined;
|
|
46
|
+
if (typeof value !== "string" || !value.trim())
|
|
47
|
+
throw new Error(`${what} must be non-empty text`);
|
|
48
|
+
return value.trim();
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* Read the config file's `metadataGroups` setting: groups of settings for the editor, by key. Throws an Error if a key
|
|
52
|
+
* is a built-in group's or isn't usable, or a group's settings aren't valid.
|
|
53
|
+
*
|
|
54
|
+
* @example
|
|
55
|
+
* parseMetadataGroups({ seo: { title: "SEO", after: "info", openedByDefault: true } });
|
|
56
|
+
*/
|
|
57
|
+
export const parseMetadataGroups = (value) => {
|
|
58
|
+
if (value === undefined || value === null)
|
|
59
|
+
return {};
|
|
60
|
+
const groups = asMap(value, '"metadataGroups"');
|
|
61
|
+
return Object.fromEntries(Object.entries(groups).map(([key, settings]) => {
|
|
62
|
+
const what = `"metadataGroups.${key}"`;
|
|
63
|
+
if (BUILT_IN_GROUPS.some((group) => group.key === key))
|
|
64
|
+
throw new Error(`${what} can't be used: "${key}" is a built-in group`);
|
|
65
|
+
if (!KEY.test(key))
|
|
66
|
+
throw new Error(`${what} must start with a letter and have only letters, digits, "_" and "-"`);
|
|
67
|
+
const fields = asMap(settings, what);
|
|
68
|
+
const unknown = Object.keys(fields).filter((name) => !GROUP_KEYS.includes(name));
|
|
69
|
+
if (unknown.length)
|
|
70
|
+
throw new Error(`${what} has unknown settings: ${unknown.map((name) => `"${name}"`).join(", ")}`);
|
|
71
|
+
const opened = fields.openedByDefault ?? false;
|
|
72
|
+
if (typeof opened !== "boolean")
|
|
73
|
+
throw new Error(`${what}.openedByDefault must be true or false`);
|
|
74
|
+
return [
|
|
75
|
+
key,
|
|
76
|
+
{
|
|
77
|
+
title: optionalText(fields.title, `${what}.title`) ??
|
|
78
|
+
fail(`${what}.title is required`),
|
|
79
|
+
description: optionalText(fields.description, `${what}.description`),
|
|
80
|
+
after: optionalText(fields.after, `${what}.after`),
|
|
81
|
+
openedByDefault: opened,
|
|
82
|
+
},
|
|
83
|
+
];
|
|
84
|
+
}));
|
|
85
|
+
};
|
|
86
|
+
/** Throw an Error with a message */
|
|
87
|
+
const fail = (message) => {
|
|
88
|
+
throw new Error(message);
|
|
89
|
+
};
|
|
90
|
+
/**
|
|
91
|
+
* Where a custom field's `$edahaField.group` puts it: a group key, or `{ key, after }`. Fields without one go in
|
|
92
|
+
* "custom". Throws an Error naming the field if it isn't valid.
|
|
93
|
+
*/
|
|
94
|
+
const fieldPlace = (name, group) => {
|
|
95
|
+
const what = `"metadata.${name}.$edahaField.group"`;
|
|
96
|
+
if (group === undefined || group === null)
|
|
97
|
+
return { key: "custom" };
|
|
98
|
+
if (typeof group === "string")
|
|
99
|
+
return { key: group };
|
|
100
|
+
const place = asMap(group, what);
|
|
101
|
+
return {
|
|
102
|
+
key: optionalText(place.key, `${what}.key`) ?? fail(`${what}.key is required`),
|
|
103
|
+
after: optionalText(place.after, `${what}.after`),
|
|
104
|
+
};
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* Put items in order: those without `after` in the order given, then each after the one it names. Throws an Error
|
|
108
|
+
* (from `missing`) for an item whose `after` names nothing in the list.
|
|
109
|
+
*/
|
|
110
|
+
const placeAfter = (start, items, missing) => {
|
|
111
|
+
const order = [...start, ...items.filter((i) => !i.after).map((i) => i.name)];
|
|
112
|
+
let waiting = items.filter((i) => i.after);
|
|
113
|
+
// Each pass places the items whose `after` is already placed, until none are left or none can be
|
|
114
|
+
while (waiting.length) {
|
|
115
|
+
const ready = waiting.filter((i) => order.includes(i.after));
|
|
116
|
+
if (!ready.length) {
|
|
117
|
+
const [first] = waiting;
|
|
118
|
+
throw new Error(missing(first.name, first.after));
|
|
119
|
+
}
|
|
120
|
+
for (const { name, after } of ready)
|
|
121
|
+
order.splice(order.indexOf(after) + 1, 0, name);
|
|
122
|
+
waiting = waiting.filter((i) => !ready.includes(i));
|
|
123
|
+
}
|
|
124
|
+
return order;
|
|
125
|
+
};
|
|
126
|
+
/**
|
|
127
|
+
* The editor's groups of settings in order, each with its fields in order: the built-in groups (and the custom groups,
|
|
128
|
+
* placed after the group they name or at the end), with every custom field in its group (after the field it names, or
|
|
129
|
+
* at the group's end). Throws an Error if a field's group doesn't exist, or a field or group names one to follow that
|
|
130
|
+
* isn't there.
|
|
131
|
+
*
|
|
132
|
+
* @example
|
|
133
|
+
* metadataLayout({ hero: { $edahaField: { group: { key: "files", after: "thumbnail" }, file: true } } }, {});
|
|
134
|
+
* // [..., { key: "files", fields: ["thumbnail", "hero", "attachments", "uploaded"], ... }, ...]
|
|
135
|
+
*/
|
|
136
|
+
export const metadataLayout = (definitions, groups) => {
|
|
137
|
+
const all = [
|
|
138
|
+
...BUILT_IN_GROUPS.map((group) => ({
|
|
139
|
+
...group,
|
|
140
|
+
fields: [...group.fields],
|
|
141
|
+
})),
|
|
142
|
+
...Object.entries(groups).map(([key, group]) => ({
|
|
143
|
+
key,
|
|
144
|
+
title: group.title,
|
|
145
|
+
description: group.description,
|
|
146
|
+
openedByDefault: group.openedByDefault,
|
|
147
|
+
fields: [],
|
|
148
|
+
})),
|
|
149
|
+
];
|
|
150
|
+
const byKey = new Map(all.map((group) => [group.key, group]));
|
|
151
|
+
// Each group's custom fields, in the config file's order
|
|
152
|
+
const placed = new Map();
|
|
153
|
+
for (const [name, schema] of Object.entries(definitions)) {
|
|
154
|
+
const place = fieldPlace(name, schema.$edahaField?.group);
|
|
155
|
+
if (!byKey.has(place.key))
|
|
156
|
+
throw new Error(`"metadata.${name}" is in group "${place.key}", which isn't a built-in group or in "metadataGroups"`);
|
|
157
|
+
placed.set(place.key, [
|
|
158
|
+
...(placed.get(place.key) ?? []),
|
|
159
|
+
{ name, after: place.after },
|
|
160
|
+
]);
|
|
161
|
+
}
|
|
162
|
+
for (const group of all)
|
|
163
|
+
group.fields = placeAfter(group.fields, placed.get(group.key) ?? [], (name, after) => `"metadata.${name}" comes after "${after}", which isn't in group "${group.key}"`);
|
|
164
|
+
const order = placeAfter(BUILT_IN_GROUPS.map((group) => group.key), Object.entries(groups).map(([key, group]) => ({
|
|
165
|
+
name: key,
|
|
166
|
+
after: group.after,
|
|
167
|
+
})), (name, after) => `"metadataGroups.${name}" comes after "${after}", which isn't a group`);
|
|
168
|
+
return order.map((key) => byKey.get(key));
|
|
169
|
+
};
|
|
@@ -1,17 +1,49 @@
|
|
|
1
|
+
import nunjucks from "nunjucks";
|
|
1
2
|
import type { Logger, TemplateData } from "../types/index.ts";
|
|
2
3
|
/** Templates that must exist for the build to run */
|
|
3
4
|
export declare const REQUIRED_TEMPLATES: string[];
|
|
4
5
|
/**
|
|
5
|
-
*
|
|
6
|
+
* Template names starting with this always load from the last template folder (the default theme's), e.g.
|
|
7
|
+
* `{% extends "@theme/article/single.njk" %}` in a site's own `article/single.njk`, to build on the theme's version.
|
|
8
|
+
*/
|
|
9
|
+
export declare const THEME_PREFIX = "@theme/";
|
|
10
|
+
/**
|
|
11
|
+
* A Nunjucks loader for template names starting with THEME_PREFIX, from one folder. Other names are left to the next
|
|
12
|
+
* loader.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* themeLoader("/theme/templates").getSource("@theme/article/single.njk"); // the theme's article/single.njk
|
|
16
|
+
*/
|
|
17
|
+
export declare const themeLoader: (dir: string) => nunjucks.ILoader;
|
|
18
|
+
/**
|
|
19
|
+
* Make a root-relative URL absolute on the website's domain, e.g. for RSS feeds read outside the website. Template
|
|
20
|
+
* data URLs already start with the website's base URL, so only its origin is added.
|
|
21
|
+
*
|
|
22
|
+
* @example
|
|
23
|
+
* absoluteUrl("/news/", "https://example.com"); // "https://example.com/news/"
|
|
24
|
+
* absoluteUrl("/edaha.md/news/", "https://lvl99.github.io/edaha.md"); // "https://lvl99.github.io/edaha.md/news/"
|
|
25
|
+
*/
|
|
26
|
+
export declare const absoluteUrl: (url: string, siteUrl: string) => string;
|
|
27
|
+
/**
|
|
28
|
+
* Make root-relative `href` and `src` URLs in HTML absolute (see absoluteUrl), e.g. for RSS feeds read outside the
|
|
29
|
+
* website.
|
|
6
30
|
*
|
|
7
31
|
* @example
|
|
8
32
|
* absoluteUrls('<a href="/news/">', "https://example.com"); // '<a href="https://example.com/news/">'
|
|
9
33
|
*/
|
|
10
34
|
export declare const absoluteUrls: (html: string, siteUrl: string) => string;
|
|
35
|
+
/** Template tags that output the page's embed HTML (`TemplateData.embeds`), by where it goes */
|
|
36
|
+
export declare const EMBED_TAGS: {
|
|
37
|
+
readonly embedHead: "head";
|
|
38
|
+
readonly embedFoot: "foot";
|
|
39
|
+
readonly embedRenderHead: "head";
|
|
40
|
+
readonly embedRenderFoot: "foot";
|
|
41
|
+
};
|
|
11
42
|
/**
|
|
12
|
-
* Loads and renders the
|
|
43
|
+
* Loads and renders the site's Nunjucks templates from one or more folders. A file in an earlier folder overrides the
|
|
13
44
|
* same file in later ones (e.g. a site's templates over the default theme's). Falls back to the `article` templates
|
|
14
|
-
* (with a warning) when an article type has none of its own.
|
|
45
|
+
* (with a warning) when an article type has none of its own. Names starting with THEME_PREFIX (`@theme/`) load from
|
|
46
|
+
* the last folder only.
|
|
15
47
|
*
|
|
16
48
|
* @example
|
|
17
49
|
* const templates = new Templates(["site/templates", join(THEME_DIR, "templates")], console);
|