Markdown tag for document title
MarkdownMarkdown Problem Overview
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.
Markdown Solutions
Solution 1 - Markdown
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.
Solution 2 - Markdown
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.
Solution 3 - Markdown
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
Solution 4 - Markdown
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
Solution 5 - Markdown
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.
Solution 6 - Markdown
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