dedicated syntax for document title

[matklad]

HTML says there can be only one h1, which doubles as a title of the document.

However, in typical markdown usage it's very common to see

some text

# first section

more text

# second section

...

That is, people use # as a generic section title.

This is understandable: the fact that # is thee title of the document, and that sections should be ## is a somewhat arcane knowledge.

So, I am thinking that perhaps we should roll with this usage, and create some dedicated syntax for document's title:

= Doc Title 

abstract

# Section title

## Subsection

Benefits:

• resolve ambiguity between # as a document title, and # as a section title
• "first-level section" is the most frequent use-case, makes sense for it to be the shortest syntax
• Somewhat nicer AST, as currently a section around top-level heading is pretty useless. For documents in titles, the top-level doc always has exactly one child, the section.

[matklad]

No opinion on specific concrete syntax, but, to starwman = title or # title # or indentation # title could work

[chrisjsewell]

It's common in markdown to put the title in the (yaml) front matter.
If #35 was implemented would you maybe do this also?

[matklad]

Not really: I'd much rather have a proper document title in the document itself, and extract metadata from it, than go in the opposite direction.

[uvtc]

= is already used for {=highlight=}, and it also shows up a lot already in attributes of divs and spans (and for marking what type a raw block contains). But aside from that, I suspect that equals signs === may end up being used as a fence marker in the future, for what I do not know.

[jgm]

So, I am thinking that perhaps we should roll with this usage, and create some dedicated syntax for document's title:

Yes, in pandoc we use # for regular section headings (one reason for this is that we don't just target HTML), and the document title comes from the title field in metadata, which may be specified either in an old-fashioned pandoc title block

% Title
% Author Q. Writer
% 2022-01-03

or in a a YAML format

title: Title
author: Author Q. Writer
date: 2022-01-03

I think it's a bit artificial to give the document title special treatment when it is just one of a number of metadata, though usually it's the most important of these.

[matklad]

when it is just one of a number of metadata

I don’t see the title as metadata, to me it seems a proper part of the document, which I’d expect to see in html output as h1, be able to inline-style it, see it bolded with syntax highlighting, etc.

Though, if we do create a dedicate syntax for either metadata or title, it makes sense to make them work in concert as just one syntax for document header. I do like pandoc title block, as well as asciidoctor’s https://docs.asciidoctor.org/asciidoc/latest/document/header/

[jgm]

Well, the title isn't the only metadata element you'd expect to see in the output. Author and date, for example, are often included, sometimes things like abstracts. I completely agree that you should be able to apply formatting to it -- metadata in general need this.

[kai-tub]

This is a bit off-topic, but something that I also find frustrating is that there are often limitations in pushing down the header level when rendering Markdown in other tools.

HTML says there can be only one h1

Some of us strict HTML followers take this spec and conclude from it that the only part of a web page that should be considered as an H1 heading is the actual site title/logo (for example, the GitHub logo on the top-left part would be the single H1 heading of GitHub) and everything else falls below that.

Some tools forcibly define the top-heading level to h1 with no easy way to change this behavior.

Would it be possible to define the starting level?
So when title is set in yaml, define that it should start with h2 and not h1?
Or would/should this be solved as a post-transform on the AST?

Just something that I thought might be worth giving my 2cts on. :)

PS: I am very aware that there are different opinions on this HTML spec but it would be nice if both interpretations were kept in mind ❤️

[jgm]

In pandoc we have the option --shift-heading-level-by which allows you to make this sort of adjustment. I think it makes sense to think of it as a rendering issue. Now that djot puts the AST into sections, we could have the HTML renderer just use h2 for top-level section headings, and so on, reserving h1 for the document title. A renderer into another format, say LaTeX, could do something different and appropriate to that format.