If there is no H1, do not indent H2

[zhouhua]

For web-based document editors, there is an interesting issue regarding headings. HTML defines six levels of headings, from h1 to h6, but it's recommended to have only one h1 heading. This means that if you follow this convention, the main body of a document can only start from h2 as the first-level outline, while h1 should be reserved for the overall title of the document.For web-based document editors, there is an interesting issue regarding headings. HTML defines six levels of headings, from h1 to h6, but it's recommended to have only one h1 heading. This means that if you follow this convention, the main body of a document can only start from h2 as the first-level outline, while h1 should be reserved for the overall title of the document.

Different document editors often handle this issue in various ways. Based on my knowledge, here are a few possible approaches:

1. Notion: Allows any number of h1 to h3 headings, but when converted to HTML, they are automatically downgraded to h2 to h4.
2. Lark (a well-known office software in China, from my company): Breaks the HTML constraint and allows any number of h1 to h6 headings, defining the overall title of the document as h0.
3. Obsidian: Offers users maximum flexibility (though a bit chaotic). Users can decide whether to use the file name as the overall document title (h1) through a setting (settings -> appearance -> show inline title). The number of h1 headings in the markdown is not restricted within Obsidian.

So, to enhance the user experience of this plugin, the following optimizations can be made:

• The indentation of headings should depend on their relative hierarchy rather than absolute values. For example, if a document has no h1 and only h2, then h2 should not be indented. Similarly, if there is no h3 under h2 but there is an h4, then h4 should be indented one level relative to h2, not two levels.
• If the beginning of the document consists of body text without any headings, the current plugin’s quick jump functionality cannot navigate directly to the top of the document. In this case, we could add the filename as an additional global title. If the document lacks an h1 heading, it can be added as an h1. Otherwise, it can be defined as h0.
• As a supplement to the previous point: Should we consider the user setting 'show inline title'?
  • If we need to consider this, then if the user has enabled 'show inline title', the filename should be added as the top-level heading.
  • If we do not consider this setting, then the filename should only be added as the top-level heading when the first heading is not in the first line.
  • Or adding a setting.

[zhouhua]

@itsonlyjames maybe we can discuss here

[itsonlyjames]

The indentation of headings should depend on their relative hierarchy rather than absolute values. For example, if a document has no h1 and only h2, then h2 should not be indented. Similarly, if there is no h3 under h2 but there is an h4, then h4 should be indented one level relative to h2, not two levels.

Agreed. I use Linter to automatically adjust the hierarchy for my notes and as such any H4s under H2s get automatically converted to H3s, however let's assume most users don't have this and as such we can indent based on :nth rather than specifically for the heading title. This is an easy update. I would like to make these CSS changes.

I think the last 2 items are rather similar, and my initial thoughts are we respect the inline title setting, so if there is a H1 displayed in the page, that gets rendered in the sticky heading element. Now, it could be considered redundant because the page title is right above this, however it is for the click functionality to go back to the top rather than clicking the page title to rename. I press cmd + up arrow to go all the way to the top, but let's again most users don't know these shortcuts. This is similar to Apple's implementation of tapping the top of the screen to scroll all the way to the top.

I think we respect inline title by default, sticking H1 if it is there, and not if it is not, and then add a setting to this plugin that is along the lines of "Page header sticky: boolean, default true" so that should a user have an inline title, but not wish it to be stuck, this alleviates that and allows all options here to be considered and up to the user.

What do you think @zhouhua?

[itsonlyjames]

Turns out inline title is not considered a "heading element" in terms of HTML, so it's not a H1, we would need to manually push that into the headings array. However I've gone ahead and opened a CSS PR: #7, pull it and check it out

[zhouhua]

Regarding inline titles, my thoughts are more complex. When should they be displayed? When should they not be displayed? How should they be displayed?

• When should they be displayed? Of course, following the user's settings or adding a setting option is the simplest approach. But perhaps we can make it smarter (or have a smarter option). For instance, if a note starts without a title, the user might need a full document title, or perhaps a way to quickly jump to the top of the page.

• When should they not be displayed? Similarly, the simplest way is to have a true/false option, but I believe there should also be a smarter method (which I didn't mention above). Have you ever used the official daily note plugin? The notes it generates always have an H1 title that matches the filename (this style of note is quite common). In such cases, displaying an inline title would be unnecessary. Automatically recognizing this situation through programming shouldn't be difficult, for example, if the first title matches the filename or if the first title is the only H1.

• How should they be displayed? This is the issue I wanted to discuss above. Sometimes directly inserting an H1 is inappropriate because the document might already have multiple H1s that are not equivalent to the filename. I provided examples of implementations in Notion and Lark, and I believe that in our scenario, the Lark example is more feasible. If the document has multiple H1s, the inline title could be inserted as H0.

[zhouhua]

Oh, most of what I mentioned above pertains to the default mode.

[zhouhua]

The indentation of headings should depend on their relative hierarchy rather than absolute values. For example, if a document has no h1 and only h2, then h2 should not be indented. Similarly, if there is no h3 under h2 but there is an h4, then h4 should be indented one level relative to h2, not two levels.

This feature is complete.

[itsonlyjames]

This is such an interesting discussion because you are thinking about this in such an abstract way, it's brilliant. Whereas my view is much more focused on structure, all of my notes follow the same structure. The page title is the H1, and any heading within the document is then considered subordinate to that Page title—H1. So for me inline title, while it makes sense to include in the sticky, it does then, like you say, interfere with the other options where users might have both page title and H1's...

In this case, with my relatively simple thinking of this, and seeking a simple solution, I think your idea is best. We had an option to stick the Page Title as H0, and then any H1s would be indented once, and H2s would be indented twice, and so on...

I would not need to turn this setting off/on because I don't have the inline page title enabled, which means it could never stick when there's no inline title. However the option existing should users have the inline title enabled, would then allow all combinations to be considered.

So I think of these scenarios (within the sticky header):

1. Inline title disabled, setting does not matter:

# h1 (indent level 1)
## h2 (indented level 2)

2. Inline title, setting to stick inline title enabled:

Page Title (indent level 1, considered H0)
# h1 (indent level 2)
## h2 (indented level 3)

3. Inline title, setting to stick inline title disabled:

# h1 (indent level 1)
## h2 (indented level 2)

Altering Indent level meanings

This does also raise a concern of mine that indent level should be indexed, so the first element with no indent is not level 1 but 0. Indent level 1 to me means it is indented 1 level

# h1 (indent level 0)
## h2 (indent level 1)

This would better suit the implementation of inline title also, because it could look like so:

Page Title (indent level 0, considered H0)
# h1 (indent level 1)
## h2 (indented level 2)

[zhouhua]

Altering Indent level meanings

We've already broken the equivalence between indentation levels and title levels, haven't we?

If users are indeed troubled by this, we can set the default value to false.

[itsonlyjames]

You are correct, but what I speak of is highly low level and pendantic in regards to logic. I have created this PR for you to visualise: #14