UX Basics: Markdown filename vs H1

Right now markdown docs appear to save in the filesystem adding the doc name as an h1 at the top formatted as: “# My Heading“

However, the filename may not be what you want as an H1. This is why a famous editor Obsidian has settings for this:

If I were you I would avoid all this confusion and never put the filename inside the text itself. It’s a typical issue in all markdown editors which is handled differently by each app. The fact is a filename is not the same as content and sometime you dont want the filename to be the same as your H1.

Examples:

1) Sort order. You may deliberately prefix filenames to enforce a kind of sequence, without making that prefix part of the displayed title. People do this in markdown apps like Obsidian or Bear quite frequently because they don’t have manual sorting like Ulysses.

01-accessibility-audit-process.md

Accessibility Audit Process

2) A filename might be a short internal label while the H1 is the clear public-facing title.

a11y-ops.md

Operating an Accessibility Practice as an Independent Consultant

3) You might refine the document’s title multiple times while wanting inbound links, URLs, sync references, or automation paths to remain stable.

consulting-offer.md

Accessibility Consulting: Initial Service Menu which may change to Accessibility Consulting Packages for Small Product Teams

4) File systems and publishing tools impose rules that a human title should not have to follow. This is a major gripe of mine. The H1 can retain the human-facing punctuation and typography a reader expects.

wcag-2-2-criterion-1-4-3.md

WCAG 2.2, Success Criterion 1.4.3: Contrast (Minimum)

5) A unique filename can distinguish documents that need the same—or nearly the same—visible H1.

2026-08-26-client-a-discovery.md

Discovery Workshop

2026-08-27-client-b-discovery.md

Discovery Workshop