Docs-as-Code Templates — Complete Guide

Documentation templates standardize page structure, ensuring consistency across contributors. Learn how to create reusable templates for API references, guides, tutorials, and troubleshooting pages.

What You'll Learn

You will learn how to create documentation templates for different content types, how to use archetypes in Hugo and other SSGs, and how to ensure contributors follow consistent page structures.

Why It Matters

Without templates, every contributor invents their own page structure. This creates inconsistency, confuses readers, and makes documentation harder to maintain. Templates enforce best practices automatically.

Real-World Use

DodaTech uses Hugo archetypes for each content type. When a writer runs hugo new content/api/endpoint.md, it generates a pre-structured template with the correct frontmatter, headings, and sections.

flowchart LR
  A[Writer Runs hugo new] --> B[Archetype Template]
  B --> C[Pre-filled Frontmatter]
  C --> D[Standardized Sections]
  D --> E[Consistent Page Structure]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Hugo Archetypes for Documentation

Create an archetype for API documentation:

# archetypes/api.md
---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
weight: 10
description: "TODO: Write a 140-160 character description"
date: {{ .Date }}
lastmod: {{ .Date }}
tags: [api, reference]
---

# {{ replace .File.ContentBaseName "-" " " | title }}

TODO: Write a one-paragraph description of this endpoint.

## Endpoint

`METHOD /api/v1/resource`

## Authentication

TODO: Describe authentication requirements for this endpoint.

## Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| TODO | string | yes | TODO |

## Example Request

```bash
curl -X METHOD https://api.example.com/v1/resource \
  -H "Authorization: Bearer TOKEN"

Example Response

{
  "status": "success",
  "data": {}
}

Error Codes

Rate Limiting

TODO: Describe rate limits for this endpoint.

## Creating a Tutorial Template

```yaml
# archetypes/tutorial.md
---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
weight: 10
description: "TODO: 140-160 character description"
date: {{ .Date }}
lastmod: {{ .Date }}
tags: [tutorial]
---

# {{ replace .File.ContentBaseName "-" " " | title }}

## What You'll Learn

TODO

## Why It Matters

TODO

## Prerequisites

- TODO

## Step 1: TODO

```bash
# TODO

Step 2: TODO

# TODO

Expected Outcome

TODO

Troubleshooting

Problem: TODO

Solution: TODO

What's Next

TODO

## Template Variables and Shortcodes

Use Hugo shortcodes in templates:

```markdown
{{</* callout type="info" */>}}
This is a template callout for important notes.
{{</* /callout */>}}

{{</* tabs */>}}
{{</* tab "npm" */>}}
npm install package
{{</* /tab */>}}
{{</* tab "yarn" */>}}
yarn add package
{{</* /tab */>}}
{{</* /tabs */>}}

Template Variables

# archetypes/default.md
---
title: "{{ replace .File.ContentBaseName "-" " " | title }}"
description: "{{ .Summary }}"
date: {{ .Date }}
lastmod: {{ .Date }}
tags: []
---

Available variables: .Title, .Date, .File.ContentBaseName, .Summary, .Page.Title.

Markdown Templates Without an SSG

For projects without Hugo, use plain Markdown template files:

---
title: "Page Title"
description: "Description for search engines (140-160 chars)"
weight: 10
date: YYYY-MM-DD
lastmod: YYYY-MM-DD
tags: []
---

# Page Title

## Overview

Brief description of what this page covers.

## Prerequisites

- List prerequisites

## Steps

### Step 1: Title

Description of the step.

```bash
command

Step 2: Title

Description of the step.

command

Common Mistakes

Mistake 1

Explanation and fix.

Related

• Link to related pages

## Common Mistakes

### 1. Templates With Too Many Sections

A template with 20 optional sections overwhelms writers. Start with the essential sections and let writers add more as needed.

### 2. Not Including Frontmatter

Templates without frontmatter produce pages missing descriptions, dates, and tags. Frontmatter is essential for SEO and organization.

### 3. Templates That Are Too Generic

A single template for all content types produces uniform but inappropriate pages. Create separate templates for API docs, tutorials, and guides.

### 4. No Instructions for Template Use

Writers need to know which template to use for which content. Add a templates reference page to your contributing guide.

### 5. Ignoring Template Maintenance

Templates become outdated as style guides evolve. Review and update templates regularly.

## Practice Questions

**1. What is the purpose of documentation templates?**

They standardize page structure, ensure consistency across contributors, and reduce the effort of creating new pages.

**2. How do Hugo archetypes work?**

Archetypes are template files in the archetypes directory. Running hugo new uses the matching archetype to create a new content file with pre-filled frontmatter and structure.

**3. What should every documentation template include in its frontmatter?**

Title, description (140-160 chars), weight, date, lastmod, and tags.

**4. Why create separate templates for different content types?**

API references need different sections than tutorials. Separate templates ensure each type has the appropriate structure.

**5. Challenge:** Create three Hugo archetypes: one for API reference pages, one for tutorials, and one for troubleshooting guides. Each should have appropriate frontmatter, sections, and placeholder text.

## 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">Should templates include actual content or only structure?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Templates should include structure and placeholder text. Filled-in content would be overwritten on every new page.</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">How do I distribute templates across a documentation team?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Store templates in the repository under archetypes or templates. Reference them in the contributing guide.</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">Can I use templates with non-Hugo static site generators?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Yes. MkDocs has a similar concept with MkDocs hooks. Docusaurus uses sidebars and doc plugins.</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">How do I update templates without breaking existing pages?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Templates only affect new pages. Existing pages keep their structure. Update templates and communicate changes to the team.</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">What is the minimum number of templates needed?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>Three: API reference, conceptual guide, and tutorial. Add more as your content types grow.</p>
</div></details>

## Mini Project

Create a set of three documentation templates (API reference, tutorial, and conceptual guide) for a Hugo documentation project. Include appropriate frontmatter, section headings, and placeholder descriptions. Test each template by creating a new page.

## What's Next

With templates established, learn about Multi-Version Docs to support documentation for multiple software versions. Then explore Search Integration.