@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.
Files changed (61) hide show
  1. package/LICENSE +183 -183
  2. package/README.md +7 -252
  3. package/dist/cli/index.d.ts +36 -6
  4. package/dist/cli/index.js +48 -9
  5. package/dist/embeds/blocks/index.d.ts +59 -0
  6. package/dist/embeds/blocks/index.js +103 -0
  7. package/dist/embeds/index.d.ts +122 -19
  8. package/dist/embeds/index.js +381 -41
  9. package/dist/embeds/types/index.d.ts +111 -8
  10. package/dist/generator/article/index.d.ts +52 -12
  11. package/dist/generator/article/index.js +94 -26
  12. package/dist/generator/build/index.d.ts +55 -23
  13. package/dist/generator/build/index.js +151 -81
  14. package/dist/generator/config/index.d.ts +45 -8
  15. package/dist/generator/config/index.js +152 -30
  16. package/dist/generator/configFile/index.d.ts +58 -0
  17. package/dist/generator/configFile/index.js +122 -0
  18. package/dist/generator/fields/index.d.ts +93 -0
  19. package/dist/generator/fields/index.js +186 -0
  20. package/dist/generator/format/index.d.ts +40 -0
  21. package/dist/generator/format/index.js +75 -0
  22. package/dist/generator/lists/index.d.ts +3 -3
  23. package/dist/generator/lists/index.js +9 -8
  24. package/dist/generator/markdown/index.d.ts +8 -3
  25. package/dist/generator/markdown/index.js +11 -4
  26. package/dist/generator/metadata/index.d.ts +150 -0
  27. package/dist/generator/metadata/index.js +361 -0
  28. package/dist/generator/metadataGroups/index.d.ts +45 -0
  29. package/dist/generator/metadataGroups/index.js +169 -0
  30. package/dist/generator/templates/index.d.ts +35 -3
  31. package/dist/generator/templates/index.js +72 -6
  32. package/dist/generator/types/index.d.ts +43 -18
  33. package/dist/generator/urls/index.d.ts +18 -8
  34. package/dist/generator/urls/index.js +22 -12
  35. package/dist/index.d.ts +5 -7
  36. package/dist/index.js +6 -7
  37. package/package.json +18 -47
  38. package/theme/static/{site.css → base.css} +132 -24
  39. package/theme/templates/article/list.njk +6 -6
  40. package/theme/templates/article/single.njk +13 -7
  41. package/theme/templates/layouts/html.njk +54 -32
  42. package/theme/templates/layouts/rssfeed.njk +7 -7
  43. package/theme/templates/page/home.njk +2 -7
  44. package/theme/templates/page/single.njk +2 -2
  45. package/dist/client/assets/index-BbKEbPS8.css +0 -1
  46. package/dist/client/assets/index-DtG7vi1d.js +0 -559
  47. package/dist/client/index.html +0 -13
  48. package/dist/editor/index.d.ts +0 -62
  49. package/dist/editor/index.js +0 -102
  50. package/dist/embeds/bandcamp/index.d.ts +0 -9
  51. package/dist/embeds/bandcamp/index.js +0 -28
  52. package/dist/embeds/youtube/index.d.ts +0 -17
  53. package/dist/embeds/youtube/index.js +0 -48
  54. package/dist/server/app/index.d.ts +0 -39
  55. package/dist/server/app/index.js +0 -138
  56. package/dist/server/convert/index.d.ts +0 -25
  57. package/dist/server/convert/index.js +0 -125
  58. package/dist/server/store/index.d.ts +0 -148
  59. package/dist/server/store/index.js +0 -411
  60. package/dist/server/types/index.d.ts +0 -76
  61. package/dist/server/types/index.js +0 -1
@@ -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.yml's outputDir (and copy it into publishDir, if set)\n editor Run the local article editor (only reachable from this computer)\n\nOptions:\n --dir <folder> The site folder, which holds config.yml and articles/ (default: the current folder)\n --site-url <url> build: the website's absolute URL for feeds (default: SITE_URL, then config.yml'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";
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: buildBlog) */
36
+ /** Builds the site (default: buildSite) */
16
37
  build?: (options: BuildOptions) => Promise<BuildResult>;
17
- /** Starts the editor (default: startEditor) */
18
- editor?: (options: EditorServerOptions) => Promise<EditorServer>;
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.1.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 { buildBlog } from "../generator/build/index.js";
5
- import { EDITOR_PORT, startEditor, } from "../editor/index.js";
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.yml's outputDir (and copy it into publishDir, if set)
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
- --dir <folder> The site folder, which holds config.yml and articles/ (default: the current folder)
15
- --site-url <url> build: the website's absolute URL for feeds (default: SITE_URL, then config.yml's siteUrl)
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.1.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 ?? buildBlog)({
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 ?? startEditor)({
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 for ${siteDir} running at ${editor.url} (press Ctrl+C to stop)`);
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;
@@ -1,40 +1,143 @@
1
1
  import type { Logger } from "../generator/types/index.ts";
2
- import type { EmbedContext, EmbedRenderer } from "./types/index.ts";
3
- export type { EmbedContext, EmbedRenderer } from "./types/index.ts";
4
- /** All embed renderers, tried in order */
5
- export declare const EMBED_RENDERERS: readonly EmbedRenderer[];
6
- /** `<!-- embed -->URL<!-- /embed -->` blocks in article markdown */
7
- export declare const EMBED_BLOCK: RegExp;
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
- /** Renderers to try (defaults to all) */
11
- renderers?: readonly EmbedRenderer[];
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 URLs to HTML, rendering each URL only once.
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 markdown = await embeds.replaceBlocks(source, "article/hello");
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 cache;
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
- * Render one URL to embed HTML wrapped in `<div class="embed">`. If no renderer matches, or it fails,
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 source - where the embed is, for warnings
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
- render(rawUrl: string, source: string): Promise<string>;
79
+ place(key: string | undefined, text: string, source: string): string;
33
80
  /**
34
- * Replace every `<!-- embed -->URL<!-- /embed -->` block in markdown with its rendered HTML, as its own block.
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): Promise<string>;
39
- private renderUncached;
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[];