Publish a docs site from your notes

Turn a folder of markdown files into a browsable, searchable website — a left-hand menu of pages, a search box that finds any word, and a clean theme — then put it online so anyone opens it by clicking a link. Your agent writes the one config file, builds the site, and deploys it; the recipient just opens the URL.

Time: ~2 min to build with your agent, then the deploy is one more sentence. The only un-delegable bit is creating one free account on whatever host you deploy to (a one-time ~3 min). You'll need: Claude Code, a folder of markdown notes, and a place to put a website. Last verified: 2026-06-07 · config, build command, and site/ output checked against MkDocs' and Material's own docs. [confirmed]

New to all this? Do Set up Claude Code first — the agent installs MkDocs, writes the config, and builds the site for you. Just one or two pages, not a whole site? A single Google Doc is lighter.

Before you begin

Claude Code running — ~10 min once. It installs MkDocs, scaffolds the config, builds the site, and fixes errors it hits.
A folder of markdown. Your notes as .md files — one file per page. Sub-folders are fine; the agent maps them into the menu. No special format needed: plain markdown with # headings is enough. [confirmed]
A place to put it online — any of the static-website hosts in Deploy a website with your agent. A docs site is just a folder of web files once it's built, so it deploys exactly like any other site. The fast no-account route there gets you a live link in ~30 seconds. [confirmed]

New to letting an agent run setup for you? Read How to ask your agent — one screen, then come back.

The one thing to say

With Claude Code running in the folder that holds your notes, say:

Build a MkDocs Material site from these notes and deploy it.
Install with: uvx --with mkdocs-material mkdocs build
Write an mkdocs.yml with site_name, theme name material, and a nav menu
matching my files. Build it, fix any broken nav entries or links it
reports, then deploy the built site/ folder and give me the live URL.

Your agent writes one config file (mkdocs.yml), runs the build, and reads back any warnings — a missing page, a broken link — and fixes them before deploying. You get a live URL at the end. [confirmed]

What your agent actually builds

Two things turn your loose notes into a site: a docs/ folder holding the pages, and an mkdocs.yml next to it that names the site, picks the theme, and lists the menu. [confirmed]

my-site/
├── mkdocs.yml         ← the config: title, theme, menu
└── docs/
    ├── index.md       ← the home page
    ├── setup.md
    └── guide/
        └── basics.md

A minimal mkdocs.yml is short — the only strictly required line is site_name, but you want the theme and a menu too: [confirmed]

site_name: My Project Notes
theme:
  name: material
nav:
  - Home: index.md
  - Setup: setup.md
  - Guide:
      - Basics: guide/basics.md

Two things carry the whole site:

The nav is the left-hand menu. Each line is Page title: path/to/file.md. Indent under a heading to make a collapsible group. Leave nav out entirely and MkDocs builds the menu from your files automatically — handy for a first pass. [confirmed]
theme: name: material is the whole look. That one block gives you the searchable, mobile-friendly Material theme — and a working search box comes with it, no extra setup. [confirmed]

