Most open-source projects and developer tools ship without proper docs — or with docs that are painful to maintain. The common reasons are always the same: setting up a documentation site feels like a side project on top of the actual project.You need navigation that updates automatically when you add pages. You need code blocks with syntax highlighting. You need it to look professional without a design team. And you need it deployed somewhere fast.The result is that teams either use hosted platforms with limited customization, vendor lock-in and expensive pricing, or they build from scratch and stop maintaining it after the first month.
What makes documentation sites work
Good documentation is not about volume. It is about structure and findability. The sites that developers actually use share a few traits:
Sidebar navigation that reflects the content hierarchy — Readers need to orient themselves instantly.
Fast page loads — Documentation is a reference tool. If it is slow, people go back to the README.
Code blocks that are readable and copyable — Syntax highlighting, language labels, and a copy button are baseline expectations.
Search — Even a basic text search dramatically improves usability.
Good defaults — Spacing, typography, and colors that work out of the box so you can focus on writing.
Markdown-based systems (MDX in particular) solve the authoring problem well. You write content in a familiar format, and the framework handles rendering, routing, and metadata.
Picking the right approach
There are several solid options for documentation in 2026:
Docusaurus — Mature, feature-rich, React-based. Can feel heavy for smaller projects.
Nextra — Lightweight, Next.js-native. Good for simple docs but limited layout control.
GitBook — Hosted, no code required. Limited customization and locked into their platform.
Custom MDX setup — Full control, but you build everything: navigation, search, styling.
Purpose-built templates — Pre-configured documentation frontends that you own and customize.
The tradeoff is always between control and speed. If your docs need to be live this week, starting from a template that already handles navigation, code blocks, and responsive layout saves a significant amount of time.
Setting up Magic Docs
Magic Docs is a free documentation template built with Once UI and Next.js. It is designed for teams and solo developers who want a professional docs site without the configuration overhead.
Magic Docs comes with a Roadmap and Changelog out of the box
Clone and install:
Out of the box, you get:
Automatic sidebar navigation generated from your file structure
MDX support with syntax-highlighted code blocks
Responsive layout with dark and light mode
Copy-to-clipboard on all code blocks
SEO metadata and OpenGraph previews
Table of contents generated from headings
How the content structure works
The navigation is driven by your file system. Each folder becomes a section, and each MDX file becomes a page. A meta.json file in each folder controls the order and section title:
Adding a new page is as simple as creating an MDX file and adding it to meta.json. The sidebar updates automatically — no manual route configuration, no component imports.
This matters more than it sounds. Documentation that is easy to maintain actually gets maintained.
Writing content with MDX
Each page starts with frontmatter for metadata, followed by standard Markdown with optional JSX components:
You can use any Once UI component directly inside your MDX files. This is useful for callouts, interactive examples, or custom layouts that plain Markdown cannot express.
Standard Markdown features — headings, lists, code blocks, links, images — all work as expected and are automatically styled to match the documentation theme.
Customizing the look
Like all Once UI templates, the visual identity is controlled through once-ui.config.js. For documentation sites, a few specific choices make a big difference:
neutral: "slate" — Gives a slightly cooler, more technical feel compared to gray.
border: "conservative" — Sharper corners feel more appropriate for reference content.
surface: "translucent" — Subtle glass effect on the sidebar and header adds depth without distraction.
The layout configuration controls sidebar width, content max-width, and header behavior. Most defaults work well — only adjust if your content is unusually wide (tables, large code blocks).
Deploying documentation
Push to GitHub and connect to Vercel for automatic deployments on every push. This means your docs stay in sync with your codebase without any manual build steps.
For teams, this workflow means anyone can update docs by editing an MDX file and pushing a commit. No CMS login, no deploy button, no waiting.
Structuring docs for discoverability
Once your site is live, the structure of your content determines how well it ranks and how useful it is:
One concept per page — Resist the urge to put everything on a single page. Separate pages rank individually and are easier to link to.
Use descriptive headings — "How to configure authentication" ranks better than "Configuration" and helps readers scan.
Link between pages — Internal links help both readers and search engines understand the relationship between concepts.
Keep pages updated — Stale documentation erodes trust. Even small updates signal that the project is active.
Key takeaways
A documentation site does not need to be a large engineering effort. The critical requirements — automatic navigation, code blocks, responsive layout, and easy content authoring — are solved problems.
Starting with a template like Magic Docs lets you focus on writing content instead of building infrastructure. If your project needs docs and they are not live yet, the bottleneck is almost certainly not the technology.
For teams building their first project with Once UI, the local environment setup guide covers the prerequisites for getting started.
git clone https://github.com/once-ui-system/magic-docs.git
cd magic-docs
npm install
npm run dev
---
title: "Installation guide"
summary: "Install and configure the project in under five minutes."
---
## Prerequisites
Make sure you have Node.js v24 or later installed.
