Fix Backstage TechDocs Build – Docs Not Rendering or Build Fails

# mkdocs.yml — missing site_name
docs_dir: docs

```bash
# docs/index.md
# My Service
Welcome to the service docs.

Build output:

ERROR: Config value 'site_name' is required

TechDocs page in Backstage:

Unable to render documentation. The technical documentation for this entity
is not available. Make sure the TechDocs build has been triggered and
completed successfully.

## Right ✅

**Minimal working `mkdocs.yml`:**

```yaml
site_name: My Service
site_description: User authentication service
site_url: https://backstage.example.com/docs/my-service

docs_dir: docs

nav:
  - Home: index.md
  - Architecture: architecture.md
  - API: api.md
  - Deployment: deployment.md

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections

plugins:
  - techdocs-core
  - search

**Required file structure:**

service-repo/
├── mkdocs.yml
├── docs/
│   ├── index.md
│   ├── architecture.md
│   ├── api.md
│   └── deployment.md
├── catalog-info.yaml
└── README.md

**Build locally first:**

```bash
yarn backstage-cli techdocs:build --output-dir ./site
# or using npx
npx @techdocs/cli build

Successful output:

INFO:  Building documentation...
INFO:  Material site built in 3.24 seconds
INFO:  Documentation built successfully.

**Verify the built site:**

```bash
npx @techdocs/cli serve --site-dir ./site
# Open http://localhost:3000

Then in Backstage, re‑trigger the build via the **TechDocs** tab → **Build**.

## Root Cause

TechDocs uses `mkdocs` under the hood. The `site_name` field is the only mandatory config value. Missing it causes an early exit. Also, the `techdocs-core` plugin is required to generate Backstage‑compatible output — without it, the build succeeds but the output format is wrong.

## Prevention

- Always include `techdocs-core` in the `plugins` list.
- Build locally with `techdocs-cli` before pushing — much faster feedback.
- Set `site_url` to the actual Backstage instance so cross‑references resolve.
- Use the **material** theme — it's the only theme officially supported by TechDocs.


## Common Mistakes with techdocs build

1. **Using `foldl` instead of `foldl'` causing stack overflow on large lists**
2. **Forgetting `deriving (Show, Eq)` on custom data types needed for debugging**
3. **Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable**

These mistakes appear frequently in real-world BACKSTAGE code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

## Practice Exercise

**Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.**

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: Why does my build pass locally but fail in CI?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: The CI environment may have a different mkdocs version. Lock the version in a <code>requirements.txt</code>: <code>mkdocs-techdocs-core&gt;=1.0,&lt;2.0</code>.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: How do I add images to my docs?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Place images in <code>docs/assets/</code> and reference as <code>![Alt](assets/img.png)</code>. Ensure they're committed to the repo.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: Can I use custom CSS?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Yes — add <code>extra_css: [assets/extra.css]</code> to <code>mkdocs.yml</code>. The file goes in <code>docs/assets/</code>.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: What if I have multiple documentation repos?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Each entity (component) should have its own <code>mkdocs.yml</code> in its Repository. TechDocs builds each one independently.</p>
</div></details>

---

*TechDocs best practices are covered in the [DodaTech Backstage TechDocs course](https://dodatech.com/courses/backstage).*