@quietmind/mdx-docs 0.1.9 → 0.1.10
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 +110 -73
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,7 +6,9 @@ MDX Docs turns MDX files into routed documentation pages with a built-in layout,
|
|
|
6
6
|
|
|
7
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.
|
|
8
8
|
|
|
9
|
-
**Demo:** https://mdxdocs.com/
|
|
9
|
+
**Demo:** [https://mdxdocs.com/](https://mdxdocs.com/)
|
|
10
|
+
|
|
11
|
+
|
|
10
12
|
|
|
11
13
|
## Features
|
|
12
14
|
|
|
@@ -16,29 +18,75 @@ MDX Docs is a React + Vite framework for building MDX-powered documentation site
|
|
|
16
18
|
- Responsive sidebar navigation
|
|
17
19
|
- Built on React 19, Material-UI 7, and Vite 6
|
|
18
20
|
|
|
19
|
-
##
|
|
21
|
+
## Quick Start
|
|
22
|
+
|
|
23
|
+
Create a new documentation site:
|
|
20
24
|
|
|
21
25
|
```sh
|
|
22
|
-
|
|
26
|
+
npx create-mdx-docs@latest my-docs
|
|
23
27
|
```
|
|
24
28
|
|
|
25
|
-
|
|
29
|
+
Create an MDX file in `pages/`:
|
|
26
30
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
31
|
+
~~~mdx
|
|
32
|
+
import { Button } from "@mui/material";
|
|
33
|
+
|
|
34
|
+
# Button
|
|
35
|
+
|
|
36
|
+
<Button variant="contained" color="primary">
|
|
37
|
+
Primary Action
|
|
38
|
+
</Button>
|
|
39
|
+
|
|
40
|
+
```jsx
|
|
41
|
+
<Button variant="contained" color="primary">
|
|
42
|
+
Primary Action
|
|
43
|
+
</Button>
|
|
34
44
|
```
|
|
45
|
+
~~~
|
|
35
46
|
|
|
36
|
-
|
|
47
|
+
Register your page in `config/pages.js`:
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
const GettingStartedMDX = lazy(() => import("@pages/getting-started.mdx"));
|
|
51
|
+
|
|
52
|
+
export const pages = [
|
|
53
|
+
// ...existing pages
|
|
54
|
+
{
|
|
55
|
+
name: "Getting Started",
|
|
56
|
+
route: "/getting-started",
|
|
57
|
+
component: GettingStartedMDX,
|
|
58
|
+
},
|
|
59
|
+
];
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Pages with `isDefault: true` do not appear in the sidebar navigation.
|
|
63
|
+
|
|
64
|
+
Configure your site name and description in `config/site.js`.
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
export const site = {
|
|
68
|
+
name: "My Site",
|
|
69
|
+
description: "My site description",
|
|
70
|
+
};
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Favicon
|
|
37
74
|
|
|
38
|
-
|
|
75
|
+
Place your favicon in the `public/` directory and add a `<link>` tag to `index.html`:
|
|
39
76
|
|
|
77
|
+
```html
|
|
78
|
+
<head>
|
|
79
|
+
<!-- ... -->
|
|
80
|
+
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
|
81
|
+
</head>
|
|
40
82
|
```
|
|
41
|
-
|
|
83
|
+
|
|
84
|
+
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.
|
|
85
|
+
|
|
86
|
+
## Project Structure
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
my-docs/
|
|
42
90
|
├── pages/
|
|
43
91
|
│ └── home.mdx
|
|
44
92
|
├── config/
|
|
@@ -52,7 +100,39 @@ my-site/
|
|
|
52
100
|
└── package.json
|
|
53
101
|
```
|
|
54
102
|
|
|
55
|
-
|
|
103
|
+
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.
|
|
104
|
+
|
|
105
|
+
## Manual Installation
|
|
106
|
+
|
|
107
|
+
### 1. Install Package
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
npm install mdx-docs
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## 2. Install Peer Dependencies
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
npm install react react-dom react-router-dom \
|
|
117
|
+
@emotion/react @emotion/styled \
|
|
118
|
+
@mui/material @mui/icons-material \
|
|
119
|
+
@mdx-js/react @mdx-js/rollup \
|
|
120
|
+
prism-react-renderer prismjs \
|
|
121
|
+
vite @vitejs/plugin-react
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 3. `main.jsx`
|
|
125
|
+
|
|
126
|
+
```js
|
|
127
|
+
import "@quietmind/mdx-docs/index.css";
|
|
128
|
+
import { createApp } from "@quietmind/mdx-docs";
|
|
129
|
+
import { pages } from "./config/pages.js";
|
|
130
|
+
import { site } from "./config/site.js";
|
|
131
|
+
|
|
132
|
+
createApp({ pages, site });
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 4. `config/site.js`
|
|
56
136
|
|
|
57
137
|
```js
|
|
58
138
|
export const site = {
|
|
@@ -61,7 +141,7 @@ export const site = {
|
|
|
61
141
|
};
|
|
62
142
|
```
|
|
63
143
|
|
|
64
|
-
###
|
|
144
|
+
### 5. `config/pages.js`
|
|
65
145
|
|
|
66
146
|
```js
|
|
67
147
|
import { lazy } from "react";
|
|
@@ -78,18 +158,7 @@ export const pages = [
|
|
|
78
158
|
];
|
|
79
159
|
```
|
|
80
160
|
|
|
81
|
-
###
|
|
82
|
-
|
|
83
|
-
```js
|
|
84
|
-
import "@quietmind/mdx-docs/index.css";
|
|
85
|
-
import { createApp } from "@quietmind/mdx-docs";
|
|
86
|
-
import { pages } from "./config/pages.js";
|
|
87
|
-
import { site } from "./config/site.js";
|
|
88
|
-
|
|
89
|
-
createApp({ pages, site });
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
### 5. `vite.config.js`
|
|
161
|
+
### 6. `vite.config.js`
|
|
93
162
|
|
|
94
163
|
```js
|
|
95
164
|
import { defineConfig } from "vite";
|
|
@@ -101,7 +170,7 @@ export default defineConfig(
|
|
|
101
170
|
);
|
|
102
171
|
```
|
|
103
172
|
|
|
104
|
-
###
|
|
173
|
+
### 7. `index.html`
|
|
105
174
|
|
|
106
175
|
```html
|
|
107
176
|
<!DOCTYPE html>
|
|
@@ -119,50 +188,6 @@ export default defineConfig(
|
|
|
119
188
|
</html>
|
|
120
189
|
```
|
|
121
190
|
|
|
122
|
-
## Adding Pages
|
|
123
|
-
|
|
124
|
-
Create an MDX file in `pages/`:
|
|
125
|
-
|
|
126
|
-
~~~mdx
|
|
127
|
-
# Getting Started
|
|
128
|
-
|
|
129
|
-
This is a documentation page with **markdown** and React components.
|
|
130
|
-
|
|
131
|
-
```js
|
|
132
|
-
const hello = "world";
|
|
133
|
-
```
|
|
134
|
-
~~~
|
|
135
|
-
|
|
136
|
-
Register it in `config/pages.js`:
|
|
137
|
-
|
|
138
|
-
```js
|
|
139
|
-
const GettingStartedMDX = lazy(() => import("@pages/getting-started.mdx"));
|
|
140
|
-
|
|
141
|
-
export const pages = [
|
|
142
|
-
// ...existing pages
|
|
143
|
-
{
|
|
144
|
-
name: "Getting Started",
|
|
145
|
-
route: "/getting-started",
|
|
146
|
-
component: GettingStartedMDX,
|
|
147
|
-
},
|
|
148
|
-
];
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
Pages without `isDefault: true` appear in the sidebar navigation. The page with `isDefault: true` is the fallback/home route.
|
|
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
|
-
|
|
166
191
|
## Tech Stack
|
|
167
192
|
|
|
168
193
|
- React 19, Material-UI 7, Emotion
|
|
@@ -170,6 +195,18 @@ Vite serves files in `public/` at the root path, so `public/favicon.svg` is acce
|
|
|
170
195
|
- React Router DOM 7
|
|
171
196
|
- Prism React Renderer
|
|
172
197
|
|
|
198
|
+
## Contributing
|
|
199
|
+
|
|
200
|
+
Contributions are welcome!
|
|
201
|
+
|
|
202
|
+
1. Fork the repo
|
|
203
|
+
2. Create a branch
|
|
204
|
+
3. Submit a pull request
|
|
205
|
+
|
|
206
|
+
## Related Projects
|
|
207
|
+
|
|
208
|
+
- [https://mdxjs.com/](https://mdxjs.com/)
|
|
209
|
+
|
|
173
210
|
## License
|
|
174
211
|
|
|
175
212
|
MIT
|