Documentation Site
Definition
A documentation site is organised for lookup rather than for reading end to end. The usual shape is a sidebar of sections, a search box, a getting-started path for newcomers, and reference pages that people land on directly from a search engine. Content is generally written in Markdown and built by a tool — MkDocs, Docusaurus, Sphinx, Hugo and others — which turns the source into a folder of HTML, CSS and JavaScript. That output is the important detail. Almost every documentation generator produces static files, with search handled by a prebuilt index loaded in the browser instead of a query against a server. A folder of files is exactly what a static host serves, which is why so much documentation ends up hosted this way.
Why It Matters
Documentation is read under pressure, usually by somebody whose build has stopped working. Speed and search are the two things that matter, and both come easily with static files: pages served from an edge network open immediately, and there is no database to be slow. Versioning is the part people underestimate — users on version 1 need version 1's documentation, and publishing only the latest strands everyone who has not upgraded. The other quiet cost is broken deep links. Documentation pages collect links from forums, issue trackers and other people's posts, and reorganising the sidebar without redirects breaks all of them on the same day.
How It Works
Write the pages in Markdown, run the generator, and it writes a folder — commonly named 'site', 'build' or 'public' — containing an index.html at the root and one HTML file per page. Upload that folder as it stands; no server process is needed, because every page already exists as a file. Keep links between pages relative so the site behaves the same locally and when published. Add a custom 404 page, since a mistyped documentation address is a common way to arrive. If you version the documentation, publish each version under its own path or address and put a visible version marker on every page, so a reader who arrived from a search engine can tell which one they are looking at.
Real-World Example
A small open-source project builds its docs with a generator, ends up with a folder of 60 HTML pages plus a search index, and publishes the lot at projectname-docs.99helpers.site. There is no build server and no container involved — the folder that works when opened locally works when uploaded. A new release changes the API; the maintainer publishes the rebuilt folder to the same address, spots a broken navigation link, and rolls back to the previous version within a minute.
Common Mistakes
- ✕Uploading the Markdown source instead of the built folder — the browser shows raw text with the symbols still in it, because nothing has turned it into HTML
- ✕Leaving absolute paths in the generator config when the site is published under a subpath — every stylesheet and link resolves one level too high and the pages arrive unstyled
- ✕Reorganising the page structure without redirects — years of forum answers and issue threads stop working, and you hear about it for months
Related Terms
Style Guide
A style guide is the agreed set of rules for how something should look or be written. In publishing it governs language and punctuation; in design and front-end work it documents type, spacing, colour and components with worked examples.
Static Site Generator
A static site generator is a tool that turns content and templates into a folder of finished HTML files. Hugo, Eleventy, Astro, Jekyll and Next.js in export mode are the common ones.
index.html
index.html is the file a web server returns when a visitor asks for a folder rather than a named file. It is the default document for the site root and for every directory inside it.
Custom 404 Page
A custom 404 page is the page a site shows when someone asks for an address that does not exist, written by you rather than left to the host's default. It is returned with a 404 status code.
Markdown File
Markdown is plain text with a light set of conventions — hashes for headings, asterisks for emphasis, hyphens for lists — that a converter turns into HTML. It is a source format, not a display format: a browser shows the raw characters, not a formatted page.
Put a file online in seconds
Drop in a document, an image, a page or a whole static website and share the link — free, with no build step and no server to set up.
Host a file free →