105

Is there no way to indicate the document title in a Markdown document?

I've come to use Markdown with Sublime Text to prepare many of my personal and business documents. I often want to have a kind of "top level" heading analogous to the Title style in Word, for example. So, for example:

### Things to Do ###

At Home
=======
*    Mow the cat
*    Feed the lawn

At the Office
=============
*    Learn Markdown
*    Use Big-O notation in a clever way

But the ### Things to Do ### line is not respected by Markdown, and I don't know an alternative. Is there one?

I could use the Heading 1 style for the title and then Heading 2 for the rest, but if I need a deeper nesting of headings, I quickly run out of depth. And, after all, a title fundamentally isn't a heading per se. It would be nice, for example, if Markdown-to-HTML parsers used the Title for the page <title> as well as for a top-of-page header a la Word titles.

4
  • ### Things to Do ### should be respected, but because of the three repetitions of #, you get a third-level header, which obviously isn't suitable for your goal.
    – Ryan Prior
    Jun 13, 2013 at 22:19
  • @RyanPrior True. I was trying to come up with a notation that seemed "ultra-bold", but ran afoul of existing syntax. That's one of the reasons I don't prefer the Atx style: less important things get more boldness. Jun 13, 2013 at 22:21
  • 1
    Many Markdown-to-foo renderers are extensible. You could consider adding a rule to super-bold text underlined by a different repetition of characters. Perhaps ^^^^^s?
    – Ryan Prior
    Jun 13, 2013 at 22:29
  • 1
    Definitely make sure you mow that cat.
    – Bondolin
    Apr 28, 2022 at 17:36

6 Answers 6

58

If you are referring to pandoc markdown specifically the simplest approach is to use '%', e.g.

% Document Title

# Header 1

content

## Header 2

## Header 2

see http://pandoc.org/README.html#metadata-blocks for more information on pandoc markdown.

4
  • 3
    Thanks! Any way to prevent the title from being duplicated in the document body? I saw something about the -T option during pandoc compilation, but the manual didn't really make sense. And it's annoying to have to remember to type some extra options/parameter values each time I compile (instead of having it stored within the document) Jun 1, 2016 at 12:26
  • 1
    You can set the title metadata on the command line: --metadata=title:"Document Title".
    – Joe Bane
    Nov 8, 2018 at 21:44
  • @MichaelChirico, any way to do that with the title in the document (not -T, not --metadata title="annoying"), in pandoc 2.11 ?
    – denis
    Mar 29, 2021 at 15:07
  • % does't seem to ahve any effect for .md focs in vscode, anything else I shoudl do?
    – Je Je
    Oct 23, 2022 at 10:55
58

I write books and research papers in Markdown that I post exclusively on GitHub and HTML title tags in Markdown don't work on GitHub so I use the convention that:

Document Title
==============

***This is a subtitle***

**Author:** *Me*

# Chapter One: Overview

Do you know the way?

---

# Chapter Two: Foo

Foo is the way...

---

Which ends up looking like:


Document Title

This is a subtitle

Author: Me

Chapter One : Overview

Do you know the way?


Chapter Two : Foo

Foo is the way...


I use the --- in order to separate chapters because it looks good and helps to find the chapter in the text. This does present a problem however when the Markdown document becomes large in which case the Markdown Preview Window then begins to freeze up on you every time you type as it refreshes or Grammarly starts to bug out and take a REALLY long time. This is the justification for using the === H1 Title Format because when the document gets large you need to break it up, in which case it's nice to use the format:

Document Title
==============

***This is a subtitle***

**Author:** *Me*

[<< Previous Chapter](URL) | [Content Table](URL) | [Next Chapter >>](URL)

---

# Chapter Two: Foo

Foo is the way...

---

[<< Previous Chapter](URL) | [Content Table](URL) | [Next Chapter >> ](URL)

Which then looks like:


Document Title

This is a subtitle

Author: Me

<< Previous Chapter | Content Table | Next Chapter >>


Chapter Two : Foo

Foo is the way...


<< Previous Chapter | Content Table | Next Chapter >>


I have also given up on using the Wiki filename for the Title because it does not allow for hyphenated words, which messes up my chapter titles, so I've switched to all lowercase filenames starting with the chapter index 01_chapter_name.md, 02_chapter_name-with-hyphens.md, ... with the === H1 Title Format and moved my Markdown books into the main repository so I can use Issue Driven Development and GitHub Issues and Projects with one Project per chapter so I can remember all of the things to do and get through the backlog.

2
  • 1
    This is a great guide for others!
    – abalter
    Nov 29, 2018 at 17:01
  • 1
    At least in Azure DevOps, === is interchangeable with #, so both show up as headers in a TOC, and with the same weight in the page.
    – Bondolin
    Apr 28, 2022 at 16:34
30

One of the interesting points of Markdown's design is that HTML is explicitly allowed. HTML5 added semantic page sections including <header> and <main>, which may be a good fit for your page title.

For example:

<header>
Things to Do
============
</header>
<main>
At Home
=======
*    Mow the cat
*    Feed the lawn

At the Office
=============
*    Learn Markdown
*    Use Big-O notation in a clever way
</main>

If excluding HTML is preferable to you, you may want use the Atx-style headings in order to get more than two levels of hierarchy.

For example:

# Things to Do

## At Home
*    Mow the cat
*    Feed the lawn

## At the Office
### Morning
*    Learn Markdown
*    Use Big-O notation in a clever way
### Afternoon
*    Read e-mails
*    Scrutinize LOLcats
1
  • 28
    The problem with the Atx-style headings is that heading numbering in, say, pandoc, is affected by that top-level heading, so everything appears under section 1 (i.e. only 1.x, 1.x.x, no section 2).
    – davidA
    Mar 16, 2015 at 2:51
11

There's a brute-force one-off solution that I thought I'd post:

<font size="+12"><center>
    Things to Do
</center></font>

There's definitely a more sophisticated way of doing this, but I found that since this is used once per document, it's not so bad.

2
  • 4
    This is an old one - but for reference - HTML-tags should be nested correctly, so the last line should be </center></font>
    – Gerd
    Jul 17, 2020 at 13:50
  • 2
    I love this, finally a flavor-agnostic solution that distincts the title from headings and doesn't clutter my TOC! \o/ Mar 16, 2022 at 14:31
7

Title Metadata

If you are using MultiMarkdown you can add some metadata at the top of the document

format: complete
title: This is a title for the web-page
css: http://example.com/main.css

First line of visible text

The title will get included in a <title> in the <head> section

You can also include it by reference in the body using [%title])

Sub-sub-headings

There shouldn't be any problem in recognising ### at the start of the first line as a level 3 header to generate <h3> tags. I use this in several implementations of Markdown/MultiMarkdown

You can test it using John Gruber's Dingus, Markable, etc.

Heading offset

At least some Markdown/Multimarkdown implementations allow you to specify an offset for generated headings so that it generates <h2> and <h3> instead of <h1> and <h2>.

This would allow you to put, for example, <h1>Title</h1> or <h1>[%title]</h1> as the first line of your document (after metadata declarations).

References

0

If you don't mind using RStudio, Rmd (rmarkdown) files generate the title using a metadata section at the top, and then use #+ for headers.

Links

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.