search

nvim-neorg / norg-specs

A collection of specifications and grammars for Neorg's file format, `norg`.
88 stars 18 forks source link

[Specification 2.0]: Add entry about headings #44

Open vhyrro opened 1 month ago

vhyrro commented 1 month ago

This PR adds a headings section and attempts to describe them in the most succinct way possible.

boltlessengineer commented 1 month ago

Can we rename heading to section? I think it makes more sense.

heading -> section heading title -> heading

So when we say "content of heading" we explicitly say for the text coming after the asterisks.

This will also help users from markdown-like syntax to understand how heading in Norg work differently. (heading indents all the content below)

vhyrro commented 4 weeks ago

I don't see any added value of changing the definitions here honestly. Since norg is more org-derived than markdown-derived I'd keep the original term and not break the existing established wording in the v1 spec. "Title" is plenty explanatory :)

boltlessengineer commented 4 weeks ago

I'm saying with the context of #43. If we want to put heading everywhere and define a "block" node, heading itself should not do anything structural.

- * heading
** subheading
- second list item??

This will be hard to parse, way more than before.

If heading can be anywhere as a block without structuring the document, we are actually allowing title, not heading.

Then the wording is bit confusing because now we have to say "title can be placed anywhere that block item can exist". The word "title" doesn't seem to fit here because it sounds like it has a similar meaning to "name" from +name.

This is not that important for me (compared to other suggestions I've made). Maybe it's just me trying to do unneeded stuff. Feel free to reject this proposal.