Markdown2Site - React Library

A powerful, fully configurable React library for building beautiful, responsive websites from markdown files.

Features:

• 📝 Markdown-first content
• 🎨 Complete theme customization (light & dark modes)
• 🌓 Built-in dark mode toggle
• 📱 Fully responsive design
• ⚙️ Configurable header, footer, sidebar, and colors
• 🚀 Production-ready
• 💪 Uses React Router for navigation

Installation

npm install markdown2site

Quick Start

1. Create your app

// App.js
import { SiteConfigProvider, MarkdownSite } from 'markdown2site';

const config = {
  theme: {
    light: {
      primary: '#667eea',
      secondary: '#764ba2',
      text: '#333',
      background: '#fafafa',
      border: '#ddd',
      codeBackground: '#f5f5f5',
      accent: '#007bff',
    },
    dark: {
      primary: '#667eea',
      secondary: '#764ba2',
      text: '#f0f0f0',
      background: '#1a1a1a',
      border: '#444',
      codeBackground: '#2d2d2d',
      accent: '#4da6ff',
    },
  },
  header: {
    logo: '📚 My Site',
    logoLink: '/',
    backgroundColor: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    textColor: '#ffffff',
    height: '60px',
  },
  footer: {
    text: '© 2024 My Site',
    backgroundColor: '#f5f5f5',
    textColor: '#666',
    links: [
      { label: 'GitHub', url: 'https://github.com', external: true },
    ],
  },
  sidebar: {
    width: '220px',
    backgroundColor: '#f9f9f9',
    textColor: '#333',
    highlightColor: '#667eea',
  },
  postsList: [
    { title: 'Getting Started', slug: 'getting-started' },
    { title: 'Guide', slug: 'guide' },
  ],
};

export default function App() {
  return (
    <SiteConfigProvider config={config}>
      <MarkdownSite />
    </SiteConfigProvider>
  );
}

2. Add markdown files

public/
  └── markdown/
      ├── index.md
      └── posts/
          ├── getting-started.md
          └── guide.md

3. Run it

npm start

Done! Your site is running.

Configuration

All customization happens through the config object passed to SiteConfigProvider.

Theme

Define colors for light and dark modes:

theme: {
  light: {
    primary: '#667eea',           // Primary accent color
    secondary: '#764ba2',          // Secondary accent
    text: '#333',                  // Text color
    background: '#fafafa',         // Page background
    border: '#ddd',                // Border color
    codeBackground: '#f5f5f5',    // Code block background
    accent: '#007bff',             // Additional accent
  },
  dark: {
    // Same keys, dark mode colors
  },
}

Header

Customize the top navigation bar:

header: {
  logo: '📚 My Site',                                    // Text or image URL
  logoLink: '/',                                         // Logo link target
  backgroundColor: 'linear-gradient(...)',              // Header background
  textColor: '#ffffff',                                  // Text color
  height: '60px',                                        // Header height
  align: 'space-between',                                // 'space-between' or 'center'
}

Logo Options:

Text logo (emoji or text):

logo: '📚 My Site'

Image logo (auto-constrained to max 150px):

logo: '/logo.png'           // Local file
logo: 'https://example.com/logo.png'  // External URL

Alignment:

• 'space-between' - Logo on left, nav on right (default)
• 'center' - Everything centered, no nav menu

Footer

Add a footer section:

footer: {
  text: '© 2024 My Company',                           // Footer text
  backgroundColor: '#f5f5f5',                           // Footer background
  textColor: '#666',                                    // Footer text color
  links: [                                               // Footer links
    { label: 'GitHub', url: 'https://github.com', external: true },
    { label: 'Twitter', url: 'https://twitter.com', external: true },
    { label: 'Blog', url: '/blog', external: false },
  ],
}

Sidebar

Customize the highlights sidebar that appears on the right:

sidebar: {
  width: '220px',                 // Sidebar width
  backgroundColor: '#f9f9f9',    // Background color
  textColor: '#333',              // Text color
  borderColor: '#ddd',            // Border color
  highlightColor: '#667eea',     // Color for h2 highlights
  padding: '1rem',                // Internal padding
  fontSize: '0.9rem',             // Font size
}