Want a live preview while you tweak it? Tell your agent to run uvx --with mkdocs-material mkdocs serve — it opens a local address (usually http://127.0.0.1:8000) that updates as files change. That's for editing on your own machine; it's not the share link. The share link comes from deploying the built site/ folder. [confirmed]

Steps

Build it. Say the sentence above. Your agent writes mkdocs.yml and runs uvx --with mkdocs-material mkdocs build. No install step of your own — uvx fetches MkDocs and the Material theme into a throwaway environment each run. [confirmed]
Read the build output. A clean build prints INFO - Documentation built in ... seconds. Warnings about a missing page or a broken link appear here — your agent fixes them and rebuilds. (More on those in If it doesn't work.) [confirmed]
Find the built site. The build writes everything into a new site/ folder next to mkdocs.yml. That folder is a complete, self-contained website. [confirmed]
Deploy that site/ folder. It's a plain folder of web files now, so hand it to any host the same way you'd deploy any site → Deploy a website with your agent. Tell your agent "deploy the site/ folder and give me the URL." [confirmed]
Open the URL. It loads in any browser — yours or the recipient's, no login on their end. The menu and the search box are right there. That URL is the share. [confirmed]

What the recipient does

Just read it: click the link. ~5 sec, no account, nothing to install — it's an ordinary public website with a menu and search. [confirmed]
Navigate: the left menu lists every page; the search box up top finds any word across the whole site. On a phone the menu collapses into a hamburger button. [confirmed]
Pay: nothing. The site is static files; hosting it is free on every host in Deploy a website with your agent.

If it doesn't work

Build fails: The following pages exist in the docs directory, but are not included in the "nav" (or a nav entry points at a missing file) → a path in nav: doesn't match a real file, or vice-versa. MkDocs warns by default and errors under --strict. Fix the path so it points at a file that actually exists in docs/, or delete the stray nav line. Tell your agent "reconcile the nav with the files in docs/." [confirmed]
Build warns: contains a link ... but the target is not found → an internal [link](other-page.md) points at a page that isn't there. Internal links must use the markdown filename (../guide/basics.md), relative to the current file — not the final web address. Ask your agent to "fix the broken internal links the build reported." [confirmed]
Site looks plain / no search box / no left menu → the Material theme isn't applied. Confirm mkdocs.yml has the theme: block with name: material (not theme: material on one line, and not the default readthedocs). If you added other plugins, the search plugin must be re-listed under plugins: — it's on by default only until you set plugins: yourself. [confirmed]
No module named mkdocs / mkdocs: command not found → you ran bare mkdocs. Use the uvx --with mkdocs-material mkdocs build form (it pulls MkDocs and the theme in for you), or have your agent install them first. [confirmed]
Where did the site go? I don't see a website → look for the site/ folder next to mkdocs.yml — that's the built output. It's files on disk until you deploy it; building alone doesn't put anything online. Next step is the deploy tutorial. [confirmed]
Deployed, but links/search break or pages 404 → set site_url: in mkdocs.yml to your final web address and rebuild. Some Material navigation and the sitemap rely on it; leaving it blank can break links once the site is live. [confirmed]
Anything else → MkDocs' own build command reference and Material's setup guide cover the rest.

Prefer to do it by hand?

No agent — just a terminal and a text editor.

In a folder with your markdown, scaffold a starter project:
```
uvx --with mkdocs-material mkdocs new .
```
This creates mkdocs.yml and a docs/ folder with an index.md. Move your notes into docs/. [confirmed]
Open mkdocs.yml, set site_name:, add the theme: block with name: material, and list your pages under nav: (see the example above). [confirmed]
Preview as you edit:
```
uvx --with mkdocs-material mkdocs serve
```
Open the address it prints (http://127.0.0.1:8000). It rebuilds on save. [confirmed]
Build the final site:
```
uvx --with mkdocs-material mkdocs build
```
The website lands in the site/ folder. [confirmed]
Put it online: deploy the site/ folder by hand — e.g. drag it onto app.netlify.com/drop for a live URL with no account. Full options: Deploy a website with your agent. [confirmed]

Watch / read

YouTube blocked transcript pulls on 2026-06-07, so these aren't line-by-line verified — but each is a focused MkDocs Material walkthrough on the exact build-and-deploy task, and the steps match the commands above.

How To Create STUNNING Code Documentation With MkDocs Material Theme — James Willett, 16:10. The most-cited MkDocs Material channel; covers install, mkdocs.yml, theme, nav, and build end to end. Why this one: the tightest authoritative full walkthrough. [unclear] — transcript blocked 2026-06-07, verify against the current config.
Material for MkDocs: Full Tutorial To Build And Deploy Your Docs Portal — James Willett, 26:34. Goes past building to deploying the site/ online — the same final step this tutorial hands to the deploy guide. Why this one: it carries through to a live URL. [unclear] — transcript blocked 2026-06-07.
Level up your Python projects with MkDocs — Tech Byte Tutorials, 5:40. The shortest on-task intro if you want the gist before the longer ones. Why this one: under six minutes. [unclear] — transcript blocked 2026-06-07, length-picked not content-verified.

Best written walkthrough: Material for MkDocs' own Creating your site — mkdocs new ., the theme: name: material block, mkdocs serve, and mkdocs build. The authoritative source the commands here were checked against. Pair it with MkDocs' Getting started for the nav and site/ basics. [confirmed]

Just one or two pages people read or comment on? → a Google Doc opens in one tap, no build step, comments in the margin.
Want people to run or build on the underlying files, not just read them? → a GitHub repository hands over the whole folder.
A single interactive thing, not a multi-page reference? → a Claude Artifact or a plain deployed website.

Sources

MkDocs — Getting started — mkdocs build, the site/ output directory, minimal mkdocs.yml (site_name the only required key), nav structure, switching the theme — checked 2026-06-07
MkDocs — Configuration — validation defaults (nav not_found: warn, links not_found: warn), --strict, site_dir default of site, site_url — checked 2026-06-07
MkDocs — build command reference — build flags and warnings output — checked 2026-06-07
Material for MkDocs — Creating your site — mkdocs new ., the theme: name: material block, mkdocs serve / mkdocs build — checked 2026-06-07
Material for MkDocs — Getting started / install — pip install mkdocs-material (the package uvx --with mkdocs-material pulls in) — checked 2026-06-07
Material for MkDocs — Setting up site search — search "enabled by default, but must be re-added to mkdocs.yml when other plugins are used" — checked 2026-06-07
Material for MkDocs — Setting up navigation — site_url needed for instant navigation/previews — checked 2026-06-07

Good to know

It's free, end to end. MkDocs and the Material theme are open source; uvx --with mkdocs-material pulls them with no install of your own, and the built site/ hosts free on any static host. The only spend is the recipient's ~0 — they just open a link. [confirmed]
MkDocs warns rather than blocks on broken links by default. A missing nav file or a dead internal link prints a warning and the build still finishes — so glance at the output. Add --strict (or have your agent build with it) to turn those warnings into hard errors and catch every one before you deploy. [confirmed]
Set site_url before you deploy. A few Material features (instant navigation, the sitemap search relies on) need the final web address in mkdocs.yml. Leave it blank for a quick throwaway; set it for anything you'll keep. [confirmed]
The built site/ is static files only. No server, no database — which is why it deploys anywhere and costs nothing, but also why a docs site can't take form submissions or logins. Need those? That's a deployed app, not a docs site. [confirmed]
A rewrite is coming, but not yet — you're fine. The Material team announced (2026-02-18) that the upcoming MkDocs 2.0 is a breaking rewrite: TOML config instead of YAML, and Material won't run on it. It's pre-release with no date, and uvx --with mkdocs-material still pulls the compatible MkDocs 1.6.x, so everything above works today. If a far-future rebuild starts erroring on your YAML, that's why — re-check the Material setup guide. [confirmed] (checked 2026-06-07)