@lvl99dotcom/edaha.md 0.0.0-stage → 0.1.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 +201 -0
- package/README.md +258 -2
- package/dist/cli/bin.d.ts +2 -0
- package/dist/cli/bin.js +9 -0
- package/dist/cli/index.d.ts +41 -0
- package/dist/cli/index.js +110 -0
- package/dist/client/assets/index-BbKEbPS8.css +1 -0
- package/dist/client/assets/index-DtG7vi1d.js +559 -0
- package/dist/client/index.html +13 -0
- package/dist/editor/index.d.ts +62 -0
- package/dist/editor/index.js +102 -0
- package/dist/embeds/bandcamp/index.d.ts +9 -0
- package/dist/embeds/bandcamp/index.js +28 -0
- package/dist/embeds/index.d.ts +40 -0
- package/dist/embeds/index.js +71 -0
- package/dist/embeds/types/index.d.ts +14 -0
- package/dist/embeds/types/index.js +1 -0
- package/dist/embeds/youtube/index.d.ts +17 -0
- package/dist/embeds/youtube/index.js +48 -0
- package/dist/generator/article/index.d.ts +111 -0
- package/dist/generator/article/index.js +257 -0
- package/dist/generator/build/index.d.ts +77 -0
- package/dist/generator/build/index.js +293 -0
- package/dist/generator/config/index.d.ts +59 -0
- package/dist/generator/config/index.js +176 -0
- package/dist/generator/format/index.d.ts +52 -0
- package/dist/generator/format/index.js +102 -0
- package/dist/generator/lists/index.d.ts +63 -0
- package/dist/generator/lists/index.js +132 -0
- package/dist/generator/markdown/index.d.ts +20 -0
- package/dist/generator/markdown/index.js +55 -0
- package/dist/generator/slug/index.d.ts +26 -0
- package/dist/generator/slug/index.js +57 -0
- package/dist/generator/templates/index.d.ts +56 -0
- package/dist/generator/templates/index.js +109 -0
- package/dist/generator/types/index.d.ts +161 -0
- package/dist/generator/types/index.js +1 -0
- package/dist/generator/urls/index.d.ts +40 -0
- package/dist/generator/urls/index.js +67 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.js +10 -0
- package/dist/server/app/index.d.ts +39 -0
- package/dist/server/app/index.js +138 -0
- package/dist/server/convert/index.d.ts +25 -0
- package/dist/server/convert/index.js +125 -0
- package/dist/server/store/index.d.ts +148 -0
- package/dist/server/store/index.js +411 -0
- package/dist/server/types/index.d.ts +76 -0
- package/dist/server/types/index.js +1 -0
- package/dist/theme/index.d.ts +8 -0
- package/dist/theme/index.js +9 -0
- package/package.json +93 -3
- package/theme/static/site.css +220 -0
- package/theme/templates/article/list.njk +69 -0
- package/theme/templates/article/single.njk +58 -0
- package/theme/templates/layouts/html.njk +50 -0
- package/theme/templates/layouts/rssfeed.njk +28 -0
- package/theme/templates/page/home.njk +21 -0
- package/theme/templates/page/single.njk +18 -0
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import { Hono } from "hono";
|
|
2
|
+
import mime from "mime-types";
|
|
3
|
+
import { EmbedResolver } from "../../embeds/index.js";
|
|
4
|
+
import { editorHtmlToMarkdown, markdownToEditorHtml, } from "../convert/index.js";
|
|
5
|
+
import { bodyBaseUrl, EditorError } from "../store/index.js";
|
|
6
|
+
/**
|
|
7
|
+
* The Content Security Policy of preview pages and their files: like the website's news pages (its own files, YouTube
|
|
8
|
+
* and Bandcamp embeds), but with no scripts, requests or forms at all. Previews are served from the editor's own
|
|
9
|
+
* address, so this is what stops anything in an article from using the editor's API.
|
|
10
|
+
*/
|
|
11
|
+
export const PREVIEW_CSP = "default-src 'self'; script-src 'none'; frame-src https://www.youtube-nocookie.com https://bandcamp.com; style-src 'self'; style-src-attr 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'self'";
|
|
12
|
+
/**
|
|
13
|
+
* Create the article editor's local API. Requests that change files must come from the editor's own page (checked
|
|
14
|
+
* with the Origin header), so other websites open in the same browser can't write articles.
|
|
15
|
+
*
|
|
16
|
+
* Routes:
|
|
17
|
+
* - `GET /api/articles`: list articles
|
|
18
|
+
* - `GET /api/types`: the article types from config.yml, with their labels
|
|
19
|
+
* - `GET /api/templates/:type`: the template names an article of a type can use
|
|
20
|
+
* - `POST /api/articles`: create an article
|
|
21
|
+
* - `GET|PUT|DELETE /api/articles/:type/:slug`: load, save (and move) or delete an article
|
|
22
|
+
* - `POST /api/articles/:type/:slug/files`: upload a file (multipart field "file")
|
|
23
|
+
* - `GET /files/:type/:slug/:name`: an article's file, for previews in the editor
|
|
24
|
+
* - `GET /api/embed?url=...`: render an embed URL as the website would, for previews in the editor
|
|
25
|
+
* - `POST /api/convert/markdown` and `POST /api/convert/html`: convert an article body between editor HTML and Markdown
|
|
26
|
+
* (`{ html | markdown, location? }`, where `location` is the saved article's, which relative URLs are relative to)
|
|
27
|
+
* - `POST /api/preview`: remember unsaved article data (`{ data, location? }`) for a preview page, and give its URL
|
|
28
|
+
* (`{ url }`); answers 400 if it can't be rendered
|
|
29
|
+
* - `GET /preview/:id/`: render a remembered preview with its type's "single" template, and `GET /<path>`: one of the
|
|
30
|
+
* blog's static files (e.g. `/site.css`), both with a Content Security Policy that forbids scripts (`PREVIEW_CSP`)
|
|
31
|
+
*
|
|
32
|
+
* @example
|
|
33
|
+
* const app = createEditorApp(new ArticleStore("packages/blog"), { allowedOrigins: ["http://127.0.0.1:5180"] });
|
|
34
|
+
*/
|
|
35
|
+
export const createEditorApp = (store, { allowedOrigins, fetch: fetchFn = (...args) => fetch(...args), }) => {
|
|
36
|
+
const app = new Hono();
|
|
37
|
+
app.use(async (c, next) => {
|
|
38
|
+
if (c.req.method !== "GET" && c.req.method !== "HEAD") {
|
|
39
|
+
const origin = c.req.header("origin");
|
|
40
|
+
if (!origin || !allowedOrigins.includes(origin))
|
|
41
|
+
return c.json({ error: "Forbidden" }, 403);
|
|
42
|
+
}
|
|
43
|
+
await next();
|
|
44
|
+
});
|
|
45
|
+
app.onError((error, c) => error instanceof EditorError
|
|
46
|
+
? c.json({ error: error.message }, error.status)
|
|
47
|
+
: c.json({ error: error.message }, 500));
|
|
48
|
+
app.get("/api/articles", async (c) => c.json(await store.list()));
|
|
49
|
+
app.get("/api/types", async (c) => c.json(await store.types()));
|
|
50
|
+
app.get("/api/templates/:type", (c) => c.json(store.templates(c.req.param("type"))));
|
|
51
|
+
app.get("/api/embed", async (c) => {
|
|
52
|
+
const url = c.req.query("url") ?? "";
|
|
53
|
+
const warnings = [];
|
|
54
|
+
// A new resolver each time, so a fixed URL or a network failure isn't remembered
|
|
55
|
+
const embeds = new EmbedResolver({
|
|
56
|
+
fetch: fetchFn,
|
|
57
|
+
logger: { warn: (message) => warnings.push(message) },
|
|
58
|
+
});
|
|
59
|
+
return c.json({
|
|
60
|
+
html: await embeds.render(url, "Preview"),
|
|
61
|
+
warnings,
|
|
62
|
+
});
|
|
63
|
+
});
|
|
64
|
+
app.post("/api/convert/markdown", async (c) => {
|
|
65
|
+
const { html, location } = await c.req.json();
|
|
66
|
+
return c.json({
|
|
67
|
+
markdown: editorHtmlToMarkdown(html, bodyBaseUrl(location)),
|
|
68
|
+
});
|
|
69
|
+
});
|
|
70
|
+
app.post("/api/convert/html", async (c) => {
|
|
71
|
+
const { markdown, location } = await c.req.json();
|
|
72
|
+
return c.json({
|
|
73
|
+
html: markdownToEditorHtml(markdown, bodyBaseUrl(location)),
|
|
74
|
+
});
|
|
75
|
+
});
|
|
76
|
+
app.post("/api/preview", async (c) => {
|
|
77
|
+
const { data, location } = await c.req.json();
|
|
78
|
+
// A new resolver each time, so a fixed URL or a network failure isn't remembered
|
|
79
|
+
const embeds = new EmbedResolver({
|
|
80
|
+
fetch: fetchFn,
|
|
81
|
+
logger: { warn: () => undefined },
|
|
82
|
+
});
|
|
83
|
+
// Rendered now to report problems (e.g. a missing file), then again each time the page is shown
|
|
84
|
+
await store.preview(data, location, embeds);
|
|
85
|
+
return c.json({
|
|
86
|
+
url: `/preview/${store.rememberPreview(data, location)}/`,
|
|
87
|
+
});
|
|
88
|
+
});
|
|
89
|
+
app.post("/api/articles", async (c) => {
|
|
90
|
+
const data = await c.req.json();
|
|
91
|
+
return c.json(await store.save(data), 201);
|
|
92
|
+
});
|
|
93
|
+
app.get("/api/articles/:type/:slug", async (c) => c.json(await store.read(c.req.param("type"), c.req.param("slug"))));
|
|
94
|
+
app.put("/api/articles/:type/:slug", async (c) => {
|
|
95
|
+
const data = await c.req.json();
|
|
96
|
+
return c.json(await store.save(data, {
|
|
97
|
+
type: c.req.param("type"),
|
|
98
|
+
slug: c.req.param("slug"),
|
|
99
|
+
}));
|
|
100
|
+
});
|
|
101
|
+
app.delete("/api/articles/:type/:slug", async (c) => {
|
|
102
|
+
await store.remove(c.req.param("type"), c.req.param("slug"));
|
|
103
|
+
return c.body(null, 204);
|
|
104
|
+
});
|
|
105
|
+
app.post("/api/articles/:type/:slug/files", async (c) => {
|
|
106
|
+
const body = await c.req.parseBody();
|
|
107
|
+
const file = body.file;
|
|
108
|
+
if (!(file instanceof File))
|
|
109
|
+
throw new EditorError(400, 'Expected a file in the "file" field');
|
|
110
|
+
return c.json(await store.upload(c.req.param("type"), c.req.param("slug"), file.name, new Uint8Array(await file.arrayBuffer())), 201);
|
|
111
|
+
});
|
|
112
|
+
app.get("/files/:type/:slug/:name", async (c) => {
|
|
113
|
+
const name = c.req.param("name");
|
|
114
|
+
const contents = await store.file(c.req.param("type"), c.req.param("slug"), name);
|
|
115
|
+
return c.body(contents, 200, {
|
|
116
|
+
"Content-Type": mime.lookup(name) || "application/octet-stream",
|
|
117
|
+
"Cache-Control": "no-store",
|
|
118
|
+
});
|
|
119
|
+
});
|
|
120
|
+
// A remembered preview, rendered now, so template changes show when it reloads
|
|
121
|
+
app.get("/preview/:id/", async (c) => {
|
|
122
|
+
const html = await store.renderPreview(c.req.param("id"), new EmbedResolver({ fetch: fetchFn, logger: { warn: () => undefined } }));
|
|
123
|
+
return c.html(html, 200, {
|
|
124
|
+
"Cache-Control": "no-store",
|
|
125
|
+
"Content-Security-Policy": PREVIEW_CSP,
|
|
126
|
+
});
|
|
127
|
+
});
|
|
128
|
+
// The blog's static files (stylesheet, fonts), at the root as preview pages link them
|
|
129
|
+
app.get("/*", async (c) => {
|
|
130
|
+
const path = decodeURIComponent(c.req.path.slice(1));
|
|
131
|
+
return c.body((await store.staticFile(path)), 200, {
|
|
132
|
+
"Content-Type": mime.lookup(path) || "application/octet-stream",
|
|
133
|
+
"Cache-Control": "no-store",
|
|
134
|
+
"Content-Security-Policy": PREVIEW_CSP,
|
|
135
|
+
});
|
|
136
|
+
});
|
|
137
|
+
return app;
|
|
138
|
+
};
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The URL the editor loads an article's files from, e.g. "/files/article/hello/".
|
|
3
|
+
*
|
|
4
|
+
* @example
|
|
5
|
+
* filesUrl("article", "hello"); // "/files/article/hello/"
|
|
6
|
+
*/
|
|
7
|
+
export declare const filesUrl: (type: string, slug: string) => string;
|
|
8
|
+
/**
|
|
9
|
+
* Convert article markdown to HTML for the editor: `<!-- readmore -->` becomes `<hr class="readmore">`,
|
|
10
|
+
* embed blocks become `<div class="embed">URL</div>`, and relative URLs point at the editor's file URL.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* markdownToEditorHtml("Intro <!-- readmore -->Rest", "/files/article/hello/");
|
|
14
|
+
* // '<p>Intro</p>\n<hr class="readmore">\n<p>Rest</p>\n'
|
|
15
|
+
*/
|
|
16
|
+
export declare const markdownToEditorHtml: (source: string, baseUrl: string) => string;
|
|
17
|
+
/**
|
|
18
|
+
* Convert editor HTML back to article markdown, turning the readmore and embed blocks back into their shortcodes and
|
|
19
|
+
* the editor's file URLs back into relative URLs.
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* editorHtmlToMarkdown('<p>Hi</p><hr class="readmore"><p><img src="/files/article/a/b.png"></p>', "/files/article/a/");
|
|
23
|
+
* // "Hi\n\n<!-- readmore -->\n\n"
|
|
24
|
+
*/
|
|
25
|
+
export declare const editorHtmlToMarkdown: (html: string, baseUrl: string) => string;
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import TurndownService from "turndown";
|
|
2
|
+
import { EMBED_BLOCK } from "../../embeds/index.js";
|
|
3
|
+
import { READMORE } from "../../generator/article/index.js";
|
|
4
|
+
import { escapeHtml } from "../../generator/format/index.js";
|
|
5
|
+
import { createMarkdown, renderMarkdown, } from "../../generator/markdown/index.js";
|
|
6
|
+
// Without typographer, so text converts back to the same markdown
|
|
7
|
+
const markdown = createMarkdown({ typographer: false });
|
|
8
|
+
/**
|
|
9
|
+
* The URL the editor loads an article's files from, e.g. "/files/article/hello/".
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* filesUrl("article", "hello"); // "/files/article/hello/"
|
|
13
|
+
*/
|
|
14
|
+
export const filesUrl = (type, slug) => `/files/${type}/${slug}/`;
|
|
15
|
+
/**
|
|
16
|
+
* Convert article markdown to HTML for the editor: `<!-- readmore -->` becomes `<hr class="readmore">`,
|
|
17
|
+
* embed blocks become `<div class="embed">URL</div>`, and relative URLs point at the editor's file URL.
|
|
18
|
+
*
|
|
19
|
+
* @example
|
|
20
|
+
* markdownToEditorHtml("Intro <!-- readmore -->Rest", "/files/article/hello/");
|
|
21
|
+
* // '<p>Intro</p>\n<hr class="readmore">\n<p>Rest</p>\n'
|
|
22
|
+
*/
|
|
23
|
+
export const markdownToEditorHtml = (source, baseUrl) => renderMarkdown(markdown, source
|
|
24
|
+
.replace(READMORE, '\n\n<hr class="readmore">\n\n')
|
|
25
|
+
.replace(EMBED_BLOCK, (_, url) => `\n\n<div class="embed">${escapeHtml(url.trim())}</div>\n\n`), baseUrl);
|
|
26
|
+
/** HTML to markdown converter with rules for the readmore and embed blocks */
|
|
27
|
+
const createTurndown = () => {
|
|
28
|
+
const turndown = new TurndownService({
|
|
29
|
+
headingStyle: "atx",
|
|
30
|
+
codeBlockStyle: "fenced",
|
|
31
|
+
bulletListMarker: "-",
|
|
32
|
+
emDelimiter: "*",
|
|
33
|
+
hr: "---",
|
|
34
|
+
});
|
|
35
|
+
turndown.addRule("readmore", {
|
|
36
|
+
filter: (node) => node.nodeName === "HR" &&
|
|
37
|
+
node.classList.contains("readmore"),
|
|
38
|
+
replacement: () => "\n\n<!-- readmore -->\n\n",
|
|
39
|
+
});
|
|
40
|
+
turndown.addRule("embed", {
|
|
41
|
+
filter: (node) => node.nodeName === "DIV" &&
|
|
42
|
+
node.classList.contains("embed"),
|
|
43
|
+
replacement: (_, node) => `\n\n<!-- embed -->${String(node.textContent).trim()}<!-- /embed -->\n\n`,
|
|
44
|
+
});
|
|
45
|
+
// Small and big text, and collapsible details blocks, stay HTML. A details block's summary stays HTML (Markdown
|
|
46
|
+
// isn't read inside an HTML line) and its content becomes Markdown, between blank lines so it is read as Markdown.
|
|
47
|
+
turndown.addRule("smallBig", {
|
|
48
|
+
// `big` isn't in the DOM types' list of tag names, as HTML no longer recommends it
|
|
49
|
+
filter: (node) => node.nodeName === "SMALL" || node.nodeName === "BIG",
|
|
50
|
+
replacement: (content, node) => {
|
|
51
|
+
const tag = node.nodeName.toLowerCase();
|
|
52
|
+
return `<${tag}>${content}</${tag}>`;
|
|
53
|
+
},
|
|
54
|
+
});
|
|
55
|
+
turndown.addRule("summary", { filter: "summary", replacement: () => "" });
|
|
56
|
+
turndown.addRule("details", {
|
|
57
|
+
filter: "details",
|
|
58
|
+
replacement: (content, node) => {
|
|
59
|
+
const summary = Array.from(node.childNodes).find((child) => child.nodeName === "SUMMARY");
|
|
60
|
+
return `\n\n<details>\n<summary>${summary?.innerHTML.trim() ?? ""}</summary>\n\n${content.trim()}\n\n</details>\n\n`;
|
|
61
|
+
},
|
|
62
|
+
});
|
|
63
|
+
// List items with a single space after the marker ("- item", "1. item")
|
|
64
|
+
turndown.addRule("listItem", {
|
|
65
|
+
filter: "li",
|
|
66
|
+
replacement: (content, node) => {
|
|
67
|
+
const parent = node.parentNode;
|
|
68
|
+
const index = Array.prototype.indexOf.call(parent.children, node);
|
|
69
|
+
const start = Number(parent.getAttribute("start") ?? 1);
|
|
70
|
+
const prefix = parent.nodeName === "OL" ? `${start + index}. ` : "- ";
|
|
71
|
+
const text = content
|
|
72
|
+
.replace(/^\n+/, "")
|
|
73
|
+
.replace(/\n+$/, "")
|
|
74
|
+
// Indent continuation lines under the marker, leaving blank lines empty
|
|
75
|
+
.replace(/\n(?!\n)/g, `\n${" ".repeat(prefix.length)}`);
|
|
76
|
+
return `${prefix}${text}${node.nextSibling ? "\n" : ""}`;
|
|
77
|
+
},
|
|
78
|
+
});
|
|
79
|
+
// Tables as GFM tables: the first row is the header row. Cells are kept to one line.
|
|
80
|
+
turndown.addRule("tableCell", {
|
|
81
|
+
filter: ["th", "td"],
|
|
82
|
+
replacement: (content) => `| ${content
|
|
83
|
+
.trim()
|
|
84
|
+
.replace(/\s*\n+\s*/g, " ")
|
|
85
|
+
.replace(/\|/g, "\\|")} `,
|
|
86
|
+
});
|
|
87
|
+
turndown.addRule("tableRow", {
|
|
88
|
+
filter: "tr",
|
|
89
|
+
replacement: (content, node) => {
|
|
90
|
+
const row = `${content}|\n`;
|
|
91
|
+
const table = node.closest("table");
|
|
92
|
+
if (table.rows[0] !== node)
|
|
93
|
+
return row;
|
|
94
|
+
const separator = Array.from(node.cells, () => "| --- ").join("");
|
|
95
|
+
return `${row}${separator}|\n`;
|
|
96
|
+
},
|
|
97
|
+
});
|
|
98
|
+
turndown.addRule("tableSection", {
|
|
99
|
+
filter: ["thead", "tbody", "tfoot"],
|
|
100
|
+
replacement: (content) => content,
|
|
101
|
+
});
|
|
102
|
+
turndown.addRule("table", {
|
|
103
|
+
filter: "table",
|
|
104
|
+
replacement: (content) => `\n\n${content.trim()}\n\n`,
|
|
105
|
+
});
|
|
106
|
+
// Column widths from the editor aren't kept
|
|
107
|
+
turndown.remove("colgroup");
|
|
108
|
+
return turndown;
|
|
109
|
+
};
|
|
110
|
+
const turndown = createTurndown();
|
|
111
|
+
/**
|
|
112
|
+
* Convert editor HTML back to article markdown, turning the readmore and embed blocks back into their shortcodes and
|
|
113
|
+
* the editor's file URLs back into relative URLs.
|
|
114
|
+
*
|
|
115
|
+
* @example
|
|
116
|
+
* editorHtmlToMarkdown('<p>Hi</p><hr class="readmore"><p><img src="/files/article/a/b.png"></p>', "/files/article/a/");
|
|
117
|
+
* // "Hi\n\n<!-- readmore -->\n\n"
|
|
118
|
+
*/
|
|
119
|
+
export const editorHtmlToMarkdown = (html, baseUrl) => turndown
|
|
120
|
+
.turndown(html)
|
|
121
|
+
.replaceAll(`](${baseUrl}`, "](")
|
|
122
|
+
// Turndown escapes "1." at the start of a line, which is only needed outside headings
|
|
123
|
+
.replace(/^(#+ \d+)\\\./gm, "$1.")
|
|
124
|
+
.replace(/\n{3,}/g, "\n\n")
|
|
125
|
+
.trim();
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
import type { EmbedResolver } from "../../embeds/index.ts";
|
|
2
|
+
import type { ArticleSummary, ArticleTypeLabels, EditorArticle, EditorArticleData, UploadResult } from "../types/index.ts";
|
|
3
|
+
/** An editor request that can't be done, with the HTTP status to answer with */
|
|
4
|
+
export declare class EditorError extends Error {
|
|
5
|
+
readonly status: number;
|
|
6
|
+
constructor(status: number, message: string);
|
|
7
|
+
}
|
|
8
|
+
/** How many previews the editor remembers (the newest) */
|
|
9
|
+
export declare const MAX_PREVIEWS = 20;
|
|
10
|
+
/**
|
|
11
|
+
* Check an article type and slug are valid folder names. Throws a 400 EditorError if not.
|
|
12
|
+
*/
|
|
13
|
+
export declare const checkLocation: (type: string, slug: string) => void;
|
|
14
|
+
/**
|
|
15
|
+
* The URL relative URLs in an article's body point at in the editor: its saved folder's file URL, or "" for an article
|
|
16
|
+
* that isn't saved yet (and has no files).
|
|
17
|
+
*
|
|
18
|
+
* @example
|
|
19
|
+
* bodyBaseUrl({ type: "news", slug: "hello" }); // "/files/news/hello/"
|
|
20
|
+
* bodyBaseUrl(undefined); // ""
|
|
21
|
+
*/
|
|
22
|
+
export declare const bodyBaseUrl: (location: {
|
|
23
|
+
type: string;
|
|
24
|
+
slug: string;
|
|
25
|
+
} | undefined) => string;
|
|
26
|
+
/**
|
|
27
|
+
* Make an uploaded file name safe: a slug of its base name plus its lowercase extension.
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* safeFileName("My Photo (1).JPG"); // "my-photo-1.jpg"
|
|
31
|
+
*/
|
|
32
|
+
export declare const safeFileName: (name: string) => string;
|
|
33
|
+
/**
|
|
34
|
+
* Write an article's markdown source: the YAML config header, the title as an H1 and the body.
|
|
35
|
+
* The type (always the article's folder) and defaults (empty lists) are left out to keep the header short.
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* serializeArticle({ type: "article", slug: "hi", status: "published", date, title: "Hi", tags: [], attachments: [] }, "Body");
|
|
39
|
+
*/
|
|
40
|
+
export declare const serializeArticle: (data: EditorArticleData, body: string) => string;
|
|
41
|
+
/**
|
|
42
|
+
* Reads and writes articles in the site's `articles/` folder for the editor, and renders previews with the site's
|
|
43
|
+
* templates over the default theme's.
|
|
44
|
+
*
|
|
45
|
+
* @example
|
|
46
|
+
* const store = new ArticleStore("my-site");
|
|
47
|
+
* await store.list();
|
|
48
|
+
*/
|
|
49
|
+
export declare class ArticleStore {
|
|
50
|
+
private readonly articlesDir;
|
|
51
|
+
/** Previews' unsaved data by ID, the newest last (see `rememberPreview`) */
|
|
52
|
+
private readonly previews;
|
|
53
|
+
private readonly siteDir;
|
|
54
|
+
private readonly themeDir;
|
|
55
|
+
/**
|
|
56
|
+
* @param siteDir - the site folder (holds config.yml and articles/, and optionally templates/ and static/)
|
|
57
|
+
* @param themeDir - the default theme folder that the site's templates and static files override
|
|
58
|
+
*/
|
|
59
|
+
constructor(siteDir: string, themeDir?: string);
|
|
60
|
+
/** The site's templates over the theme's */
|
|
61
|
+
private loadTemplates;
|
|
62
|
+
/** Read config.yml */
|
|
63
|
+
private config;
|
|
64
|
+
/**
|
|
65
|
+
* The template names an article of a type can use (see Templates.names).
|
|
66
|
+
*/
|
|
67
|
+
templates(type: string): string[];
|
|
68
|
+
/**
|
|
69
|
+
* The article types from config.yml, with their labels.
|
|
70
|
+
*/
|
|
71
|
+
types(): Promise<Record<string, ArticleTypeLabels>>;
|
|
72
|
+
/** An article's folder */
|
|
73
|
+
private dir;
|
|
74
|
+
/** Read an article's source, or throw a 404 EditorError */
|
|
75
|
+
private source;
|
|
76
|
+
/**
|
|
77
|
+
* List every article, including drafts, newest first. Articles that can't be read are listed with their error.
|
|
78
|
+
*/
|
|
79
|
+
list(): Promise<ArticleSummary[]>;
|
|
80
|
+
/**
|
|
81
|
+
* Load an article for editing. Throws a 404 EditorError if it doesn't exist, or 422 if it can't be read.
|
|
82
|
+
*/
|
|
83
|
+
read(type: string, slug: string): Promise<EditorArticle>;
|
|
84
|
+
/**
|
|
85
|
+
* Save an article. When its type or slug changed, its folder (with all its files) moves to the new location.
|
|
86
|
+
* Pass no `from` for a new article. Returns where the article now is.
|
|
87
|
+
*/
|
|
88
|
+
save(data: EditorArticleData, from?: {
|
|
89
|
+
type: string;
|
|
90
|
+
slug: string;
|
|
91
|
+
}): Promise<{
|
|
92
|
+
type: string;
|
|
93
|
+
slug: string;
|
|
94
|
+
}>;
|
|
95
|
+
/**
|
|
96
|
+
* Render an article from unsaved editor data as the website would, with its type's "single" template, for the
|
|
97
|
+
* editor's preview. Drafts are shown as if published. Its files come from its saved folder (`location`), if it has one,
|
|
98
|
+
* and are shown from the editor's file URLs. Throws a 400 EditorError if it can't be rendered (e.g. a file isn't in
|
|
99
|
+
* the article's folder).
|
|
100
|
+
*
|
|
101
|
+
* @param embeds - renders embed blocks
|
|
102
|
+
*/
|
|
103
|
+
preview(data: EditorArticleData, location: {
|
|
104
|
+
type: string;
|
|
105
|
+
slug: string;
|
|
106
|
+
} | undefined, embeds: EmbedResolver): Promise<string>;
|
|
107
|
+
/**
|
|
108
|
+
* Delete an article and all its files.
|
|
109
|
+
*/
|
|
110
|
+
remove(type: string, slug: string): Promise<void>;
|
|
111
|
+
/**
|
|
112
|
+
* Save an uploaded file into an article's folder (replacing a file with the same name).
|
|
113
|
+
*/
|
|
114
|
+
upload(type: string, slug: string, fileName: string, contents: Uint8Array): Promise<UploadResult>;
|
|
115
|
+
/**
|
|
116
|
+
* Remember an article's unsaved data for its preview page, under a new ID. Only the newest `MAX_PREVIEWS` are kept,
|
|
117
|
+
* in memory: they're gone when the editor stops. Returns the ID.
|
|
118
|
+
*
|
|
119
|
+
* @example
|
|
120
|
+
* const id = store.rememberPreview(data, { type: "news", slug: "hello" }); // the editor shows it at /preview/<id>/
|
|
121
|
+
*/
|
|
122
|
+
rememberPreview(data: EditorArticleData, location: {
|
|
123
|
+
type: string;
|
|
124
|
+
slug: string;
|
|
125
|
+
} | undefined): string;
|
|
126
|
+
/**
|
|
127
|
+
* Render a remembered preview as the website would (see `preview`), so changes to templates show when it reloads.
|
|
128
|
+
* Throws a 404 EditorError if there is no preview with that ID (e.g. after the editor restarted).
|
|
129
|
+
*
|
|
130
|
+
* @param embeds - renders embed blocks
|
|
131
|
+
*/
|
|
132
|
+
renderPreview(id: string, embeds: EmbedResolver): Promise<string>;
|
|
133
|
+
/**
|
|
134
|
+
* Read one of the static files published at the website's root (the site's `static/`, then the theme's), e.g.
|
|
135
|
+
* `site.css`, for previews. Throws a 404 EditorError if there is no such file, or the path leaves the folder or
|
|
136
|
+
* names a hidden file.
|
|
137
|
+
*
|
|
138
|
+
* @example
|
|
139
|
+
* await store.staticFile("fonts/my-font.woff2");
|
|
140
|
+
*/
|
|
141
|
+
staticFile(path: string): Promise<Uint8Array>;
|
|
142
|
+
/** The static folders (stylesheet, fonts) published at the website's root: the site's, then the theme's */
|
|
143
|
+
get staticDirs(): string[];
|
|
144
|
+
/**
|
|
145
|
+
* Read a file from an article's folder. Throws a 404 EditorError if there is no such file.
|
|
146
|
+
*/
|
|
147
|
+
file(type: string, slug: string, name: string): Promise<Uint8Array>;
|
|
148
|
+
}
|