Posts Navigation

Control which posts appear in the header dropdown:

postsList: [
  { title: 'Getting Started', slug: 'getting-started' },
  { title: 'Advanced Guide', slug: 'advanced-guide' },
  { title: 'API Reference', slug: 'api-reference' },
]

Paths

Customize where markdown files are located:

markdownPath: '/markdown',           // Path to index.md
postsPath: '/markdown/posts',        // Path to posts directory
defaultDarkMode: false,              // Start in dark mode?

File Structure

public/
  └── markdown/
      ├── index.md                   # Home page
      └── posts/
          ├── getting-started.md     # First post
          ├── guide.md               # Second post
          └── api-reference.md       # Third post

Routing

URLs are automatically generated from file names:

| File | URL | |------|-----| | public/markdown/index.md | / | | public/markdown/posts/getting-started.md | /getting-started | | public/markdown/posts/contact.md | /contact |

Components

MarkdownSite

Main component that provides routing and layout.

<MarkdownSite />

SiteConfigProvider

Wraps your app and provides configuration context.

<SiteConfigProvider config={myConfig}>
  <MarkdownSite />
</SiteConfigProvider>

MarkdownRenderer

Renders individual markdown content:

import { MarkdownRenderer } from 'markdown-site';

<MarkdownRenderer markdown={mdContent} title="My Post" />

Header, Footer, Sidebar

Individual components if you need fine-grained control.

import { Header, Footer, Sidebar } from 'markdown-site';

<Header />
<Footer />
<Sidebar headings={headings} />

Hooks

useMarkdownHeadings()

Extract heading structure from markdown:

import { useMarkdownHeadings } from 'markdown-site';

const headings = useMarkdownHeadings(markdownString);
// Returns: [
//   { level: 2, text: 'Section', id: 'section' },
//   { level: 3, text: 'Subsection', id: 'subsection' }
// ]

useSiteConfig()

Access the configuration from anywhere:

import { useSiteConfig } from 'markdown-site';

function MyComponent() {
  const { config, currentTheme, isDarkMode, setIsDarkMode } = useSiteConfig();
  // Use configuration values
}

Markdown Features

All standard markdown is supported:

# Heading 1
## Heading 2 (appears in sidebar)
### Heading 3 (indented in sidebar)

**Bold** and *italic* text

[Links](https://example.com)

- Lists
- Work
- Great

```javascript
// Code blocks are syntax highlighted
console.log('Hello');

| Tables | Work | Too | |--------|------|-----| | Cell | Cell | Cell|

Blockquotes work

## Dark Mode

Users can toggle dark mode with the button in the header. Both themes are fully customizable.

## Deployment

Build for production:

```bash
npm run build

Netlify

1. Push to GitHub
2. Connect repo to Netlify
3. Set build command: npm run build
4. Set publish directory: build

GitHub Pages

npm run build
# Commit and push build/ folder

Any Static Host

Upload the build/ folder to any static hosting service.

API Reference

Config Object

interface ThemeColors {
  primary: string;
  secondary: string;
  text: string;
  background: string;
  border: string;
  codeBackground: string;
  accent: string;
}

interface SiteConfig {
  theme?: {
    light?: ThemeColors;
    dark?: ThemeColors;
  };
  header?: {
    logo?: string;
    logoLink?: string;
    backgroundColor?: string;
    textColor?: string;
    height?: string;
  };
  footer?: {
    text?: string;
    backgroundColor?: string;
    textColor?: string;
    links?: Array<{
      label: string;
      url: string;
      external?: boolean;
    }>;
  };
  sidebar?: {
    width?: string;
    backgroundColor?: string;
    textColor?: string;
    borderColor?: string;
    highlightColor?: string;
    padding?: string;
    fontSize?: string;
  };
  postsList?: Array<{
    title: string;
    slug: string;
  }>;
  markdownPath?: string;
  postsPath?: string;
  defaultDarkMode?: boolean;
}

Examples

See the src/example/ folder in the repository for a complete working example.

License

MIT - Use freely in your projects

Support

• 📖 Full Documentation
• 🐛 Report Issues
• 💬 Discussions

Happy building! 🚀