Remove applies to glitch from ToC when using inline applies to in headings

[theletterf]

Fixes #1574

[github-actions]

🔍 Preview links for changed docs

• docs/syntax/applies.md

[theletterf]

@colleenmcginnis You can check the fix here: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/1661/syntax/applies#in-text (ToC is pristine)

[colleenmcginnis]

Thanks @theletterf!

Before we merge this, I'd like to make sure we actually want to allow contributors to use both inline and section annotations with headings. Do we want to enforce one or the other and/or style them the same way for consistency? cc @florent-leborgne @shainaraskas @szabosteve

[theletterf]

Yup, makes sense! IMHO, they don't look great on headings. And, aesthetics aside, I guess it makes more sense to tag meaningful chunks, like a paragraph or a table cell.

[shainaraskas]

I think we don't want to do this and instead want to lint for it so people don't do it

we might want the tags to float inline beside the title, but I think we still want to use the other tagging style because it's easier to scan in markdown. there's a reason why we have these multiple syntax approaches

that being said, might be good to fix the visual bug just in case this sneaks in 🤷

[szabosteve]

Thank you for the fix and the ping!
We should encourage using the section-style variant if we want to add a tag to a whole section instead of the inline version for the sake of consistency and the reasons Shaina has already mentioned. Still great to have it fixed though!

[theletterf]

@elastic/docs-engineering I'm OK with either having this merged or closed!

[theletterf]

@colleenmcginnis Closing for now, but let's reopen if we want to get this one merged!

[colleenmcginnis]

@theletterf what do you think about doing something like this instead to prevent docs contributors from using this pattern in the first place instead of making it look ok in the case that they do something they shouldn't do?

if (AppliesToSyntax.IsMatch(text))
    // Where collector is `Collector` from build context
    collector.EmitWarning(
        // Where sourceFile is `MarkdownSourcePath` from context
        sourceFile,
        "Do not use inline 'applies_to' annotations with headings. Use a section 'applies_to' annotation instead."
    );

Note: I'm not sure if it makes sense to do this here or if it would be more appropriate to do it in src/Elastic.Markdown/IO/MarkdownFile.cs or somewhere else... I'm also not sure if there's a trick to getting a preview of the lines that need to updated in the build logs.

[theletterf]

Makes sense to me! Two questions:

• Are there more uses we want to discourage?
• Would this make the build fail or just be a warning (and the badge would be rendered anyway)?

[colleenmcginnis]

Are there more uses we want to discourage?

Probably, but maybe we should start small. 🙂

Would this make the build fail or just be a warning (and the badge would be rendered anyway)?

I think it should be a warning -- it should not break the preview build, but it should make the check fail (I think that's the behavior of warnings...).