# Document titles

**URL:** <https://talk.commonmark.org/t/document-titles/649>\
**Category:** Extensions\
**Created:** [September 20, 2014, 12:28am UTC](https://talk.commonmark.org/t/document-titles/649 "2014-09-20T00:28:37Z")\
**Posts on this page:** 20\
**Page:** 2

<div class="post-metadata">

**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [September 27, 2014, 11:40am UTC](https://talk.commonmark.org/t/document-titles/649/21 "2014-09-27T11:40:07Z")

</div>

# Document title

I agree with kagan, that a run of spaces before a word as first or second line is probably a title, and should be auto recognised as such. And treated as `<h1>`. As for why? It’s because I would hate to have to keep typing `##` throughout the entire document (As you would see in my metadata via `|` example below)

e.g.

lazy headers (only works if you add enough spaces)

```
                 Blogging Like a Hacker

| title: This is a title

... intro ...

# My First Chapter

## Level two header

Lorem ipsum (TBC)

```

or ( typical markdown Setext-style headers. Recall that `===...` is h1 and `---...` is h2 ). Not sure if this is a good idea, since it’s not immediately obvious that it is a document title, since it is typically used for subheadings.

```
Blogging Like a Hacker
=======================
| title: This is a title

... intro ...

# My First Chapter

## Level two header

Lorem ipsum (TBC)

```

or ( non-standard Setext-style headers, but specifically used to demarcate document titles). Babelmark2 shows that `###...` is not supported anywhere, so is a good candadate for document title declaration [babelmark2](http://johnmacfarlane.net/babelmark2/?normalize=1&text=%0Ahello+world%0A%23%23%23%23%23%23%23%23%23%23%23%23%23%23) :

```
#################################################
            Blogging Like a Hacker
#################################################
| title: This is a title

... intro ...

# My First Chapter

## Level two header

Lorem ipsum (TBC)

```

is rendered as (note: [usage of header tag](http://www.w3schools.com/tags/tag_header.asp) ):

```
<head>
    <title>This is a title</title>
</head>
<body>
   <header>
    <h1>Blogging Like a Hacker</h1>
    <p>... intro ...</p>
   </header>
   <main>
    <h1> My First Chapter </h1>
    <h2> Level two header </h2>
        <p>Lorem ipsum (TBC)</p>
   </main>
</body>

```

# Metadata

Moved to

[http://talk.commonmark.org/t/metadata-in-documents/721](http://talk.commonmark.org/t/metadata-in-documents/721)

---

<div class="post-metadata">

**Author:** ![Burt\_Harris](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/burt_harris/32/368_2.png) [@Burt\_Harris](https://talk.commonmark.org/u/Burt_Harris)\
**Post date:** [September 28, 2014, 5:07pm UTC](https://talk.commonmark.org/t/document-titles/649/23 "2014-09-28T17:07:18Z")

</div>

> [@kagan](#):
>
> I think it would not harm to create \<meta\> tags for those keywords in the HTML Header in addition to the \<p\> tag. That could be useful for other software tools that read the meta data from the meta tags.

While I agree it would cause no harm for an implemention to do this, I think that most implementations typically never generate any `<head>` tags at all, so it would complicate spec matters significantly to specify correct placement of a `<meta>` tag. .

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [September 28, 2014, 11:35pm UTC](https://talk.commonmark.org/t/document-titles/649/24 "2014-09-28T23:35:23Z")

</div>

The fenced (`---`) YAML approach is shared across jekyll, hyde, plume, nanoc actually.

And would be better to keep this kind of markup at the application level.IMHO.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [September 29, 2014, 5:32am UTC](https://talk.commonmark.org/t/document-titles/649/25 "2014-09-29T05:32:40Z")

</div>

> [@mofosyne](#):
>
> I agree with kagan, that a run of spaces before a word as first or second line is probably a title, and should be auto recognised as such. And treated as \<h1\>. As for why? It’s because I would hate to have to keep typing ## throughout the entire document (As you would see in my metadata via | example below)

Are you suggesting that a single `#` should be changed to `<h2>` in the case that a title with a run of spaces is added to the top of the file? If so, I can see this being confusing for people copy/pasting text from different Markdown files that use a single `#` to mean `<h1>`.

> [@Burt\_Harris](#):
>
> The second approach is using HTML/SGML declaration format to encapsulate YAML metadata. Same basic idea, just using delimiters that are far older: \<! and \>.

I’d prefer to keep as much XML-like syntax out of Markdown as possible. Markdown isn’t primarily for parsers, but for human readers (as Gruber writes in the philosophy of Markdown, “Readability, however, is emphasized above all else.”). Just as YAML is more readable than XML because it is closer to something a writer might jot down in a text editor, Markdown should lean towards being less of programmers tool and more of a writer’s tool.

---

<div class="post-metadata">

**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [September 29, 2014, 6:11am UTC](https://talk.commonmark.org/t/document-titles/649/26 "2014-09-29T06:11:35Z")

</div>

Yea, I should change that post. Best to maintain consistency. Though how would you make the main document title be like `<h0>` or something.

Agreed on keeping out XML syntax, it’s why we switched to markdown in the first place. However I would like to say that for document declaration, we should consider if we need to go with `<!CommonMark 0.1.23-github.username.projectname >` to inform the parser which version to use. But would like to be convinced that placing the document declaration as a meta data would still work. (Since it’s much nicer to look at)

e.g.

```
                     My Title

| !CommonMark: 0.1.23-github.username.projectname
| title: Title for the top bar of any browser

```

vs

```
<!CommonMark 0.1.23-github.username.projectname >

                     My Title

| title: Title for the top bar of any browser
```

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [September 29, 2014, 8:09am UTC](https://talk.commonmark.org/t/document-titles/649/27 "2014-09-29T08:09:24Z")

</div>

I would keep that as application-specific and possibly fit within the current target users of the markup.

Namely: hyde, jekyll, Flask-FlatPages, nanoc.

Anything that would make their life or the life of their users harder is counterproductive.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [September 29, 2014, 9:15am UTC](https://talk.commonmark.org/t/document-titles/649/28 "2014-09-29T09:15:19Z")

</div>

> [@mofosyne](#):
>
> Yea, I should change that post. Best to maintain consistency. Though how would you make the main document title be like \<h0\> or something.

I’m not quite sure what you mean here. There is no `<h0>` HTML tag, so the main document heading would need to be `<h1>`.

What I meant is that subsequent headings would need to be `##` which translates to `<h2>` for consistency when copy/pasting between Markdown documents. If we went with an overall heading it would need to be `<h1>` regardless of the Markdown syntax used.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [September 29, 2014, 9:22am UTC](https://talk.commonmark.org/t/document-titles/649/29 "2014-09-29T09:22:46Z")

</div>

I see a problem with using spaces to represent a document heading; four spaces are already used to represent a code block. What if the writer wanted to put a code block on the first line?

---

<div class="post-metadata">

**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [September 30, 2014, 1:47pm UTC](https://talk.commonmark.org/t/document-titles/649/30 "2014-09-30T13:47:17Z")

</div>

Ah… that’s so true, and so annoying as well. There is two potential ways to tackle that.

1. Heuristics. Does it look like a title? e.g. 8 or more spaces, and a newline. (I don’t like this idea)
2. Only allow lazy document titles ‘before’ a document declaration like below. The code will be placed after the document declaration. As for why? In most cases where you declare a lazy title, it would most likely be for a dedicated document. (I prefer this idea)

- Best thing about this approach, is you can declare multiple lines to be a header. E.g. like the front page of a report.

e.g.

```
                 The Report
              By Robert Smithly
                    2042

| !CommonMark: 0.1.23-github.username.projectname
| title: Title for the top bar of any browser
| layout: report

    Function(2+2);

The above function is rendered as a code block, while the title is treated as h1 since it is before the document declaration. This is a simulated paragraph.

```

the document declaration is metadata located on top of document (via compact metadata syntax):

```
| !CommonMark: 0.1.23-github.username.projectname
| title: Title for the top bar of any browser
| layout: report

```

Which if user is lazy enough, can just simply be `|`

```
                               The Report
                            By Robert Smithly
                                  2042
|

The above function is rendered as a code block, while the title is treated as h1 since it is before the document declaration. This is a simulated paragraph.

```

* * *

The reason why I really really would like some lazy document title, at least for stand alone documents, is that it looks much prettier.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [October 1, 2014, 2:11am UTC](https://talk.commonmark.org/t/document-titles/649/31 "2014-10-01T02:11:24Z")

</div>

> [@mofosyne](#):
>
> The reason why I really really would like some lazy document title, at least for stand alone documents, is that it looks much prettier.

If you resize the editor window it’s not going to remain centred which could make the heading look a bit odd. At least with an underlined heading (or a heading prefixed by `#`) it will look consistent. IMO, Markdown doesn’t need to aim to look so close to the actual output, especially if the same document’s presentation differs when reused across different sites (some site headings might be centred, others left aligned).

---

<div class="post-metadata">

**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [October 1, 2014, 3:10am UTC](https://talk.commonmark.org/t/document-titles/649/32 "2014-10-01T03:10:07Z")

</div>

I guess, but at least it would still be a choice for users. I mean, it could probbly mean the same thing to type. ( multiple spaces doesn’t matter, since it is unlikely people want to type code for the title page. But can have bold or italic) (Usually implicitly `#` in document title, but can be overrid by `##`)

```
The Report
## By: **Robert Smithly**
## Year: 2042

| !CommonMark: 0.1.23-github.username.projectname
| title: Title for the top bar of any browser
| layout: report

The above function is rendered as a code block, while the title is treated as h1 since it is before the document declaration. This is a simulated paragraph.

```

This way it is left up to the user how they want to lay out the document title in text form.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [October 1, 2014, 3:19am UTC](https://talk.commonmark.org/t/document-titles/649/33 "2014-10-01T03:19:46Z")

</div>

The writer might not intend for the first line to be heading though. For example, the document may just be some causal notes with no need for a heading.

---

<div class="post-metadata">

**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [October 1, 2014, 3:21am UTC](https://talk.commonmark.org/t/document-titles/649/34 "2014-10-01T03:21:43Z")

</div>

Then you place it under the document declaration. (If document declaration is not done, then there is no cover page, but the first header will be auto detected as the page title.)

```
<< This area is for the 'Cover Page' and title >>

| !CommonMark: 0.1.23-github.username.projectname
| title: Title for the top bar of any browser
| layout: report

<< This area is for everything else like casual notes >>
```

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [October 1, 2014, 4:14am UTC](https://talk.commonmark.org/t/document-titles/649/35 "2014-10-01T04:14:16Z")

</div>

Markdown doesn’t traditionally support the concept of “pages”; it’s more fluid than that. A piece of Markdown is usually pastable between different parts of different documents. Markdown typically represents a _section_ of an HTML document, rather than the entire document.

That’s not to say that supporting cover page use cases is a bad idea, but I do think any syntax should be defined in more abstract terms that correspond to particular HTML elements. You would typically use a “print” stylesheet in CSS for print documents and apply page break rules to particular HTML elements.

It is common to reuse a document heading in multiple places. For example, the following HTML is common:

```auto
<html>
  <head>
    <title>Site Name - Article Name</title>
  </head>
  <body>
    <img src="site-name-logo.png" alt="Site Name's Logo" />
    <h1>Article Name</h1>
  </body>
</html>

```

As you can see, the article name is reused in two places. This is essentially our “document heading”.

In my view, it does not make sense to require the writer to define the document heading in two places - that’s tedious and violates the DRY principle. It should be the content management system’s job to reuse the contents of the `<h1>` tag inside the `<title>` tag. The same approach could apply to a cover page.

---

<div class="post-metadata">

**Author:** ![Rick](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/rick/32/420_2.png) [@Rick](https://talk.commonmark.org/u/Rick)\
**Post date:** [October 2, 2014, 2:54am UTC](https://talk.commonmark.org/t/document-titles/649/36 "2014-10-02T02:54:06Z")

</div>

I have been playing with a new static web page generator that reads Markdown. It also reads three different kinds of Document Metadata or Front Matter:

YAML, JSON, or the new TOML

> **[Front Matter](http://gohugo.io/content-management/front-matter/)**
>
> Hugo allows you to add front matter in yaml, toml, or json to your content files.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [October 2, 2014, 3:07am UTC](https://talk.commonmark.org/t/document-titles/649/37 "2014-10-02T03:07:52Z")

</div>

`---` seems to be quite common for defining YAML frontmatter. [Middleman](http://middlemanapp.com/basics/frontmatter) uses this as well, but `;;;` for defining JSON frontmatter.

---

<div class="post-metadata">

**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [October 2, 2014, 3:12am UTC](https://talk.commonmark.org/t/document-titles/649/38 "2014-10-02T03:12:58Z")

</div>

How hard would it be to recognise something like below for Front Matter, in terms of implementation complexity

```
| !CommonMark: 0.1.23-github.username.projectname
| title: Title for the top bar of any browser
| layout: report

```

or

```
| !CommonMark: 0.1.23-github.username.projectname | title: Title for the top bar of any browser | layout: report
```

---

<div class="post-metadata">

**Author:** ![lu\_zero](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/lu_zero/32/557_2.png) [@lu\_zero](https://talk.commonmark.org/u/lu_zero)\
**Post date:** [October 2, 2014, 8:01am UTC](https://talk.commonmark.org/t/document-titles/649/39 "2014-10-02T08:01:11Z")

</div>

> [@mofosyne](#):
>
> How hard would it be to recognise something like below for Front Matter, in terms of implementation complexity
> 
> | !CommonMark: 0.1.23-github.username.projectname  
> | title: Title for the top bar of any browser  
> | layout: report
> 
> or
> 
> | !CommonMark: 0.1.23-github.username.projectname | title: Title for the top bar of any browser | layout: repor

given that the second example looks like a table, a **lot**.

---

<div class="post-metadata">

**Author:** ![mofosyne](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/mofosyne/32/1438_2.png) [@mofosyne](https://talk.commonmark.org/u/mofosyne)\
**Post date:** [October 2, 2014, 9:06am UTC](https://talk.commonmark.org/t/document-titles/649/41 "2014-10-02T09:06:23Z")

</div>

Well if we excude the second example, then `|` could work well.

Else the other option is to use `:` as first character of each line to indicate that it is a metadata.

```
: !CommonMark: 0.1.23-github.username.projectname
: title: Title for the top bar of any browser
: layout: report

```

It’s not to replace the block YAML or json. But rather to allow for a lazy typing of quick meta data.

---

<div class="post-metadata">

**Author:** ![chrisalley](https://cdn.commonmark.org/user_avatar/talk.commonmark.org/chrisalley/32/906_2.png) [@chrisalley](https://talk.commonmark.org/u/chrisalley)\
**Post date:** [October 2, 2014, 9:20am UTC](https://talk.commonmark.org/t/document-titles/649/42 "2014-10-02T09:20:22Z")

</div>

Using `:` at the start of a line might conflict with the data definition list syntax.

[Previous page](https://talk.commonmark.org/t/document-titles/649.md?page=1)

[Next page](https://talk.commonmark.org/t/document-titles/649.md?page=3)