@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
package/dist/cli/index.d.ts
CHANGED
|
@@ -1,7 +1,28 @@
|
|
|
1
|
-
import { type EditorServer, type EditorServerOptions } from "../editor/index.ts";
|
|
2
1
|
import type { BuildOptions, BuildResult } from "../generator/build/index.ts";
|
|
2
|
+
/** The package with the article editor, which `edaha editor` loads when it is installed */
|
|
3
|
+
export declare const EDITOR_PACKAGE = "@lvl99dotcom/edaha-editor";
|
|
4
|
+
/** The editor's default port */
|
|
5
|
+
export declare const EDITOR_PORT = 5180;
|
|
6
|
+
/** What `edaha editor` passes to the editor package's `startEditor` */
|
|
7
|
+
export interface EditorOptions {
|
|
8
|
+
/** The folder to look for a config file in */
|
|
9
|
+
siteDir: string;
|
|
10
|
+
/** The config file, if one was named */
|
|
11
|
+
configFile?: string | undefined;
|
|
12
|
+
/** The port to listen on */
|
|
13
|
+
port: number;
|
|
14
|
+
}
|
|
15
|
+
/** A running editor, as the editor package's `startEditor` gives it */
|
|
16
|
+
export interface RunningEditor {
|
|
17
|
+
/** The editor's address, e.g. "http://127.0.0.1:5180" */
|
|
18
|
+
url: string;
|
|
19
|
+
/** Stop the editor */
|
|
20
|
+
close: () => Promise<void>;
|
|
21
|
+
}
|
|
22
|
+
/** Starts the article editor */
|
|
23
|
+
export type StartEditor = (options: EditorOptions) => Promise<RunningEditor>;
|
|
3
24
|
/** How to use the `edaha` command */
|
|
4
|
-
export declare const USAGE = "Usage: edaha <command> [options]\n\nCommands:\n build Build the site into config
|
|
25
|
+
export declare const USAGE = "Usage: edaha <command> [options]\n\nCommands:\n build Build the site into the config file's outputDir (and copy it into publishDir, if set)\n editor Run the local article editor (only reachable from this computer)\n\nOptions:\n -c, --config <file> The config file (default: the first edahaconfig file found in --dir, then in the nearest\n package.json's folder). The site folder is the config file's folder.\n --dir <folder> The folder to look for a config file in (default: the current folder)\n --site-url <url> build: the website's absolute URL for feeds (default: SITE_URL, then the config's siteUrl)\n --port <number> editor: the port to listen on (default: 5180)\n -h, --help Show this help\n -v, --version Show edaha.md's version\n";
|
|
5
26
|
/** What the command line needs from its surroundings, so it can be tested */
|
|
6
27
|
export interface CliContext {
|
|
7
28
|
/** The folder the command runs in */
|
|
@@ -12,16 +33,25 @@ export interface CliContext {
|
|
|
12
33
|
log: (message: string) => void;
|
|
13
34
|
/** Where errors and warnings go */
|
|
14
35
|
error: (message: string) => void;
|
|
15
|
-
/** Builds the site (default:
|
|
36
|
+
/** Builds the site (default: buildSite) */
|
|
16
37
|
build?: (options: BuildOptions) => Promise<BuildResult>;
|
|
17
|
-
/** Starts the editor (default: startEditor) */
|
|
18
|
-
editor?:
|
|
38
|
+
/** Starts the editor (default: the editor package's startEditor, see loadEditor) */
|
|
39
|
+
editor?: StartEditor;
|
|
19
40
|
}
|
|
41
|
+
/**
|
|
42
|
+
* Load `startEditor` from the editor package. Throws with how to install it if it isn't installed.
|
|
43
|
+
*
|
|
44
|
+
* @param importPackage - imports a package by name (replaceable for tests)
|
|
45
|
+
* @example
|
|
46
|
+
* const startEditor = await loadEditor();
|
|
47
|
+
* await startEditor({ siteDir: "my-site", port: EDITOR_PORT });
|
|
48
|
+
*/
|
|
49
|
+
export declare const loadEditor: (importPackage?: (name: string) => Promise<unknown>) => Promise<StartEditor>;
|
|
20
50
|
/**
|
|
21
51
|
* edaha.md's version, from its package.json.
|
|
22
52
|
*
|
|
23
53
|
* @example
|
|
24
|
-
* version(); // "0.
|
|
54
|
+
* version(); // "0.2.0"
|
|
25
55
|
*/
|
|
26
56
|
export declare const version: () => string;
|
|
27
57
|
/**
|
package/dist/cli/index.js
CHANGED
|
@@ -1,27 +1,60 @@
|
|
|
1
|
+
var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
|
|
2
|
+
if (typeof path === "string" && /^\.\.?\//.test(path)) {
|
|
3
|
+
return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
|
|
4
|
+
return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
|
|
5
|
+
});
|
|
6
|
+
}
|
|
7
|
+
return path;
|
|
8
|
+
};
|
|
1
9
|
import { readFileSync } from "node:fs";
|
|
2
10
|
import { resolve } from "node:path";
|
|
3
11
|
import { parseArgs } from "node:util";
|
|
4
|
-
import {
|
|
5
|
-
|
|
12
|
+
import { buildSite } from "../generator/build/index.js";
|
|
13
|
+
/** The package with the article editor, which `edaha editor` loads when it is installed */
|
|
14
|
+
export const EDITOR_PACKAGE = "@lvl99dotcom/edaha-editor";
|
|
15
|
+
/** The editor's default port */
|
|
16
|
+
export const EDITOR_PORT = 5180;
|
|
6
17
|
/** How to use the `edaha` command */
|
|
7
18
|
export const USAGE = `Usage: edaha <command> [options]
|
|
8
19
|
|
|
9
20
|
Commands:
|
|
10
|
-
build Build the site into config
|
|
21
|
+
build Build the site into the config file's outputDir (and copy it into publishDir, if set)
|
|
11
22
|
editor Run the local article editor (only reachable from this computer)
|
|
12
23
|
|
|
13
24
|
Options:
|
|
14
|
-
--
|
|
15
|
-
|
|
25
|
+
-c, --config <file> The config file (default: the first edahaconfig file found in --dir, then in the nearest
|
|
26
|
+
package.json's folder). The site folder is the config file's folder.
|
|
27
|
+
--dir <folder> The folder to look for a config file in (default: the current folder)
|
|
28
|
+
--site-url <url> build: the website's absolute URL for feeds (default: SITE_URL, then the config's siteUrl)
|
|
16
29
|
--port <number> editor: the port to listen on (default: ${EDITOR_PORT})
|
|
17
30
|
-h, --help Show this help
|
|
18
31
|
-v, --version Show edaha.md's version
|
|
19
32
|
`;
|
|
33
|
+
/**
|
|
34
|
+
* Load `startEditor` from the editor package. Throws with how to install it if it isn't installed.
|
|
35
|
+
*
|
|
36
|
+
* @param importPackage - imports a package by name (replaceable for tests)
|
|
37
|
+
* @example
|
|
38
|
+
* const startEditor = await loadEditor();
|
|
39
|
+
* await startEditor({ siteDir: "my-site", port: EDITOR_PORT });
|
|
40
|
+
*/
|
|
41
|
+
export const loadEditor = async (importPackage = (name) => import(__rewriteRelativeImportExtension(name))) => {
|
|
42
|
+
try {
|
|
43
|
+
return (await importPackage(EDITOR_PACKAGE)).startEditor;
|
|
44
|
+
}
|
|
45
|
+
catch (error) {
|
|
46
|
+
// Only when the editor package itself is missing, not one of its own dependencies
|
|
47
|
+
if (error.code === "ERR_MODULE_NOT_FOUND" &&
|
|
48
|
+
error.message.includes(`'${EDITOR_PACKAGE}'`))
|
|
49
|
+
throw new Error(`The article editor isn't installed. Install it next to edaha.md with \`npm add -D ${EDITOR_PACKAGE}\` (or pnpm/yarn).`, { cause: error });
|
|
50
|
+
throw error;
|
|
51
|
+
}
|
|
52
|
+
};
|
|
20
53
|
/**
|
|
21
54
|
* edaha.md's version, from its package.json.
|
|
22
55
|
*
|
|
23
56
|
* @example
|
|
24
|
-
* version(); // "0.
|
|
57
|
+
* version(); // "0.2.0"
|
|
25
58
|
*/
|
|
26
59
|
export const version = () => JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
|
|
27
60
|
/**
|
|
@@ -67,10 +100,14 @@ export const runCli = async (args, context) => {
|
|
|
67
100
|
return 1;
|
|
68
101
|
}
|
|
69
102
|
const siteDir = resolve(context.cwd, values.dir ?? ".");
|
|
103
|
+
const configFile = values.config === undefined
|
|
104
|
+
? undefined
|
|
105
|
+
: resolve(context.cwd, values.config);
|
|
70
106
|
try {
|
|
71
107
|
if (command === "build") {
|
|
72
|
-
const result = await (context.build ??
|
|
108
|
+
const result = await (context.build ?? buildSite)({
|
|
73
109
|
siteDir,
|
|
110
|
+
configFile,
|
|
74
111
|
siteUrl: values["site-url"] ?? context.env.SITE_URL,
|
|
75
112
|
logger: { warn: context.error },
|
|
76
113
|
});
|
|
@@ -81,11 +118,12 @@ export const runCli = async (args, context) => {
|
|
|
81
118
|
return 0;
|
|
82
119
|
}
|
|
83
120
|
if (command === "editor") {
|
|
84
|
-
const editor = await (context.editor ??
|
|
121
|
+
const editor = await (context.editor ?? (await loadEditor()))({
|
|
85
122
|
siteDir,
|
|
123
|
+
configFile,
|
|
86
124
|
port: values.port === undefined ? EDITOR_PORT : parsePort(values.port),
|
|
87
125
|
});
|
|
88
|
-
context.log(`Article editor
|
|
126
|
+
context.log(`Article editor running at ${editor.url} (press Ctrl+C to stop)`);
|
|
89
127
|
return 0;
|
|
90
128
|
}
|
|
91
129
|
}
|
|
@@ -101,6 +139,7 @@ const parse = (args) => parseArgs({
|
|
|
101
139
|
args,
|
|
102
140
|
allowPositionals: true,
|
|
103
141
|
options: {
|
|
142
|
+
config: { type: "string", short: "c" },
|
|
104
143
|
dir: { type: "string" },
|
|
105
144
|
"site-url": { type: "string" },
|
|
106
145
|
port: { type: "string" },
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Embed blocks in article markdown: `<!-- embed:<key> -->content<!-- /embed:<key> -->`, where the closing tag may leave
|
|
3
|
+
* out the key. Group 1 is the key (undefined for an old `<!-- embed -->` block without one), group 2 the content.
|
|
4
|
+
*/
|
|
5
|
+
export declare const EMBED_BLOCK: RegExp;
|
|
6
|
+
/**
|
|
7
|
+
* An embed block's content without the blank lines around it, so blocks can be written on their own lines. Spaces at
|
|
8
|
+
* the start of its first line are kept (e.g. indented code).
|
|
9
|
+
*
|
|
10
|
+
* @example
|
|
11
|
+
* embedContent("\n graph TD;\n A-->B;\n"); // " graph TD;\n A-->B;"
|
|
12
|
+
*/
|
|
13
|
+
export declare const embedContent: (content: string) => string;
|
|
14
|
+
/** An embed's options, by name, as set in the embed dialog */
|
|
15
|
+
export type EmbedOptionValues = Record<string, unknown>;
|
|
16
|
+
/** An embed block's options and content */
|
|
17
|
+
export interface EmbedBlockParts {
|
|
18
|
+
/** What is between its tags after its options, without blank lines around it (see embedContent) */
|
|
19
|
+
content: string;
|
|
20
|
+
/** Its options (empty when it has none, or they can't be read) */
|
|
21
|
+
options: EmbedOptionValues;
|
|
22
|
+
/** Why its options can't be read, if they can't */
|
|
23
|
+
optionsError?: string | undefined;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Split an embed block's text (between its tags) into its options and content.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* splitEmbed("\n<!--yaml\nlayout: large\n-->\nhttps://a.bandcamp.com/album/b\n");
|
|
30
|
+
* // { content: "https://a.bandcamp.com/album/b", options: { layout: "large" } }
|
|
31
|
+
*/
|
|
32
|
+
export declare const splitEmbed: (text: string) => EmbedBlockParts;
|
|
33
|
+
/**
|
|
34
|
+
* An embed block's options from JSON (e.g. an editor's `data-options` attribute), or none when it isn't a map.
|
|
35
|
+
*
|
|
36
|
+
* @example
|
|
37
|
+
* embedOptionsOf('{"layout":"large"}'); // { layout: "large" }
|
|
38
|
+
* embedOptionsOf(null); // {}
|
|
39
|
+
*/
|
|
40
|
+
export declare const embedOptionsOf: (json: string | null) => EmbedOptionValues;
|
|
41
|
+
/**
|
|
42
|
+
* Write an embed block: on one line for single-line content (e.g. a URL) without options, otherwise with its tags on
|
|
43
|
+
* their own lines, and its options (if any) in YAML before the content.
|
|
44
|
+
*
|
|
45
|
+
* @example
|
|
46
|
+
* embedBlock("youtube", "https://youtu.be/aju_UB5VIf8"); // "<!-- embed:youtube -->https://youtu.be/aju_UB5VIf8<!-- /embed:youtube -->"
|
|
47
|
+
* embedBlock("mermaidjs", "graph TD;\n A-->B;"); // "<!-- embed:mermaidjs -->\ngraph TD;\n A-->B;\n<!-- /embed:mermaidjs -->"
|
|
48
|
+
* embedBlock("bandcamp", "https://a.bandcamp.com/album/b", { layout: "large" });
|
|
49
|
+
* // "<!-- embed:bandcamp -->\n<!--yaml\nlayout: large\n-->\nhttps://a.bandcamp.com/album/b\n<!-- /embed:bandcamp -->"
|
|
50
|
+
*/
|
|
51
|
+
export declare const embedBlock: (key: string, content: string, options?: EmbedOptionValues) => string;
|
|
52
|
+
/**
|
|
53
|
+
* What goes between an embed block's tags: its options (if any) in YAML, then its content.
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* embedText("https://youtu.be/x"); // "https://youtu.be/x"
|
|
57
|
+
* embedText("https://a.bandcamp.com/album/b", { layout: "large" }); // "<!--yaml\nlayout: large\n-->\nhttps://a.bandcamp.com/album/b"
|
|
58
|
+
*/
|
|
59
|
+
export declare const embedText: (content: string, options?: EmbedOptionValues) => string;
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
// Reading and writing embed blocks in article markdown. Has no Node.js imports, so the editor's page can use it too.
|
|
2
|
+
import { parse, stringify } from "yaml";
|
|
3
|
+
/**
|
|
4
|
+
* Embed blocks in article markdown: `<!-- embed:<key> -->content<!-- /embed:<key> -->`, where the closing tag may leave
|
|
5
|
+
* out the key. Group 1 is the key (undefined for an old `<!-- embed -->` block without one), group 2 the content.
|
|
6
|
+
*/
|
|
7
|
+
export const EMBED_BLOCK = /<!--\s*embed(?::([a-z0-9]+(?:-[a-z0-9]+)*))?\s*-->([\s\S]*?)<!--\s*\/embed(?::\1)?\s*-->/g;
|
|
8
|
+
/**
|
|
9
|
+
* An embed block's content without the blank lines around it, so blocks can be written on their own lines. Spaces at
|
|
10
|
+
* the start of its first line are kept (e.g. indented code).
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* embedContent("\n graph TD;\n A-->B;\n"); // " graph TD;\n A-->B;"
|
|
14
|
+
*/
|
|
15
|
+
export const embedContent = (content) => content.replace(/^(?:[ \t]*\r?\n)+/, "").trimEnd();
|
|
16
|
+
/**
|
|
17
|
+
* The options at the start of an embed block: `<!--yaml ... -->` (or `<!--yml`, or `<!--json` for JSON), like an
|
|
18
|
+
* article's config header.
|
|
19
|
+
*/
|
|
20
|
+
const EMBED_OPTIONS = /^\s*<!--(yaml|yml|json)[ \t]*\r?\n([\s\S]*?)-->/;
|
|
21
|
+
/**
|
|
22
|
+
* Split an embed block's text (between its tags) into its options and content.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* splitEmbed("\n<!--yaml\nlayout: large\n-->\nhttps://a.bandcamp.com/album/b\n");
|
|
26
|
+
* // { content: "https://a.bandcamp.com/album/b", options: { layout: "large" } }
|
|
27
|
+
*/
|
|
28
|
+
export const splitEmbed = (text) => {
|
|
29
|
+
const match = EMBED_OPTIONS.exec(text);
|
|
30
|
+
if (!match)
|
|
31
|
+
return { content: embedContent(text), options: {} };
|
|
32
|
+
const content = embedContent(text.slice(match[0].length));
|
|
33
|
+
let options;
|
|
34
|
+
try {
|
|
35
|
+
const source = match[2];
|
|
36
|
+
options =
|
|
37
|
+
match[1] === "json"
|
|
38
|
+
? source.trim()
|
|
39
|
+
? JSON.parse(source)
|
|
40
|
+
: null
|
|
41
|
+
: parse(source);
|
|
42
|
+
}
|
|
43
|
+
catch (error) {
|
|
44
|
+
return {
|
|
45
|
+
content,
|
|
46
|
+
options: {},
|
|
47
|
+
optionsError: `The options can't be read: ${error.message}`,
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
if (options === null || options === undefined)
|
|
51
|
+
return { content, options: {} };
|
|
52
|
+
return typeof options === "object" && !Array.isArray(options)
|
|
53
|
+
? { content, options: options }
|
|
54
|
+
: {
|
|
55
|
+
content,
|
|
56
|
+
options: {},
|
|
57
|
+
optionsError: "The options must be a map of names to values",
|
|
58
|
+
};
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* An embed block's options from JSON (e.g. an editor's `data-options` attribute), or none when it isn't a map.
|
|
62
|
+
*
|
|
63
|
+
* @example
|
|
64
|
+
* embedOptionsOf('{"layout":"large"}'); // { layout: "large" }
|
|
65
|
+
* embedOptionsOf(null); // {}
|
|
66
|
+
*/
|
|
67
|
+
export const embedOptionsOf = (json) => {
|
|
68
|
+
try {
|
|
69
|
+
const options = JSON.parse(json ?? "");
|
|
70
|
+
return options && typeof options === "object" && !Array.isArray(options)
|
|
71
|
+
? options
|
|
72
|
+
: {};
|
|
73
|
+
}
|
|
74
|
+
catch {
|
|
75
|
+
return {};
|
|
76
|
+
}
|
|
77
|
+
};
|
|
78
|
+
/**
|
|
79
|
+
* Write an embed block: on one line for single-line content (e.g. a URL) without options, otherwise with its tags on
|
|
80
|
+
* their own lines, and its options (if any) in YAML before the content.
|
|
81
|
+
*
|
|
82
|
+
* @example
|
|
83
|
+
* embedBlock("youtube", "https://youtu.be/aju_UB5VIf8"); // "<!-- embed:youtube -->https://youtu.be/aju_UB5VIf8<!-- /embed:youtube -->"
|
|
84
|
+
* embedBlock("mermaidjs", "graph TD;\n A-->B;"); // "<!-- embed:mermaidjs -->\ngraph TD;\n A-->B;\n<!-- /embed:mermaidjs -->"
|
|
85
|
+
* embedBlock("bandcamp", "https://a.bandcamp.com/album/b", { layout: "large" });
|
|
86
|
+
* // "<!-- embed:bandcamp -->\n<!--yaml\nlayout: large\n-->\nhttps://a.bandcamp.com/album/b\n<!-- /embed:bandcamp -->"
|
|
87
|
+
*/
|
|
88
|
+
export const embedBlock = (key, content, options = {}) => {
|
|
89
|
+
const text = embedText(content, options);
|
|
90
|
+
return text.includes("\n")
|
|
91
|
+
? `<!-- embed:${key} -->\n${text}\n<!-- /embed:${key} -->`
|
|
92
|
+
: `<!-- embed:${key} -->${text}<!-- /embed:${key} -->`;
|
|
93
|
+
};
|
|
94
|
+
/**
|
|
95
|
+
* What goes between an embed block's tags: its options (if any) in YAML, then its content.
|
|
96
|
+
*
|
|
97
|
+
* @example
|
|
98
|
+
* embedText("https://youtu.be/x"); // "https://youtu.be/x"
|
|
99
|
+
* embedText("https://a.bandcamp.com/album/b", { layout: "large" }); // "<!--yaml\nlayout: large\n-->\nhttps://a.bandcamp.com/album/b"
|
|
100
|
+
*/
|
|
101
|
+
export const embedText = (content, options = {}) => Object.keys(options).length
|
|
102
|
+
? `<!--yaml\n${stringify(options)}-->\n${content}`
|
|
103
|
+
: content;
|
package/dist/embeds/index.d.ts
CHANGED
|
@@ -1,40 +1,143 @@
|
|
|
1
1
|
import type { Logger } from "../generator/types/index.ts";
|
|
2
|
-
import
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
export
|
|
6
|
-
/**
|
|
7
|
-
|
|
2
|
+
import { type EmbedOptionValues } from "./blocks/index.ts";
|
|
3
|
+
import type { EmbedContext, EmbedPageParts, EmbedPlugin, EmbedTarget } from "./types/index.ts";
|
|
4
|
+
export type * from "./types/index.ts";
|
|
5
|
+
export { EMBED_BLOCK, embedBlock, embedContent, embedOptionsOf, embedText, splitEmbed, } from "./blocks/index.ts";
|
|
6
|
+
/**
|
|
7
|
+
* Template data for the `{% embedHead %}` and `{% embedFoot %}` tags while a page is rendered: where `renderPage` puts
|
|
8
|
+
* the HTML the page's embeds need, once it knows which embeds the page shows.
|
|
9
|
+
*/
|
|
10
|
+
export declare const EMBED_PAGE_PARTS: EmbedPageParts;
|
|
11
|
+
/** The kinds of web addresses an embed can list in its `sources` */
|
|
12
|
+
export declare const EMBED_SOURCE_KINDS: readonly ["frame", "script", "style", "font", "connect"];
|
|
13
|
+
/**
|
|
14
|
+
* Whether a value is an embed plugin: a kebab-case `key`, a `name`, a `build.render` function, and valid optional
|
|
15
|
+
* `description`, `info`, `sources`, `options` (a map), `validate` and `editor` renderers.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* isEmbedPlugin({ key: "quote", name: "Quote", build: { render: async (text) => text } }); // true
|
|
19
|
+
*/
|
|
20
|
+
export declare const isEmbedPlugin: (value: unknown) => value is EmbedPlugin;
|
|
21
|
+
/**
|
|
22
|
+
* Check a list of embed plugins: each must be valid (see isEmbedPlugin), with a key of its own, and its options must be
|
|
23
|
+
* fields like article metadata's (see EmbedPlugin.options). Throws describing the first problem.
|
|
24
|
+
*
|
|
25
|
+
* @example
|
|
26
|
+
* checkEmbedPlugins([youtube, bandcamp]); // [youtube, bandcamp]
|
|
27
|
+
*/
|
|
28
|
+
export declare const checkEmbedPlugins: (plugins: unknown[]) => EmbedPlugin[];
|
|
29
|
+
/**
|
|
30
|
+
* Load a config file's `plugins`: package names are imported from the config file's folder (their default export is
|
|
31
|
+
* an embed plugin or a list of them); objects are used as they are. Throws naming a package that can't be loaded.
|
|
32
|
+
*
|
|
33
|
+
* @param fromDir - the folder package names are found from, i.e. the config file's
|
|
34
|
+
* @example
|
|
35
|
+
* await loadPlugins(["@lvl99dotcom/edaha-plugin-youtube"], "my-site"); // [youtube]
|
|
36
|
+
*/
|
|
37
|
+
export declare const loadPlugins: (entries: unknown, fromDir: string) => Promise<unknown[]>;
|
|
8
38
|
/** Options for resolving embeds */
|
|
9
39
|
export interface EmbedOptions extends EmbedContext {
|
|
10
|
-
/**
|
|
11
|
-
|
|
40
|
+
/** The embed plugins */
|
|
41
|
+
plugins: readonly EmbedPlugin[];
|
|
12
42
|
/** Where to report embeds that can't be rendered */
|
|
13
43
|
logger: Logger;
|
|
14
44
|
}
|
|
15
45
|
/**
|
|
16
|
-
* Renders embed
|
|
46
|
+
* Renders embed blocks to HTML with embed plugins, page by page: each page's blocks share their embed's `state`, and
|
|
47
|
+
* the page gets the HTML its embeds need once (`renderHead` and `renderFoot`).
|
|
48
|
+
*
|
|
49
|
+
* Put blocks in markdown with placeholders (`replaceBlocks`), render the markdown and the page's template (with
|
|
50
|
+
* EMBED_PAGE_PARTS for the `{% embedHead %}` and `{% embedFoot %}` tags), then render the page's embeds
|
|
51
|
+
* (`renderPage`).
|
|
17
52
|
*
|
|
18
53
|
* @example
|
|
19
|
-
* const embeds = new EmbedResolver({ fetch, logger: console });
|
|
20
|
-
* const
|
|
54
|
+
* const embeds = new EmbedResolver({ fetch, logger: console, plugins: [youtube] });
|
|
55
|
+
* const body = renderMarkdown(embeds.replaceBlocks(source, "news/hello"));
|
|
56
|
+
* const page = await embeds.renderPage(render("article.njk", { body, embeds: EMBED_PAGE_PARTS }), "/news/hello/");
|
|
21
57
|
*/
|
|
22
58
|
export declare class EmbedResolver {
|
|
23
59
|
private readonly options;
|
|
24
|
-
private readonly
|
|
60
|
+
private readonly plugins;
|
|
61
|
+
/** Embed blocks put in pages, by their placeholders' IDs */
|
|
62
|
+
private readonly placed;
|
|
63
|
+
/** Why blocks aren't valid, by their key, options and content (see validate) */
|
|
64
|
+
private readonly checked;
|
|
65
|
+
/** Each embed's options' validator, by its key */
|
|
66
|
+
private readonly optionValidators;
|
|
67
|
+
/** Warnings given, so a block shown on several pages is warned about once */
|
|
68
|
+
private readonly warned;
|
|
25
69
|
constructor(options: EmbedOptions);
|
|
26
70
|
/**
|
|
27
|
-
*
|
|
28
|
-
* warn and render a plain link instead.
|
|
71
|
+
* Put an embed block in a page by a placeholder, which `renderPage` renders.
|
|
29
72
|
*
|
|
30
|
-
* @param
|
|
73
|
+
* @param key - the block's key, or undefined for an old `<!-- embed -->` block
|
|
74
|
+
* @param text - what is between its tags: its options and content
|
|
75
|
+
* @param source - where it is, for warnings
|
|
76
|
+
* @example
|
|
77
|
+
* embeds.place("youtube", "https://youtu.be/x", "Embed"); // "<!--edaha-embed:0-->"
|
|
31
78
|
*/
|
|
32
|
-
|
|
79
|
+
place(key: string | undefined, text: string, source: string): string;
|
|
33
80
|
/**
|
|
34
|
-
* Replace every
|
|
81
|
+
* Replace every embed block in markdown with a placeholder (see place), as its own block. Blocks in code blocks and
|
|
82
|
+
* inline code are left as they are. Embed HTML put straight into markdown would end at its first blank line, so the
|
|
83
|
+
* blocks are rendered with the page they are shown on (see renderPage).
|
|
35
84
|
*
|
|
36
85
|
* @param source - where the markdown is from, for warnings
|
|
86
|
+
* @example
|
|
87
|
+
* embeds.replaceBlocks("Hi\n<!-- embed:youtube -->https://youtu.be/x<!-- /embed:youtube -->", "news/hello");
|
|
88
|
+
* // "Hi\n\n\n<!--edaha-embed:0-->\n\n"
|
|
37
89
|
*/
|
|
38
|
-
replaceBlocks(markdown: string, source: string):
|
|
39
|
-
|
|
90
|
+
replaceBlocks(markdown: string, source: string): string;
|
|
91
|
+
/**
|
|
92
|
+
* Render a page's embeds: each placeholder of a block (see place) in order, sharing each embed's state on the page,
|
|
93
|
+
* then the HTML the page's embeds need in place of EMBED_PAGE_PARTS' placeholders. A block whose key has no plugin,
|
|
94
|
+
* or whose plugin fails, is shown as it is (a link for a URL, otherwise as text), and one that isn't valid is left
|
|
95
|
+
* out, with a warning (once, however many pages show it). An escaped placeholder (e.g. in a feed) gets escaped HTML.
|
|
96
|
+
*
|
|
97
|
+
* @param source - which page it is, for warnings
|
|
98
|
+
* @param target - render for the website (default) or the editor
|
|
99
|
+
* @example
|
|
100
|
+
* await embeds.renderPage('<head><!--edaha-embeds-head--></head><body><!--edaha-embed:0--></body>', "/news/hello/");
|
|
101
|
+
*/
|
|
102
|
+
renderPage(html: string, source: string, target?: EmbedTarget): Promise<string>;
|
|
103
|
+
/**
|
|
104
|
+
* Why a block isn't valid, or nothing when it is: its key has no plugin, its options aren't the embed's (see
|
|
105
|
+
* EmbedPlugin.options), or the embed's `validate` says its content (or options) isn't valid. The options are checked
|
|
106
|
+
* with their defaults and without hidden ones. Used by the editor to check blocks before they are saved.
|
|
107
|
+
*
|
|
108
|
+
* @example
|
|
109
|
+
* await embeds.validate("youtube", "https://example.com/"); // ["https://example.com/ is not a YouTube URL"]
|
|
110
|
+
* await embeds.validate("bandcamp", url, { layout: "huge" }); // ['Layout must be one of "slim", "artwork-only", "large"']
|
|
111
|
+
*/
|
|
112
|
+
validate(key: string | undefined, content: string, options?: EmbedOptionValues): Promise<string[]>;
|
|
113
|
+
/** Why a block with its options resolved isn't valid (see validate), checked once */
|
|
114
|
+
private check;
|
|
115
|
+
/** Why a block's options (resolved) aren't the embed's, in plain words, e.g. 'Layout must be one of "slim", "large"' */
|
|
116
|
+
private optionProblems;
|
|
117
|
+
/** Warn about a block or page, unless that warning was given before */
|
|
118
|
+
private warn;
|
|
119
|
+
/** Render a block on a page: its HTML, a fallback, or nothing when it is left out (see renderPage) */
|
|
120
|
+
private renderBlock;
|
|
121
|
+
/**
|
|
122
|
+
* The HTML a page needs for the embeds it shows: each shown embed's `renderHead` and `renderFoot`, once, in the
|
|
123
|
+
* order of the plugins. One that fails is left out with a warning.
|
|
124
|
+
*/
|
|
125
|
+
private pageParts;
|
|
40
126
|
}
|
|
127
|
+
/**
|
|
128
|
+
* A fetch that fetches each address once (requests without other settings only), giving each caller a copy of the
|
|
129
|
+
* response, e.g. so pages that show the same embed don't fetch it again.
|
|
130
|
+
*
|
|
131
|
+
* @example
|
|
132
|
+
* const fetchOnce = cachedFetch(fetch);
|
|
133
|
+
* await fetchOnce("https://example.com/"); // fetched
|
|
134
|
+
* await fetchOnce("https://example.com/"); // the same response, not fetched again
|
|
135
|
+
*/
|
|
136
|
+
export declare const cachedFetch: (fetcher: typeof fetch) => typeof fetch;
|
|
137
|
+
/**
|
|
138
|
+
* The messages of an error thrown by an embed's `validate`: each of an `AggregateError`'s errors, or the error's own.
|
|
139
|
+
*
|
|
140
|
+
* @example
|
|
141
|
+
* validationErrors(new AggregateError([new Error("No ID"), new Error("Too long")])); // ["No ID", "Too long"]
|
|
142
|
+
*/
|
|
143
|
+
export declare const validationErrors: (error: unknown) => string[];
|