NCMDS is a zero-configuration documentation site builder that converts Markdown files into beautiful, dark-themed documentation websites with automatic navigation, AI-powered assistance, and an optimized reading experience.
Author: Eduardo J. Barrios (edujbarrios)
- 🏠 Local-First - Runs on localhost by default, no cloud required
- 🤖 AI-Powered Chat - Ask questions about documentation with built-in AI assistant and switchable models
- 📤 Export Functionality - Export documentation to PDF and QMD (Quarto Markdown) formats
- 🎨 Dark Theme - Optimized for comfortable reading and coding
- 📱 Responsive Design - Works seamlessly on desktop and mobile
- 🔍 Auto Navigation - Automatic table of contents and page navigation
Caution
Default Mode: NCMDS runs locally on your machine. Cloud deployment is completely optional.
# Clone repository
git clone https://github.com/edujbarrios/ncmds.git
cd ncmds
# Install dependencies
pip install -r requirements.txt
# Run locally (default)
python ncmds.pyOpen http://localhost:5000 in your browser.
That's it! The tool is designed to run on localhost by default. No additional configuration needed.
If you want to use NCMDS as a reusable module in development:
# Install in editable mode (one time only)
pip install -e .This allows you to:
- Run
ncmdscommand from anywhere - Import NCMDS in other Python projects
- Use changes immediately without reinstalling
# Run via CLI command
ncmds
# Or with custom port
PORT=8000 ncmds
# Or still use the traditional way
python ncmds.pyfrom ncmds import app, DocumentationSite, config_manager
from ai_chat import register_ai_chat_routes
from export import register_export_routes- Add
.mdfiles to thedocs/folder - Use numeric prefixes for ordering:
01-index.md,02-guide.md - Write in Markdown
- Reload browser to see changes
Edit config/config.yaml:
site_name: "My Documentation"
author: "Your Name"
description: "Your site description"
hero:
enabled: true
project_name: "My Project"
company: "Your Company"
tagline: "Your tagline here"
description: "Your project description"
# AI Chat Assistant
ai_chat:
enabled: true
api_url: "https://api.llm7.io/v1/chat/completions"
api_key: "your-api-key" # Get your key from LLM7.io
model: "gpt-4o-mini" # Default model (switchable in chat UI)
provider: "LLM7.io"
AI Features:
- Model selector dropdown to switch between available models in real-time
- Context-aware responses based on current documentation page
- Fullscreen mode for better reading experience
NCMDS includes a powerful export module that allows you to export your documentation to different formats:
- PDF Export - Generate professional PDFs with WeasyPrint
- QMD Export - Export to Quarto Markdown format for rendering with Quarto
- Customizable Settings - Configure project name, paper size, and more
- Easy to Use - Click floating export buttons on any documentation page
- Automatic table of contents generation
- Professional cover page with project branding
- Optimized for print and digital reading
NEW: NCMDS now supports publishing your site via Vercel with auto-detection!
See the Deployment Guide for complete instructions on deploying to production.
NEW: Internal Search is now available to quickly find content across your documentation.
NEW: NCMDS now supports extended YAML frontmatter fields: tags, difficulty, owner, and writer (plus alias writter).
---
title: "API Authentication"
tags:
- api
- auth
difficulty: "intermediate"
owner: "backend-team"
writer: "alice"
---What this adds:
- Automatic metadata chips on each documentation page
- Search filtering by metadata directly in the search bar
- Better content organization and ownership tracking
Search filter examples:
tag:api authenticationdifficulty:beginnerowner:docs-teamwriter:alice
Full documentation available at /docs when running the server, or view:
- Getting Started
- Configuration Guide
- Markdown Features
- Theme Creation
- Deployment Guide
- Template Components
- Flask - Web framework
- Python-Markdown - Markdown processing with extensions
- PyYAML - Configuration management
- Highlight.js - Syntax highlighting
- LLM7.io - AI chat integration with model switching
- Quarto - QMD rendering support in PDF format (optional)
- Project documentation
- Technical documentation
- API documentation
- Personal wikis
- Educational materials
- User guides
Inspired by Docusaurus, MkDocs, Read the Docs, and Quarto.
- Author: edujbarrios - eduardojbarriosgarcia@gmail.com