Skip to main content

​
Quickstart Guide

This guide will take you from zero to your first published documentation page in under 5 minutes. No prior experience with EasyGoDocs required.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 20+ installed (download here)
  • Git for version control
  • A code editor (VS Code recommended)
  • Basic familiarity with Markdown
New to Markdown? It’s just text with simple formatting. # Heading, **bold**, [link](url). That’s 90% of what you need!

​
Installation

1

Clone the Repository

git clone https://github.com/EasyGoDocs/easygodocs.git
cd easygodocs
2

Install Dependencies

EasyGoDocs uses pnpm for package management:
npm install -g pnpm  # If you don't have pnpm
pnpm install
This installs all dependencies including:
  • Next.js 15 (React framework)
  • MDX support (@mdx-js/loader, @next/mdx)
  • UI components (Radix UI, Tailwind)
  • Syntax highlighting (prism-react-renderer)
3

Start Development Server

pnpm dev
The server starts at http://localhost:3000 with Turbopack for blazing-fast hot reload.
Port already in use? The dev server will automatically try the next available port (3001, 3002, etc.).

​
Create Your First Documentation Page

1

Create an MDX File

Create a new file in the src/docs/ directory:
touch src/docs/my-first-doc.mdx
File naming: Use lowercase with hyphens (kebab-case). The filename becomes your URL slug.
2

Add Content

Open src/docs/my-first-doc.mdx and add some content:
# My First Documentation

Welcome to my documentation page! This is incredibly easy.

## Getting Started

Here's a simple example with a list and code.
Your documentation supports:
  • Lists and bullet points
  • Code blocks with syntax highlighting
  • Links to external resources
  • And much more!
3

View Your Page

Navigate to http://localhost:3000/mdx/my-first-docThat’s it! Your documentation is live with:
  • Auto-generated table of contents
  • Syntax-highlighted code blocks
  • Responsive design
  • Dark mode support

​
Project Structure

Understanding the file organization: 
easygodocs/
├── src/
│   ├── docs/                          # 📝 Your MDX files
│   │   ├── react.mdx                 # Example: /mdx/react
│   │   ├── install-git-ubuntu.mdx    # Example: /mdx/install-git-ubuntu
│   │   └── my-first-doc.mdx          # Your new doc: /mdx/my-first-doc
│   │
│   ├── db/                            # 🗂️ JSON documentation (advanced)
│   │   ├── react.json                # Structured doc data
│   │   └── export-json/
│   │       └── db-index.ts           # Auto-generated index
│   │
│   ├── app/
│   │   └── (main)/
│   │       ├── [slug]/               # JSON doc routes
│   │       │   └── page.tsx          # Renders from src/db/*.json
│   │       └── mdx/
│   │           └── [slug]/           # MDX doc routes  
│   │               └── page.tsx      # Renders from src/docs/*.mdx
│   │
│   ├── components/
│   │   ├── documentation/
│   │   │   └── documentation-component.tsx  # JSON renderer
│   │   └── ui/
│   │       └── code-block.tsx        # Syntax highlighting
│   │
│   └── lib/
│       └── mdx-headings.ts           # TOC extraction
│
├── scripts/
│   ├── generate-db-index.cjs         # Index JSON docs
│   └── generate-mdx-routes.cjs       # List MDX files
│
├── package.json                       # Dependencies & scripts
└── next.config.ts                     # Next.js + MDX config
Don’t edit auto-generated files: src/db/export-json/db-index.ts and src/app/(main)/mdx/mdx-files.json are created by build scripts.

​
Build Scripts Explained

EasyGoDocs uses Node.js scripts to generate documentation indexes:

​
generate-mdx-routes.cjs

// Scripts location: scripts/generate-mdx-routes.cjs:1
// Scans src/docs/ for all .mdx files
// Outputs src/app/(main)/mdx/mdx-files.json

// Run manually:
pnpm run generate-mdx-routes
This creates a JSON list of all MDX files for build optimization.

​
generate-db-index.cjs

// Scripts location: scripts/generate-db-index.cjs:1
// Scans src/db/ for all .json files
// Generates static imports in src/db/export-json/db-index.ts

// Run manually:
pnpm run generate-db-index
Required for JSON-based docs to work in serverless environments (like Vercel).
Build process: Both scripts run automatically during pnpm build (see package.json:7).

​
Available Scripts

# Development
pnpm dev              # Start dev server with Turbopack

# Production
pnpm build            # Build for production
pnpm start            # Start production server

# Code Quality
pnpm lint             # Check for linting errors
pnpm lint:fix         # Auto-fix linting issues

# Generators (auto-run during build)
pnpm run generate-db-index      # Create DB index
pnpm run generate-mdx-routes    # List MDX files

​
Adding Features to Your Documentation

​
Code Blocks with Syntax Highlighting

```typescript
interface User {
  id: number;
  name: string;
}

const user: User = {
  id: 1,
  name: "John Doe"
};
```
Supported languages: JavaScript, TypeScript, Python, Bash, JSON, YAML, and 100+ more via Prism.

​
Lists and Steps

## Ordered List
1. First step
2. Second step
3. Third step

## Unordered List  
- Feature A
- Feature B
- Feature C

[Link text](https://example.com)

![Checks passed](/images/checks-passed.png)

​
Tables

| Feature | Support |
|---------|--------|
| MDX | ✅ |
| JSON | ✅ |
| Hot Reload | ✅ |

​
Blockquotes

> This is a blockquote. Use it for callouts or important notes.

​
Using React Components in MDX

MDX lets you import and use React components: 
import { MyButton } from '../components/MyButton'

# Interactive Documentation

Click this button:

<MyButton onClick={() => alert('Hello!')}>  
  Click Me
</MyButton>
Component imports: Path resolution is relative to the MDX file location. Use @/ alias for absolute imports from src/.

​
Next Steps

Explore Features

Learn about advanced capabilities like JSON docs, custom components, and styling.

Contribute

Add your own documentation and earn GSSoC points!

Deploy to Vercel

vercel deploy
One command deployment with zero configuration.

Join the Community

Open issues, submit PRs, and help shape the future of EasyGoDocs.

​
Troubleshooting

Next.js will automatically use the next available port. Check the terminal output for the actual URL.Or manually specify a port:
pnpm dev -- -p 3001
  1. Ensure the file is in src/docs/ with .mdx extension
  2. Check the filename has no spaces (use hyphens)
  3. Restart the dev server (Ctrl+C, then pnpm dev)
  4. Visit /mdx/[your-filename] (without the .mdx extension)
Make sure your code block specifies a language:
```javascript  // ✅ Highlighted
```          // ❌ Plain text
The TOC is generated from Markdown headings (#, ##, ###). Ensure you’re using standard Markdown syntax, not HTML tags.

​
Learning Resources

Need help? Open an issue on GitHub or check out existing discussions.

View GitHub Issues →

Build docs developers (and LLMs) love

Get started for freeTalk to us