{"id":30556263,"url":"https://github.com/xentixar/vexdocs","last_synced_at":"2026-01-20T16:57:41.248Z","repository":{"id":308398956,"uuid":"1032383993","full_name":"xentixar/vexdocs","owner":"xentixar","description":"A modern, fast, and lightweight documentation tool with multi-version support and built-in markdown rendering. Create beautiful documentation websites without any external dependencies.","archived":false,"fork":false,"pushed_at":"2025-08-05T18:43:34.000Z","size":213,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-05T19:13:09.938Z","etag":null,"topics":["docs","docs-generator","documentation","documentation-tool","markdown"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xentixar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-05T08:23:54.000Z","updated_at":"2025-08-05T18:43:37.000Z","dependencies_parsed_at":"2025-08-05T19:14:14.723Z","dependency_job_id":"c3832568-53be-41ef-85b7-0740657d7fad","html_url":"https://github.com/xentixar/vexdocs","commit_stats":null,"previous_names":["xentixar/vexdocs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/xentixar/vexdocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xentixar%2Fvexdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xentixar%2Fvexdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xentixar%2Fvexdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xentixar%2Fvexdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xentixar","download_url":"https://codeload.github.com/xentixar/vexdocs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xentixar%2Fvexdocs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272454050,"owners_count":24937513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-28T02:00:10.768Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","docs-generator","documentation","documentation-tool","markdown"],"created_at":"2025-08-28T06:37:10.864Z","updated_at":"2026-01-20T16:57:41.241Z","avatar_url":"https://github.com/xentixar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Vexdocs\n\nA modern, fast, and lightweight documentation tool with multi-version support and built-in markdown rendering. Create beautiful documentation websites without any external dependencies.\n\n## ✨ Features\n\n- 📚 **Multi-version documentation support** - Seamlessly manage and switch between different documentation versions\n- 📝 **Pure JavaScript markdown renderer** - Zero external dependencies for fast, reliable rendering\n- 🎨 **Professional UI** - Modern, clean design with responsive layout and light theme support\n- 🔍 **Smart search functionality** - Real-time filtering with intelligent navigation and keyboard shortcuts\n- 📱 **Mobile-first responsive design** - Optimized experience across all devices and screen sizes\n- 🚀 **Fast static site generation** - Build optimized static sites ready for CDN deployment\n- 🌲 **Intelligent sidebar navigation** - Auto-generated navigation tree from your folder structure\n- ⌨️ **Keyboard shortcuts** - Ctrl+K for search, arrow keys for navigation, and more\n- ♿ **Accessibility features** - ARIA labels, focus management, high contrast support, and screen reader friendly\n- 🎯 **Zero configuration** - Works out of the box with sensible defaults\n- 🔧 **Highly customizable** - Flexible theming and configuration options\n\n## 🚀 Quick Start\n\nVexdocs is designed to get you up and running in seconds. No complex setup, no heavy dependencies.\n\n### Option 1: Create a New Project (Recommended)\n\n```bash\n# Create a new Vexdocs project\nnpx create-vexdocs-app my-docs\n\n# Navigate to your project\ncd my-docs\n\n# Start development server\nnpm start\n```\n\n### Option 2: Using the Vexdocs CLI\n\n```bash\n# Start development server (auto-opens http://localhost:3000)\n./vexdocs serve\n\n# Development mode with enhanced logging and hot reload\n./vexdocs dev\n\n# Build static site for production deployment\n./vexdocs build\n\n# Build prerendered site with SEO optimization\n./vexdocs buildStatic\n\n# Show help and all available commands\n./vexdocs help\n```\n\n### Option 3: Using npm scripts\n\n```bash\n# Quick start - install and run\nnpm start\n\n# Development mode with detailed logging\nnpm run dev\n\n# Build optimized static site\nnpm run build\n\n# Build prerendered site with full SEO optimization  \nnpm run build:static\n\n# Start production server\nnpm run serve\n```\n\n### 🌐 Access Your Documentation\n\nOnce started, your documentation will be available at:\n**http://localhost:3000**\n\nThe server will automatically detect changes and reload your browser in development mode.\n\n## 📁 Project Structure\n\nVexdocs follows a simple, intuitive directory structure:\n\n```\nyour-project/\n├── docs/                    # Your documentation source\n│   ├── config.json         # Global configuration\n│   ├── v1.0/               # Version 1.0 docs\n│   │   ├── README.md       # Version homepage\n│   │   ├── getting-started.md\n│   │   └── api/\n│   │       └── reference.md\n│   ├── v2.0/               # Version 2.0 docs\n│   │   ├── README.md\n│   │   ├── guide.md\n│   │   └── advanced/\n│   │       └── configuration.md\n│   └── assets/             # Images and static files\n├── dist/                   # Generated static site (after build)\n├── assets/                 # Theme assets (CSS, JS)\n│   ├── css/\n│   │   └── main.css\n│   └── js/\n│       ├── app.js\n│       └── markdown-parser.js\n├── src/                    # Vexdocs core files\n│   ├── server.js          # Development server\n│   └── build.js           # Static site builder\n├── vexdocs                 # CLI executable\n└── package.json\n```\n\n### 🎯 Key Concepts\n\n- **Versions**: Each subdirectory in `docs/` represents a documentation version\n- **Automatic Navigation**: Sidebar is generated from your folder structure\n- **Custom Sidebar Ordering**: Control the order of sidebar items through `config.json`\n- **Markdown-First**: All content is written in standard Markdown\n- **Asset Management**: Images and files can be placed in any `assets/` folder\n\n## ⚙️ Configuration\n\nConfigure Vexdocs by creating a `docs/config.json` file. Here's a complete example:\n\n```json\n{\n  \"title\": \"Your Project Documentation\",\n  \"description\": \"Comprehensive documentation for your amazing project\",\n  \"baseUrl\": \"https://docs.yourproject.com\",\n  \"versions\": {\n    \"v2.1\": \"Latest\",\n    \"v2.0\": \"Stable\",\n    \"v1.0\": \"Legacy\"\n  },\n  \"defaultVersion\": \"v2.1\",\n  \"theme\": {\n    \"primaryColor\": \"#2563eb\",\n    \"sidebarWidth\": \"320px\"\n  },\n}\n```\n\n### Configuration Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `title` | Site title displayed in header | \"Documentation\" |\n| `description` | Meta description for SEO | \"Project Documentation\" |\n| `versions` | Available versions with labels | `{\"v1.0\": \"Latest\"}` |\n| `defaultVersion` | Version to show by default | First version |\n| `theme.primaryColor` | Primary brand color | \"#007acc\" |\n| `theme.sidebarWidth` | Sidebar width | \"300px\" |\n\n### 📋 Sidebar Ordering\n\nControl the order of sidebar items by adding a `sidebarOrder` configuration to your `config.json`:\n\n```json\n{\n  \"sidebarOrder\": {\n    \"v1.0\": [\n      \"getting-started.md\",\n      {\n        \"folder\": \"guides\",\n        \"items\": [\n          \"deployment.md\",\n          \"markdown-guide.md\",\n          \"troubleshooting.md\"\n        ]\n      },\n      \"api-reference.md\",\n      \"configuration.md\"\n    ]\n  }\n}\n```\n\n**Features:**\n- **README always first**: The README file is automatically placed at the top\n- **Custom file order**: List files in your desired order\n- **Folder ordering**: Control the order of files within folders\n- **Mixed structure**: Combine files and folders in any order\n- **Fallback behavior**: Items not in the order list appear at the end\n\n**Ordering Rules:**\n1. README files are always placed first\n2. Files and folders are ordered according to your configuration\n3. Files within folders can be ordered using the `items` array\n4. Any items not specified in the order appear at the end\n\n## 📝 Markdown Support\n\nVexdocs includes a powerful, custom-built markdown parser with extensive feature support:\n\n### Core Features\n- **Headers (H1-H6)** with auto-generated anchor links and IDs\n- **Text formatting**: **Bold**, *italic*, ~~strikethrough~~, `inline code`\n- **Code blocks** with syntax highlighting (PHP, JavaScript, TypeScript, Python, Java, HTML, CSS, JSON, Bash, and more)\n- **Lists**: Ordered, unordered, and nested lists with proper indentation\n- **Links and images** with automatic optimization and lazy loading\n- **Tables** with professional styling and responsive design\n- **Blockquotes** with elegant formatting and nested support\n- **Horizontal rules** for content separation\n- **Line breaks** and paragraph handling\n\n### Advanced Features\n- **Auto-linking**: URLs automatically become clickable links\n- **Image optimization**: Automatic alt text and responsive sizing\n- **Table of contents**: Auto-generated from headers\n- **Cross-references**: Link between documents and versions\n- **Code syntax highlighting**: 10+ programming languages supported including PHP, TypeScript, and enhanced patterns\n- **Custom containers**: Warning, info, tip, and danger callouts\n\n## Features List\n\n- ✅ Multi-version support\n- ✅ Fast rendering\n- ✅ Mobile responsive\n\n\u003e **Tip**: Use the search function (Ctrl+K) to quickly find content!\n```\n\n## 🛠️ CLI Commands\n\nVexdocs provides a comprehensive CLI for all your documentation needs:\n\n```bash\n# Development\n./vexdocs serve     # Start development server on http://localhost:3000\n./vexdocs dev       # Development mode with hot reload and enhanced logging\n\n# Production\n./vexdocs build     # Generate optimized static site in dist/ folder\n./vexdocs buildStatic # Generate prerendered site with full SEO optimization\n./vexdocs serve --production  # Serve built static files\n\n# Utilities\n./vexdocs help      # Show all available commands and options\n./vexdocs --version # Show Vexdocs version\n./vexdocs clean     # Clean build artifacts and cache\n```\n\n### Command Options\n\n| Command | Options | Description |\n|---------|---------|-------------|\n| `serve` | `--port \u003cnumber\u003e` | Specify custom port (default: 3000) |\n| `serve` | `--host \u003cstring\u003e` | Specify host address (default: localhost) |\n| `build` | `--output \u003cpath\u003e` | Custom output directory (default: dist/) |\n| `dev` | `--watch` | Enable file watching for auto-reload |\n\n## 🚀 Deployment\n\nDeploy your Vexdocs site to any static hosting service in just a few steps:\n\n### 1. Build Your Site\n\n```bash\n./vexdocs build\n```\n\nThis generates an optimized static site in the `dist/` directory with:\n- Minified HTML, CSS, and JavaScript\n- Optimized images and assets\n- Pre-generated search indices\n- SEO-friendly meta tags and sitemaps\n\n### 2. Deploy to Your Platform\n\n#### GitHub Pages\n```bash\n# Build with SEO optimization for public docs\n./vexdocs buildStatic\ncd dist\ngit init\ngit add .\ngit commit -m \"Deploy documentation\"\ngit push origin main:gh-pages\n\n# Alternative: Standard build for internal docs\n./vexdocs build\ncd dist\ngit init\ngit add .\ngit commit -m \"Deploy documentation\"  \ngit push origin main:gh-pages\n```\n\n#### Netlify\n- Connect your repository\n- Set build command: `./vexdocs build` (or `./vexdocs buildStatic` for SEO)\n- Set publish directory: `dist`\n- Deploy automatically on every push\n\n**Build Command Recommendations:**\n- For public documentation: `./vexdocs buildStatic` (better SEO)\n- For internal docs: `./vexdocs build` (faster builds)\n\n#### Vercel\n```bash\n# Using Vercel CLI\nvercel --prod\n# Or connect via Vercel dashboard\n```\n\n#### AWS S3 + CloudFront\n```bash\n# Upload to S3 bucket\naws s3 sync dist/ s3://your-bucket-name --delete\n# Invalidate CloudFront cache\naws cloudfront create-invalidation --distribution-id YOUR_ID --paths \"/*\"\n```\n\n#### Docker\n```dockerfile\nFROM nginx:alpine\nCOPY dist/ /usr/share/nginx/html/\nEXPOSE 80\nCMD [\"nginx\", \"-g\", \"daemon off;\"]\n```\n\n### 3. Performance Optimization\n\nThe built site includes:\n- **Gzipped assets** for faster loading\n- **Service worker** for offline access\n- **Lazy loading** for images and components\n- **CDN-ready** with proper cache headers\n\n## 🔧 Advanced Features\n\n### Custom Themes\nCreate custom themes by overriding CSS variables:\n\n```css\n:root {\n  --primary-color: #your-color;\n  --sidebar-bg: #custom-bg;\n  --text-color: #your-text-color;\n}\n```\n\n## 🌍 Browser Support\n\nVexdocs is built with modern web standards and supports:\n\n- ✅ **Chrome/Edge** 88+ (Full support)\n- ✅ **Firefox** 78+ (Full support)  \n- ✅ **Safari** 14+ (Full support)\n- ✅ **Mobile Chrome** (Optimized experience)\n- ✅ **Mobile Safari** (Optimized experience)\n- ⚠️ **Internet Explorer** (Not supported)\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Make your changes** and add tests\n4. **Run tests**: `npm test`\n5. **Commit your changes**: `git commit -m 'Add amazing feature'`\n6. **Push to the branch**: `git push origin feature/amazing-feature`\n7. **Open a Pull Request**\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/xentixar/vexdocs.git\ncd vexdocs\n\n# Install development dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Run tests\nnpm test\n```\n\n## 📞 Support\n\n- 📖 **Documentation**: Check out our comprehensive [documentation](docs/)\n- 🐛 **Bug Reports**: [Open an issue](https://github.com/xentixar/vexdocs/issues)\n- 💡 **Feature Requests**: [Start a discussion](https://github.com/xentixar/vexdocs/discussions)\n\n## 📄 License\n\nMIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by the Xentixar**\n\n[Documentation](docs/) • [GitHub](https://github.com/xentixar/vexdocs)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxentixar%2Fvexdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxentixar%2Fvexdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxentixar%2Fvexdocs/lists"}