How to turn markdown files into a documentation website

What are the options?

You have a folder of .md files, probably in a Git repository, and you want a website with a sidebar, page titles and links that work. There are two broad ways to get there.

A static site generator. Docusaurus, MkDocs, Hugo, VitePress and others read your markdown, apply a theme and write HTML files. You host the output on GitHub Pages, Netlify, Vercel, Cloudflare Pages or your own server. You control everything, and you maintain everything: the config, the theme, the build, the dependency upgrades and the hosting.

A host that reads the repository. A service reads the markdown from the repository on each push and serves it as a site. There is no build for you to run, and less to configure. You give up control over layout in exchange.

Neither is wrong. The question is how much of the site you want to own.

When is a static site generator the right choice?

Choose a generator when:

• You want a custom design, landing page or React components inside your docs.
• You need versioned docs (v1, v2, v3) side by side; Docusaurus does this well.
• Your docs must be public and you already have hosting you like.
• You have someone who will maintain the build when a dependency breaks.

Generators are free and well documented. Their gap is access control: they produce static files and have no login. If some of your docs should be private, the protection has to come from the host or a proxy in front of it. See how to password protect a documentation site.

When is a hosted reader the right choice?

Choose a host that reads the repository when:

• The markdown already exists and you want it readable today.
• You do not want a config file to keep in step with your folders.
• Some readers should see the docs and others should not.
• People who are not developers need to fix a typo without cloning anything.

How does DocuGate turn a folder into a site?

DocuGate reads one folder, on one branch, of a GitHub repository. The rules are short, and there is no config file you have to write:

docs/
  index.md              ->  /acme/handbook
  installation.md       ->  /acme/handbook/installation
  guides/
    deploying.md        ->  /acme/handbook/guides/deploying

• Only .md files become pages. .MD works too.
• A folder becomes a sidebar group, named after the folder with dashes and underscores turned into spaces. Nested folders nest.
• A file's title is its first # heading; without one, the file name.
• index.md is the landing page. Without it, README.md stands in.
• Pages sort with the index first, then files by title, then folders.

If you want a fixed order, add docugate.json at the repository root:

{
  "sidebar": ["index.md", "quickstart.md", "guides"]
}

Anything not listed is appended after. See connecting a repository for the rest.

Content is cached per commit. Push to the branch and the next reader gets the new pages. Nothing is copied into DocuGate permanently.

What else comes with it?

• Access control. Each space is Public, Repo access (GitHub decides who can read) or Allowlist (named GitHub logins or emails). See access control.
• Edit in place. Anyone who can push to the repository sees Edit on a page. The change commits to the branch as them.
• An API reference. Commit an OpenAPI 3.0 or 3.1 file and the space gains a page per endpoint with examples and a console. See API reference.
• Several repositories in one space. On Pro, a frontend, a backend and a mobile app can publish into one set of pages. See merging repositories.
• Checks before you publish. npx docugate check catches broken links and pages without titles, and can run in CI. See the CLI.

What it does not do: custom themes and layouts. You get DocuGate's reader, with light and dark mode, an accent colour and a density setting. If the design of your docs site is part of your brand, a generator gives you more room.

Steps

1. Put your markdown in a folder, such as docs, with an index.md or README.md.
2. Start each page with a # heading.
3. Optionally run npx docugate init and npx docugate check in the repository.
4. Sign up with GitHub and open Dashboard → New space.
5. Pick the repository, branch and folder, choose who can read, and create the space.
6. Open it at /{your-handle}/{slug}.

One space from a public repository is free on Starter. Unlimited spaces and private repositories are on Pro, at $5 a month, $50 a year or $2 a week. See pricing.

Try it

Create a space from a folder of markdown you already have.