@quietmind/mdx-docs 0.1.0 → 0.1.1

package/README.md

@@ -1,277 +1,153 @@
-# Quietmind Wiki
+# @quietmind/mdx-docs
 
-https://quietmind.dev/
+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.
 
-## 🚀 Quick Start
+**Demo:** https://thequietmind.github.io/mdx-docs/
 
-### Prerequisites
+## Features
 
-- Node.js (version 16 or higher)
-- Yarn package manager
+- MDX pages — write Markdown with embedded React components
+- Syntax highlighting with copy-to-clipboard on code blocks
+- Dark/light mode with system preference detection
+- Responsive sidebar navigation
+- Built on React 19, Material-UI 7, and Vite 6
 
-### Installation
-
-Clone the repository:
-
-```sh
-git clone https://github.com/ezrafree/quietmind-dev.git && \
-cd quietmind-dev
-```
-
-Install dependencies:
+## Installation
 
 ```sh
-yarn
+npm install @quietmind/mdx-docs
 ```
 
-Start the development server:
+### Peer dependencies
 
 ```sh
-yarn dev
+npm install react react-dom react-router-dom \
+  @emotion/react @emotion/styled \
+  @mui/material @mui/icons-material \
+  @mdx-js/react @mdx-js/rollup \
+  prism-react-renderer prismjs \
+  vite @vitejs/plugin-react
 ```
 
