mdsvr 1.0.3 → 2.0.1

package/README.md

@@ -1,6 +1,25 @@
 # mdsvr
 
-Static file server with auto-render Markdown → HTML. Similar to Vercel's `serve` but understands `.md` files.
+> Full-featured documentation website server with **MDX support**, **site-wide settings**, **dark/light mode**, **SEO meta tags**, and **auto-generated navigation**.
+
+Transform any folder of Markdown/Markdown files into a beautiful documentation website — zero config required.
+
+```bash
+npx mdsvr ./docs
+```
+
+## What's New in v2.0
+
+| Feature            | v1  | v2                      |
+| ------------------ | --- | ----------------------- |
+| Markdown rendering | ✅  | ✅ Enhanced             |
+| MDX support        | ❌  | ✅ Full pipeline        |
+| Site settings      | ❌  | ✅ `settings.json`      |
+| Dark/Light mode    | ❌  | ✅ Toggle + auto        |
+| SEO meta tags      | ❌  | ✅ OG, Twitter, sitemap |
+| Sidebar navigation | ❌  | ✅ Auto-generated       |
+| Search             | ❌  | ✅ Full-text            |
+| Sitemap/RSS        | ❌  | ✅ Auto-generated       |
 
 ## Quick Start
 
@@ -8,6 +27,9 @@ Static file server with auto-render Markdown → HTML. Similar to Vercel's `serv
 # One-shot, no install
 npx mdsvr ./docs
 
+# Create a starter settings.json
+npx mdsvr ./docs --init
+
 # With options
 npx mdsvr ./notes --port 4000 --open
 
@@ -33,32 +55,186 @@ Options:
   --host H           Bind address (default: localhost)
   -o, --open         Auto-open browser
   -s, --silent       Suppress console output
+  --init             Create a starter settings.json in [dir]
+  --validate         Validate settings.json and exit
+  --no-watch         Disable settings.json hot-reload
   -v, --version      Print version
   -h, --help         Print this help
 ```
 
+## Configuration (`settings.json`)
+
+Place `settings.json` in your docs root for full customization:
+
+```json
+{
+  "$schema": "https://mdsvr.dev/schema/v2.json",
+  "site": {
+    "title": "My Docs",
+    "description": "Project documentation",
+    "language": "en"
+  },
+  "appearance": {
+    "defaultTheme": "system",
+    "allowThemeToggle": true,
+    "accentColor": "#0969da"
+  },
+  "navigation": {
+    "sidebar": { "enabled": true },
+    "tocEnabled": true
+  },
+  "search": { "enabled": true },
+  "seo": {
+    "generateSitemap": true,
+    "generateRssFeed": false
+  },
+  "mdx": { "enabled": true }
+}
+```
+
+Create one with `npx mdsvr ./docs --init`.
+
+## MDX Support
+
+Write interactive documentation with MDX:
+
+```mdx
+---
+title: Getting Started
+description: How to install and configure
+---
+
+# Getting Started
+
+<Callout type="warning">Make sure you have Node.js 18+ installed.</Callout>
+
+<Steps>
+  ### Install the package
+  Run `npm install mdsvr`
+
+### Create your docs folder
+
+Create a `./docs` directory
+
+### Start the server
+
+Run `npx mdsvr ./docs --open`
+
+</Steps>
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="⚡" href="/quickstart">
+    Get up and running in 5 minutes
+  </Card>
+  <Card title="Configuration" icon="⚙️" href="/config">
+    Full settings reference
+  </Card>
+</CardGroup>
+```
+
+### Built-in MDX Components
+
+- `<Callout type="info|warning|danger|success|tip">` - Highlighted boxes
+- `<CodeGroup title="...">` - Tabbed code blocks
+- `<Steps>` - Numbered step-by-step guide
+- `<Card title="..." icon="..." href="...">` - Link cards
+- `<CardGroup cols={2}>` - Grid layout for cards
+- `<Tabs items={[...]}>` - Tabbed content
+- `<Accordion title="...">` - Collapsible sections
+- `<Badge color="green|orange|red|blue|purple|gray">` - Status badges
+- `<Mermaid>` - Diagrams (client-side rendered)
+
 ## Programmatic API
 
 ```typescript
 import { createServer } from "mdsvr";
 
-const server = await createServer("./docs", { port: 4000, open: true });
+const server = await createServer("./docs", {
+  port: 4000,
+  host: "localhost",
+  open: true,
+  silent: false,
+  watchSettings: true, // Auto-reload on settings.json changes
+});
+
 console.log(`Running at ${server.url}`);
