gomddoc vs MkDocs
MkDocs is a mature Python static site generator with a large plugin ecosystem and, through Material for MkDocs, one of the most popular documentation themes around. gomddoc serves the same kind of Markdown folder over HTTP, renders pages on request, and exposes the content to MCP clients alongside the website.
At a glance
| gomddoc | MkDocs | |
|---|---|---|
| Runtime | Single Go binary | Python package (pip install mkdocs) |
| Model | HTTP server, plus gomddoc build for static output |
Static site generator, plus mkdocs serve for development |
| Build before publishing | Not needed with serve |
mkdocs build |
| Config file | Optional (.gomddoc/config.yml) |
Required (mkdocs.yml) |
| Navigation | Generated from the directory tree | Generated from the tree, or defined in nav |
| Serve a Git URL | Built in, with #branch:subdir |
Files must be on disk |
| MCP server | Built in: stdio and HTTP at /_mcp/ |
Not built in |
Markdown via Accept header |
Built in | Not built in |
| Search | Server-side TF-IDF with tag: filters |
Built-in search plugin, client-side (lunr.js) |
| Themes | default bundled, 7 more in gomddoc-themes |
mkdocs and readthedocs bundled, many third-party |
| Admonitions | GitHub [!NOTE] syntax, built in |
!!! syntax via the admonition extension |
| Math and diagrams | KaTeX and Mermaid built in | Via extensions and plugins |
| Multiple languages | Language directories detected automatically | Via plugins |
| Metrics and health checks | Prometheus /metrics, /health/live, /health/ready |
Left to your web server |
| Licence | PolyForm Noncommercial 1.0.0 + commercial licence (per deployment) | BSD-2-Clause |
MkDocs is free for any use. gomddoc is free for noncommercial use and needs a commercial licence for business use; see licensing.
Where gomddoc differs
Publishing is a restart
With MkDocs, publishing means running mkdocs build and uploading the site/ directory to a web server or static host. mkdocs serve exists, but it is a development server. gomddoc's serve command is the production server, so the folder you write in is the folder you deploy:
gomddoc serve ./docs
Page edits show on the next request. New pages join the navigation and search index when the server restarts.
Configuration is optional
MkDocs needs a mkdocs.yml with at least a site_name. gomddoc starts with no configuration at all: README.md is the home page, the directory tree is the navigation, and a .gomddoc/config.yml is only needed when you want to change a default.
Your docs are available to MCP clients
gomddoc includes an MCP server with six tools, four resources and three prompts. Clients can search the docs, read a page or a single section, list pages, get a table of contents and find related pages. Local clients launch gomddoc mcp ./docs over stdio; remote clients connect to /_mcp/ on a running server.
The same URL also answers in Markdown. The response carries a generated frontmatter block with the page's metadata, related pages and previous/next links:
curl -H "Accept: text/markdown" https://docs.example.com/guides/deploy
Search accepts tag: filters in the search dialog, at /api/search and in the search_docs MCP tool:
tag:docker tag:k8s deployment
Serve straight from Git
gomddoc accepts a Git URL wherever it accepts a directory. The fragment selects a branch and a subdirectory, and private repositories work over SSH:
gomddoc serve "git+https://github.com/your-org/repo.git#main:docs"
gomddoc serve "git+ssh://git@github.com/your-org/docs.git" --git-key-file ~/.ssh/id_ed25519
The repository is shallow-cloned at startup, in memory by default. Restart the server to publish new commits.
When MkDocs is the better choice
- You rely on its plugin ecosystem, which is far larger than anything gomddoc offers.
- You want Material for MkDocs and its feature set.
- Your team already works in Python and prefers to extend its tools in Python.
- You publish to a static host and want search to work there. gomddoc's
buildoutput has no search backend, content negotiation, MCP endpoint or metrics, because those need the server. - You need a permissive licence for commercial use at no cost. MkDocs is BSD-2-Clause.
Get started
brew install monolithiclab/tap/gomddoc
gomddoc preview --open ./docs
The getting started guide covers the other install options and the first configuration steps.