react-router-markdown 0.9.0

package/LICENSE.md

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Javier Aguilar (itsjavi.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
+OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# react-router-markdown
+
+Vite plugin to parse Markdown files as React Router pages. It supports defining React Router's meta
+function returned data, as frontmatter.
+
+## Setup
+
+```bash
+pnpm add react-router-markdown
+```
+
+## Usage
+
+### Vite config
+
+```tsx
+// vite.config.ts
+
+import { defineConfig } from 'vite'
+import markdown from 'react-router-markdown/vite'
+
+export default defineConfig({
+  plugins: [
+    markdown({
+      parseHtml: true,
+      wrapperModule: '@/components/markdown-wrapper',
+      handleData: (mdContent, frontmatter) => ({
+        layoutClass: 'mx-auto max-w-5xl lg:p-4',
+        title: frontmatter.title,
+        contentLength: mdContent.length,
+      }),
+      beforeTransform: (rawFileContent) =>
+        rawFileContent.replaceAll('%YEAR%', new Date().getFullYear().toString()),
+      afterTransform: (mdContent, frontmatter) => [mdContent, frontmatter],
+    }),
+  ],
+})
+```
+
+### Plugin options
+
+- `parseHtml?: boolean` - Parse HTML tags in markdown as HTML (default: `false`).
+- `wrapperModule?: string` - Module specifier of a default-exported React wrapper component.
+- `beforeTransform?: (content: string) => string` - Transform raw markdown before frontmatter
+  parsing.
+- `afterTransform?: (content: string, frontmatter: Record<string, any>) => [string, Record<string, any>]` -
+  Transform parsed content/frontmatter.
+- `handleData?: (content: string, frontmatter: Record<string, any>) => Record<string, any>` - Return
+  React Router `handle` export data.
+
+### Imports and TypeScript support
+
+In order to TypeScript import `.md` files with type hints, add the following to your `vite.d.ts`
+file:
+
+```tsx
+/// <reference types="react-router-markdown/references" />
+```
+
+Optionally, you can also add the following to your `tsconfig.json` file:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["react-router-markdown/references"]
+  }
+}
+```
+
+Now you can use any `.md` file as a React Router page.

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+//#region src/lib/markdow-page.d.ts
+type MarkdownPageProps = {
+  parseHtml: boolean;
+  rawContent: string;
+  frontmatter: Record<string, unknown>;
+  Wrapper: React.ComponentType<{
+    children: React.ReactNode;
+    frontmatter: Record<string, unknown>;
+  }> | null;
+};
+declare function MarkdownPage({
+  parseHtml,
+  rawContent,
+  frontmatter,
+  Wrapper
+}: MarkdownPageProps): React.ReactElement;
+//#endregion
+export { MarkdownPage };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,25 @@
+import { raw } from "hast-util-raw";
+import ReactMarkdown from "react-markdown";
+import { jsx } from "react/jsx-runtime";
+//#region src/lib/markdow-page.ts
+function rehypeRaw(options) {
+	return (tree, file) => raw(tree, {
+		...options,
+		file
+	});
+}
+function MarkdownPage({ parseHtml, rawContent, frontmatter, Wrapper }) {
+	const mdElement = jsx(ReactMarkdown, {
+		children: rawContent,
+		rehypePlugins: parseHtml ? [rehypeRaw] : []
+	});
+	if (!Wrapper) return mdElement;
+	return jsx(Wrapper, {
+		children: mdElement,
+		frontmatter
+	});
+}
+//#endregion
+export { MarkdownPage };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/lib/markdow-page.ts"],"sourcesContent":["import { raw } from 'hast-util-raw'\nimport ReactMarkdown from 'react-markdown'\nimport { jsx } from 'react/jsx-runtime'\n\ntype HastNodes = Parameters<typeof raw>[0]\ntype HastOptions = NonNullable<Parameters<typeof raw>[1]>\ntype MarkdownPageProps = {\n  parseHtml: boolean\n  rawContent: string\n  frontmatter: Record<string, unknown>\n  Wrapper: React.ComponentType<{\n    children: React.ReactNode\n    frontmatter: Record<string, unknown>\n  }> | null\n}\n\nfunction rehypeRaw(options: HastOptions) {\n  return (tree: HastNodes, file: HastOptions['file']) => raw(tree, { ...options, file })\n}\n\nexport function MarkdownPage({\n  parseHtml,\n  rawContent,\n  frontmatter,\n  Wrapper,\n}: MarkdownPageProps): React.ReactElement {\n  const rehypePlugins = parseHtml ? [rehypeRaw] : []\n  const mdElement = jsx(ReactMarkdown, { children: rawContent, rehypePlugins: rehypePlugins })\n\n  if (!Wrapper) {\n    return mdElement\n  }\n\n  return jsx(Wrapper, {\n    children: mdElement,\n    frontmatter: frontmatter,\n  })\n}\n"],"mappings":";;;;AAgBA,SAAS,UAAU,SAAsB;AACvC,SAAQ,MAAiB,SAA8B,IAAI,MAAM;EAAE,GAAG;EAAS;EAAM,CAAC;;AAGxF,SAAgB,aAAa,EAC3B,WACA,YACA,aACA,WACwC;CAExC,MAAM,YAAY,IAAI,eAAe;EAAE,UAAU;EAAY,eADvC,YAAY,CAAC,UAAU,GAAG,EAAE;EACyC,CAAC;AAE5F,KAAI,CAAC,QACH,QAAO;AAGT,QAAO,IAAI,SAAS;EAClB,UAAU;EACG;EACd,CAAC"}

package/dist/references.d.ts

@@ -0,0 +1,12 @@
+// allows importing md files
+// Add this to your vite.d.ts file: /// <reference types="react-router-markdown/references" />
+declare module '*.md' {
+  export const frontmatter: Record<string, any>
+  export const rawContent: string
+  export const meta: () => any[]
+  export const handle: any
+
+  const Page: () => JSX.Element
+
+  export default Page
+}

package/dist/vite.d.mts

@@ -0,0 +1,39 @@
+import { Plugin } from "vite";
+
+//#region src/lib/vite-plugin.d.ts
+type ReactRouterMarkdownOptions<D = Record<string, any>> = {
+  /**
+   * Module specifier to import a wrapper component from.
+   * Must default-export a React component.
+   *
+   * Example: '#/components/markdown/wrapper'
+   * @default undefined
+   */
+  wrapperModule?: string;
+  /**
+   * If true, any HTML tags in the markdown content will be parsed as HTML instead of escaped.
+   * @default false
+   */
+  parseHtml?: boolean;
+  /**
+   * A function to return the handle data to be used for each page.
+   * It accepts the post-processed content and frontmatter as arguments.
+   * @default undefined
+   */
+  handleData?: (content: string, frontmatter: Record<string, any>) => Partial<D>;
+  /**
+   * A function to transform the raw MD file content before it is parsed.
+   * @default undefined
+   */
+  beforeTransform?: (content: string) => string;
+  /**
+   * A function to transform the parsed MD content and/or frontmatter after they are parsed.
+   * It should return back the transformed content and frontmatter.
+   * @default undefined
+   */
+  afterTransform?: (content: string, frontmatter: Record<string, any>) => [string, Record<string, any>];
+};
+declare function reactRouterMarkdown<D = Record<string, any>>(options?: ReactRouterMarkdownOptions<D>): Plugin;
+//#endregion
+export { type ReactRouterMarkdownOptions, reactRouterMarkdown as default };
+//# sourceMappingURL=vite.d.mts.map

package/dist/vite.mjs

@@ -0,0 +1,47 @@
+import matter from "gray-matter";
+import "vite";
+//#region src/lib/vite-plugin.ts
+function reactRouterMarkdown(options = {}) {
+	const { wrapperModule, parseHtml = false, handleData: handleDataFn = () => ({}), beforeTransform = (content) => content, afterTransform = (content, frontmatter) => [content, frontmatter] } = options;
+	return {
+		name: "react-router-markdown",
+		enforce: "pre",
+		transform(code, id) {
+			if (!(id.split("?", 1)[0] ?? id).endsWith(".md")) return null;
+			const { data, content } = matter(beforeTransform(code));
+			const [transformedContent, transformedFrontmatter] = afterTransform(content, data || {});
+			const handleData = handleDataFn(transformedContent, transformedFrontmatter);
+			return {
+				code: [
+					`import { MarkdownPage } from 'react-router-markdown';`,
+					wrapperModule ? `import Wrapper from ${JSON.stringify(wrapperModule)};` : "const Wrapper = null;",
+					"",
+					`export const frontmatter = ${JSON.stringify(transformedFrontmatter || {})};`,
+					`export const rawContent = ${JSON.stringify(transformedContent || "")};`,
+					"",
+					"export const meta = () => frontmatter.meta || [];",
+					`export const handle = ${JSON.stringify(handleData)};`,
+					"",
+					`function Page() {
+            return _jsx(MarkdownPage, {
+              Wrapper,
+              parseHtml: ${parseHtml ? "true" : "false"},
+              rawContent: rawContent,
+              frontmatter: frontmatter,
+            })
+          }
+          export default Page;
+          `
+				].join("\n"),
+				map: null
+			};
+		}
+	};
+}
+//#endregion
+//#region src/vite.ts
+var vite_default = reactRouterMarkdown;
+//#endregion
+export { vite_default as default };
+
+//# sourceMappingURL=vite.mjs.map

package/dist/vite.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.mjs","names":[],"sources":["../src/lib/vite-plugin.ts","../src/vite.ts"],"sourcesContent":["import matter from 'gray-matter'\nimport { type Plugin } from 'vite'\n\nexport type ReactRouterMarkdownOptions<D = Record<string, any>> = {\n  /**\n   * Module specifier to import a wrapper component from.\n   * Must default-export a React component.\n   *\n   * Example: '#/components/markdown/wrapper'\n   * @default undefined\n   */\n  wrapperModule?: string\n  /**\n   * If true, any HTML tags in the markdown content will be parsed as HTML instead of escaped.\n   * @default false\n   */\n  parseHtml?: boolean\n  /**\n   * A function to return the handle data to be used for each page.\n   * It accepts the post-processed content and frontmatter as arguments.\n   * @default undefined\n   */\n  handleData?: (content: string, frontmatter: Record<string, any>) => Partial<D>\n\n  /**\n   * A function to transform the raw MD file content before it is parsed.\n   * @default undefined\n   */\n  beforeTransform?: (content: string) => string\n\n  /**\n   * A function to transform the parsed MD content and/or frontmatter after they are parsed.\n   * It should return back the transformed content and frontmatter.\n   * @default undefined\n   */\n  afterTransform?: (\n    content: string,\n    frontmatter: Record<string, any>,\n  ) => [string, Record<string, any>]\n}\n\nexport function reactRouterMarkdown<D = Record<string, any>>(\n  options: ReactRouterMarkdownOptions<D> = {},\n): Plugin {\n  const {\n    wrapperModule,\n    parseHtml = false,\n    handleData: handleDataFn = () => ({}) as Partial<D>,\n    beforeTransform = (content) => content,\n    afterTransform = (content, frontmatter) => [content, frontmatter],\n  }: ReactRouterMarkdownOptions<D> = options\n\n  return {\n    name: 'react-router-markdown',\n    enforce: 'pre',\n\n    transform(code, id) {\n      const filePath = id.split('?', 1)[0] ?? id\n      if (!filePath.endsWith('.md')) return null\n\n      const transformedCode = beforeTransform(code)\n      const { data, content } = matter(transformedCode)\n      const [transformedContent, transformedFrontmatter] = afterTransform(content, data || {})\n      const handleData = handleDataFn(transformedContent, transformedFrontmatter)\n\n      return {\n        code: [\n          `import { MarkdownPage } from 'react-router-markdown';`,\n          wrapperModule\n            ? `import Wrapper from ${JSON.stringify(wrapperModule)};`\n            : 'const Wrapper = null;',\n          '',\n          `export const frontmatter = ${JSON.stringify(transformedFrontmatter || {})};`,\n          `export const rawContent = ${JSON.stringify(transformedContent || '')};`,\n          '',\n          'export const meta = () => frontmatter.meta || [];',\n          `export const handle = ${JSON.stringify(handleData)};`,\n          '',\n          `function Page() {\n            return _jsx(MarkdownPage, {\n              Wrapper,\n              parseHtml: ${parseHtml ? 'true' : 'false'},\n              rawContent: rawContent,\n              frontmatter: frontmatter,\n            })\n          }\n          export default Page;\n          `,\n        ].join('\\n'),\n        map: null,\n      }\n    },\n  }\n}\n","export { type ReactRouterMarkdownOptions } from './lib/vite-plugin'\n\nimport { reactRouterMarkdown } from './lib/vite-plugin'\n\nexport default reactRouterMarkdown\n"],"mappings":";;;AAyCA,SAAgB,oBACd,UAAyC,EAAE,EACnC;CACR,MAAM,EACJ,eACA,YAAY,OACZ,YAAY,sBAAsB,EAAE,GACpC,mBAAmB,YAAY,SAC/B,kBAAkB,SAAS,gBAAgB,CAAC,SAAS,YAAY,KAChC;AAEnC,QAAO;EACL,MAAM;EACN,SAAS;EAET,UAAU,MAAM,IAAI;AAElB,OAAI,EADa,GAAG,MAAM,KAAK,EAAE,CAAC,MAAM,IAC1B,SAAS,MAAM,CAAE,QAAO;GAGtC,MAAM,EAAE,MAAM,YAAY,OADF,gBAAgB,KAAK,CACI;GACjD,MAAM,CAAC,oBAAoB,0BAA0B,eAAe,SAAS,QAAQ,EAAE,CAAC;GACxF,MAAM,aAAa,aAAa,oBAAoB,uBAAuB;AAE3E,UAAO;IACL,MAAM;KACJ;KACA,gBACI,uBAAuB,KAAK,UAAU,cAAc,CAAC,KACrD;KACJ;KACA,8BAA8B,KAAK,UAAU,0BAA0B,EAAE,CAAC,CAAC;KAC3E,6BAA6B,KAAK,UAAU,sBAAsB,GAAG,CAAC;KACtE;KACA;KACA,yBAAyB,KAAK,UAAU,WAAW,CAAC;KACpD;KACA;;;2BAGiB,YAAY,SAAS,QAAQ;;;;;;;KAO/C,CAAC,KAAK,KAAK;IACZ,KAAK;IACN;;EAEJ;;;;ACxFH,IAAA,eAAe"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "react-router-markdown",
+  "version": "0.9.0",
+  "description": "Vite plugin to parse and use markdown files as React Router pages, including frontmatter support.",
+  "keywords": [
+    "markdown",
+    "react-router",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/itsjavi/react-router-markdown#readme",
+  "bugs": {
+    "url": "https://github.com/itsjavi/react-router-markdown/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Javier Aguilar",
+    "url": "https://itsjavi.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itsjavi/react-router-markdown.git"
+  },
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "import": "./dist/vite.mjs"
+    },
+    "./references": "./dist/references.d.ts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "lint": "pnpm typecheck && pnpm publint",
+    "publint": "publint",
+    "test": "vitest --run",
+    "test:coverage": "vitest --run --coverage",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "hast-util-raw": "^9.1.0",
+    "react-markdown": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
+    "@vitest/coverage-v8": "^4.1.2",
+    "oxfmt": "^0.42.0",
+    "publint": "^0.3.18",
+    "react": "^19.2.4",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
+  },
+  "peerDependencies": {
+    "react": "^19.2.4",
+    "vite": "^7.0.0 || ^8.0.0"
+  },
+  "packageManager": "pnpm@10.33.0"
+}