Your docs site is quietly killing trial conversions

Someone finds your repo, gets what the tool does, and clicks "docs." That click is your trial. Whether it turns into an install is decided in the next thirty seconds, on a page most projects treat as an afterthought. Docs rarely fail loudly; they leak. Here are the five leaks I keep finding, and what closing them actually looks like.

The five silent killers

1. The pipeline tax. Every docs edit needs a build: hundreds of MB of node_modules, a stack of config files, a CI job that breaks when the runner image updates. The cost is not build time. The cost is that a typo fix becomes a project, so docs quietly stop getting fixed at all. Stale docs read like an abandoned product, and readers can tell.

2. Heavy pages. If a docs page ships hundreds of kilobytes of JavaScript before the first paragraph paints, anyone on a slow connection is gone. A docs page has one job: show prose and code fast. The payload should prove it.

3. Mobile neglect. Plenty of docs reading happens on a phone, on a couch or in a queue, while something else builds. If the layout only works at desktop width, every one of those sessions feels like a downgrade. A downgrade is a bad moment to ask for an install.

4. Blinding light at 2 a.m. Developers read docs late. A page that ignores the OS dark-mode preference says nobody thought about the reader's context. It is a small signal, and small signals compound across every visit you paid to earn.

5. Self-mangling formatting. Nested lists that flatten, code fences that disappear, pasted markup that renders as garbage characters. Every broken snippet undermines the very tool the docs are vouching for. Formatting failures read as product failures.

A ten-minute audit

Run this against your own docs before changing anything:

• Open a docs page on a real phone, cell data only. Time how long until the first paragraph is readable.
• Flip the OS to dark mode. Does the page follow?
• Fix one typo end to end and count every command and wait between the edit and the live page. More than one command means you are paying the pipeline tax.
• Read one page top to bottom as a stranger. Would you install after it?

Usually the content is fine. The friction around it is what fails.

Make publishing cheaper than the excuse

Docs rot because publishing weighs more than the change you wanted to make. The fix that holds is making publishing one command. My tool, Quillmark, is a single-file Node CLI with zero dependencies and no config. Point it at a Markdown file, or a whole folder of them, and it writes one production-ready, self-contained HTML file: inline CSS, responsive layout, automatic dark mode via prefers-color-scheme, front-matter titles, and solid handling of code blocks, nested lists, images, and escaped markup.

node quillmark.js docs.md -o index.html --title "My Project Docs"

It is deliberately scoped: the Markdown subset real docs use, no plugin system, no watch mode, and multi-page navigation stays on the roadmap rather than in the binary. What that buys is a file you host anywhere and keep forever, and the end of build-pipeline babysitting. When updating docs costs less than skipping the update, docs stay alive. That habit, not another framework, is what turns the docs click into an install.

If that is the stack you want for your own project, the Quillmark CLI is $29 with premium templates and lifetime updates: https://contentclips.gumroad.com/l/quillmark