Markup and Static Sites for Technical Writers
Markup and static sites are the tools that turn plain-text documentation into a website. Writers use Markdown, MDX and reStructuredText for content, and documentation platforms and static site generators such as Docusaurus, MkDocs and Sphinx to build and host it. Content stays in text files, so it can be versioned and reviewed like code.
Stage: Docs-as-Code and Tooling · Part of the Technical Writer roadmap · Last reviewed 19 November 2026
What to learn in Markup and Static Sites
- Write structured pages in Markdown with headings, lists, tables and code blocks
- Use MDX to embed an interactive component in a documentation page
- Explain how reStructuredText and Sphinx differ from Markdown and MkDocs
- Build and preview a docs site locally with a static site generator
- Configure navigation and a search feature for a documentation site
Markup and Static Sites interview questions
What is a static site generator?
A static site generator takes source files, such as Markdown, plus templates and configuration, and builds plain HTML, CSS and JavaScript pages ahead of time. The output is fast, cheap to host and secure because no server-side code runs per request. Docusaurus and MkDocs are common examples.
When would you choose MDX over plain Markdown?
Choose MDX when documentation needs interactive or reusable components, such as tabbed code samples, live examples or callouts, inside the text. Plain Markdown is simpler and easier for contributors, so use MDX only where components add value.
Where Markup and Static Sites fits in the Technical Writer roadmap
Markup and Static Sites belongs to the Docs-as-Code and Tooling stage (beginner level), which takes about 4 hours. Modern doc workflows.
Other units in this stage
Back to the full Technical Writer roadmap