A beautiful documentation platform built with Finch, showcasing how to use Finch to display Markdown documentation
Welcome! This is the official documentation website for Finch - a powerful web framework for Dart. What makes it special? This documentation platform is built using Finch itself! It's a perfect example of Finch's capabilities in creating elegant, functional web applications.
This project serves two purposes:
- A Documentation Platform: A clean, user-friendly environment for displaying Markdown documentation
- A Real-World Example: Demonstrates Finch's powerful features by using it to document itself (how meta! 🎭)
Think of it as a documentation viewer that's both the teacher and the student - it teaches you about Finch while being built with Finch!
- Docker and Docker Compose installed on your system
- OR Dart SDK (if you prefer running without Docker)
The easiest way to get started:
docker compose up --buildThat's it! Open your browser and navigate to http://localhost:9902 to view the documentation.
If you prefer to run it directly with Dart:
- Install dependencies:
dart pub get- Run the application:
dart run lib/app.dart- Visit
http://localhost:9902in your browser
Want to add or modify documentation? It's super simple!
- Navigate to the
contentfolder - This is where all your Markdown files live - Create or edit
.mdfiles - Write your documentation in standard Markdown format - Restart the application - Your changes will be reflected automatically
content/
├── README.md # Main documentation index
├── 1.install_femch.md # Installation guide
├── 2.finch_cli.md # CLI documentation
└── ... # Your custom docs here!
Pro tip: Follow the numbering convention (1., 2., 3., etc.) to maintain a logical order in your documentation.
- Markdown Support: Write documentation in familiar Markdown syntax
- Beautiful UI: Clean, responsive design built with Twig templates
- Fast & Lightweight: Powered by Finch's efficient routing and templating
- Easy to Customize: Simple structure makes it easy to theme and extend
- Docker Ready: One command deployment with Docker Compose
- RESTful API: JSON API endpoints for programmatic access to documentation
- Multi-language Support: Built-in language switching with query parameters
- Framework: Finch - A powerful Dart web framework
- Template Engine: Twig templates for HTML rendering
- Styling: Custom CSS for a clean, modern look
- Deployment: Docker & Docker Compose support
We'd love your help making this documentation platform even better! Here's how you can contribute:
- Fork the repository on GitHub
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes: Add new features, fix bugs, or improve documentation
- Commit your changes:
git commit -m 'Add some amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request: We'll review it as soon as possible!
- 📖 Improve documentation content
- 🐛 Report bugs or issues
- ✨ Suggest new features
- 🎨 Enhance the UI/UX
- 🌍 Add translations
- 📝 Fix typos or improve clarity
webapp-doc/
├── content/ # 📝 All your Markdown documentation files
├── lib/
│ ├── app.dart # 🚀 Application entry point
│ ├── controllers/ # 🎮 Request handlers
│ ├── route/ # 🛣️ URL routing configuration
│ └── widgets/ # 🎨 Twig templates
├── public/ # 🌐 Static assets (CSS, JS, images)
├── docker-compose.yaml # 🐋 Docker configuration
└── README.md # 📄 This file!
Want to dive deeper into Finch? Check out:
This documentation platform provides a RESTful API for programmatic access to all documentation content in JSON format.
Access any documentation page in JSON format by prefixing the URL with /api/:
GET /api/{page-key}
Example:
curl http://localhost:9902/api/
curl http://localhost:9902/api/install_finchResponse Format:
{
"content": "<html>...</html>",
"title": "Page Title",
"index": [...],
"filename": "1.install_finch.md",
"key": "install_finch",
"configs": {...},
"meta": {...},
"description": "Page description",
"finchVersion": "1.0.0",
"language": {...},
"languages": [...],
"menus": [...]
}All API endpoints support multi-language content via the lang query parameter:
GET /api/{page-key}?lang={language-code}
Supported Languages:
en- English (default)fa- Persian (فارسی)zh- Chinese (中文)- Any other languages added to the
contentfolder
Examples:
# Get documentation in English (default)
curl http://localhost:9902/api/install_finch
# Get documentation in Persian
curl http://localhost:9902/api/install_finch?lang=fa
# Get documentation in Chinese
curl http://localhost:9902/api/install_finch?lang=zhSearch through documentation content:
GET /api/search?q={query}
Example:
curl http://localhost:9902/api/search?q=routingResponse Format:
{
"count": 3,
"data": [
{
"title": "Routing",
"key": "routing",
"description": "Learn about routing in Finch",
"meta": {...}
}
]
}API access is controlled via the enableApi constant in lib/core/configs.dart:
const enableApi = true; // Set to false to disable API endpointsWhen API is enabled:
- All documentation pages are accessible via
/api/{page-key} - Language switching works with
?lang={code}parameter - Search functionality is available at
/api/search
The JSON API enables powerful integrations:
- Mobile Applications: Build native mobile apps that consume documentation
- IDE Plugins: Integrate documentation directly into development environments
- Static Site Generators: Fetch and render documentation in other frameworks
- Documentation Bots: Create chatbots that reference documentation
- CI/CD Pipelines: Validate documentation structure and content
- Analytics: Track documentation usage and popular pages
This project is open source and available under the MIT License.
Having issues or questions? Feel free to:
- Open an issue on GitHub
- Check out existing documentation in the
contentfolder - Contribute to improving this documentation!
Built with ❤️ using Finch
Happy documenting! 📚✨