I’m trying to convert this chunk of Markdown (taken from here) into HTML:
1. **Install the prerequisite build tools.**
Make sure that you have Git and Visual Studio 2022 with the “Desktop development with C++” workload and the “C++ MFC for latest v143 build tools (x86 & x64)” component. If you don’t already have those installed or you aren’t sure, then open an elevated Command Prompt and run:
<!--
The following code block specifies the full path to the Visual Studio Installer because the Visual Studio Installer doesn’t add itself to the user’s Path. The installer is guaranteed to be in a specific location on 64-bit systems [1]. The installer will be in a different location on 32-bit systems [2], but Visual Studio 2022 doesn’t support 32-bit systems [3] so we can ignore that detail.
[1]: <https://learn.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2022>
[2]: <https://github.com/microsoft/vswhere/wiki#installing>
[3]: <https://learn.microsoft.com/en-us/answers/questions/1689898/does-visual-studio-build-tools-2022-support-32-bit>
-->
```batch
winget install Git.Git Microsoft.VisualStudio.2022.Community
"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\setup.exe" modify^
--passive^
--channelId VisualStudio.17.Release^
--productId Microsoft.VisualStudio.Product.Community^
--add Microsoft.VisualStudio.Workload.NativeDesktop;includeRecommended^
--add Microsoft.VisualStudio.Component.VC.ATLMFC
```
markdown-it turns that chunk of Markdown into this chunk of HTML:
<ol>
<li>
<p><strong>Install the prerequisite build tools.</strong></p>
<p>Make sure that you have Git and Visual Studio 2022 with the “Desktop development with C++” workload and the “C++ MFC for latest v143 build tools (x86 & x64)” component. If you don’t already have those installed or you aren’t sure, then open an elevated Command Prompt and run:</p>
<!--
The following code block specifies the full path to the Visual Studio Installer because the Visual Studio Installer doesn’t add itself to the user’s Path. The installer is guaranteed to be in a specific location on 64-bit systems [1]. The installer will be in a different location on 32-bit systems [2], but Visual Studio 2022 doesn’t support 32-bit systems [3] so we can ignore that detail.
<p>–></p>
<pre><code class="hljs">winget install Git.Git Microsoft.VisualStudio.2022.Community
"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\setup.exe" modify^
--passive^
--channelId VisualStudio.17.Release^
--productId Microsoft.VisualStudio.Product.Community^
--add Microsoft.VisualStudio.Workload.NativeDesktop;includeRecommended^
--add Microsoft.VisualStudio.Component.VC.ATLMFC
</code></pre>
</li>
</ol>
Notice how the comment never ends. When this HTML is displayed in a Web browser, all of the text after “then open an elevated Command Prompt and run:” does not appear because all of it is a part of a comment.
CommonMark’s JavaScript reference implementation turns that same chunk of Markdown into this chunk of HTML:
<ol>
<li>
<p><strong>Install the prerequisite build tools.</strong></p>
<p>Make sure that you have Git and Visual Studio 2022 with the “Desktop development with C++” workload and the “C++ MFC for latest v143 build tools (x86 & x64)” component. If you don’t already have those installed or you aren’t sure, then open an elevated Command Prompt and run:</p>
<!--
The following code block specifies the full path to the Visual Studio Installer because the Visual Studio Installer doesn’t add itself to the user’s Path. The installer is guaranteed to be in a specific location on 64-bit systems [1]. The installer will be in a different location on 32-bit systems [2], but Visual Studio 2022 doesn’t support 32-bit systems [3] so we can ignore that detail.
[1]: <https://learn.microsoft.com/en-us/visualstudio/install/use-command-line-parameters-to-install-visual-studio?view=vs-2022>
[2]: <https://github.com/microsoft/vswhere/wiki#installing>
[3]: <https://learn.microsoft.com/en-us/answers/questions/1689898/does-visual-studio-build-tools-2022-support-32-bit>
-->
<pre><code class="language-batch">winget install Git.Git Microsoft.VisualStudio.2022.Community
"%ProgramFiles(x86)%\Microsoft Visual Studio\Installer\setup.exe" modify^
--passive^
--channelId VisualStudio.17.Release^
--productId Microsoft.VisualStudio.Product.Community^
--add Microsoft.VisualStudio.Workload.NativeDesktop;includeRecommended^
--add Microsoft.VisualStudio.Component.VC.ATLMFC
</code></pre>
</li>
</ol>
Notice how the comment ends right after the third URL.
In this situation, it looks like markdown-it is not quite conforming to the CommonMark specification properly. Section 4.6 of version 0.31.2 of the CommonMark specification says:
There are seven kinds of HTML block, which can be defined by their
start and end conditions. The block begins with a line that meets a
start condition (after up to three optional spaces of indentation).
It ends with the first subsequent line that meets a matching
end condition, or the last line of the document, or the last line of
the container block containing the current HTML
block, if no line is encountered that meets the end condition. If
the first line meets both the start condition and the end
condition, the block will contain just that line.
-
Start condition: line begins with the string <pre,
<script, <style, or <textarea (case-insensitive), followed by a space,
a tab, the string >, or the end of the line.
End condition: line contains an end tag
</pre>, </script>, </style>, or </textarea> (case-insensitive; it
need not match the start tag).
-
Start condition: line begins with the string <!--.
End condition: line contains the string -->.
-
Start condition: line begins with the string <?.
End condition: line contains the string ?>.
-
Start condition: line begins with the string <!
followed by an ASCII letter.
End condition: line contains the character >.
-
Start condition: line begins with the string
<![CDATA[.
End condition: line contains the string ]]>.
-
Start condition: line begins with the string < or </
followed by one of the strings (case-insensitive) address,
article, aside, base, basefont, blockquote, body,
caption, center, col, colgroup, dd, details, dialog,
dir, div, dl, dt, fieldset, figcaption, figure,
footer, form, frame, frameset,
h1, h2, h3, h4, h5, h6, head, header, hr,
html, iframe, legend, li, link, main, menu, menuitem,
nav, noframes, ol, optgroup, option, p, param,
search, section, summary, table, tbody, td,
tfoot, th, thead, title, tr, track, ul, followed
by a space, a tab, the end of the line, the string >, or
the string />.
End condition: line is followed by a blank line.
-
Start condition: line begins with a complete open tag
(with any tag name other than pre, script,
style, or textarea) or a complete closing tag,
followed by zero or more spaces and tabs, followed by the end of the line.
End condition: line is followed by a blank line.
HTML blocks continue until they are closed by their appropriate
end condition, or the last line of the document or other container
block.
Based on that quote, it seems like HTML blocks that start with <!-- should not end until there is a -->, the current container block ends or the file ends. In this situation, it looks like markdown-it is mistakenly ending the HTML block after a line that is followed by a blank line. While it is correct for a line followed by a blank line to end an HTML block that began with <details> (for example), it is not correct for a line followed by a blank line to end an HTML block that began with <!--.
I’m trying to convert this chunk of Markdown (taken from here) into HTML:
markdown-itturns that chunk of Markdown into this chunk of HTML:Notice how the comment never ends. When this HTML is displayed in a Web browser, all of the text after “then open an elevated Command Prompt and run:” does not appear because all of it is a part of a comment.
CommonMark’s JavaScript reference implementation turns that same chunk of Markdown into this chunk of HTML:
Notice how the comment ends right after the third URL.
In this situation, it looks like markdown-it is not quite conforming to the CommonMark specification properly. Section 4.6 of version 0.31.2 of the CommonMark specification says:
Based on that quote, it seems like HTML blocks that start with
<!--should not end until there is a-->, the current container block ends or the file ends. In this situation, it looks like markdown-it is mistakenly ending the HTML block after a line that is followed by a blank line. While it is correct for a line followed by a blank line to end an HTML block that began with<details>(for example), it is not correct for a line followed by a blank line to end an HTML block that began with<!--.