@mastrojs/markdown 0.0.0-stage → 0.2.3

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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Mastro
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,97 @@
1
- # Temporary Holding Version
1
+ # @mastrojs/markdown
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A few simple helper functions to generate HTML from markdown. Just enough to get you started with markdown with [Mastro](https://mastrojs.github.io/).
4
+
5
+ By default, it uses `micromark` with `micromark-extension-gfm` under the hood.
6
+
7
+ Validate YAML frontmatter by bringing your own [Standard Schema](https://standardschema.dev/)-compliant validation library (e.g. [Zod](https://zod.dev), [Valibot](https://valibot.dev) or [validate.js](https://github.com/jakelazaroff/validate.js)).
8
+
9
+
10
+ ## Install
11
+
12
+ The easiest way to get started is to [install Mastro](https://mastrojs.github.io/#powerful-for-experienced-developers) and select the "blog" template. Alternatively:
13
+
14
+ pnpm add @mastrojs/markdown
15
+
16
+
17
+ ## Usage
18
+
19
+ ```ts
20
+ import { renderToString } from "@mastrojs";
21
+ import { markdownToHtml } from "@mastrojs/markdown";
22
+
23
+ const { content, meta } = await markdownToHtml(`
24
+ ---
25
+ title: my title
26
+ ---
27
+
28
+ hi *there*
29
+ `);
30
+
31
+ const htmlStr = await renderToString(content);
32
+ ```
33
+
34
+ In addition to `markdownToHtml(inputStr, opts)`, there is:
35
+
36
+ - `readMarkdownFile(filePath, opts)`
37
+ - `readMarkdownFiles(globPattern, opts)`
38
+ - `serveMarkdownFolder(opts, renderFn)`
39
+
40
+ See the [source](src/markdown.ts) for their documentation.
41
+
42
+ For a tutorial, read the chapter [A static blog from markdown files](https://mastrojs.github.io/guide/static-blog-from-markdown-files/) in the Mastro Guide.
43
+
44
+ ### Options
45
+
46
+ #### Parse
47
+
48
+ The `parse` option can either take an options object, or a parse function. To supply a [Micromark options object](https://github.com/micromark/micromark/blob/main/packages/micromark/readme.md#options):
49
+
50
+ ```ts
51
+ const { content, meta } = markdownToHtml(input, { parse: { allowDangerousHtml: true } });
52
+ ```
53
+
54
+ Micromark is fairly basic (e.g. no server-side syntax highlighting of code blocks, but you can use e.g. [microlighter](https://davatron5000.github.io/microlighter/) or [syntaxp](https://github.com/j9t/syntaxp)). If you want a more feature-rich markdown engine, supply a custom markdown-to-HTML function to `parse`, which will be called with the markdown body (YAML frontmatter already stripped).
55
+
56
+ For example using [markdown-it](https://github.com/markdown-it/markdown-it):
57
+
58
+ ```ts
59
+ import { markdownToHtml } from "@mastrojs/markdown";
60
+ import markdownIt from "markdown-it";
61
+
62
+ const { content, meta } = markdownToHtml(input, { parse: markdownIt.render });
63
+ ```
64
+
65
+ Or using [remark-rehype](https://github.com/remarkjs/remark-rehype):
66
+
67
+ ```ts
68
+ import { markdownToHtml } from "@mastrojs/markdown";
69
+ import { unified } from "unified";
70
+ import remarkParse from "remark-parse";
71
+ import remarkRehype from "remark-rehype";
72
+ import rehypeHighlight from "rehype-highlight";
73
+ import rehypeStringify from "rehype-stringify";
74
+
75
+ const parse = async (markdownText: string) =>
76
+ String(
77
+ await unified()
78
+ .use(remarkParse)
79
+ .use(remarkRehype)
80
+ .use(rehypeHighlight)
81
+ .use(rehypeStringify)
82
+ .process(markdownText)
83
+ );
84
+ const { content, meta } = markdownToHtml(input, { parse });
85
+ ```
86
+
87
+ #### Schema
88
+
89
+ The default TypeScript type for the YAML metadata is `Record<string, unknown>`. You can override that with e.g. `readMarkdownFile<{title: string}>("post.md")`. But to actually verify the metadata is correct, you should use a schema. For example using [validate.js](https://github.com/jakelazaroff/validate.js):
90
+
91
+ ```ts
92
+ import { object, string } from "./validate.js";
93
+ const schema = object({
94
+ title: string,
95
+ });
96
+ const { content, meta } = await markdownToHtml(input, { schema }),
97
+ ```
@@ -0,0 +1,103 @@
1
+ /**
2
+ * Module with helper function to generate HTML from markdown.
3
+ * By default, it uses `micromark` with `micromark-extension-gfm`.
4
+ * @module
5
+ */
6
+ import { type Html } from "@mastrojs/mastro";
7
+ import { type Options } from "micromark";
8
+ import type { StandardSchemaV1 } from "./standard-schema.ts";
9
+ export type { Options };
10
+ /**
11
+ * Return type containing the generated HTML and the YAML metadata.
12
+ */
13
+ export interface Md<M extends DefaultM = DefaultM> {
14
+ content: Html;
15
+ meta: M;
16
+ }
17
+ /**
18
+ * [Micromark options](https://github.com/micromark/micromark/blob/main/packages/micromark/readme.md#options)
19
+ * or a custom markdown-to-HTML function to be used instead of the default `micromark` with GFM.
20
+ */
21
+ export type Parse = Options | ((md: string) => string | Promise<string>);
22
+ /**
23
+ * A [Standard Schema](https://standardschema.dev/) to validate YAML frontmatter metadata
24
+ */
25
+ export type MetaSchema<M> = StandardSchemaV1<unknown, M>;
26
+ /**
27
+ * If no schema is provided, we fall back to this type for the metadata.
28
+ *
29
+ * We use `unknown` instead of `string | number | boolean | Date | null | undefined>`
30
+ * because you could have deeply nested objects or arrays.
31
+ */
32
+ export type DefaultM = Record<string, unknown>;
33
+ /**
34
+ * Convert a markdown string (incl. YAML frontmatter metadata) to an `Html` node
35
+ * and an object for the metadata. Like the other exported functions, it optionally takes a
36
+ * `schema`, and a `mdToHtml` function to use instead of the default micromark with GFM.
37
+ */
38
+ export declare const markdownToHtml: <M extends DefaultM = DefaultM>(md: string, opts?: {
39
+ parse?: Parse;
40
+ schema?: MetaSchema<M>;
41
+ }) => Promise<Md<M>>;
42
+ /**
43
+ * Convert a markdown string with no YAML frontmatter to an `Html` node
44
+ */
45
+ export declare const markdownPlainToHtml: (md: string, opts?: Parse) => Html;
46
+ /**
47
+ * Read a file from the local filesystem and convert its markdown contents
48
+ * to an `Html` node and an object for the metadata.
49
+ */
50
+ export declare const readMarkdownFile: <M extends DefaultM = DefaultM>(path: string, opts?: {
51
+ parse?: Parse;
52
+ schema?: MetaSchema<M>;
53
+ }) => Promise<Md<M>>;
54
+ /**
55
+ * Read all files from the local filesystem that match the supplied glob pattern, (via `findFiles`)
56
+ * and convert their markdown contents to `Html` nodes and objects for their metadata.
57
+ * Filepath is in `path`, filename without suffix in `slug`.
58
+ */
59
+ export declare const readMarkdownFiles: <M extends DefaultM = DefaultM>(pattern: string, opts?: {
60
+ parse?: Parse;
61
+ schema?: MetaSchema<M>;
62
+ }) => Promise<Array<Md<M> & {
63
+ path: string;
64
+ slug: string;
65
+ }>>;
66
+ /**
67
+ * Serve a folder on the local filesystem containing potentially deeply nested markdown files,
68
+ * and convert them to `Html` and metadata.
69
+ *
70
+ * Place the following in e.g. `routes/[...slug].server.js`
71
+ *
72
+ * ```ts
73
+ * import { serveMarkdownFolder } from "@mastrojs/markdown";
74
+ * import { html, htmlToResponse } from "@mastrojs/mastro";
75
+ *
76
+ * export const { GET, getStaticPaths } = serveMarkdownFolder(
77
+ * {
78
+ * folder: "data",
79
+ * },
80
+ * ({ content, meta }, req) => {
81
+ * return htmlToResponse(html`
82
+ * <!DOCTYPE html>
83
+ * <title>${meta.title}</title>
84
+ * <main>${content}</main>
85
+ * `);
86
+ * }
87
+ * }
88
+ * ```
89
+ *
90
+ * Then, make sure to access the route with URLs having a trailing slash.
91
+ *
92
+ * With the above example, the URL `/blog/hello-world/` will read out the file
93
+ * `data/blog/hello-world.md`, and the URL `/` will read out the file `data/index.md`.
94
+ */
95
+ export declare const serveMarkdownFolder: <M extends DefaultM = DefaultM>(opts: {
96
+ folder: string;
97
+ parse?: Parse;
98
+ schema?: MetaSchema<M>;
99
+ }, renderFn: (convertedMd: Md<M>, req: Request) => Promise<Response> | Response) => {
100
+ GET: (req: Request) => Promise<Response>;
101
+ getStaticPaths: () => Promise<string[]>;
102
+ };
103
+ //# sourceMappingURL=markdown.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAa,KAAK,IAAI,EAAiC,MAAM,kBAAkB,CAAC;AAEvF,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,EAAE,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC;CACT;AAED;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,QAAQ,GAAG,QAAQ,MACtD,MAAM,SACH;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,KAC/C,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAsB,CAAC;AAEvC;;GAEG;AACH,eAAO,MAAM,mBAAmB,OAAQ,MAAM,SAAS,KAAK,KAAG,IACgC,CAAC;AAEhG;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAU,CAAC,SAAS,QAAQ,GAAG,QAAQ,QAC5D,MAAM,SACL;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,KAC/C,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAkD,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAU,CAAC,SAAS,QAAQ,GAAG,QAAQ,WAC1D,MAAM,SACR;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,KAC/C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE,CAAC,CAUxD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,QAAQ,GAAG,QAAQ,QACzD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,YACrD,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,KAC3E;IACD,GAAG,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAsCzC,CAAC"}
@@ -0,0 +1,152 @@
1
+ /**
2
+ * Module with helper function to generate HTML from markdown.
3
+ * By default, it uses `micromark` with `micromark-extension-gfm`.
4
+ * @module
5
+ */
6
+ import { sep } from "node:path";
7
+ import { findFiles, readTextFile, unsafeInnerHtml } from "@mastrojs/mastro";
8
+ import { parse } from "yaml";
9
+ import { micromark } from "micromark";
10
+ import { gfm, gfmHtml } from "micromark-extension-gfm";
11
+ /**
12
+ * Convert a markdown string (incl. YAML frontmatter metadata) to an `Html` node
13
+ * and an object for the metadata. Like the other exported functions, it optionally takes a
14
+ * `schema`, and a `mdToHtml` function to use instead of the default micromark with GFM.
15
+ */
16
+ export const markdownToHtml = (md, opts) => parseMd(md, opts);
17
+ /**
18
+ * Convert a markdown string with no YAML frontmatter to an `Html` node
19
+ */
20
+ export const markdownPlainToHtml = (md, opts) => unsafeInnerHtml(micromark(md, { extensions: [gfm()], htmlExtensions: [gfmHtml()], ...opts }));
21
+ /**
22
+ * Read a file from the local filesystem and convert its markdown contents
23
+ * to an `Html` node and an object for the metadata.
24
+ */
25
+ export const readMarkdownFile = async (path, opts) => parseMd(await readTextFile(path), opts, path);
26
+ /**
27
+ * Read all files from the local filesystem that match the supplied glob pattern, (via `findFiles`)
28
+ * and convert their markdown contents to `Html` nodes and objects for their metadata.
29
+ * Filepath is in `path`, filename without suffix in `slug`.
30
+ */
31
+ export const readMarkdownFiles = async (pattern, opts) => {
32
+ const paths = await findFiles(pattern);
33
+ return Promise.all(paths.map(async (path) => {
34
+ const file = await readTextFile(path);
35
+ const md = await parseMd(file, opts, path);
36
+ const slug = path.split(sep).at(-1)?.split(".").at(0) || "";
37
+ return { ...md, path, slug };
38
+ }));
39
+ };
40
+ /**
41
+ * Serve a folder on the local filesystem containing potentially deeply nested markdown files,
42
+ * and convert them to `Html` and metadata.
43
+ *
44
+ * Place the following in e.g. `routes/[...slug].server.js`
45
+ *
46
+ * ```ts
47
+ * import { serveMarkdownFolder } from "@mastrojs/markdown";
48
+ * import { html, htmlToResponse } from "@mastrojs/mastro";
49
+ *
50
+ * export const { GET, getStaticPaths } = serveMarkdownFolder(
51
+ * {
52
+ * folder: "data",
53
+ * },
54
+ * ({ content, meta }, req) => {
55
+ * return htmlToResponse(html`
56
+ * <!DOCTYPE html>
57
+ * <title>${meta.title}</title>
58
+ * <main>${content}</main>
59
+ * `);
60
+ * }
61
+ * }
62
+ * ```
63
+ *
64
+ * Then, make sure to access the route with URLs having a trailing slash.
65
+ *
66
+ * With the above example, the URL `/blog/hello-world/` will read out the file
67
+ * `data/blog/hello-world.md`, and the URL `/` will read out the file `data/index.md`.
68
+ */
69
+ export const serveMarkdownFolder = (opts, renderFn) => {
70
+ const { folder } = opts;
71
+ const GET = async (req) => {
72
+ let { pathname } = new URL(req.url);
73
+ if (!pathname.endsWith("/")) {
74
+ const err = Error("NotFound: path must end with a /");
75
+ err.name = "NotFound";
76
+ throw err;
77
+ }
78
+ pathname = pathname.slice(0, -1);
79
+ pathname = pathname.startsWith("/") ? pathname : "/" + pathname;
80
+ let filePath = folder + pathname + ".md";
81
+ let txt;
82
+ try {
83
+ txt = await readTextFile(filePath);
84
+ }
85
+ catch (e) {
86
+ if (e instanceof Error && "code" in e && e.code === "ENOENT") {
87
+ filePath = folder + pathname + "/index.md";
88
+ txt = await readTextFile(filePath);
89
+ }
90
+ else {
91
+ throw e;
92
+ }
93
+ }
94
+ const converted = await parseMd(txt, opts, filePath);
95
+ return renderFn(converted, req);
96
+ };
97
+ const getStaticPaths = async () => {
98
+ const files = await findFiles(folder + "/**/*.md");
99
+ const l = folder.length;
100
+ return files.map((file) => file.endsWith("/index.md") ? file.slice(l, -8) : file.slice(l, -3) + "/");
101
+ };
102
+ return { GET, getStaticPaths };
103
+ };
104
+ const parseMd = async (md, opts, filePath) => {
105
+ const { parse, schema } = opts || {};
106
+ const { body, meta } = await parseYamlFrontmatter(md, schema, filePath);
107
+ const content = typeof parse === "function"
108
+ ? unsafeInnerHtml(await parse(body))
109
+ : markdownPlainToHtml(body, parse);
110
+ return { content, meta };
111
+ };
112
+ /**
113
+ * Converts a string possibly containing yaml frontmatter to a `{ meta, body }` object.
114
+ *
115
+ * - `meta` is an object with the parsed yaml.
116
+ * - `body` is a string with the rest of the input.
117
+ */
118
+ const parseYamlFrontmatter = async (md, schema, filePath) => {
119
+ let meta = {};
120
+ let body = md;
121
+ const results = yamlFrontRe.exec(md);
122
+ try {
123
+ const yaml = results?.[2];
124
+ if (yaml) {
125
+ const metaObj = parse(yaml, { schema: "core" });
126
+ if (metaObj && typeof metaObj === "object" && !(metaObj instanceof Array)) {
127
+ body = results?.[3] || "";
128
+ meta = metaObj;
129
+ }
130
+ }
131
+ }
132
+ catch (e) {
133
+ const msg = `Could not parse YAML in ${filePath}: ${e}`;
134
+ if (schema) {
135
+ throw Error(msg, { cause: e });
136
+ }
137
+ else {
138
+ console.warn(msg);
139
+ }
140
+ }
141
+ if (schema) {
142
+ const res = await schema["~standard"].validate(meta);
143
+ if (res.issues) {
144
+ const issues = res.issues.map((i) => `${i.message} (${i.path})`);
145
+ throw Error(`YAML in ${filePath} did not validate:\n ${issues.join("\n ")}`);
146
+ }
147
+ meta = res.value;
148
+ }
149
+ return { meta, body };
150
+ };
151
+ // from https://github.com/dworthen/js-yaml-front-matter/blob/master/src/index.js#L14
152
+ const yamlFrontRe = /^(-{3}(?:\n|\r)([\w\W]+?)(?:\n|\r)-{3})?([\w\W]*)*/;
@@ -0,0 +1,60 @@
1
+ /** The Standard Schema interface. */
2
+ export interface StandardSchemaV1<Input = unknown, Output = Input> {
3
+ /** The Standard Schema properties. */
4
+ readonly "~standard": StandardSchemaV1.Props<Input, Output>;
5
+ }
6
+ export declare namespace StandardSchemaV1 {
7
+ /** The Standard Schema properties interface. */
8
+ interface Props<Input = unknown, Output = Input> {
9
+ /** The version number of the standard. */
10
+ readonly version: 1;
11
+ /** The vendor name of the schema library. */
12
+ readonly vendor: string;
13
+ /** Validates unknown input values. */
14
+ readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
15
+ /** Inferred types associated with the schema. */
16
+ readonly types?: Types<Input, Output> | undefined;
17
+ }
18
+ /** The result interface of the validate function. */
19
+ type Result<Output> = SuccessResult<Output> | FailureResult;
20
+ /** The result interface if validation succeeds. */
21
+ interface SuccessResult<Output> {
22
+ /** The typed output value. */
23
+ readonly value: Output;
24
+ /** A falsy value for `issues` indicates success. */
25
+ readonly issues?: undefined;
26
+ }
27
+ interface Options {
28
+ /** Explicit support for additional vendor-specific parameters, if needed. */
29
+ readonly libraryOptions?: Record<string, unknown> | undefined;
30
+ }
31
+ /** The result interface if validation fails. */
32
+ interface FailureResult {
33
+ /** The issues of failed validation. */
34
+ readonly issues: ReadonlyArray<Issue>;
35
+ }
36
+ /** The issue interface of the failure output. */
37
+ interface Issue {
38
+ /** The error message of the issue. */
39
+ readonly message: string;
40
+ /** The path of the issue, if any. */
41
+ readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
42
+ }
43
+ /** The path segment interface of the issue. */
44
+ interface PathSegment {
45
+ /** The key representing a path segment. */
46
+ readonly key: PropertyKey;
47
+ }
48
+ /** The Standard Schema types interface. */
49
+ interface Types<Input = unknown, Output = Input> {
50
+ /** The input type of the schema. */
51
+ readonly input: Input;
52
+ /** The output type of the schema. */
53
+ readonly output: Output;
54
+ }
55
+ /** Infers the input type of a Standard Schema. */
56
+ type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
57
+ /** Infers the output type of a Standard Schema. */
58
+ type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
59
+ }
60
+ //# sourceMappingURL=standard-schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"standard-schema.d.ts","sourceRoot":"","sources":["../src/standard-schema.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CAC7D;AAED,MAAM,CAAC,OAAO,WAAW,gBAAgB,CAAC;IACxC,gDAAgD;IAChD,UAAiB,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;QACpD,0CAA0C;QAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,6CAA6C;QAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,sCAAsC;QACtC,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,gBAAgB,CAAC,OAAO,GAAG,SAAS,KAC3C,MAAM,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9C,iDAAiD;QACjD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;KACnD;IAED,qDAAqD;IACrD,KAAY,MAAM,CAAC,MAAM,IAAI,aAAa,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC;IAEnE,mDAAmD;IACnD,UAAiB,aAAa,CAAC,MAAM;QACnC,8BAA8B;QAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,oDAAoD;QACpD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;KAC7B;IAED,UAAiB,OAAO;QACtB,6EAA6E;QAC7E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;KAC/D;IAED,gDAAgD;IAChD,UAAiB,aAAa;QAC5B,uCAAuC;QACvC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;KACvC;IAED,iDAAiD;IACjD,UAAiB,KAAK;QACpB,sCAAsC;QACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,qCAAqC;QACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,GAAG,WAAW,CAAC,GAAG,SAAS,CAAC;KACtE;IAED,+CAA+C;IAC/C,UAAiB,WAAW;QAC1B,2CAA2C;QAC3C,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;KAC3B;IAED,2CAA2C;IAC3C,UAAiB,KAAK,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;QACpD,oCAAoC;QACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QACtB,qCAAqC;QACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB;IAED,kDAAkD;IAClD,KAAY,UAAU,CAAC,MAAM,SAAS,gBAAgB,IAAI,WAAW,CACnE,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAC7B,CAAC,OAAO,CAAC,CAAC;IAEX,mDAAmD;IACnD,KAAY,WAAW,CAAC,MAAM,SAAS,gBAAgB,IAAI,WAAW,CACpE,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAC7B,CAAC,QAAQ,CAAC,CAAC;CACb"}
@@ -0,0 +1 @@
1
+ export {};
package/package.json CHANGED
@@ -1,6 +1,42 @@
1
1
  {
2
2
  "name": "@mastrojs/markdown",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.3",
4
+ "description": "Generate HTML from Markdown with Mastro.",
5
+ "homepage": "https://github.com/mastrojs/mastro/tree/main/libs/markdown",
6
+ "bugs": "https://github.com/mastrojs/mastro/issues",
7
+ "license": "MIT",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/mastrojs/mastro.git",
11
+ "directory": "libs/markdown"
12
+ },
13
+ "files": [
14
+ "README.md",
15
+ "dist",
16
+ "src",
17
+ "!**/*.test.*",
18
+ "!**/*.bench.*"
19
+ ],
20
+ "type": "module",
21
+ "exports": {
22
+ ".": {
23
+ "types": "./dist/markdown.d.ts",
24
+ "default": "./dist/markdown.js"
25
+ }
26
+ },
27
+ "publishConfig": {
28
+ "access": "public",
29
+ "directory": "dist",
30
+ "linkDirectory": false
31
+ },
32
+ "dependencies": {
33
+ "@mastrojs/mastro": "^0",
34
+ "yaml": "^2.9.1",
35
+ "micromark": "^4.0.3",
36
+ "micromark-extension-gfm": "^3.0.0"
37
+ },
38
+ "scripts": {
39
+ "check": "tsc --noEmit",
40
+ "test": "node --test 'src/**/*.test.ts'"
41
+ }
6
42
  }
@@ -0,0 +1,220 @@
1
+ /**
2
+ * Module with helper function to generate HTML from markdown.
3
+ * By default, it uses `micromark` with `micromark-extension-gfm`.
4
+ * @module
5
+ */
6
+
7
+ import { sep } from "node:path";
8
+
9
+ import { findFiles, type Html, readTextFile, unsafeInnerHtml } from "@mastrojs/mastro";
10
+ import { parse } from "yaml";
11
+ import { micromark, type Options } from "micromark";
12
+ import { gfm, gfmHtml } from "micromark-extension-gfm";
13
+ import type { StandardSchemaV1 } from "./standard-schema.ts";
14
+
15
+ export type { Options };
16
+
17
+ /**
18
+ * Return type containing the generated HTML and the YAML metadata.
19
+ */
20
+ export interface Md<M extends DefaultM = DefaultM> {
21
+ content: Html;
22
+ meta: M;
23
+ }
24
+
25
+ /**
26
+ * [Micromark options](https://github.com/micromark/micromark/blob/main/packages/micromark/readme.md#options)
27
+ * or a custom markdown-to-HTML function to be used instead of the default `micromark` with GFM.
28
+ */
29
+ export type Parse = Options | ((md: string) => string | Promise<string>);
30
+
31
+ /**
32
+ * A [Standard Schema](https://standardschema.dev/) to validate YAML frontmatter metadata
33
+ */
34
+ export type MetaSchema<M> = StandardSchemaV1<unknown, M>;
35
+
36
+ /**
37
+ * If no schema is provided, we fall back to this type for the metadata.
38
+ *
39
+ * We use `unknown` instead of `string | number | boolean | Date | null | undefined>`
40
+ * because you could have deeply nested objects or arrays.
41
+ */
42
+ export type DefaultM = Record<string, unknown>;
43
+
44
+ /**
45
+ * Convert a markdown string (incl. YAML frontmatter metadata) to an `Html` node
46
+ * and an object for the metadata. Like the other exported functions, it optionally takes a
47
+ * `schema`, and a `mdToHtml` function to use instead of the default micromark with GFM.
48
+ */
49
+ export const markdownToHtml = <M extends DefaultM = DefaultM>(
50
+ md: string,
51
+ opts?: { parse?: Parse; schema?: MetaSchema<M> },
52
+ ): Promise<Md<M>> => parseMd(md, opts);
53
+
54
+ /**
55
+ * Convert a markdown string with no YAML frontmatter to an `Html` node
56
+ */
57
+ export const markdownPlainToHtml = (md: string, opts?: Parse): Html =>
58
+ unsafeInnerHtml(micromark(md, { extensions: [gfm()], htmlExtensions: [gfmHtml()], ...opts }));
59
+
60
+ /**
61
+ * Read a file from the local filesystem and convert its markdown contents
62
+ * to an `Html` node and an object for the metadata.
63
+ */
64
+ export const readMarkdownFile = async <M extends DefaultM = DefaultM>(
65
+ path: string,
66
+ opts?: { parse?: Parse; schema?: MetaSchema<M> },
67
+ ): Promise<Md<M>> => parseMd(await readTextFile(path), opts, path);
68
+
69
+ /**
70
+ * Read all files from the local filesystem that match the supplied glob pattern, (via `findFiles`)
71
+ * and convert their markdown contents to `Html` nodes and objects for their metadata.
72
+ * Filepath is in `path`, filename without suffix in `slug`.
73
+ */
74
+ export const readMarkdownFiles = async <M extends DefaultM = DefaultM>(
75
+ pattern: string,
76
+ opts?: { parse?: Parse; schema?: MetaSchema<M> },
77
+ ): Promise<Array<Md<M> & { path: string, slug: string; }>> => {
78
+ const paths = await findFiles(pattern);
79
+ return Promise.all(
80
+ paths.map(async (path) => {
81
+ const file = await readTextFile(path);
82
+ const md = await parseMd(file, opts, path);
83
+ const slug = path.split(sep).at(-1)?.split(".").at(0) || "";
84
+ return { ...md, path, slug };
85
+ }),
86
+ );
87
+ };
88
+
89
+ /**
90
+ * Serve a folder on the local filesystem containing potentially deeply nested markdown files,
91
+ * and convert them to `Html` and metadata.
92
+ *
93
+ * Place the following in e.g. `routes/[...slug].server.js`
94
+ *
95
+ * ```ts
96
+ * import { serveMarkdownFolder } from "@mastrojs/markdown";
97
+ * import { html, htmlToResponse } from "@mastrojs/mastro";
98
+ *
99
+ * export const { GET, getStaticPaths } = serveMarkdownFolder(
100
+ * {
101
+ * folder: "data",
102
+ * },
103
+ * ({ content, meta }, req) => {
104
+ * return htmlToResponse(html`
105
+ * <!DOCTYPE html>
106
+ * <title>${meta.title}</title>
107
+ * <main>${content}</main>
108
+ * `);
109
+ * }
110
+ * }
111
+ * ```
112
+ *
113
+ * Then, make sure to access the route with URLs having a trailing slash.
114
+ *
115
+ * With the above example, the URL `/blog/hello-world/` will read out the file
116
+ * `data/blog/hello-world.md`, and the URL `/` will read out the file `data/index.md`.
117
+ */
118
+ export const serveMarkdownFolder = <M extends DefaultM = DefaultM>(
119
+ opts: { folder: string; parse?: Parse; schema?: MetaSchema<M> },
120
+ renderFn: (convertedMd: Md<M>, req: Request) => Promise<Response> | Response,
121
+ ): {
122
+ GET: (req: Request) => Promise<Response>;
123
+ getStaticPaths: () => Promise<string[]>;
124
+ } => {
125
+ const { folder } = opts;
126
+
127
+ const GET = async (req: Request) => {
128
+ let { pathname } = new URL(req.url);
129
+ if (!pathname.endsWith("/")) {
130
+ const err = Error("NotFound: path must end with a /");
131
+ err.name = "NotFound";
132
+ throw err;
133
+ }
134
+ pathname = pathname.slice(0, -1);
135
+ pathname = pathname.startsWith("/") ? pathname : "/" + pathname;
136
+ let filePath = folder + pathname + ".md";
137
+ let txt;
138
+ try {
139
+ txt = await readTextFile(filePath);
140
+ } catch (e: unknown) {
141
+ if (e instanceof Error && "code" in e && e.code === "ENOENT") {
142
+ filePath = folder + pathname + "/index.md";
143
+ txt = await readTextFile(filePath);
144
+ } else {
145
+ throw e;
146
+ }
147
+ }
148
+ const converted = await parseMd(txt, opts, filePath);
149
+ return renderFn(converted, req);
150
+ };
151
+
152
+ const getStaticPaths = async () => {
153
+ const files = await findFiles(folder + "/**/*.md");
154
+ const l = folder.length;
155
+ return files.map((file) =>
156
+ file.endsWith("/index.md") ? file.slice(l, -8) : file.slice(l, -3) + "/"
157
+ );
158
+ };
159
+
160
+ return { GET, getStaticPaths };
161
+ };
162
+
163
+ const parseMd = async <M extends DefaultM = DefaultM>(
164
+ md: string,
165
+ opts?: { parse?: Parse; schema?: MetaSchema<M> },
166
+ filePath?: string,
167
+ ) => {
168
+ const { parse, schema } = opts || {};
169
+ const { body, meta } = await parseYamlFrontmatter(md, schema, filePath);
170
+ const content = typeof parse === "function"
171
+ ? unsafeInnerHtml(await parse(body))
172
+ : markdownPlainToHtml(body, parse);
173
+ return { content, meta };
174
+ };
175
+
176
+ /**
177
+ * Converts a string possibly containing yaml frontmatter to a `{ meta, body }` object.
178
+ *
179
+ * - `meta` is an object with the parsed yaml.
180
+ * - `body` is a string with the rest of the input.
181
+ */
182
+ const parseYamlFrontmatter = async <M extends DefaultM>(
183
+ md: string,
184
+ schema?: MetaSchema<M>,
185
+ filePath?: string,
186
+ ): Promise<{ body: string; meta: M }> => {
187
+ let meta = {} as M;
188
+ let body = md;
189
+ const results = yamlFrontRe.exec(md);
190
+ try {
191
+ const yaml = results?.[2];
192
+ if (yaml) {
193
+ const metaObj = parse(yaml, { schema: "core" });
194
+ if (metaObj && typeof metaObj === "object" && !(metaObj instanceof Array)) {
195
+ body = results?.[3] || "";
196
+ meta = metaObj as M;
197
+ }
198
+ }
199
+ } catch (e) {
200
+ const msg = `Could not parse YAML in ${filePath}: ${e}`;
201
+ if (schema) {
202
+ throw Error(msg, { cause: e });
203
+ } else {
204
+ console.warn(msg);
205
+ }
206
+ }
207
+
208
+ if (schema) {
209
+ const res = await schema["~standard"].validate(meta);
210
+ if (res.issues) {
211
+ const issues = res.issues.map((i) => `${i.message} (${i.path})`);
212
+ throw Error(`YAML in ${filePath} did not validate:\n ${issues.join("\n ")}`);
213
+ }
214
+ meta = res.value;
215
+ }
216
+ return { meta, body };
217
+ };
218
+
219
+ // from https://github.com/dworthen/js-yaml-front-matter/blob/master/src/index.js#L14
220
+ const yamlFrontRe = /^(-{3}(?:\n|\r)([\w\W]+?)(?:\n|\r)-{3})?([\w\W]*)*/;
@@ -0,0 +1,76 @@
1
+ /** The Standard Schema interface. */
2
+ export interface StandardSchemaV1<Input = unknown, Output = Input> {
3
+ /** The Standard Schema properties. */
4
+ readonly "~standard": StandardSchemaV1.Props<Input, Output>;
5
+ }
6
+
7
+ export declare namespace StandardSchemaV1 {
8
+ /** The Standard Schema properties interface. */
9
+ export interface Props<Input = unknown, Output = Input> {
10
+ /** The version number of the standard. */
11
+ readonly version: 1;
12
+ /** The vendor name of the schema library. */
13
+ readonly vendor: string;
14
+ /** Validates unknown input values. */
15
+ readonly validate: (
16
+ value: unknown,
17
+ options?: StandardSchemaV1.Options | undefined,
18
+ ) => Result<Output> | Promise<Result<Output>>;
19
+ /** Inferred types associated with the schema. */
20
+ readonly types?: Types<Input, Output> | undefined;
21
+ }
22
+
23
+ /** The result interface of the validate function. */
24
+ export type Result<Output> = SuccessResult<Output> | FailureResult;
25
+
26
+ /** The result interface if validation succeeds. */
27
+ export interface SuccessResult<Output> {
28
+ /** The typed output value. */
29
+ readonly value: Output;
30
+ /** A falsy value for `issues` indicates success. */
31
+ readonly issues?: undefined;
32
+ }
33
+
34
+ export interface Options {
35
+ /** Explicit support for additional vendor-specific parameters, if needed. */
36
+ readonly libraryOptions?: Record<string, unknown> | undefined;
37
+ }
38
+
39
+ /** The result interface if validation fails. */
40
+ export interface FailureResult {
41
+ /** The issues of failed validation. */
42
+ readonly issues: ReadonlyArray<Issue>;
43
+ }
44
+
45
+ /** The issue interface of the failure output. */
46
+ export interface Issue {
47
+ /** The error message of the issue. */
48
+ readonly message: string;
49
+ /** The path of the issue, if any. */
50
+ readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
51
+ }
52
+
53
+ /** The path segment interface of the issue. */
54
+ export interface PathSegment {
55
+ /** The key representing a path segment. */
56
+ readonly key: PropertyKey;
57
+ }
58
+
59
+ /** The Standard Schema types interface. */
60
+ export interface Types<Input = unknown, Output = Input> {
61
+ /** The input type of the schema. */
62
+ readonly input: Input;
63
+ /** The output type of the schema. */
64
+ readonly output: Output;
65
+ }
66
+
67
+ /** Infers the input type of a Standard Schema. */
68
+ export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
69
+ Schema["~standard"]["types"]
70
+ >["input"];
71
+
72
+ /** Infers the output type of a Standard Schema. */
73
+ export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
74
+ Schema["~standard"]["types"]
75
+ >["output"];
76
+ }