Custom block directive is not rendered if output includes an ID

[noelwelsh]

I'm creating a custom directive to render an element with an ID. This is it's sole purpose: I need an element in the DOM with a known ID so I can hook into it from Javascript (to render some Doodle images). This should be straightforward, but whenever I set an ID on the element I create it doesn't get rendered. If I remove the ID it does get rendered!

Here's the code I'm currently using:

  val mount: Blocks.Directive =
    Blocks.create("mount") {
      import Blocks.dsl._

      attribute(0)
        .as[String]
        .map { (id) =>
          println(s"Creating a mounting point with id $id")
          // LiteralBlock(s"<p>Doodle mount point $id</p>", Id(id))
          BlockSequence(
            Seq(
              Paragraph(Seq(Text(s"<p>Doodle mount point $id</p>")))
            )
          )
        }
    }

I've tried many variants on the result (e.g. just a Paragraph etc.) with the same effect.

[jenshalm]

That's a known issue and has the same underlying cause as #289 (the only difference is that Header nodes have implicitly added ids whereas your directive explicitly adds one). It has been fixed for 0.19 in #302. As you can see this is a big refactoring as unfortunately this was not a simple bug, but a bigger structural problem that existed for years, but has never been reported until a few months ago. This also means it's impossible to fix in a binary compatible patch release for 0.18.

The RC for 0.19 is still several weeks away, so if you need to use the above directive with 0.18 you could try some workarounds. The limitation for all workarounds will be that you cannot write Markdown with internal links pointing to that id, as all workarounds involve sneaking past the link resolver which actually causes the issue, meaning those links would not validate.

One option is to defer the id insertion by using a BlockResolver or SpanResolver - in your case it would be the former. Those nodes would not be touched by the link resolver as they would not have an id themselves and then produce the final AST node in a later phase where it is safe to do so.

Example:

case class BlockIdWorkaround (targetBlock: Block, id: String, options: Options = NoOpt) extends BlockResolver {
  type Self = BlockIdWorkaround
  val source: SourceFragment = GeneratedSource
  def resolve (cursor: DocumentCursor): Block = targetBlock.withId(id)
  def unresolvedMessage: String = s"unresolved block id workaround '$id'"
  def withOptions (options: Options): BlockIdWorkaround = copy(options = options)
}

and then produce the above in your directive instead. This is entirely untested, but my gut feeling tells me that this has a decent chance of actually working as long as the content of that target block is simple (e.g. not having a lot of nested content that would require resolving links recursively). Let me know if it does not.

The normal use case for those resolvers, outside of dirty hacks like this, is having AST nodes that can have access to parent or sibling nodes or user config via the cursor passed into the resolve method. Since directives have access to the cursor themselves, they are usually not used in directives, but more likely in custom parser extensions for example.

Once 0.19 is out, you should be able to remove all the indirection.

[noelwelsh]

Thanks. For my situation raw content is sufficient, as I only need the ID for Scala JS code to hook into. I'll revisit this when 0.19 comes out.