+console.log(`Settings: ${server.settings.site.title}`);
+
+// Manual settings reload
+await server.reloadSettings();
 
 // Graceful shutdown
 process.on("SIGINT", () => server.close());
 ```
 
+### Accessing Settings
+
+```typescript
+import { loadSettings, validateSettingsFile } from "mdsvr";
+
+// Load settings from directory
+const settings = await loadSettings("./docs");
+
+// Validate settings.json
+const result = await validateSettingsFile("./docs");
+if (!result.valid) {
+  console.error(result.errors);
+}
+```
+
+## Generated Endpoints
+
+When enabled in `settings.json`:
+
+| Endpoint             | Description                         |
+| -------------------- | ----------------------------------- |
+| `/sitemap.xml`       | XML sitemap for search engines      |
+| `/feed.xml`          | RSS feed for blog posts             |
+| `/search-index.json` | Search index for client-side search |
+
 ## Features
 
-- **Markdown rendering**: `.md` files automatically rendered as beautiful GitHub-style HTML
+- **Markdown rendering**: `.md` files automatically rendered as beautiful HTML
+- **MDX support**: Interactive components in your docs
 - **Directory listings**: Browse directories with clickable file links
 - **Static files**: Serve any file type with correct MIME types
 - **Syntax highlighting**: Code blocks highlighted with highlight.js
 - **Anchor links**: Headers have clickable anchors
+- **Sidebar navigation**: Auto-generated from your file structure
+- **Table of contents**: Auto-generated from page headings
+- **Dark/Light mode**: Toggle or auto-detect system preference
+- **Full-text search**: Client-side search with keyboard shortcut (⌘K)
+- **SEO optimized**: Open Graph, Twitter Cards, canonical URLs, sitemap
 - **Mobile responsive**: Works on all devices
+- **Hot reload**: Settings auto-reload on change
 - **Path traversal protection**: Secure by default
-- **Zero config**: Works out of the box
+- **Zero config**: Works out of the box, fully customizable
+
+## File Structure
+
+```
+docs/
+├── settings.json      # Site configuration (optional)
+├── README.md          # Homepage (auto-detected)
+├── guide/
+│   ├── getting-started.md
+│   └── configuration.mdx
+├── api/
+│   └── reference.md
+└── assets/
+    └── logo.svg
+```
+
+## Security
+
+- **Path traversal**: Resolved paths are verified to be within root directory
+- **Hidden files**: Files starting with `_` or listed in `settings.json` are hidden
+- **Blocked extensions**: `.env`, `.key`, `.pem`, etc. are blocked by default
+- **Read-only**: Server only serves files, no write operations
+
+## Requirements
+
+- Node.js 18+
 
 ## License
 

package/dist/assets/assets/highlight.js-styles/1c-light.css

@@ -0,0 +1,107 @@
+pre code.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 1em
+}
+code.hljs {
+  padding: 3px 5px
+}
+/*!
+  Theme: 1c-light
+  Description: Style IDE 1C:Enterprise 8
+  Author: (c) Barilko Vitaliy <barilkovetal@gmail.com>
+  Maintainer: @Diversus23
+  Website: https://softonit.ru/
+  License: see project LICENSE
+  Touched: 2023
+*/
+/* end baseline CSS */
+.hljs {
+  color: #0000ff;
+  background: #ffffff
+}
+/* Base color: saturation 0; */
+.hljs-subst {
+  /* default */
+  
+}
+/* purposely ignored */
+.hljs-formula,
+.hljs-attr,
+.hljs-property {
+  
+}
+.hljs-comment {
+  color: #008000
+}
+.hljs-tag {
+  color: #444a
+}
+.hljs-tag .hljs-name,
+.hljs-tag .hljs-attr {
+  color: #444
+}
+.hljs-punctuation,
+.hljs-function,
+.hljs-keyword,
+.hljs-attribute,
+.hljs-selector-tag,
+.hljs-doctag,
+.hljs-name {
+  color: #ff0000
+}
+.hljs-type,
+.hljs-params {
+  color: #0000ff
+}
+/* User color: hue: 0 */
+.hljs-string,
+.hljs-number,
+.hljs-selector-id,
+.hljs-selector-class,
+.hljs-quote,
+.hljs-template-tag,
+.hljs-symbol,
+.hljs-deletion {
+  color: #000000
+}
+.hljs-title,
+.hljs-section {
+  color: #0000ff
+}
+.hljs-regexp,
+.hljs-variable,
+.hljs-template-variable,
+.hljs-link,
+.hljs-selector-attr,
+.hljs-operator,
+.hljs-selector-pseudo {
+  color: #ab5656
+}
+/* Language color: hue: 90; */
+.hljs-literal {
+  color: #ff0000
+}
+.hljs-built_in,
+.hljs-bullet,
+.hljs-code,
+.hljs-addition {
+  color: #0000ff
+}
+/* Meta color: hue: 200 */
+.hljs-meta {
+  color: #963200
+}
+.hljs-meta .hljs-string {
+  color: #963200
+}
+.hljs-meta .hljs-keyword {
+  color: #963200
+}
+/* Misc effects */
+.hljs-emphasis {
+  font-style: italic
+}
+.hljs-strong {
+  font-weight: bold
+}

package/dist/assets/assets/highlight.js-styles/1c-light.min.css

@@ -0,0 +1,9 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: 1c-light
+  Description: Style IDE 1C:Enterprise 8
+  Author: (c) Barilko Vitaliy <barilkovetal@gmail.com>
+  Maintainer: @Diversus23
+  Website: https://softonit.ru/
+  License: see project LICENSE
+  Touched: 2023
+*/.hljs{color:#00f;background:#fff}.hljs-comment{color:green}.hljs-tag{color:#444a}.hljs-tag .hljs-attr,.hljs-tag .hljs-name{color:#444}.hljs-attribute,.hljs-doctag,.hljs-function,.hljs-keyword,.hljs-name,.hljs-punctuation,.hljs-selector-tag{color:red}.hljs-params,.hljs-type{color:#00f}.hljs-deletion,.hljs-number,.hljs-quote,.hljs-selector-class,.hljs-selector-id,.hljs-string,.hljs-symbol,.hljs-template-tag{color:#000}.hljs-section,.hljs-title{color:#00f}.hljs-link,.hljs-operator,.hljs-regexp,.hljs-selector-attr,.hljs-selector-pseudo,.hljs-template-variable,.hljs-variable{color:#ab5656}.hljs-literal{color:red}.hljs-addition,.hljs-built_in,.hljs-bullet,.hljs-code{color:#00f}.hljs-meta,.hljs-meta .hljs-keyword,.hljs-meta .hljs-string{color:#963200}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}

package/dist/assets/assets/highlight.js-styles/a11y-dark.css

@@ -0,0 +1,94 @@
+pre code.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 1em
+}
+code.hljs {
+  padding: 3px 5px
+}
+/*!
+  Theme: a11y-dark
+  Author: @ericwbailey
+  Maintainer: @ericwbailey
+
+  Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css
+*/
+.hljs {
+  background: #2b2b2b;
+  color: #f8f8f2
+}
+/* Comment */
+.hljs-comment,
+.hljs-quote {
+  color: #d4d0ab
+}
+/* Red */
+.hljs-variable,
+.hljs-template-variable,
+.hljs-tag,
+.hljs-name,
+.hljs-selector-id,
+.hljs-selector-class,
+.hljs-regexp,
+.hljs-deletion {
+  color: #ffa07a
+}
+/* Orange */
+.hljs-number,
+.hljs-built_in,
+.hljs-literal,
+.hljs-type,
+.hljs-params,
+.hljs-meta,
+.hljs-link {
+  color: #f5ab35
+}
+/* Yellow */
+.hljs-attribute {
+  color: #ffd700
+}
+/* Green */
+.hljs-string,
+.hljs-symbol,
+.hljs-bullet,
+.hljs-addition {
+  color: #abe338
+}
+/* Blue */
+.hljs-title,
+.hljs-section {
+  color: #00e0e0
+}
+/* Purple */
+.hljs-keyword,
+.hljs-selector-tag {
+  color: #dcc6e0
+}
+.hljs-emphasis {
+  font-style: italic
+}
+.hljs-strong {
+  font-weight: bold
+}
+@media screen and (-ms-high-contrast: active) {
+  .hljs-addition,
+  .hljs-attribute,
+  .hljs-built_in,
+  .hljs-bullet,
+  .hljs-comment,
+  .hljs-link,
+  .hljs-literal,
+  .hljs-meta,
+  .hljs-number,
+  .hljs-params,
+  .hljs-string,
+  .hljs-symbol,
+  .hljs-type,
+  .hljs-quote {
+    color: highlight
+  }
+  .hljs-keyword,
+  .hljs-selector-tag {
+    font-weight: bold
+  }
+}

package/dist/assets/assets/highlight.js-styles/a11y-dark.min.css

@@ -0,0 +1,7 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: a11y-dark
+  Author: @ericwbailey
+  Maintainer: @ericwbailey
+
+  Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css
+*/.hljs{background:#2b2b2b;color:#f8f8f2}.hljs-comment,.hljs-quote{color:#d4d0ab}.hljs-deletion,.hljs-name,.hljs-regexp,.hljs-selector-class,.hljs-selector-id,.hljs-tag,.hljs-template-variable,.hljs-variable{color:#ffa07a}.hljs-built_in,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-type{color:#f5ab35}.hljs-attribute{color:gold}.hljs-addition,.hljs-bullet,.hljs-string,.hljs-symbol{color:#abe338}.hljs-section,.hljs-title{color:#00e0e0}.hljs-keyword,.hljs-selector-tag{color:#dcc6e0}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}@media screen and (-ms-high-contrast:active){.hljs-addition,.hljs-attribute,.hljs-built_in,.hljs-bullet,.hljs-comment,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-quote,.hljs-string,.hljs-symbol,.hljs-type{color:highlight}.hljs-keyword,.hljs-selector-tag{font-weight:700}}

package/dist/assets/assets/highlight.js-styles/a11y-light.css

@@ -0,0 +1,94 @@
+pre code.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 1em
+}
+code.hljs {
+  padding: 3px 5px
+}
+/*!
+  Theme: a11y-light
+  Author: @ericwbailey
+  Maintainer: @ericwbailey
+
+  Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css
+*/
+.hljs {
+  background: #fefefe;
+  color: #545454
+}
+/* Comment */
+.hljs-comment,
+.hljs-quote {
+  color: #696969
+}
+/* Red */
+.hljs-variable,
+.hljs-template-variable,
+.hljs-tag,
+.hljs-name,
+.hljs-selector-id,
+.hljs-selector-class,
+.hljs-regexp,
+.hljs-deletion {
+  color: #d91e18
+}
+/* Orange */
+.hljs-number,
+.hljs-built_in,
+.hljs-literal,
+.hljs-type,
+.hljs-params,
+.hljs-meta,
+.hljs-link {
+  color: #aa5d00
+}
+/* Yellow */
+.hljs-attribute {
+  color: #aa5d00
+}
+/* Green */
+.hljs-string,
+.hljs-symbol,
+.hljs-bullet,
+.hljs-addition {
+  color: #008000
+}
+/* Blue */
+.hljs-title,
+.hljs-section {
+  color: #007faa
+}
+/* Purple */
+.hljs-keyword,
+.hljs-selector-tag {
+  color: #7928a1
+}
+.hljs-emphasis {
+  font-style: italic
+}
+.hljs-strong {
+  font-weight: bold
+}
+@media screen and (-ms-high-contrast: active) {
+  .hljs-addition,
+  .hljs-attribute,
+  .hljs-built_in,
+  .hljs-bullet,
+  .hljs-comment,
+  .hljs-link,
+  .hljs-literal,
+  .hljs-meta,
+  .hljs-number,
+  .hljs-params,
+  .hljs-string,
+  .hljs-symbol,
+  .hljs-type,
+  .hljs-quote {
+    color: highlight
+  }
+  .hljs-keyword,
+  .hljs-selector-tag {
+    font-weight: bold
+  }
+}

package/dist/assets/assets/highlight.js-styles/a11y-light.min.css

@@ -0,0 +1,7 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+  Theme: a11y-light
+  Author: @ericwbailey
+  Maintainer: @ericwbailey
+
+  Based on the Tomorrow Night Eighties theme: https://github.com/isagalaev/highlight.js/blob/master/src/styles/tomorrow-night-eighties.css
+*/.hljs{background:#fefefe;color:#545454}.hljs-comment,.hljs-quote{color:#696969}.hljs-deletion,.hljs-name,.hljs-regexp,.hljs-selector-class,.hljs-selector-id,.hljs-tag,.hljs-template-variable,.hljs-variable{color:#d91e18}.hljs-attribute,.hljs-built_in,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-type{color:#aa5d00}.hljs-addition,.hljs-bullet,.hljs-string,.hljs-symbol{color:green}.hljs-section,.hljs-title{color:#007faa}.hljs-keyword,.hljs-selector-tag{color:#7928a1}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}@media screen and (-ms-high-contrast:active){.hljs-addition,.hljs-attribute,.hljs-built_in,.hljs-bullet,.hljs-comment,.hljs-link,.hljs-literal,.hljs-meta,.hljs-number,.hljs-params,.hljs-quote,.hljs-string,.hljs-symbol,.hljs-type{color:highlight}.hljs-keyword,.hljs-selector-tag{font-weight:700}}

package/dist/assets/assets/highlight.js-styles/agate.css

@@ -0,0 +1,127 @@
+pre code.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 1em
+}
+code.hljs {
+  padding: 3px 5px
+}
+/*!
+   Theme: Agate
+   Author: (c) Taufik Nurrohman <hi@taufik-nurrohman.com>
+   Maintainer: @taufik-nurrohman
+   Updated: 2021-04-24
+
+   #333
+   #62c8f3
+   #7bd694
+   #888
+   #a2fca2
+   #ade5fc
+   #b8d8a2
+   #c6b4f0
+   #d36363
+   #fc9b9b
+   #fcc28c
+   #ffa
+   #fff
+*/
+.hljs {
+  background: #333;
+  color: #fff
+}
+.hljs-doctag,
+.hljs-meta-keyword,
+.hljs-name,
+.hljs-strong {
+  font-weight: bold
+}
+.hljs-code,
+.hljs-emphasis {
+  font-style: italic
+}
+.hljs-section,
+.hljs-tag {
+  color: #62c8f3
+}
+.hljs-selector-class,
+.hljs-selector-id,
+.hljs-template-variable,
+.hljs-variable {
+  color: #ade5fc
+}
+.hljs-meta-string,
+.hljs-string {
+  color: #a2fca2
+}
+.hljs-attr,
+.hljs-quote,
+.hljs-selector-attr {
+  color: #7bd694
+}
+.hljs-tag .hljs-attr {
+  color: inherit
+}
+.hljs-attribute,
+.hljs-title,
+.hljs-type {
+  color: #ffa
+}
+.hljs-number,
+.hljs-symbol {
+  color: #d36363
+}
+.hljs-bullet,
+.hljs-template-tag {
+  color: #b8d8a2
+}
+.hljs-built_in,
+.hljs-keyword,
+.hljs-literal,
+.hljs-selector-tag {
+  color: #fcc28c
+}
+.hljs-code,
+.hljs-comment,
+.hljs-formula {
+  color: #888
+}
+.hljs-link,
+.hljs-selector-pseudo,
+.hljs-regexp {
+  color: #c6b4f0
+}
+.hljs-meta {
+  color: #fc9b9b
+}
+.hljs-deletion {
+  background: #fc9b9b;
+  color: #333
+}
+.hljs-addition {
+  background: #a2fca2;
+  color: #333
+}
+/* Purposely ignored */
+.hljs-operator,
+.hljs-params,
+.hljs-property,
+.hljs-punctuation {
+  
+}
+.hljs-subst {
+  color: #fff
+}
+/* This applies only if HTML auto-merging plugin is enabled by user (#2889) */
+.hljs a {
+  color: inherit
+}
+.hljs a:focus,
+.hljs a:hover {
+  color: inherit;
+  text-decoration: underline
+}
+.hljs mark {
+  background: #555;
+  color: inherit
+}

package/dist/assets/assets/highlight.js-styles/agate.min.css

@@ -0,0 +1,20 @@
+pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}/*!
+   Theme: Agate
+   Author: (c) Taufik Nurrohman <hi@taufik-nurrohman.com>
+   Maintainer: @taufik-nurrohman
+   Updated: 2021-04-24
+
+   #333
+   #62c8f3
+   #7bd694
+   #888
+   #a2fca2
+   #ade5fc
+   #b8d8a2
+   #c6b4f0
+   #d36363
+   #fc9b9b
+   #fcc28c
+   #ffa
+   #fff
+*/.hljs{background:#333;color:#fff}.hljs-doctag,.hljs-meta-keyword,.hljs-name,.hljs-strong{font-weight:700}.hljs-code,.hljs-emphasis{font-style:italic}.hljs-section,.hljs-tag{color:#62c8f3}.hljs-selector-class,.hljs-selector-id,.hljs-template-variable,.hljs-variable{color:#ade5fc}.hljs-meta-string,.hljs-string{color:#a2fca2}.hljs-attr,.hljs-quote,.hljs-selector-attr{color:#7bd694}.hljs-tag .hljs-attr{color:inherit}.hljs-attribute,.hljs-title,.hljs-type{color:#ffa}.hljs-number,.hljs-symbol{color:#d36363}.hljs-bullet,.hljs-template-tag{color:#b8d8a2}.hljs-built_in,.hljs-keyword,.hljs-literal,.hljs-selector-tag{color:#fcc28c}.hljs-code,.hljs-comment,.hljs-formula{color:#888}.hljs-link,.hljs-regexp,.hljs-selector-pseudo{color:#c6b4f0}.hljs-meta{color:#fc9b9b}.hljs-deletion{background:#fc9b9b;color:#333}.hljs-addition{background:#a2fca2;color:#333}.hljs-subst{color:#fff}.hljs a{color:inherit}.hljs a:focus,.hljs a:hover{color:inherit;text-decoration:underline}.hljs mark{background:#555;color:inherit}