Skip to main content
OwnDocs

Documentation

5 min read

OwnDocs is a self-hosted documentation platform that turns Markdown files into a searchable, secure documentation site. It's built on Next.js v16, MDX v3, and Tailwind CSS v4.

You get 25 MDX components, 40+ features with their own pages, 26 color themes, full-text search, dark mode, password protection, and llms.txt endpoints for AI agents — and you don't have to configure any of it.

Quick Start

Four steps to a running site:

  1. Clone the repository

    Bash
    Bash
    git clone https://github.com/devops-infinity/owndocs.git my-docs
cd my-docs

  2. Set up environment variables

    The setup script generates the passwords, JWT keys, and cookie salts.

    Bash
    Bash
    bash scripts/setup-env.sh

  3. Install dependencies and start

    Bash
    Bash
    npm install
npm run dev

  4. Open your docs site

    Visit http://localhost:3000. Any .mdx file you add under app/ becomes a page — no routing setup, no config files, no build plugins.

For the full setup guide and deployment options, see Getting Started.

What You Get

OwnDocs is one platform with several parts. Here's what ships with it, grouped by job. For a page-by-page tour, start with the features hub or the getting started guide.

Content and Authoring

Write pages in Markdown and drop in React components where you need them. OwnDocs supports GitHub Flavored Markdown (tables, strikethrough, task lists), six callout types, and 25 MDX components for API references, diagrams, and more.

  • MDX Support — Markdown with embedded React components
  • Syntax Highlighting — 71 languages with language detection, line numbers, line highlighting, diff markers, word highlighting, collapsible sections, and copy-to-clipboard
  • Code Groups — Tabbed code blocks for the same concept in multiple languages or package managers
  • Mermaid Diagrams — 16 diagram types (flowchart, sequence, ER, class, state, gantt, pie, gitGraph, journey, mindmap, timeline, and more) rendered in Markdown
  • GitHub-Style Alerts — Note, tip, important, warning, caution, and danger callouts
  • Copy Page as Markdown — Copy the whole page as Markdown or plain text for pasting into AI tools

Components

Each documentation pattern — API references, feature comparisons, release announcements — has its own MDX component. They're responsive, keyboard-accessible, dark-mode compatible, and styled to match your theme. See the component pages for live examples.

  • API Documentation Blocks — Styled endpoint display with color-coded method badges (GET, POST, PUT, PATCH, DELETE), headers, multi-response tabs, authentication indicators, rate limiting, deprecation notices, and auto-generated cURL examples
  • Parameter and Response Fields — Structured field docs with type badges, location indicators, required/optional markers, and default values
  • Tabs — Tabbed panels with keyboard navigation
  • Steps — Numbered step-by-step guides with visual connectors
  • Cards — Feature showcases and navigation grids with configurable columns
  • Accordion — Collapsible sections with smooth animation
  • Badge — Inline status indicators in 5 variants (default, info, success, warning, danger)
  • File Tree — Directory structure from indented text
  • Changelog — Release timeline with 7 typed labels (added, fixed, changed, removed, breaking, deprecated, security)
  • Release Notes — User-facing announcements with 8 highlight types
  • Image Zoom — Click-to-zoom lightbox for images
  • Embed — Responsive iframe embeds with a URL allowlist (YouTube, GitHub)
  • Comparison Table — Side-by-side feature comparison with 10 visual indicator types and optional column highlighting

The sidebar, search, breadcrumbs, table of contents, and page navigation are generated from your file structure. Add a file and it shows up in every navigation surface.

  • Auto-Generated Sidebar — Built from the file system with 3-level depth and name formatting for 120 technical acronyms
  • Full-Text Search — Search all pages with scored ranking, context snippets, and Cmd+K / Ctrl+K
  • Table of Contents — Scroll-spy TOC on desktop, collapsible TOC on mobile
  • Breadcrumb Navigation — Path breadcrumbs on every page
  • Previous/Next Navigation — Sequential page links at the bottom of each article

Themes and Accessibility

Pick a palette and a dark-mode preference. OwnDocs ships 26 color themes, each with matching light and dark modes. Set THEME_VARIANT to switch — no code changes or CSS overrides.

  • 26 Theme Variants — emerald, amber, blue, cyan, fuchsia, gray, green, indigo, lime, mauve, mist, neutral, olive, orange, pink, purple, red, rose, sky, slate, stone, taupe, teal, violet, yellow, and zinc via the THEME_VARIANT environment variable
  • Dark Mode Toggle — Light, dark, and system modes that follow prefers-color-scheme and persist in localStorage
  • Responsive Design — Mobile layout with collapsible sidebar and backdrop overlay
  • Skip to Content — Keyboard-accessible skip link for screen reader users
  • Focus Management — Route-change focus and visible focus indicators
  • Reduced Motion — Respects prefers-reduced-motion
  • Print Stylesheet — Printing-ready layout for documentation

Security

In private mode, OwnDocs protects pages with password authentication, JWT sessions, browser fingerprinting, timing-safe password comparison, CSRF protection, and rate limiting. It configures nine HTTP security headers, and four layers of crawler blocking keep private pages out of search indexes.

  • Password Protection — JWT sessions with 14-day expiry and browser fingerprinting
  • Secure Cookies — __Host- prefix, httpOnly, secure, sameSite: lax
  • Rate Limiting — 5 login attempts per IP with a 15-minute lockout
  • 9 Security Headers — HSTS, CSP, X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy, X-DNS-Prefetch-Control, and X-Robots-Tag in private mode
  • Public/Private Mode — Toggle open and password-protected access with the ACCESS_MODE environment variable

SEO and AI

In public mode, OwnDocs generates sitemaps, OpenGraph tags, canonical URLs, structured data, and AI endpoints from your content.

  • Dynamic Sitemap — Auto-generated sitemap.xml in public mode
  • OpenGraph and Twitter Cards — Per-page social sharing tags with descriptions pulled from content
  • Canonical URLs — <link rel="canonical"> on every page
  • JSON-LD Structured Data — TechArticle and BreadcrumbList schema.org markup
  • Dynamic robots.txt — Blocks 28 named crawlers plus a catch-all rule in private mode; open crawling in public mode
  • llms.txt and llms-full.txt — Auto-generated endpoints for AI agents
  • Health Check — /api/health endpoint for uptime monitoring

Pages

Getting Started (7 pages)

Features (53 pages)

API — Code — Components — Content — Diagrams — Markdown — Platform

Api (3 pages)

API Blocks — Parameter Fields — Response Fields

Code (8 pages)

Code Blocks — Line Highlighting — Line Numbers — File Title — Diff Highlighting — Word Highlighting — Collapsible Code — Code Groups

Components (12 pages)

Alerts — Tabs — Steps — Cards — Accordion — Badge — Comparison Table — File Tree — Image Zoom — Embed — Changelog — Release Notes

Content (3 pages)

Math — Snippets — Variables

Diagrams (1 page)

Mermaid

Markdown (6 pages)

Tables — Inline Code — Links — Text Formatting — Lists — Blockquotes

Platform (13 pages)

Search — Theme Variants — Table of Contents — Breadcrumbs — Page Meta — Page Metadata — Related Pages — Heading Anchors — AI Deeplinks — Smart 404 — OG Images — Announcement Bar — MCP Server

API Reference (3 pages)

Integrations (3 pages)

Total Documentation Pages: 66

Was this page helpful?