When developing an application ecosystem, be it large or small, complete and up-to-date documentation is a necessary foundation. As projects scale and evolve — such as the trend toward consolidating various applications into a monorepo — the documentation is under constant pressure for change. Maintaining a simple, universal structure across these different projects is vital for development speed and code comprehension.
Existing Solutions
When the moment arrives to share this documentation publicly, the available options generally fall into two main categories:
- Static Site Generators (e.g., Docusaurus, VuePress, Jekyll): These offer maximum customization and are free to use, but they quickly become a separate software project to maintain. Dealing with dependency updates, theme management, and build issues adds significant maintenance overhead.
- Hosted SaaS Platforms: Solutions like Read the Docs or other subscription-based services offer a ready-to-use hosting infrastructure. The primary drawback? A recurring monthly cost, which often seems disproportionate if you're only hosting a few basic Markdown pages.
Both paths inherently force a trade-off: time/maintenance versus operational cost.
Static Documentation, Client-Side Generation
Tired of the constant search for the ideal documentation management method, I set out to develop a hybrid, zero-maintenance solution to ensure clarity and simplicity for our smaller projects: mdGen.
mdGen is a static documentation generator designed to do one simple thing: take a folder full of .md files and instantly transform it into a navigable static HTML/CSS/JS website, ready to be downloaded and hosted anywhere.
Crucially, it uses neither cloud services nor server-side generators. Everything is generated statically and instantly within the user's browser (client-side).
By leveraging modern Filesystem APIs (where available), mdGen allows users to select a local folder and generate a real-time preview. This means the repository only contains the source .md files, and the preview can be managed completely independently.
Simplified Workflow and Advantages
- Folder Selection: Simply load your local documentation folder.
- Real-Time Preview: Thanks to Filesystem API Observers (all experimental features), any changes you save locally in your editor (VS Code, Sublime, etc.) are instantly reflected in the mdGen browser preview.
- Instant Deploy: When satisfied, you simply click a button and download a
.ziparchive containing all the static assets (HTML, CSS, JS). These files can be uploaded to Netlify, Vercel, or any static CDN with zero ongoing maintenance or build costs.
Note: Filesystem APIs are not yet fully supported on Firefox and Safari, which currently limits the optimal user experience on those browsers.
Contribute
The project is still in an embryonic, primarily personal-use phase, but it is functional enough to be adopted:
- Live Demo: mdgen.hund.studio
- Source Code: GitHub - hund-studio/mdgen
While several limitations remain (e.g., the JS bundle can be optimized with chunk splitting, and the routing system is basic), the core goal is to deliver a lightweight, fast, and free solution.
Top comments (0)