Headers created in custom directives disappear

[japgolly]

Hi. Consider this custom directive:

    val demoDirective = Blocks.create("demo") {
      import Blocks.dsl._
      attribute(0).as[String].map { arg =>
        BlockSequence(
          Paragraph("before"),
          Header(1, "Arg = " + arg),
          Paragraph("after"),
        )
      }
    }

when I used it like this

# Test
# Here we go...
@:demo(hello)

for some reason the header disappears. The output is

Test
Here we go...
before

after

instead of

Test
Here we go...
before
Arg = hello
after

[jenshalm]

Welcome and thanks for reporting, this does indeed look like a bug.

Just as an FYI about directives generating headers: Even after fixing this bug there will be limitations, which may or may not matter to you. Due to the processing order a header inserted by a directive will not have an id and not appear in any auto-generated navigation for the page. This is by design. The reason is that it is more likely that a directive wants to look at the page structure to generate navigation (e.g. the @:navigationTree directive) than to contribute to the navigation structure itself. Allowing both would be a chicken-and-egg scenario that is difficult/impossible to resolve.

I assume (without verifying yet) that the bug relates to that limitation and when detecting that the header is "late to the party", Laika wrongly discards it instead of rendering it with those limitations.

This means that if you do need an extension that generates headers you can also link to you'd need a parser extension instead which would be processed before all directives.

Update: the above limitations do no longer apply after the refactoring in #302 which will be part of 0.19. In most cases things like adding headers in directives will then just work, and only a much smaller number of edge case scenarios will still come with some limitations.