-Open [http://localhost:5173](http://localhost:5173) in your browser
-
-## 📋 Available Scripts
-
-| Command | Description |
-|---------|-------------|
-| `yarn dev` | Start development server |
-| `yarn build` | Build for production |
-| `yarn preview` | Preview production build locally |
-| `yarn serve` | Preview production build with network access |
-| `yarn lint` | Run ESLint |
-| `yarn test` | Run tests |
-| `yarn test:watch` | Run tests in watch mode |
-| `yarn test:coverage` | Run tests with coverage |
-| `yarn test:ui` | Run tests with UI |
-| `yarn deploy` | Deploy to GitHub Pages |
-
-## 📚 Tech Stack
-
-- **Frontend**: React 19, Material-UI 7, Emotion
-- **Build Tool**: Vite 6
-- **Routing**: React Router DOM 7
-- **Documentation**: MDX 3
-- **Testing**: Vitest, Testing Library
-- **Deployment**: GitHub Pages
-
-## 📖 Documentation Structure
+## Quick Start
 
-### Adding New Pages
+### 1. Site structure
 
-Create a new MDX file in `src/contents/`:
-
-```mdx
-# My New Page
-
-This is my new documentation page with **markdown** and React components.
 ```
-
-Update the pages configuration in `src/config/pages.js`:
-
-```js
-import MyNewPageMDX from "../contents/my-new-page.mdx";
-
-export const pages = [
-  // ... existing pages
-  {
-    name: "My New Page",
-    route: "/my-new-page",
-    component: MyNewPageMDX,
-  },
-];
+my-site/
+├── pages/
+│   └── home.mdx
+├── config/
+│   ├── pages.js
+│   └── site.js
+├── index.html
+├── main.jsx
+├── vite.config.js
+└── package.json
 ```
 
-### MDX Features
-
-- **Code Blocks**: Syntax highlighting with copy buttons
-- **Inline Code**: Styled inline code snippets
-- **React Components**: Embed any React component directly in MDX
-- **External Links**: Automatically open in new tabs
-
-## 🎨 Theming
-
-### Customizing Colors
-
-Update the theme files to customize the appearance:
-
-- **Light Theme**: `src/themes/lightTheme.js`
-- **Dark Theme**: `src/themes/darkTheme.js`
-
-Example theme customization:
+### 2. `config/site.js`
 
 ```js
-export const lightTheme = {
-  palette: {
-    primary: {
-      main: '#1976d2',
-    },
-    secondary: {
-      main: '#dc004e',
-    },
-  },
+export const site = {
+  name: "My Site",
 };
 ```
 
-### Theme Hook
-
-Use the `useTheme` hook to access theme state:
+### 3. `config/pages.js`
 
 ```js
-import { useTheme } from './hooks/useTheme';
-
-function MyComponent() {
-  const { darkMode, setDarkMode } = useTheme();
-  // ...
-}
-```
+import { lazy } from "react";
 
-## 🏗️ Project Structure
+const HomeMDX = lazy(() => import("@pages/home.mdx"));
 
-```none
-src/
-├── components/          # React components
-│   ├── AppBar.jsx      # Top navigation bar
-│   ├── CodeBlock.jsx   # Syntax highlighted code blocks
-│   ├── InlineCode.jsx  # Inline code styling
-│   ├── MDXContent.jsx  # MDX content renderer
-│   └── SideNavigation.jsx # Sidebar navigation
-├── config/
-│   └── pages.js        # Page configuration
-├── contents/           # MDX documentation files
-│   ├── button.mdx
-│   ├── colors.mdx
-│   ├── home.mdx
-│   └── typography.mdx
-├── hooks/
-│   └── useTheme.js     # Theme management hook
-├── themes/             # Material-UI themes
-│   ├── darkTheme.js
-│   ├── lightTheme.js
-│   └── index.js
-└── utils/
-    └── navigation.js   # Navigation utilities
+export const pages = [
+  {
+    name: "Home",
+    route: "/",
+    component: HomeMDX,
+    isDefault: true,
+  },
+];
 ```
 
-## 🧪 Testing
-
-The project includes comprehensive tests with good coverage thresholds:
+### 4. `main.jsx`
 
-- **Unit Tests**: Component and utility testing
-- **Coverage**: 70% minimum for branches, functions, lines, and statements
-- **Tools**: Vitest, Testing Library, jsdom
-
-Run tests:
-
-```sh
-# Run all tests
-yarn test
-
-# Watch mode
-yarn test:watch
-
-# With coverage
-yarn test:coverage
+```js
+import "@quietmind/mdx-docs/index.css";
+import { createApp } from "@quietmind/mdx-docs";
+import { pages } from "./config/pages.js";
+import { site } from "./config/site.js";
 
-# Interactive UI
-yarn test:ui
+createApp({ pages, site });
 ```
 
-## 🚀 Deployment
-
-### GitHub Pages
-
-The project is configured for GitHub Pages deployment:
+### 5. `vite.config.js`
 
-1. Update the `homepage` field in `package.json`
-2. Run the deploy command:
+```js
+import { defineConfig } from "vite";
+import { createMdxDocsConfig } from "@quietmind/mdx-docs/vite";
 
-```sh
-yarn deploy
+export default defineConfig(
+  createMdxDocsConfig({ rootDir: import.meta.dirname })
+);
 ```
 
-### Production Serving
-
-To serve the app in production mode locally:
-
-#### Option 1: Using Vite Preview (Recommended)
-
-```sh
-yarn build
-yarn preview
+### 6. `index.html`
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Site</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/main.jsx"></script>
+  </body>
+</html>
 ```
 
-This serves the production build at `http://localhost:4173` (or another port if 4173 is taken).
+## Adding Pages
 
-#### Option 2: Using Vite Preview with Network Access
+Create an MDX file in `pages/`:
 
-```sh
-yarn build
-yarn serve
-```
-
-This serves the production build and makes it accessible on your local network.
-
-#### Option 3: Using a Static File Server
+```mdx
+# Getting Started
 
-Install a static server globally:
+This is a documentation page with **markdown** and React components.
 
-```sh
-npm install -g serve
-# or
-yarn global add serve
+```js
+const hello = "world";
 ```
-
-Then build and serve:
-
-```sh
-yarn build
-serve -s dist -l 3000
 ```
 
-### Custom Deployment
+Register it in `config/pages.js`:
 
-For other hosting platforms (Netlify, Vercel, AWS S3, etc.), build the project and serve the `dist` folder:
+```js
+const GettingStartedMDX = lazy(() => import("@pages/getting-started.mdx"));
 
-```sh
-yarn build
-# Upload the dist/ directory to your hosting platform
+export const pages = [
+  // ...existing pages
+  {
+    name: "Getting Started",
+    route: "/getting-started",
+    component: GettingStartedMDX,
+  },
+];
 ```
 
-## 🔧 Configuration
-
-### Vite Configuration
-
-The Vite config (`vite.config.js`) includes:
-
-- MDX plugin configuration
-- Emotion JSX runtime
-- Dynamic base URL for GitHub Pages
-
-### ESLint
-
-ESLint is configured with:
-
-- React and React Hooks rules
-- Import organization
-- Modern JavaScript standards
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
-3. Commit your changes: `git commit -m 'Add amazing feature'`
-4. Push to the branch: `git push origin feature/amazing-feature`
-5. Open a Pull Request
+Pages without `isDefault: true` appear in the sidebar navigation. The page with `isDefault: true` is the fallback/home route.
 
-## 📄 License
+## Tech Stack
 
-This project is open source and available under the [MIT License](LICENSE).
+- React 19, Material-UI 7, Emotion
+- Vite 6, MDX 3
+- React Router DOM 7
+- Prism React Renderer
 
-## 🙏 Acknowledgments
+## License
 
-- [MDX](https://mdxjs.com/) for the amazing documentation framework
-- [Material-UI](https://mui.com/) for the beautiful component library
-- [Vite](https://vitejs.dev/) for the lightning-fast build tool
-- [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) for syntax highlighting
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quietmind/mdx-docs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "homepage": "https://thequietmind.github.io/mdx-docs",
   "exports": {