Adds comment syntax to Markdoc #198
Conversation
There was a problem hiding this comment.
This is great! Just have one question around whether we should make allowComments default true. PTAL @rpaul-stripe
| const tokenizer = new markdoc.Tokenizer({ allowIndentation: true }); | ||
| const tokenizer = new markdoc.Tokenizer({ | ||
| allowIndentation: true, | ||
| allowComments: true, |
There was a problem hiding this comment.
Feels to me like allowComments should be true by default, no?
There was a problem hiding this comment.
I do intend for it to eventually be on by default, but for the moment I want to keep it to off until we've had an opportunity to test it in practice more comprehensively.
| type: 'document', | ||
| children: [ | ||
| { type: 'paragraph' }, | ||
| { type: 'comment', attributes: { content: 'foo' } }, |
| @@ -45,6 +45,7 @@ function handleAttrs(token: Token, type: string) { | |||
| } | |||
| case 'text': | |||
| case 'code': | |||
| case 'comment': | |||
There was a problem hiding this comment.
Love how this part of the code is working.
| config: MarkdownIt.Options & { allowIndentation?: boolean } = {} | ||
| config: MarkdownIt.Options & { | ||
| allowIndentation?: boolean; | ||
| allowComments?: boolean; |
| const example = parse(` | ||
| this is a test | ||
|
|
||
| <!-- example comment --> |
There was a problem hiding this comment.
For these last few tests, should we include the foo after the comments just to ensure it keeps the content after a multi-line comment?
There was a problem hiding this comment.
This was a good suggestion, adding it to the tests caught a bug. I'll have a push fixed shortly.
| import type StateBlock from 'markdown-it/lib/rules_block/state_block'; | ||
| import type StateInline from 'markdown-it/lib/rules_inline/state_inline'; | ||
|
|
||
| const OPEN = '<!--'; |
There was a problem hiding this comment.
I'm totally peaceful with this approach, but I wonder if we should use the same regex that markdown-it uses internally: https://github.com/markdown-it/markdown-it/blob/df4607f1d4d4be7fdc32e71c04109aea8cc373fa/lib/common/html_re.js#L18
var comment = '<!---->|<!--(?:-?[^>-])(?:-?[^-])*-->';There was a problem hiding this comment.
I'd prefer to avoid using a regex here
Co-authored-by: Mike Fix <62121649+mfix-stripe@users.noreply.github.com>
rpaul-stripe
force-pushed
the
rpaul/comments
branch
from
5577396
to
fef4d38
Compare
This PR introduces support for comments in Markdoc. Some users (including Stripe) have previously relied on a no-op
{% comment %}tag to be able to include non-rendering content in a document, but the content inside of the tag is still subject to parsing and validation, which creates some undesirable side effects, particularly when trying to comment out portions of a doc that contain other tags or malformed tags.Rather than special-casing the behavior of the
{% comment %}tag in a way that would undermine the consistency of tag semantics, we instead decided that Markdoc comments will use the standard HTML comment syntax (<!-- -->). This syntax is already supported for commenting in many CommonMark-compliant parsers, via broader support for arbitrary HTML markup inside of Markdown.This PR adds a new plugin to MarkdownIt that just adds that comment syntax, making it possible to have HTML comments without having to enable general HTML parsing. The resulting comments are incorporated into the AST but are omitted from the rendered document (they do not get propagated through as HTML comments in the output). Users can override the schema definition for comment nodes and implement their own transform function if they would like different behavior, though we do not have support for rendering actual HTML comments via the render tree.
Things included in this PR: