Documentation That Developers Actually Want to Write

Documentation is an essential part of software development in the open-source world. We all know it's crucial, yet somehow, it always ends up as a collection of outdated markdown files and half-finished README.md lurking in our repositories. That's exactly why Query Docs exists—not to reinvent documentation but to make it actually work for both contributors and developers.

I created Query Docs because I was drowning in half-baked documentation solutions that felt like trying to solve a Rubik's Cube blindfolded. The frustration was real: great software deserves great documentation, but the tools to create it often felt like they were working against us.

What do Query Docs do? It takes your existing markdown files—the ones you're already writing—and transforms them into a complete documentation site. The kind that doesn't make your users want to file a bug report just to navigate it.

And no, this isn't another "60-second setup" tool that secretly requires a PhD in configuration files to use properly.

Here's what you get:

• Navigation that doesn't hate your users: A clear page hierarchy with intuitive structure (yes, even for complex products)
• Search that works: Type a term and find relevant results—seems basic, but it's surprisingly rare
• Workflows that don't fight you: Your content stays in simple markdown—easy to update, version, and collaborate on
• Full syntax highlighting: Code blocks that are readable, with proper language detection

Ready to transform your documentation experience? It takes seconds to get started without the usual headaches:

1​. Create a new project using the Query CLI:

Use either of these commands—whatever works for you:

# With pnpm
pnpm dlx @qery/query create

# With npm
npx @qery/query create

When prompted, select the docs project type. This sets up everything with sensible defaults.

2​. Launch your development server:

Navigate to your new project directory and run:

pnpm dev

3​. View your site:

Open your browser and go to http://localhost:3000. Your starter documentation site is ready for your content.

Tada!

Here's where the frustration-free experience really begins. Create a SUMMARY.md file—it's like a table of contents that makes sense to humans:

# Summary

## Intro Stuff  
- [What Even Is This?](index.md) Your elevator pitch  
- [Quick Start](getting-started.md) The "shut up and let me code" section  

## Features  
- [Feature X](features/x.md) The thing your VP overpromised to clients  
- [Feature Y](features/y.md) The thing that actually works  

Each link points to a markdown file. Your index.md could be as simple as:

# Welcome to Our App

We made a thing! It (probably) won't crash.

## What's This For?

Imagine [insert competitor] but with fewer existential crises during setup.

Query Docs is designed with a simple, logical structure that stays out of your way:

src/  
└── docs/   # Your markdown lives here  
└── api/    # Search endpoints  
└── pages/  # Where the server turns MD into HTML  

When you organize your content, it creates a file-based routing system that mirrors your documentation's logical structure. The docs generator produces JSON files containing all the necessary information—content, navigation links, table of contents—ready for your server to render.

Query's JSX Server-Side Rendering lets you build dynamic documentation pages with a component-based architecture—without loading your users' browsers with unnecessary JavaScript. The result? Fast-loading docs that work everywhere, even on that ancient laptop your QA person refuses to upgrade.

Documentation shouldn't look like it was styled by someone who thinks "UX" is a myth. Query Docs uses Tailwind to make your docs match your brand without requiring design expertise.

Let's talk about search—what's the point of documentation if no one can find anything? Query Docs pre-builds a search index, so when users type a keyword from your content, they get relevant results. There's no spinning up Elasticsearch, no extra configuration, or third parties—just functional search that understands your content.

Beyond the basics, Query Docs includes features that solve real documentation problems:

• Smart navigation: Automatically generates previous/following links between pages
• Hierarchical TOC: Creates structured navigation from your content organization
• Customizable templates: Use your own JSX templates for complete control
• Metadata support: Add YAML frontmatter for additional page information

Is It Perfect? Of course not—no documentation system is. However, Query Docs focuses on solving the problems that matter to open-source creators and their users. The goal isn't perfection; it's making documentation less painful and more useful.

So, should you give Query Docs a try? If you're tired of documentation being the worst part of your development process, absolutely. At worst, you'll save a few hours of frustration. At best, you might—and I say this with cautious optimism—not hate writing docs anymore.

And that might be the most revolutionary feature of all.

Learn More About Query Docs

• See it in action
• Query Docs
• Query Docs Server

---

Disclaimer: As a dyslexic, I rely on AI tools to help write and organize blog articles. While I review the content, AI helps me articulate my thoughts more clearly.