Markdown Tips for Technical Writers

Markdown is the lingua franca of technical documentation. Most developers know the basics, but a few habits separate clear, maintainable docs from the kind that accumulate confusion over time.

Fenced Code Blocks With Language Tags

Always specify the language on fenced code blocks. It enables syntax highlighting and signals to readers what they’re looking at:

```bash
npm install
```

```typescript
function greet(name: string): string {
  return `Hello, ${name}!`;
}
```

Without the language tag you lose highlighting and make it harder for tooling (linters, doc generators) to process the content correctly.

Filename Comments in Code Blocks

When showing code that lives in a specific file, make that clear:

# .github/workflows/deploy.yml
name: Deploy

Or as a comment in the language:

// src/utils/format.ts
export function formatDate(date: Date): string {
  return date.toISOString().split("T")[0];
}

This small habit saves readers from hunting for where to put the code.

Prefer Reference Links for Repeated URLs

If you link to the same URL multiple times, use reference-style links to keep the prose readable and make URL updates a single-line change:

See the [Hugo documentation][hugo-docs] for details.
The [Hugo docs][hugo-docs] also cover themes.

[hugo-docs]: https://gohugo.io/documentation/

Tables for Comparison, Not for Layout

Markdown tables work well for structured comparisons:

Format	Pros	Cons
TOML	Clear syntax, widely used in Go ecosystem	Less common in frontend tooling
YAML	Familiar to most developers	Whitespace-sensitive, error-prone
JSON	Universally parseable	Verbose, no comments

Avoid using tables for layout or when a simple list would do — they’re harder to maintain and often don’t render well on narrow screens.

Front Matter Conventions

For Hugo (and most static site generators), front matter is where you set page metadata. Keep it consistent across your content:

---
title: "Clear, Descriptive Title"
date: 2024-07-22
draft: false
description: "One or two sentences — this often appears in SEO meta tags and link previews."
tags: ["tag-one", "tag-two"]
---

A few conventions that help:

description: Write it for link previews and search results — not as a teaser for readers already on the page
tags: Use lowercase kebab-case and keep the taxonomy consistent across posts
draft: Default new content to draft: true in your archetype so you don’t accidentally publish unfinished posts

Heading Hierarchy

One h1 per page (usually the title), then use h2 and h3 for sections and subsections. Screen readers and document outliners depend on correct heading hierarchy.

# Page Title (h1 — usually set from front matter, skip in content)

## Main Section (h2)

### Subsection (h3)

In Hugo specifically, the page title is rendered as an h1 in most themes, so your content should start at ##.

Writing Alt Text for Images

Alt text isn’t optional for technical docs. Describe what the image shows, not what it is:

<!-- Not helpful -->
![screenshot](dashboard.png)

<!-- Helpful -->
![The Deployments dashboard showing three active environments with their status and last deploy time](dashboard.png)

For decorative images with no informational content, use an empty alt attribute: ![](decorative.png).

Callouts and Admonitions

Hugo doesn’t have built-in admonition support, but you can use blockquotes with a label prefix as a lightweight convention:

> **Note**: This feature requires Hugo 0.110 or later.

> **Warning**: Changing this setting will invalidate all cached builds.

Or create a shortcode for more structured callouts if you use them frequently.