The ambiguity
In HTML, <h1> means "the most important heading on this page."
By convention, that is usually the page title — but the spec doesn't require it.
Markdown inherited this ambiguity: # produces the largest heading,
and what that heading is depends entirely on context.
In practice, two different conventions have developed and both are widespread. They produce identical markdown but carry different intent, and that intent matters the moment you do anything structured with the output.
| Convention | What # means |
Where it's common |
|---|---|---|
| Title convention | Document title. One per file, at the top. Not a content heading. | README files, documentation sites, blog posts, GitHub wikis |
| Heading convention | Top-level section heading. Can appear multiple times. Title is implicit or in metadata. | AI output, academic writing, long-form articles, YAML-fronted docs |
Neither is wrong. They are just different assumptions about the same syntax. The problem is when software has to make a choice between them.
What AI does
When you ask a language model to write a structured document, it will almost
always open with # Title followed by ## Section headings.
This follows the title convention — the H1 is the document name, not a content
section. That is reasonable and readable.
But when AI writes a report, analysis, or list of recommendations in response
to a conversational prompt, it sometimes uses # headings for each
major point — treating H1 as a section heading with no document title above it.
Both patterns appear regularly in AI output, often depending on how the prompt
was phrased.
The same model can produce either convention depending on the prompt. If you ask for "a report on X," you are more likely to get a title-convention H1. If you ask to "list the main reasons for X," you may get heading-convention H1s with no title.
Why it matters for Word conversion
Word documents have a dedicated Title style — separate from Heading 1. The Title style is typically larger, centred, and used once at the top of the document. Heading 1 is a section heading that can repeat.
When you convert markdown to Word, the converter has to decide: should the
first # become a Word Title, or a Heading 1? The right answer
depends entirely on which convention the author was using — and the converter
cannot know this from the syntax alone.
# Quarterly Review — Q1 2025 ## Executive Summary The first quarter results show... ## Key Findings ...
If the author intended the title convention, # Quarterly Review
should map to Word's Title style and ## sections to Heading 1.
If the author intended the heading convention, # should map to
Heading 1 and there is no Word Title at all.
Converting without this decision produces either a document with a gigantic Heading 1 at the top that looks wrong, or one where the title is swallowed into the heading hierarchy.
How markdownword handles it
markdownword gives you two distinct ways to set a document title, and handles both correctly.
Option 1 — YAML front matter
If your markdown file opens with a YAML front matter block, markdownword
parses it and uses the title field as the Word Title style.
No H1 heading needed at all. Additional fields — author,
date, subject, abstract, and more —
are written into the Word document's built-in metadata properties.
--- title: "Quarterly Review Q1 2025" author: "Mattias Linder" date: "2025-04-01" status: "Draft" --- ## Executive Summary The first quarter results show...
With this approach, your H1 slots are free to use as section headings — or you can skip H1 entirely and start directly at H2. Word's Title field, author, and date fields are populated correctly.
Option 2 — firstH1AsTitle
If there is no front matter, the firstH1AsTitle option treats
the first # heading as the Word Title style, with all subsequent
headings shifting down one level. This covers the common case where a document
opens with a single H1 title followed by H2 sections.
Default: on. Most markdown documents with a single #
at the top are using the title convention. Turn it off if your H1 is a content
heading rather than a document title.
If both a YAML title: field and firstH1AsTitle are
active at the same time, markdownword will warn you — two title sources in one
document is almost always unintentional.
What to do in practice
If you are writing markdown that will be converted to Word or another structured format, the clearest approach is to commit to one convention and be consistent:
- Use
#once, at the top, as the document title. Use##for your main sections. This is the title convention and works well with most converters. - If you are writing AI prompts that ask for structured output, include a note about which convention you expect — or specify in your style guide that output should always open with a title H1.
- When converting AI output that uses H1 as a section heading with no title,
turn
firstH1AsTitleoff — or add a title manually before converting.
The ambiguity is baked into markdown and will not be resolved by the spec. The only practical answer is consistent intent.