@lvl99dotcom/edaha.md 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +13 -2
  3. package/dist/cli/bin.d.ts +2 -0
  4. package/dist/cli/bin.js +9 -0
  5. package/dist/cli/index.d.ts +71 -0
  6. package/dist/cli/index.js +149 -0
  7. package/dist/embeds/blocks/index.d.ts +59 -0
  8. package/dist/embeds/blocks/index.js +103 -0
  9. package/dist/embeds/index.d.ts +143 -0
  10. package/dist/embeds/index.js +411 -0
  11. package/dist/embeds/types/index.d.ts +117 -0
  12. package/dist/embeds/types/index.js +1 -0
  13. package/dist/generator/article/index.d.ts +151 -0
  14. package/dist/generator/article/index.js +325 -0
  15. package/dist/generator/build/index.d.ts +109 -0
  16. package/dist/generator/build/index.js +363 -0
  17. package/dist/generator/config/index.d.ts +96 -0
  18. package/dist/generator/config/index.js +298 -0
  19. package/dist/generator/configFile/index.d.ts +58 -0
  20. package/dist/generator/configFile/index.js +122 -0
  21. package/dist/generator/fields/index.d.ts +93 -0
  22. package/dist/generator/fields/index.js +186 -0
  23. package/dist/generator/format/index.d.ts +92 -0
  24. package/dist/generator/format/index.js +177 -0
  25. package/dist/generator/lists/index.d.ts +63 -0
  26. package/dist/generator/lists/index.js +133 -0
  27. package/dist/generator/markdown/index.d.ts +25 -0
  28. package/dist/generator/markdown/index.js +62 -0
  29. package/dist/generator/metadata/index.d.ts +150 -0
  30. package/dist/generator/metadata/index.js +361 -0
  31. package/dist/generator/metadataGroups/index.d.ts +45 -0
  32. package/dist/generator/metadataGroups/index.js +169 -0
  33. package/dist/generator/slug/index.d.ts +26 -0
  34. package/dist/generator/slug/index.js +57 -0
  35. package/dist/generator/templates/index.d.ts +88 -0
  36. package/dist/generator/templates/index.js +175 -0
  37. package/dist/generator/types/index.d.ts +186 -0
  38. package/dist/generator/types/index.js +1 -0
  39. package/dist/generator/urls/index.d.ts +50 -0
  40. package/dist/generator/urls/index.js +77 -0
  41. package/dist/index.d.ts +8 -0
  42. package/dist/index.js +9 -0
  43. package/dist/theme/index.d.ts +8 -0
  44. package/dist/theme/index.js +9 -0
  45. package/package.json +64 -3
  46. package/theme/static/base.css +328 -0
  47. package/theme/templates/article/list.njk +69 -0
  48. package/theme/templates/article/single.njk +64 -0
  49. package/theme/templates/layouts/html.njk +72 -0
  50. package/theme/templates/layouts/rssfeed.njk +28 -0
  51. package/theme/templates/page/home.njk +16 -0
  52. package/theme/templates/page/single.njk +18 -0
