How is a glossary different from a definition list?

Under The job of a glossary file, the post sets the file apart from the definition list syntax.

Should one file hold every term in a project?

Under Where GLOSSARY.md lives and how to link it, this post gives its choice of one glossary file per project.

Where should a new term go in the file?

The section Keeping entries sorted has tips on placing a new term where it fits in the order.

Glossary template in Markdown: define project terms once

Bobby Huang · 2026-10-22

Under The glossary template, this post gives a fenced Markdown block with a title line, a sort line and three sample entries, each a bold term over a meaning line.

Key takeaways

The section The job of a glossary file describes the file and the newcomer it is written for.
The section A made-up Doe Holdings glossary fills in the template with four invented office terms.
Under Keeping entries sorted, the post gives short tips on adding terms in their place and points to a guide on lettered lists.
The section Where GLOSSARY.md lives and how to link it names this post's choice of file name and folder.
Under A made-up Doe Holdings glossary, the four terms appear in sorted order with a meaning line under each.

A glossary template gives a project one plain Markdown file for its own words. Each entry pairs a term with a short meaning, and the entries stay sorted, so a person who joins the project can look up a word without asking around.

Below you'll get the template, a note on each part of an entry, and one worked glossary for a made-up company. You can do all of it in whatever plain text editor you already use. You won't need to install a thing.

The job of a glossary file

A glossary is one .md file that lists the terms a project uses, each with a meaning in plain words. This post calls the file GLOSSARY.md. Its reader is someone new to the project. That person can follow plain English but missed the talks where a phrase like "close week" picked up its local sense.

An entry answers one question: what does this word mean here? It doesn't need to define the word for the whole world. When a term means one thing in general speech and another inside the project, the entry gives the project's sense, since that's the one a newcomer can't guess.

A definition list is a syntax that pairs a term with its meaning, and plain CommonMark doesn't include it. A glossary is a file, and its entries can use more than one syntax. This template uses a bold term with a meaning line under it.

The glossary template

Paste the block below into a fresh GLOSSARY.md, then swap the placeholder entries for your own terms.

# Glossary

Keep entries sorted by term.

**First term**

What this word means in this project, in one or two plain sentences.

- See also: Second term
- Not to be confused with: a nearby word that means something else here

**Second term**

What this word means in this project, in one or two plain sentences.

**Third term**

What this word means in this project, in one or two plain sentences.

- See also: First term

The parts of the template, one by one:

Title line. One # heading with the word Glossary, so the file says what it is on its first line.
Sort line. One sentence under the title that tells anyone adding a term to keep the order. Because it sits in the file, the rule stays with the file wherever it goes.
Term. The word or phrase in bold, alone on its line, spelled the way people on the project write it.
Meaning line. One or two sentences in plain words. Write it so that someone who started this week could act on it.
See also. Optional. It names other terms in the same file that a reader may want next. Spell each one exactly as its own entry does.
Not to be confused with. Optional. It names a word that sounds close but means something different in this project, plus a few words on the difference.

In the template, one empty line separates the term, the meaning and the list lines. That keeps each part easy to pick out when you read the raw file.

If you'd rather write each meaning on a colon line under its term, the post on Markdown definition lists shows that syntax along with its test results.

A made-up Doe Holdings glossary

Below, the template holds entries for an invented company. Doe Holdings, plus the two Doe staff named in the sample, are placeholders invented here. The terms come from no real project.

# Doe Holdings glossary

Keep entries sorted by term.

**Close week**

The last five working days of each month. Jane Doe posts the month's entries and signs off on the totals during this week.

- See also: Owner of record
- Not to be confused with: Year end, which Jane Doe handles with its own steps

**Handover note**

A short file that a person writes before time off. A colleague reads it to pick up the open work.

- See also: Owner of record

**Owner of record**

The one person named as answerable for a file or a task. John Doe is the owner of record for the vendor list.

- Not to be confused with: the last person who edited the file

**Quiet hours**

The hours after 6 p.m. on weekdays. Staff at Doe Holdings don't answer work messages during quiet hours.

The four terms sit in sorted order: C, H, O, Q. Each See also line names a term that has its own entry in the same file. Each Not to be confused with line names something a newcomer could mix up with the term above it.

Keeping entries sorted

A sorted file lets a reader find a term by running an eye down the bold lines. This template keeps the order easy to hold with a few habits:

Add a term in its place. Find the spot where the new word fits in the order and put it there, rather than tacking it on last.
Sort by the first word that counts. Drop a leading "the" or "a", so a term first written as The owner of record goes under O as Owner of record.
Settle a tie on the next word. When two terms open with the same word, the second word decides which one goes first.
Keep one entry per term. If a word turns up twice, merge the two meanings into a single entry and delete the copy.
Scan the bold lines after an edit. Reading only the terms, from top to bottom, shows any entry that landed out of order.

Sorting is a separate matter from labeling items a, b and c. For lettered list markers, the post on Markdown alphabetical lists tests what happens to them.

Where GLOSSARY.md lives and how to link it

The setup here gives a project one GLOSSARY.md, kept in the top folder beside the README.md. One file gives a newcomer a single place to look, and the capital letters help the name catch a reader's eye in a folder listing. On lowercase, hyphens, the one file ending and names that stay fixed once links use them, the post on naming Markdown files has a section for each.

A file in the top folder can point to the glossary by its path, as in [glossary](GLOSSARY.md). To aim a link at a heading inside some other file, see how heading links work across files, where the path comes before the heading id.

You can hand the finished file to anyone who needs it, including your own agent.

Answers to the questions people ask more than once go in an FAQ file of their own.

A team's style guide file can point to this glossary for how team terms are spelled.

Where Sashmark fits

On paper, the Sashmark plan is a Markdown reader plus editor for the desktop, meant for people who get .md files from their AI agents. It's in development and not out yet, so there's nothing to try today. A project folder with a GLOSSARY.md sitting next to its other .md files is one example of the files its plan is shaped around.

See the planned features, the help pages and the roadmap for where each part stands.

Visit sashmark.com.

Questions

How is a glossary different from a definition list?: Under The job of a glossary file, the post sets the file apart from the definition list syntax.
Should one file hold every term in a project?: Under Where GLOSSARY.md lives and how to link it, this post gives its choice of one glossary file per project.
Where should a new term go in the file?: The section Keeping entries sorted has tips on placing a new term where it fits in the order.