# Markdown to website, without a static site generator

You have a folder of .md files and you want it on the web. The usual answer is install a generator, pick a theme, write a config and wire up CI. Here is the version where you upload the folder.

_Source: https://docszero.com/resources/markdown-to-website_
_how-to · 6 min read_
_Published 10 September 2026_

> **In short:** Zip the folder and upload it. Folder names become sections, filenames become pages, a README or index file becomes the section’s front page, and relative links and images are rewritten to match. Search and navigation are built for you.

## The route you were about to take

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](https://docszero.com/resources/do-you-need-a-static-site-generator) works through exactly when it is. This page is for when it is not.

## What your folder becomes

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.

| In your folder | On the site |
| --- | --- |
| A subfolder | A section in the navigation, titled the way it reads |
| `README.md` or `index.md` | That section’s front page |
| `getting-started.md` | A page, titled from its first heading |
| A relative link to another `.md` | A link to that page, rewritten |
| `![](images/thing.png)` | The image, carried across, link rewritten |
| A fenced mermaid block | A rendered diagram |
| `mkdocs.yml` or `zensical.toml` | Read for site name, description, language and nav |

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

**a folder that needs no preparation at all**

```
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.

## The steps

### 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.

## What you give up by not running a generator

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.

## Leaving again, whenever

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.

## Questions

### How do I turn Markdown files into a website?

Zip the folder and upload it. Subfolders become sections, README.md or index.md becomes a section’s front page, each .md becomes a page titled from its first heading, and relative links and images are rewritten to match. Search, navigation and a 404 page are built for you, with no generator to install and no config to write.

### Do I need a static site generator to publish Markdown?

Not to get a website. You need to run one yourself if your docs must live in the same repository as your code, if pages are generated from source by a plugin, or if the build has to run offline. Otherwise a generator is a route to a static site rather than a requirement for one.

### Do numbered filenames still control page order?

No, and you do not need them. Order is set by dragging pages and folders in the editor, and the tree you are looking at is the navigation the published site uses. Prefixes like 01- will simply show up in your URLs, so most people strip them.

### What happens to my relative links and images?

Both are rewritten so they keep working. A relative link to another .md file becomes a link to that page, and images referenced from a folder inside the zip are carried across with their paths updated. Mermaid code fences render as diagrams on the published page.

### Can I move to a static site generator later?

Yes. Export source hands back your Markdown together with a config that builds the same site with plain Zensical, on every plan including Free. Starting with an upload does not close the generator route; it just delays the decision until you know whether you need it.

---

Published by Docszero (https://docszero.com) — docs, minus the setup. Upload Markdown, a Word document or a PDF and get a searchable documentation site. Free for one site; export the source on every plan.