# Template authoring guide
> Move from Markdown authoring to your first upgrade-safe Hugo shortcode and layout, step by step.
This guide starts with the knowledge needed to create ordinary Markdown pages.
You do not need to know Go, HTML templating or Tailwind beforehand. By the end,
you will have created a reusable `status-panel` component and will understand
when and how to change a complete page layout.
## 1. Understand what changes when Markdown is not enough
A Markdown file supplies content: headings, paragraphs, lists, images and front
matter. A **template** supplies the HTML around that content. Hugo combines the
two when it builds the site.
For example, this Markdown:
```md
+++
title = "Service status"
+++
The service is available.
```
becomes a complete HTML page because the theme supplies the header, sidebar,
main content area and footer. You only need to author a template when you want
reusable presentation that Markdown and the theme's existing shortcodes do not
already provide.
Hugo has three relevant building blocks:
| Building block | What it does | Who invokes it |
|---|---|---|
| Shortcode | Embeds a reusable component inside Markdown | Content author |
| Partial | Reuses HTML inside another template | Template author |
| Layout | Defines the structure of a complete page or section | Hugo |
Start with a shortcode for a component used in content. It is the smallest and
safest first customization. Do not copy a complete theme layout merely to add a
box to one page.
## 2. Know which project you are editing
The theme is a dependency of your Hugo site. Your site should have a structure
similar to this:
```text
my-site/
├── assets/
├── content/
│ └── docs/
├── layouts/
├── hugo.toml
├── go.mod
└── package.json
```
All paths in this guide are relative to `my-site/`, the directory containing
your site's `hugo.toml`. Create `assets/` or `layouts/` if they do not exist.
Do not edit the downloaded theme in Hugo's module cache. Hugo checks your local
site first, so a local file can add to or override the theme without changing
the dependency.
Before changing templates, make sure the ordinary site still builds:
```sh
hugo
```
If this command fails, first complete the [from-scratch installation](../getting-started.md).
## 3. Learn the small amount of template syntax you need
Hugo templates are HTML with instructions between `{{` and `}}`. These are
called template actions. The first example uses only five ideas:
| Syntax | Meaning |
|---|---|
| `{{ .Get "title" }}` | Read the shortcode argument named `title` |
| `{{ .Inner }}` | Read the Markdown between the opening and closing shortcode tags |
| `{{ $name := value }}` | Store a value in a local variable |
| `{{ default "info" value }}` | Use `"info"` when no value was supplied |
| `{{ index $map $key }}` | Read the value for `$key` from a map |
A leading or trailing hyphen, as in `{{-` or `-}}`, only trims surrounding
whitespace in the generated HTML. It does not change the value.
## 4. Create your first shortcode without styling
Create `layouts/shortcodes/status-panel.html` in your site:
```go-html-template {filename="layouts/shortcodes/status-panel.html"}
```
This is a paired shortcode because it accepts content between an opening and a
closing tag. `.Page.RenderString` tells Hugo to render Markdown such as emphasis
and links inside that content.
Use the shortcode in any Markdown page:
```md
{{}}
The **documentation build** passed all checks.
{{}}
```
Run the development server and open the page containing the shortcode:
```sh
hugo server
```
At this stage the component is intentionally plain. Confirm that its heading and
bold text render before adding styling. If Hugo reports `failed to extract
shortcode`, check the filename, paired closing tag and quotation marks.
## 5. Enable the theme's Tailwind integration
Tailwind turns utility names in `class="..."` attributes into CSS. The theme
already owns the stylesheet and exposes a documented set of semantic utilities.
Your site must let Hugo record the class names found in your local templates.
In the site-root `hugo.toml`, add or merge this setting:
```toml
[build.buildStats]
enable = true
```
Do not create a second `[build.buildStats]` table if one already exists; add
`enable = true` to the existing table.
If you build the theme CSS in the consuming project, install the same major
Tailwind CLI version and commit `package.json` and the generated lockfile:
```sh
npm install --save-dev @tailwindcss/cli@^4.1.0
```
The theme reads Hugo's generated `hugo_stats.json`. This is how utility classes
used by local templates become visible to Tailwind. Run the repository's normal
build command after adding a class; `hugo server` alone may not rebuild CSS in a
custom build setup.
## 6. Style the shortcode with theme utilities
Replace the simple shortcode with this styled version:
```go-html-template {filename="layouts/shortcodes/status-panel.html"}
{{- $kind := .Get "kind" | default "info" -}}
{{- $classes := dict
"info" "border-default bg-subtle text-hi"
"important" "border-accent bg-surface text-hi"
-}}
```
Use it from Markdown:
```md
{{}}
The documentation build passed all checks.
{{}}
```
Read it from top to bottom:
1. `$kind` reads an optional argument and falls back to `info`.
2. `$classes` maps the two supported values to complete class strings.
3. `index` selects one class string for the `