Markdown to website, without a static site generator

Search for how to publish Markdown and every answer has the same shape. It is a good route and it is much longer than the question deserved.

• Choose a generator — MkDocs, Hugo, Docusaurus, Eleventy, Jekyll.
• Install it, and whatever runtime it needs.
• Pick a theme, install that too.
• Write a config file, and learn its particular spelling of "navigation".
• Write a CI workflow to build on push.
• Choose somewhere to host the output, and point DNS at it.
• Add a search plugin, because search is rarely included.
• Maintain all of the above, forever.

Every one of those steps is reasonable in isolation, and together they are why a lot of Markdown never becomes a website. If your docs must live beside code in a repository, that cost is worth paying — the decision guide works through exactly when it is. This page is for when it is not.

The short route is: zip the folder, upload the zip. What matters is knowing what the structure turns into, so you can arrange it before rather than fix it after.

So a folder like this arrives as three sections with their own front pages, and every relative link between them still resolves:

docs/
  README.md
  getting-started/
    index.md
    install.md
    first-steps.md
  guides/
    index.md
    deploying.md
    images/diagram.png
  reference/
    cli.md
    config.md

You do not need a mkdocs.yml for this to work. If one happens to be in the zip we read it, so an existing project keeps its navigation — but a folder of plain Markdown with no config imports perfectly well on its own.

1. Tidy the folder, or do not

The only thing worth checking is that each page starts with a heading, because that heading becomes the page title. If a file opens with a paragraph, the title falls back to the filename, which is usually less readable.

Numbered filenames like 01-install.md are common and worth knowing about: you do not need them here. Order is set by dragging, so the numbers become noise in your URLs. Strip them if you like, or leave them and rename later.

2. Zip it and upload

A zip of Markdown and images, up to 200 MB. A single .md file works too if that is all you have. There is no build command to pick and no theme to install; the config is written for you.

3. Check the tree before the content

Look at the page list first. It is the navigation your readers will get, and it is where you notice that a folder you meant as a group came in as something else. Drag pages and folders into the order you want; sort A to Z puts it all back if you make a mess.

4. Publish

The site builds with full-text search, navigation and a 404 page already inside it. Search is generated at publish time and served from the site — there is nothing to sign up for and no index to pay for.

This is the honest column, and it is short but real. Skipping the pipeline means skipping what the pipeline could have done.

• No plugins. Nothing generating API reference from docstrings, no custom hooks at build time.
• No theme forking. Four themes, a brand colour and a logo, rather than templates you control.
• No build-time checks of your own — a link checker or a spell check you wired into CI does not come with you.
• No offline or air-gapped build. The build happens here.
• Docs no longer version with the code, because they are not in the repository any more.

If two or more of those matter, run the generator. That is not a consolation answer — it is the right one, and the tools are good.

The reasonable objection to uploading your Markdown somewhere is that you now have your Markdown somewhere. So the exit is worth stating plainly.

Export source gives you back your Markdown with a generated config that builds the site with plain Zensical — the generator written by the Material for MkDocs team — with nothing of ours involved. Export site gives you the built HTML, search index included, which works from a folder with no internet. Both are on every plan, including the free one.

That is the whole argument for taking the short route first. If the upload turns out to be all you needed, you are done in ten minutes. If you later need the pipeline, you leave with a folder of Markdown and a working config — which is roughly where you would have started anyway.