@@ -0,0 +1,186 @@
1
+ import type { EmbedPageParts } from "../../embeds/types/index.ts";
2
+ import type { ArticleTypeConfig, GenerateConfig } from "../config/index.ts";
3
+ /** Website data */
4
+ export interface TemplateDataSite {
5
+ /** The name of the website */
6
+ name: string;
7
+ /** The website description */
8
+ description: string;
9
+ /** The website's absolute URL, without a trailing slash, e.g. "https://example.com" */
10
+ url: string;
11
+ /**
12
+ * The URL path the website lives under: `url`'s path without a trailing slash, e.g. "/edaha.md", or "" at a domain's
13
+ * root. Every URL in the template data already starts with it; use it for the site's static files, e.g.
14
+ * `{{ site.baseUrl }}/base.css`.
15
+ */
16
+ baseUrl: string;
17
+ /** The URL of the site's home: "/", or its `path` setting's folder, e.g. "/docs/" (after `baseUrl`) */
18
+ path: string;
19
+ /** Article type settings (configured types, plus any other types articles use) */
20
+ types: Record<string, TemplateDataArticleType>;
21
+ /**
22
+ * The author of articles that don't name one (unless their type has its own): the config file's `author`, the
23
+ * website's name without one, or undefined when it is `false`
24
+ */
25
+ author?: {
26
+ name: string;
27
+ email?: string | undefined;
28
+ url?: string | undefined;
29
+ } | undefined;
30
+ }
31
+ /** What is built for an article type */
32
+ export type TemplateDataArticleTypeGenerationConfig = GenerateConfig;
33
+ /** An article type's settings */
34
+ export interface TemplateDataArticleType extends ArticleTypeConfig {
35
+ /** The URL of the type's front page (its list or index article), e.g. "/news/" */
36
+ url: string;
37
+ }
38
+ /** An article's author */
39
+ export interface TemplateDataAuthor {
40
+ /** The author's name */
41
+ name: string;
42
+ /** The author's name converted to a slug */
43
+ slug: string;
44
+ /** The author's email address */
45
+ email?: string | undefined;
46
+ /** The author's homepage URL */
47
+ url?: string | undefined;
48
+ /** The URL to the author's list of articles */
49
+ listUrl: string;
50
+ }
51
+ /** A tag on an article */
52
+ export interface TemplateDataTag {
53
+ /** The tag's name */
54
+ name: string;
55
+ /** The tag's name converted to a slug */
56
+ slug: string;
57
+ /** The URL to the tag's list of articles */
58
+ url: string;
59
+ }
60
+ /** A downloadable attachment on an article */
61
+ export interface TemplateDataAttachment {
62
+ /** The attachment's name */
63
+ name: string;
64
+ /** The attachment's thumbnail URL */
65
+ thumbnail?: string | undefined;
66
+ /** The attachment's download URL */
67
+ url: string;
68
+ /** The attachment's mime type */
69
+ mimeType: string;
70
+ /** The attachment's file size in bytes (only for files in the article's subfolder) */
71
+ size?: number | undefined;
72
+ /** The attachment's file size in a human-readable form, e.g. "200 KB", "2.5 MB" */
73
+ sizeRelative?: string | undefined;
74
+ }
75
+ /** Article status: published articles are listed, unlisted ones only get their own page, drafts are not built */
76
+ export type ArticleStatus = "published" | "draft" | "unlisted";
77
+ /** A rendered article */
78
+ export interface TemplateDataArticle {
79
+ /** The article type */
80
+ type: string;
81
+ /** The article status (drafts are never rendered) */
82
+ status: Exclude<ArticleStatus, "draft">;
83
+ /** The article date (ISO 8601) */
84
+ date: string;
85
+ /** The article slug (i.e. the name of the article's subfolder) */
86
+ slug: string;
87
+ /** The template the article is rendered with, e.g. "single" */
88
+ template: string;
89
+ /** The article URL */
90
+ url: string;
91
+ /** The article title */
92
+ title: string;
93
+ /** The article's author: its own, its type's or the website's default, or undefined for none */
94
+ author?: TemplateDataAuthor | undefined;
95
+ /** The article thumbnail URL */
96
+ thumbnail?: string | undefined;
97
+ /** The article tags */
98
+ tags: TemplateDataTag[];
99
+ /** The article excerpt (in markdown) */
100
+ excerpt: string;
101
+ /** The article excerpt (in plaintext, stripped of any formatting) */
102
+ excerptText: string;
103
+ /** The article excerpt (in HTML) */
104
+ excerptHtml: string;
105
+ /** The article body (in markdown) */
106
+ body: string;
107
+ /** The article body (in plaintext, stripped of any formatting) */
108
+ bodyText: string;
109
+ /** The article body (in HTML) */
110
+ bodyHtml: string;
111
+ /** Article attachments */
112
+ attachments: TemplateDataAttachment[];
113
+ /**
114
+ * The article's custom metadata (see the config file's `metadata`): the valid values of the fields its type uses, by
115
+ * key, with file fields as paths on the website
116
+ */
117
+ meta: Record<string, unknown>;
118
+ }
119
+ /** One page of a paginated list */
120
+ export interface TemplateDataPaginationPage {
121
+ /** The page index (1, 2, ...) */
122
+ index: number;
123
+ /** The page URL, e.g. "/news/" for the first page, "/news/2" for the second */
124
+ url: string;
125
+ /** If the page is the current page or not */
126
+ isCurrent: boolean;
127
+ }
128
+ /** Pagination of a list */
129
+ export interface TemplateDataPagination {
130
+ /** The list of pages of articles */
131
+ pages: TemplateDataPaginationPage[];
132
+ /** The current page data */
133
+ page: TemplateDataPaginationPage;
134
+ /** The previous page data (only if not on first page) */
135
+ prevPage: TemplateDataPaginationPage | undefined;
136
+ /** The next page data (only if not on last page) */
137
+ nextPage: TemplateDataPaginationPage | undefined;
138
+ }
139
+ /** What a list groups articles by */
140
+ export type ListKind = "type" | "tag" | "author";
141
+ /** A paginated list of articles */
142
+ export interface TemplateDataList {
143
+ /** The list's name (the article type's plural label, the tag or the author name) */
144
+ name: string;
145
+ /** The slug of the article type/tag/author that was used for the list */
146
+ slug: string;
147
+ /** The article type the list belongs to */
148
+ type: string;
149
+ /** What the list groups articles by */
150
+ kind: ListKind;
151
+ /** The URL of the list's first page */
152
+ url: string;
153
+ /** The URL of the list's RSS feed */
154
+ feedUrl: string;
155
+ /** Whether the list has an RSS feed */
156
+ hasFeed: boolean;
157
+ /** The articles on the current page */
158
+ articles: TemplateDataArticle[];
159
+ /** The list's paginated pages */
160
+ pagination: TemplateDataPagination;
161
+ }
162
+ /** Everything given to a template */
163
+ export interface TemplateData {
164
+ /** Website data, always provided */
165
+ site: TemplateDataSite;
166
+ /** The page's article type, e.g. "news": the article's or the list's */
167
+ type: string;
168
+ /** Whether the page is an article's page (index articles and editor previews included) */
169
+ isArticle: boolean;
170
+ /** Whether the page is a list's page or feed */
171
+ isList: boolean;
172
+ /** List data, provided when rendering list and feed templates, and index articles (the first page of their type's list) */
173
+ list?: TemplateDataList;
174
+ /** Article data, only provided when rendering single templates */
175
+ article?: TemplateDataArticle;
176
+ /**
177
+ * HTML the page's embeds need once, output by the `{% embedHead %}` and `{% embedFoot %}` tags. Not provided for
178
+ * feeds.
179
+ */
180
+ embeds?: EmbedPageParts | undefined;
181
+ }
182
+ /** Where build warnings go */
183
+ export interface Logger {
184
+ /** Report a problem that doesn't stop the build */
185
+ warn(message: string): void;
186
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,50 @@
1
+ import type { ArticleTypeConfig } from "../config/index.ts";
2
+ /** Folders inside a type's URL path used by its tag and author lists */
3
+ export declare const RESERVED_SLUGS: string[];
4
+ /**
5
+ * Join URL path segments into a folder path relative to the website's root, ignoring empty segments.
6
+ *
7
+ * @example
8
+ * folderPath("", "news"); // "news/"
9
+ * folderPath("", ""); // ""
10
+ */
11
+ export declare const folderPath: (...segments: string[]) => string;
12
+ /**
13
+ * The root-relative URL of a folder path, under the website's base URL (see baseUrlOf).
14
+ *
15
+ * @example
16
+ * folderUrl("news/"); // "/news/"
17
+ * folderUrl(""); // "/"
18
+ * folderUrl("news/", "/edaha.md"); // "/edaha.md/news/"
19
+ */
20
+ export declare const folderUrl: (folder: string, baseUrl?: string) => string;
21
+ /**
22
+ * The URL path a website lives under: its absolute URL's path, without a trailing slash, or "" at a domain's root.
23
+ * Every URL in its pages starts with it, e.g. for a website in a sub-folder like a GitHub Pages project site.
24
+ *
25
+ * @example
26
+ * baseUrlOf("https://lvl99.github.io/edaha.md"); // "/edaha.md"
27
+ * baseUrlOf("https://example.com/"); // ""
28
+ */
29
+ export declare const baseUrlOf: (siteUrl: string) => string;
30
+ /**
31
+ * Check article types' URL paths: no two the same, and none clashing with the website's reserved paths at its root
32
+ * (`reservedPaths` in the config file). Throws an Error describing the first problem.
33
+ *
34
+ * @param sitePath - the site's URL path prefix
35
+ * @param reservedPaths - paths at the website's root that the site can't use, e.g. another app's routes
36
+ *
37
+ * @example
38
+ * checkTypePaths("", { app: defaultTypeConfig("app") }, ["app"]); // throws: type "app" can't use the path "app"
39
+ */
40
+ export declare const checkTypePaths: (sitePath: string, types: Record<string, ArticleTypeConfig>, reservedPaths?: readonly string[]) => void;
41
+ /**
42
+ * Why an article slug can't be used in a type, or undefined if it can. Slugs can't be the tag and author list folders
43
+ * or numbers (list pages), and at the website's root, its reserved paths or another type's path.
44
+ *
45
+ * @param reservedPaths - paths at the website's root that the site can't use (`reservedPaths` in the config file)
46
+ *
47
+ * @example
48
+ * slugProblem("tags", "news", "", types); // 'the slug "tags" is used by tag lists'
49
+ */
50
+ export declare const slugProblem: (slug: string, type: string, sitePath: string, types: Record<string, ArticleTypeConfig>, reservedPaths?: readonly string[]) => string | undefined;
@@ -0,0 +1,77 @@
1
+ /** Folders inside a type's URL path used by its tag and author lists */
2
+ export const RESERVED_SLUGS = ["tags", "authors"];
3
+ /**
4
+ * Join URL path segments into a folder path relative to the website's root, ignoring empty segments.
5
+ *
6
+ * @example
7
+ * folderPath("", "news"); // "news/"
8
+ * folderPath("", ""); // ""
9
+ */
10
+ export const folderPath = (...segments) => segments
11
+ .filter(Boolean)
12
+ .map((segment) => `${segment}/`)
13
+ .join("");
14
+ /**
15
+ * The root-relative URL of a folder path, under the website's base URL (see baseUrlOf).
16
+ *
17
+ * @example
18
+ * folderUrl("news/"); // "/news/"
19
+ * folderUrl(""); // "/"
20
+ * folderUrl("news/", "/edaha.md"); // "/edaha.md/news/"
21
+ */
22
+ export const folderUrl = (folder, baseUrl = "") => `${baseUrl}/${folder}`;
23
+ /**
24
+ * The URL path a website lives under: its absolute URL's path, without a trailing slash, or "" at a domain's root.
25
+ * Every URL in its pages starts with it, e.g. for a website in a sub-folder like a GitHub Pages project site.
26
+ *
27
+ * @example
28
+ * baseUrlOf("https://lvl99.github.io/edaha.md"); // "/edaha.md"
29
+ * baseUrlOf("https://example.com/"); // ""
30
+ */
31
+ export const baseUrlOf = (siteUrl) => new URL(siteUrl).pathname.replace(/\/+$/, "");
32
+ /**
33
+ * Check article types' URL paths: no two the same, and none clashing with the website's reserved paths at its root
34
+ * (`reservedPaths` in the config file). Throws an Error describing the first problem.
35
+ *
36
+ * @param sitePath - the site's URL path prefix
37
+ * @param reservedPaths - paths at the website's root that the site can't use, e.g. another app's routes
38
+ *
39
+ * @example
40
+ * checkTypePaths("", { app: defaultTypeConfig("app") }, ["app"]); // throws: type "app" can't use the path "app"
41
+ */
42
+ export const checkTypePaths = (sitePath, types, reservedPaths = []) => {
43
+ const seen = new Map();
44
+ for (const [type, { path }] of Object.entries(types)) {
45
+ const other = seen.get(path);
46
+ if (other !== undefined)
47
+ throw new Error(`types "${other}" and "${type}" have the same path "${path}"`);
48
+ seen.set(path, type);
49
+ if (!sitePath && reservedPaths.includes(path))
50
+ throw new Error(`type "${type}" can't use the path "${path}", which is reserved`);
51
+ }
52
+ };
53
+ /**
54
+ * Why an article slug can't be used in a type, or undefined if it can. Slugs can't be the tag and author list folders
55
+ * or numbers (list pages), and at the website's root, its reserved paths or another type's path.
56
+ *
57
+ * @param reservedPaths - paths at the website's root that the site can't use (`reservedPaths` in the config file)
58
+ *
59
+ * @example
60
+ * slugProblem("tags", "news", "", types); // 'the slug "tags" is used by tag lists'
61
+ */
62
+ export const slugProblem = (slug, type, sitePath, types, reservedPaths = []) => {
63
+ if (RESERVED_SLUGS.includes(slug))
64
+ return `the slug "${slug}" is used by ${slug === "tags" ? "tag" : "author"} lists`;
65
+ if (/^\d+$/.test(slug))
66
+ return `the slug "${slug}" is used by list pages`;
67
+ // A type that isn't configured is at its own name
68
+ const atRoot = !sitePath && !(types[type]?.path ?? type);
69
+ if (atRoot && reservedPaths.includes(slug))
70
+ return `the slug "${slug}" is reserved`;
71
+ if (atRoot) {
72
+ const other = Object.entries(types).find(([name, config]) => name !== type && config.path === slug);
73
+ if (other)
74
+ return `the slug "${slug}" is the path of type "${other[0]}"`;
75
+ }
76
+ return undefined;
77
+ };
@@ -0,0 +1,8 @@
1
+ export { buildSite, DEFAULT_SITE_URL, type BuildOptions, type BuildResult, } from "./generator/build/index.ts";
2
+ export { parseConfig, type ArticleTypeConfig, type EdahaConfig, type GenerateConfig, } from "./generator/config/index.ts";
3
+ export { CONFIG_FILES, findConfigFile, loadSiteConfig, readConfigFile, type SiteConfig, type SiteConfigOptions, } from "./generator/configFile/index.ts";
4
+ export { REQUIRED_TEMPLATES } from "./generator/templates/index.ts";
5
+ export type * from "./generator/types/index.ts";
6
+ export { EMBED_BLOCK, EmbedResolver, embedBlock, isEmbedPlugin, loadPlugins, validationErrors, type EmbedBuildRenderers, type EmbedContext, type EmbedEditorRenderers, type EmbedPageContext, type EmbedPageParts, type EmbedPlugin, type EmbedRenderContext, type EmbedSources, } from "./embeds/index.ts";
7
+ export { EDITOR_PACKAGE, EDITOR_PORT, loadEditor, runCli, type CliContext, type EditorOptions, type RunningEditor, type StartEditor, } from "./cli/index.ts";
8
+ export { THEME_DIR } from "./theme/index.ts";
package/dist/index.js ADDED
@@ -0,0 +1,9 @@
1
+ // edaha.md's public API: build a site from Markdown articles, run the `edaha` command, and write embed plugins. The
2
+ // article editor is in its own package, @lvl99dotcom/edaha-editor.
3
+ export { buildSite, DEFAULT_SITE_URL, } from "./generator/build/index.js";
4
+ export { parseConfig, } from "./generator/config/index.js";
5
+ export { CONFIG_FILES, findConfigFile, loadSiteConfig, readConfigFile, } from "./generator/configFile/index.js";
6
+ export { REQUIRED_TEMPLATES } from "./generator/templates/index.js";
7
+ export { EMBED_BLOCK, EmbedResolver, embedBlock, isEmbedPlugin, loadPlugins, validationErrors, } from "./embeds/index.js";
8
+ export { EDITOR_PACKAGE, EDITOR_PORT, loadEditor, runCli, } from "./cli/index.js";
9
+ export { THEME_DIR } from "./theme/index.js";
@@ -0,0 +1,8 @@
1
+ /**
2
+ * edaha.md's default theme folder, which holds `templates/` and `static/`. A site's own `templates/` and `static/`
3
+ * override its files one by one. The path is the same from `src/` and from the published `dist/`.
4
+ *
5
+ * @example
6
+ * join(THEME_DIR, "templates"); // ".../node_modules/@lvl99dotcom/edaha.md/theme/templates"
7
+ */
8
+ export declare const THEME_DIR: string;
@@ -0,0 +1,9 @@
1
+ import { fileURLToPath } from "node:url";
2
+ /**
3
+ * edaha.md's default theme folder, which holds `templates/` and `static/`. A site's own `templates/` and `static/`
4
+ * override its files one by one. The path is the same from `src/` and from the published `dist/`.
5
+ *
6
+ * @example
7
+ * join(THEME_DIR, "templates"); // ".../node_modules/@lvl99dotcom/edaha.md/theme/templates"
8
+ */
9
+ export const THEME_DIR = fileURLToPath(new URL("../../theme", import.meta.url));
package/package.json CHANGED
@@ -1,6 +1,67 @@
1
1
  {
2
2
  "name": "@lvl99dotcom/edaha.md",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "Static site generator using markdown.",
5
+ "keywords": [
6
+ "blog",
7
+ "static-site-generator",
8
+ "markdown",
9
+ "nunjucks",
10
+ "rss"
11
+ ],
12
+ "author": "Matt Scheurich <matt@lvl99.com>",
13
+ "license": "Apache-2.0",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/lvl99/edaha.md.git",
17
+ "directory": "packages/edaha"
18
+ },
19
+ "homepage": "https://github.com/lvl99/edaha.md#readme",
20
+ "bugs": "https://github.com/lvl99/edaha.md/issues",
21
+ "type": "module",
22
+ "engines": {
23
+ "node": ">=22"
24
+ },
25
+ "bin": {
26
+ "edaha": "./dist/cli/bin.js"
27
+ },
28
+ "exports": {
29
+ ".": {
30
+ "types": "./dist/index.d.ts",
31
+ "default": "./dist/index.js"
32
+ },
33
+ "./package.json": "./package.json",
34
+ "./*": {
35
+ "types": "./dist/*/index.d.ts",
36
+ "default": "./dist/*/index.js"
37
+ }
38
+ },
39
+ "files": [
40
+ "dist",
41
+ "theme",
42
+ "README.md",
43
+ "LICENSE"
44
+ ],
45
+ "publishConfig": {
46
+ "access": "public"
47
+ },
48
+ "dependencies": {
49
+ "ajv": "^8.20.0",
50
+ "ajv-formats": "^3.0.1",
51
+ "markdown-it": "^15.0.3",
52
+ "mime-types": "^3.0.2",
53
+ "nunjucks": "^3.2.4",
54
+ "yaml": "^2.9.1"
55
+ },
56
+ "peerDependencies": {
57
+ "@lvl99dotcom/edaha-editor": "^0.2.0"
58
+ },
59
+ "peerDependenciesMeta": {
60
+ "@lvl99dotcom/edaha-editor": {
61
+ "optional": true
62
+ }
63
+ },
64
+ "scripts": {
65
+ "build": "node scripts/build.ts"
66
+ }
6
67
  }