@quietmind/mdx-docs 0.1.7 → 0.1.9
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/README.md +25 -3
- package/package.json +1 -1
- package/src/vite.config.helper.js +39 -1
package/README.md
CHANGED
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
# @quietmind/mdx-docs
|
|
2
2
|
|
|
3
|
-
A React
|
|
3
|
+
> A lightweight React framework for MDX documentation sites.
|
|
4
|
+
|
|
5
|
+
MDX Docs turns MDX files into routed documentation pages with a built-in layout, sidebar, and navigation.
|
|
6
|
+
|
|
7
|
+
MDX Docs is a React + Vite framework for building MDX-powered documentation sites. Write pages in Markdown with embedded React components, and get a fully-featured site with syntax highlighting, dark/light mode, and responsive navigation out of the box.
|
|
4
8
|
|
|
5
9
|
**Demo:** https://mdxdocs.com/
|
|
6
10
|
|
|
@@ -40,6 +44,8 @@ my-site/
|
|
|
40
44
|
├── config/
|
|
41
45
|
│ ├── pages.js
|
|
42
46
|
│ └── site.js
|
|
47
|
+
├── public/
|
|
48
|
+
│ └── favicon.svg
|
|
43
49
|
├── index.html
|
|
44
50
|
├── main.jsx
|
|
45
51
|
├── vite.config.js
|
|
@@ -51,6 +57,7 @@ my-site/
|
|
|
51
57
|
```js
|
|
52
58
|
export const site = {
|
|
53
59
|
name: "My Site",
|
|
60
|
+
description: "My site description",
|
|
54
61
|
};
|
|
55
62
|
```
|
|
56
63
|
|
|
@@ -87,9 +94,10 @@ createApp({ pages, site });
|
|
|
87
94
|
```js
|
|
88
95
|
import { defineConfig } from "vite";
|
|
89
96
|
import { createMdxDocsConfig } from "@quietmind/mdx-docs/vite";
|
|
97
|
+
import { site } from "./config/site.js";
|
|
90
98
|
|
|
91
99
|
export default defineConfig(
|
|
92
|
-
createMdxDocsConfig({ rootDir: import.meta.dirname })
|
|
100
|
+
createMdxDocsConfig({ rootDir: import.meta.dirname, site })
|
|
93
101
|
);
|
|
94
102
|
```
|
|
95
103
|
|
|
@@ -101,7 +109,8 @@ export default defineConfig(
|
|
|
101
109
|
<head>
|
|
102
110
|
<meta charset="UTF-8" />
|
|
103
111
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
104
|
-
<
|
|
112
|
+
<meta name="description" content="%SITE_DESCRIPTION%" />
|
|
113
|
+
<title>%SITE_NAME%</title>
|
|
105
114
|
</head>
|
|
106
115
|
<body>
|
|
107
116
|
<div id="root"></div>
|
|
@@ -141,6 +150,19 @@ export const pages = [
|
|
|
141
150
|
|
|
142
151
|
Pages without `isDefault: true` appear in the sidebar navigation. The page with `isDefault: true` is the fallback/home route.
|
|
143
152
|
|
|
153
|
+
## Favicon
|
|
154
|
+
|
|
155
|
+
Place your favicon in the `public/` directory and add a `<link>` tag to `index.html`:
|
|
156
|
+
|
|
157
|
+
```html
|
|
158
|
+
<head>
|
|
159
|
+
<!-- ... -->
|
|
160
|
+
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
|
161
|
+
</head>
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Vite serves files in `public/` at the root path, so `public/favicon.svg` is accessible as `/favicon.svg`. Use `.ico`, `.png`, or `.svg` depending on your file.
|
|
165
|
+
|
|
144
166
|
## Tech Stack
|
|
145
167
|
|
|
146
168
|
- React 19, Material-UI 7, Emotion
|
package/package.json
CHANGED
|
@@ -2,12 +2,42 @@ import mdx from "@mdx-js/rollup";
|
|
|
2
2
|
import react from "@vitejs/plugin-react";
|
|
3
3
|
import { fileURLToPath } from "url";
|
|
4
4
|
|
|
5
|
+
/**
|
|
6
|
+
* Rehype plugin that removes <p> wrappers MDX generates around text children
|
|
7
|
+
* of JSX flow elements. This happens because Prettier formats JSX text onto
|
|
8
|
+
* its own line, which MDX interprets as a paragraph. The unwrapping only
|
|
9
|
+
* applies to <p> elements whose children are all plain text nodes — explicit
|
|
10
|
+
* block content is left untouched.
|
|
11
|
+
*/
|
|
12
|
+
export function rehypeUnwrapJsxParagraphs() {
|
|
13
|
+
function processNode(node) {
|
|
14
|
+
if (!node.children) return;
|
|
15
|
+
node.children.forEach(processNode);
|
|
16
|
+
if (node.type === "mdxJsxFlowElement") {
|
|
17
|
+
node.children = node.children.flatMap((child) => {
|
|
18
|
+
if (
|
|
19
|
+
child.type === "element" &&
|
|
20
|
+
child.tagName === "p" &&
|
|
21
|
+
child.children.every((c) => c.type === "text")
|
|
22
|
+
) {
|
|
23
|
+
return child.children;
|
|
24
|
+
}
|
|
25
|
+
return [child];
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
return processNode;
|
|
30
|
+
}
|
|
31
|
+
|
|
5
32
|
/**
|
|
6
33
|
* Creates a base Vite config for an mdx-docs site.
|
|
7
34
|
*
|
|
8
35
|
* @param {object} options
|
|
9
36
|
* @param {string} options.rootDir - The site's root directory (pass `import.meta.dirname`)
|
|
10
37
|
* @param {string} [options.base="/"] - The base URL for the site
|
|
38
|
+
* @param {object} [options.site] - The site config object (from `config/site.js`)
|
|
39
|
+
* @param {string} [options.site.name] - Site name, replaces `%SITE_NAME%` in index.html
|
|
40
|
+
* @param {string} [options.site.description] - Site description, replaces `%SITE_DESCRIPTION%` in index.html
|
|
11
41
|
* @returns {import('vite').UserConfig}
|
|
12
42
|
*
|
|
13
43
|
* @example
|
|
@@ -19,14 +49,22 @@ import { fileURLToPath } from "url";
|
|
|
19
49
|
* createMdxDocsConfig({ rootDir: import.meta.dirname })
|
|
20
50
|
* );
|
|
21
51
|
*/
|
|
22
|
-
export function createMdxDocsConfig({ rootDir, base = "/" } = {}) {
|
|
52
|
+
export function createMdxDocsConfig({ rootDir, base = "/", site = {} } = {}) {
|
|
23
53
|
return {
|
|
24
54
|
base,
|
|
25
55
|
plugins: [
|
|
56
|
+
{
|
|
57
|
+
name: "html-site-config",
|
|
58
|
+
transformIndexHtml: (html) =>
|
|
59
|
+
html
|
|
60
|
+
.replace("%SITE_NAME%", site.name ?? "")
|
|
61
|
+
.replace("%SITE_DESCRIPTION%", site.description ?? ""),
|
|
62
|
+
},
|
|
26
63
|
react(),
|
|
27
64
|
mdx({
|
|
28
65
|
jsxImportSource: "@emotion/react",
|
|
29
66
|
providerImportSource: "@mdx-js/react",
|
|
67
|
+
rehypePlugins: [rehypeUnwrapJsxParagraphs],
|
|
30
68
|
}),
|
|
31
69
|
],
|
|
32
70
|
resolve: {
|