Markdown file naming conventions that keep links working

An agent writes Plan Final v2.md on Monday and plan-final-v3.md on Tuesday. By Friday the folder holds a dozen files, and you can't tell at a glance which one is current or which links still reach their targets.

Good names won't rescue a messy job, but they make one much easier to read. This post walks through the markdown file naming conventions many teams use, and marks the two spots where a name stops being taste and starts deciding whether a link works. For the wider folder system around these files, see how to organize agent-written docs.

Habits versus hard facts

Most of what follows is convention. Teams settle on a style because it's quick to scan and quick to type, then hold to it.

Two points aren't taste. A file name containing a space changes how a link to that file has to be written. And renaming a file usually breaks relative links that still use the old name. Both get worked examples below.

Lowercase names

Plenty of teams go all lowercase: meeting-notes.md, not Meeting-Notes.md. Some file systems treat those two names as one file and others treat them as two, so a link written as Plan.md may reach plan.md on one machine and miss on another. Lowercase everywhere takes the question off the table.

Many projects carve out a few exceptions for files meant to stand out, such as README.md or HANDOFF.md. Capitals make them catch the eye when you open the folder. If you do this, spell the name the same way in every link.

Hyphens instead of spaces

Spaces in names can cause real trouble, because of how CommonMark reads a link destination. A destination written without angle brackets can't contain a space character. Wrapping it in angle brackets lifts that limit.

Take a file called meeting notes.md and three ways to point at it:

[Jane Doe notes](meeting notes.md)

[Jane Doe notes](<meeting notes.md>)

[Jane Doe notes](meeting%20notes.md)

Save it as links.md, then render: pandoc -f commonmark -t html links.md. The first line stays plain text, brackets and all. The second becomes a link, and pandoc keeps the space inside the href. The third becomes a link whose target is meeting%20notes.md, since %20 is three ordinary characters, not a space.

In the spec, the example for the angle-bracket form prints the space as %20 in its HTML, while pandoc kept a literal space. Both are allowed: the spec says renderers may make different decisions about how to escape URLs. Viewers also differ on decoding %20 to a space before opening the file, so some will open it and some may not.

A hyphen sidesteps all of this. Rename the file to meeting-notes.md and the plain form [Jane Doe notes](/blog/meeting-notes) works with no brackets and no codes. Many teams prefer hyphens to underscores as well. An underscore can be hard to see when a viewer underlines links, and a hyphen reads as a word break. The guide to links between local files covers relative paths and heading links in more depth.

One extension

The usual ending is .md, and .markdown is a longer spelling of the same format. Most tools open either ending, but mixing them in one folder means every link has to remember which file got which ending. A common habit is to pick .md and use it for every file. Just starting with Markdown? The .md file primer explains it, including a save dialog that may tack .txt onto the end.

Dates at the front, year first

For files that pile up over time, such as test results, meeting notes or receipts, many teams start the name with a YYYY-MM-DD date: 2026-10-20-test-results.md. The year leads, then the month, then the day, and each part has a fixed width. Sorted as plain text, names in that form line up in date order.

Other date styles don't. With 10-20-2026, the month leads, so October of one year lands next to October of the next. A name like oct-20.md sorts by letter, which puts April ahead of January.

Keep the date at the front rather than the end. With the date last, names group by topic instead, which can suit a reference folder but rarely suits a log. Skip words like "final" or "v3" as well; a newer date already tells the reader which file came later.

Not every file wants a date. A file edited in place, like a handoff or a plan, keeps one name for its whole life. A date in that name would be wrong after the first edit.

A README or index in each folder

A folder with forty files needs a front door. Many teams give each folder a README.md or an index.md in its root, with a line or two on what the folder holds and links to the files that matter most. Many viewers give a file named README pride of place or open it first, though that varies.

Agent work has its own version of this: a single handoff file for each job, which a new session reads before anything else and which links out to the plan and the receipts. The agent handoff file explainer lists what usually goes inside.

Choose one name for this entry file and use it in every folder. If some folders use README.md and others use index.md, a reader, or an agent told to "read the README first", will skip half of them.

Short names that stay put

A relative link names its target by path. Rename the target and the link still carries the old path, so unless something else now sits at that path, it points at nothing. CommonMark doesn't check that a target exists. During a local test, pandoc turned [Jane Doe notes](/blog/meeting-notes) into a normal link even though no such file sat in the folder, so a broken link can look fine until someone clicks it.

An agent asked to update a plan may write plan-v2.md beside plan.md, or rename the file to match a new title. Links aimed at the old name can now miss, and the folder holds two plans with no sign of which one counts.

Three habits help:

1. Name the file for its job, not its current content. plan.md survives a rewrite. plan-move-billing-to-q3.md goes stale the day the plan changes.
2. Keep names short. Two to four words joined by hyphens is a common target. Short names are easy to type into a link and give a rewrite less reason to touch them.
3. Let the agent know names don't change. Put a sentence in its instructions such as "Keep editing the existing file. Never rename it or save a new copy with a version number." If a rename is truly needed, the same change should update every link that used the old name.

A naming pass for an agent's folder

Before a folder grows past a few dozen files, go through it once:

1. Look for spaces. Each name with a space either gets hyphens, or every link to it gets angle brackets. Hyphens are less work over time.
2. Check the case. Lowercase names, with capitals kept to the one or two entry files you chose.
3. Check the extension. One ending across the whole folder.
4. Check the dated files. Year first, at the front of the name, and only on files that pile up rather than files edited in place.
5. Check the entry file. One README or index per folder, under the same name everywhere.
6. Fix links in the same sitting as any rename. Open each file that pointed at the old name and update the path. A rename and its link fixes belong in one change.

Then write the choices into the agent's instruction file, so the next session starts from the same rules.

Where Sashmark fits

For people who check what their agents write, Sashmark is planned as a desktop project for reading and editing .md files. It is in development and has not been released. The app itself has no AI features. Plans for v1 cover live rendering for lists, tables, links and headings, plus edits made right on that view that leave the bytes of every untouched line unchanged. Reloading in place after an agent changes the file, without losing your reading position, is planned too, along with highlights showing what's new since your last look. Each part's progress is on the roadmap, while scope lives in the help pages plus planned features.

Follow the project at sashmark.com.