Style guide template in Markdown: voice, words and dates
Bobby Huang ·
Under The basics, a style guide is defined as one plain .md file holding a team's writing rules for the team's own pages. Under The template, six level-two headings follow a title line: Voice, Words to use and avoid, Numbers and dates, Headings and lists, Example, and Who looks after this page.
Key takeaways
- Under The basics, short pointers lead to the agent instruction file post and the glossary template, with a few lines on how each of those files differs from a style guide.
- Under The template, each part gets a sentence or two, and the last sentence of the section names the post on Markdown bullet points.
- Under The sample, Jane Doe is the made-up writer of a Doe Holdings style guide, and John Doe looks after it.
- Under Length and layout, three tips come from the two blocks, and one points to a glossary file for team terms.
- Under The filename, one .md file for the team gets a short name, with a pointer to the post on Markdown file naming.
A writing style guide template gives a team one place to set down how its pages are written. This one is a single plain .md file. It holds a short voice paragraph, dash lines for words, for numbers and dates, and for headings and lists, one before-and-after example, and a line naming whoever looks after the page.
Next up are the template, a short remark on every part, an invented sample for Doe Holdings, four tips on length and layout, and one choice of file name. Since the file is just characters on lines, you can write it with whatever text editor is on hand.
The basics
A style guide, for this post, means a single .md file holding a team's writing rules for the team's own pages. People write the rules, and people follow them. This template sets out to give those pages one voice and one set of word choices, whoever wrote them. That takes in pages from AI agents too, once a person edits them to the rules.
Instruction files written for AI coding agents are a separate kind of file. Those files carry the rules of a project, the steps to build it and test it, and its conventions. In the post on agent instruction files, you'll find their file names, where each one goes and how several of them combine. The style guide here is a page of writing rules for people to read and follow.
A glossary is another separate file. In the glossary template, every entry sets a project term beside a brief meaning, and a style guide can point to that file for how team terms are spelled.
The template
Below sits this post's template. Copy all of it into a .md file that has nothing in it yet, then swap every placeholder for wording the team chooses.
# Style guide for Team Name
## Voice
Write two or three plain sentences on how the team's pages sound.
## Words to use and avoid
- Use one plain word; avoid a longer word with the same meaning.
- Use a second plain word; avoid a longer word with the same meaning.
## Numbers and dates
- Write dates year first, as YYYY-MM-DD.
- Write numbers as words or as digits, whichever the team picks.
## Headings and lists
- Write headings in sentence case.
- Put one idea in each bullet.
## Example
Before:
> A line as someone first wrote it.
After:
> The same line, rewritten to follow this guide.
## Who looks after this page
- Looked after by: Name
- Date last changed: YYYY-MM-DD
Each part, from the top of the block down:
- Title line. One top-level heading with the team's name in it.
- Voice. A few plain sentences, two or three, about the sound of the team's pages. Voice is the one part in paragraph form.
- Words to use and avoid. One dash line per word pair. The word to use comes first, and the word to avoid comes after a semicolon.
- Numbers and dates. Dash lines on how numbers and dates appear in the team's pages. In the template, dates go year first on the opening dash line.
- Headings and lists. Dash lines on how headings and bullets look, such as sentence case and one idea per bullet.
- Example. A short line from before the rules and the same line after them. Both quotes sit under a one-word label line of their own.
- Who looks after this page. A name for whoever looks after the page, plus a last-edit date.
Under Words to use and avoid, Numbers and dates, and Headings and lists, each rule gets a dash line to itself, and an empty line separates each heading from the first dash under it. Tests on dash lines sitting right below a sentence, with and without an empty line before them, are in the post on Markdown bullet points.
You can describe who reads the team's pages in a separate file beside the style guide, starting from a persona template.
The sample
Nothing in this sample is real: the company, the two people in it and each line are invented for this post. Jane Doe writes the style guide for the Doe Holdings pages, and John Doe looks after it.
# Doe Holdings style guide
## Voice
We write the way we talk to a colleague at the next desk. We use short sentences and plain words. We name the person who does each task.
## Words to use and avoid
- Use start; avoid commence.
- Use about; avoid regarding.
- Use before; avoid prior to.
- Use need; avoid require.
## Numbers and dates
- Write dates year first, as in 2026-11-02.
- Write the day name before the date, as in Monday 2026-11-02.
- Write numbers from one to nine as words, and 10 and up as digits.
## Headings and lists
- Write headings in sentence case.
- Put one idea in each bullet.
- Start each bullet with a capital letter.
## Example
Before:
> You are requested to commence watering the office plants prior to Friday.
After:
> Start watering the office plants before Friday.
## Who looks after this page
- Looked after by: John Doe
- Date last changed: Thursday 2026-10-22
The sample has three voice sentences, four word lines, three lines under Numbers and dates, and three under Headings and lists. Its Example heading holds two quotes. The after line has start and before in place of commence and prior to, two of the pairs set out in the word lines. The date 2026-11-02 falls on a Monday, which matches the day name in the second date line.
Length and layout
Keeping a style guide short and plain is an aim of this template. The first three tips draw on the template block and the sample block, and the fourth points to a glossary:
- Two or three voice sentences. Under Voice, the template leaves space for two or three sentences, while three sit there in the sample.
- One rule to a dash line. In both blocks, a rule line is a single dash line holding a single instruction.
- A single example pair. Under Example, each block holds one before quote and one after quote.
- Team terms left to a glossary. The template has no heading for team terms. A glossary file can hold how those terms are spelled, and the style guide can point to it.
The filename
Keep one style guide file for the team's pages. A short name of two to four hyphen-joined words is a target given in the post on Markdown file naming, and style-guide.md fits it. Per the same post, a file changed in place keeps a single name, and that name carries no date. The style guide is a file of that kind, and its last-change date stays in the body under Who looks after this page.
Where Sashmark fits
Sashmark, planned as a reader and editor of Markdown for desktop use, is aimed at anyone keeping .md files that arrive from AI agents. No part of it has come out; it is in development. One project folder with a style guide file beside other .md files is a kind of file set Sashmark is meant for.
See the planned features, the help pages and the roadmap for where each part stands.
Visit sashmark.com.
Questions
- How is a style guide different from an agent instruction file?
- Under The basics, instruction files written for AI coding agents carry the rules of a project, the steps to build and test it, and its conventions, while this style guide is a page of writing rules that people read and follow.
- Where do spellings of team terms go?
- Under The basics, the glossary template is named as the file a style guide can point to for how team terms are spelled.
- Who looks after the style guide page?
- Under The template, a line names whoever looks after the page, with a line for the date it last changed.