Multiline comments do not hide @Step in tutorials.

[mbrandonw]

Description

If you use a multiline HTML comment with @Steps inside, those steps will be rendered in docs:

<!--

This text will not be rendered in docs.

@Step {
  This text **will** be rendered in docs.
}

--!>

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

I would expect that everything inside <!-- --> is omitted from rendering.

Actual behavior

Instead, @Steps are rendered.

Steps To Reproduce

Put the following in any tutorial to see that the step will be rendered:

<!--

This text will not be rendered in docs.

@Step {
  This text **will** be rendered in docs.
}

--!>

Swift-DocC Version Information

Xcode 15.4

Swift Compiler Version Information

swift-driver version: 1.90.11.1 Apple Swift version 5.10 (swiftlang-5.10.0.13 clang-1500.3.9.4)
Target: arm64-apple-macosx14.0

[d-ronnqvist]

This is an issue with directive parsing in swift-markdown. It can be reproduced with this test

func testDirectiveInMultilineHTMLComment() {
    let content = """
    # Some heading

    <!--

    Some commented out text

    @SomeDirectiveName {
      Some content within the directive
    }

    -->

    A paragraph with some text.
    """
    let document = Document(parsing: content, source: nil, options: .parseBlockDirectives)
    XCTAssertEqual(document.debugDescription(), """
    Document
    ├─ Heading level: 1
    │  └─ Text "Some heading"
    ├─ HTMLBlock
    │  <!--
    │  Some commented out text
    │  @SomeDirectiveName {
    │    Some content within the directive
    │  }
    │  -->
    └─ Paragraph
       └─ Text "A paragraph with some text."
    """)
}

[QuietMisdreavus]

The interaction between block directives and any other Markdown/HTML syntax is awkward, and fixing this properly will require a severe rewrite of the code.

As a workaround, you can use the @Comment directive instead of an HTML comment:

@Comment {
  This text will not be rendered in docs.

  @Step {
    This text will also not be rendered in docs.
  }
}