Your Markdown note contains a named section, a titled callout and a superscript marker. A basic conversion leaves the callout fences visible or loses the role’s meaning. Render that source with the MyST parser and the extension the source actually uses, then inspect the generated structure before packaging the HTML.
Choose the parser from the document’s syntax, not from its .md extension alone. This original fictional editorial note exercises three MyST features. It is not a shipping instruction or a record of an actual package.
Open the complete example · Download the full HTML source
Start with one complete source note
Save this source as package-note.md:
(package-note)=
# Package note
Fictional editorial exercise: keep the current label beside its
source record. No package is dispatched by this document.
:::{admonition} Source context
:class: note
Read the label beside the source record.{sup}`2`
:::
[Return to package note](#package-note)
The named target and its return link belong together. The callout has a readable title, and its text carries a superscript marker. The marker is an authored example, not a citation to a missing footnote or a measured quantity.
MyST’s getting-started guide demonstrates the myst-docutils-demo command, a colon-fenced admonition, a sup role and explicit reference targets. Its roles and directives reference explains the directive name and option block. Keep those syntax choices with the source rather than asking a generic converter to infer them.
Enable the colon-fence extension explicitly
With a compatible MyST-Parser environment available, render the source using the documented demonstration command:
myst-docutils-demo package-note.md --myst-enable-extensions=colon_fence
The selected reproduction for this article uses MyST-Parser 4.0.1. Preserve the exact tool and dependency versions with your build record. This command produces a rendered fragment for inspection; it is not a claim that an entire documentation site has been built.
Run a comparison without colon_fence in a separate output record. Look for whether the colon-fenced block becomes the intended admonition structure. Do not repair an unparsed directive by deleting its visible markers from the generated page: the next render would still begin from the same unsupported source configuration.
Inspect three separate results
First, locate the section with the package-note target. Follow “Return to package note” and confirm that it reaches the section containing the original editorial sentence.
Second, inspect the callout’s generated structure and readable title. For this source, the configured output should contain the title “Source context” and the original note text inside an admonition. Its border color is a presentation choice, not the evidence that the directive was parsed.
Third, check the superscript marker. The authored sup role should produce superscript text containing 2, rather than leaving role notation in the reading copy. A working anchor does not prove that the directive and role were converted correctly. Check all three against the maintained source.
The existing Markdown admonition guide configures a named markdown-it container. That plugin’s ::: warning notation is a different rule from this MyST directive and role combination. The Sphinx reference-warning guide tests a documentation project’s unresolved references; this reproduction uses the MyST Docutils path and one source note.
For the target-and-link part of this check, the HTML section-link guide explains the relationship between a fragment address and its destination ID. Inspect the actual generated target before replacing the document shell; keep that check separate from whether MyST parsed the admonition and superscript role.
Keep the rendered fragment inside a complete reading page
Add the accepted fragment to a document shell with its title, local styles and viewport metadata. Keep the original Markdown and the raw parser output as separate downloads. If you later change a target or callout title, edit the source and render it again instead of maintaining a competing correction only in the visible HTML.
MyST’s guide notes that Sphinx provides roles and directives beyond Docutils. Do not assume a Sphinx-specific source will work in the standalone Docutils command merely because both environments accept MyST. Check the actual feature and renderer you intend to deliver.
For a prepared reading copy in NOS, keep the full note, callout title and return link available to the reviewer. The reading page does not dispatch work, submit a document or synchronize the source project. Hand over the source and renderer settings with the HTML so the next revision can reproduce the same structure.