Skip to content

Support multi-paragraph notes and warnings in Markdown #992

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
daira wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Support multi-paragraph notes and warnings in Markdown #992

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8a42203
Add a hacky way to make <div> work across paragraphs in Markdown ZIPs.
daira Mar 18, 2025
34ceb8f
zip-guide[-markdown]: Fix the syntax for references in Markdown ZIPs.
daira Mar 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 35 additions & 12 deletions rendered/css/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,10 @@
background-color: #6060e0;
color: #ffffff;
}
div.note-cont + p {
background-color: #6060e0;
color: #ffffff;
}
aside.note::before {
background-color: #3030e0;
}
Expand All @@ -138,6 +142,11 @@
color: #ffffff;
font-weight: 700;
}
div.warning-cont + p {
background-color: #e08060;
color: #ffffff;
font-weight: 700;
}
aside.warning::before {
background-color: #e05030;
font-weight: 800;
Expand All @@ -152,9 +161,15 @@
div.note + p > a, a:visited {
color: #50e7f4;
}
div.note-cont + p > a, a:visited {
color: #50e7f4;
}
div.warning + p > a, a:visited {
color: #50e7f4;
}
div.warning-cont + p > a, a:visited {
color: #50e7f4;
}
aside > p > a:hover {
color: #90ffff;
}
Expand All @@ -181,16 +196,32 @@ aside {
}
div.note + p {
padding-top: 4.4rem;
padding-left: 0.15rem;
padding-right: 0.15rem;
padding-left: 1rem;
padding-right: 1rem;
padding-bottom: 1.4rem;
margin-top: -2.25rem;
margin-bottom: 1.5rem;
}
div.note-cont + p {
padding-top: 1rem;
padding-left: 1rem;
padding-right: 1rem;
padding-bottom: 1.4rem;
margin-top: -2.25rem;
margin-bottom: 1.5rem;
}
div.warning + p {
padding-top: 4.4rem;
padding-left: 0.15rem;
padding-right: 0.15rem;
padding-left: 1rem;
padding-right: 1rem;
padding-bottom: 1.4rem;
margin-top: -2.25rem;
margin-bottom: 1.5rem;
}
div.warning-cont + p {
padding-top: 1rem;
padding-left: 1rem;
padding-right: 1rem;
padding-bottom: 1.4rem;
margin-top: -2.25rem;
margin-bottom: 1.5rem;
Expand Down Expand Up @@ -245,14 +276,6 @@ aside > p {
padding-left: 1rem;
padding-right: 1rem;
}
div.note + p {
padding-left: 1rem;
padding-right: 1rem;
}
div.warning + p {
padding-left: 1rem;
padding-right: 1rem;
}

@font-face {
font-family: robotolight;
Expand Down
9 changes: 6 additions & 3 deletions rendered/zip-0325.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,13 +202,16 @@ <h2 id="private-usemetadatakeys"><span class="section-heading">Private-use metad
<li>Return <span class="math">\(\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFF}, \mathsf{PrivateUseSubject})\)</span></li>
</ul>

<div class=warning></div>
<div class="warning"></div>

<p>It is the responsibility of wallet developers to ensure that they do not use
colliding <span class="math">\(\mathsf{PrivateUseSubject}\)</span> values, and to analyse their private use for
any security risks related to potential cross-protocol attacks (in the event that
two wallet developers happen to select a colliding <span class="math">\(\mathsf{PrivateUseSubject}\)</span>).
Wallet developers that are unwilling to accept these risks SHOULD propose new
two wallet developers happen to select a colliding <span class="math">\(\mathsf{PrivateUseSubject}\)</span>).</p>

<div class="warning-cont"></div>

<p>Wallet developers that are unwilling to accept these risks SHOULD propose new
standardised metadata protocols instead, to benefit from ecosystem coordination
and review.</p>

Expand Down
26 changes: 17 additions & 9 deletions rendered/zip-guide-markdown.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,21 +168,29 @@ <h2 id="notesandwarnings"><span class="section-heading">Notes and warnings</span

<div class="note"></div>

<p>&#8220;<code>.. note::</code>&#8221; in reStructuredText or &#8220;<code>&lt;div class=&quot;note&quot;&gt;&lt;/div&gt;</code>&#8221; in Markdown
(followed by a blank line in either case), can be used for an aside from the main
text. The rendering of notes is colourful and may be distracting, so they should
<p>&#8220;<code>.. note::</code>&#8221; in reStructuredText, or &#8220;<code>&lt;div class=&quot;note&quot;&gt;&lt;/div&gt;</code>&#8221; followed by a
blank line in Markdown, can be used for an aside from the main text.</p>

<div class="note-cont"></div>

<p>The rendering of notes is colourful and may be distracting, so they should
only be used for important points.</p>

<div class="warning"></div>

<p>&#8220;<code>.. warning::</code>&#8221; in reStructuredText or &#8220;<code>&lt;div class=&quot;warning&quot;&gt;&lt;/div&gt;</code>&#8221; in
Markdown (followed by a blank line in either case), can be used for warnings.
Warnings should be used very sparingly — for example to signal that a
<p>&#8220;<code>.. warning::</code>&#8221; in reStructuredText, or &#8220;<code>&lt;div class=&quot;warning&quot;&gt;&lt;/div&gt;</code>&#8221; followed
by a blank line in Markdown, can be used for warnings.</p>

<div class="warning-cont"></div>

<p>Warnings should be used very sparingly — for example to signal that a
entire specification, or part of it, may be inapplicable or could cause
significant interoperability or security problems. In most cases, a &#8220;MUST&#8221;
or &#8220;SHOULD&#8221; conformance requirement is more appropriate.</p>

<p>In Markdown, notes and warnings can currently only be a single paragraph.</p>
<p>In Markdown, notes and warnings can be extended across multiple paragraphs by
using &#8220;<code>&lt;div class=&quot;note-cont&quot;&gt;&lt;/div&gt;</code>&#8221; or &#8220;<code>&lt;div class=&quot;warning-cont&quot;&gt;&lt;/div&gt;</code>&#8221;
(preceded and followed by a blank line) between paragraphs.</p>

<h2 id="validmarkup"><span class="section-heading">Valid markup</span><span class="section-anchor"> <a rel="bookmark" href="#validmarkup"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h2>

Expand Down Expand Up @@ -219,9 +227,9 @@ <h2 id="citationsandreferences"><span class="section-heading">Citations and refe
<pre><code class="rst">.. [#snark] `The Hunting of the Snark &lt;<a href="https://www.gutenberg.org/files/29888/29888-h/29888-h.htm">https://www.gutenberg.org/files/29888/29888-h/29888-h.htm</a>&gt;_. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
</code></pre>

<p>or like this in Markdown::</p>
<p>or like this in Markdown:</p>

<pre><code class="markdown">[^snark] [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
<pre><code class="markdown">[^snark]: [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
</code></pre>

<p>Note that each entry must be on a single line regardless of how long that makes the
Expand Down
8 changes: 4 additions & 4 deletions rendered/zip-guide.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,14 +91,14 @@
</section>
<section id="notes-and-warnings"><h3><span class="section-heading">Notes and warnings</span><span class="section-anchor"> <a rel="bookmark" href="#notes-and-warnings"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<aside class="note">
<p>"<code>.. note::</code>" in reStructuredText or "<code>&lt;div class="note"&gt;&lt;/div&gt;</code>" in Markdown (followed by a blank line in either case), can be used for an aside from the main text.</p>
<p>"<code>.. note::</code>" in reStructuredText, or "<code>&lt;div class="note"&gt;&lt;/div&gt;</code>" followed by a blank line in Markdown, can be used for an aside from the main text.</p>
<p>The rendering of notes is colourful and may be distracting, so they should only be used for important points.</p>
</aside>
<aside class="warning">
<p>"<code>.. warning::</code>" in reStructuredText, or "<code>&lt;div class="warning"&gt;&lt;/div&gt;</code>" in Markdown (followed by a blank line in either case), can be used for warnings.</p>
<p>"<code>.. warning::</code>" in reStructuredText, or "<code>&lt;div class="warning"&gt;&lt;/div&gt;</code>" followed by a blank line in Markdown, can be used for warnings.</p>
<p>Warnings should be used very sparingly — for example to signal that a entire specification, or part of it, may be inapplicable or could cause significant interoperability or security problems. In most cases, a "MUST" or "SHOULD" conformance requirement is more appropriate.</p>
</aside>
<p>In Markdown, notes and warnings can currently only be a single paragraph.</p>
<p>In Markdown, notes and warnings can be extended across multiple paragraphs by using "<code>&lt;div class="note-cont"&gt;&lt;/div&gt;</code>" or "<code>&lt;div class="warning-cont"&gt;&lt;/div&gt;</code>" (preceded and followed by a blank line) between paragraphs.</p>
</section>
<section id="valid-markup"><h3><span class="section-heading">Valid markup</span><span class="section-anchor"> <a rel="bookmark" href="#valid-markup"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
<p>This is optional before publishing a PR, but to check whether a document is valid reStructuredText or Markdown, first install <code>docutils</code> and <code>rst2html5</code>, and build <code>MultiMarkdown-6</code>. E.g. on Debian-based distros:</p>
Expand All @@ -119,7 +119,7 @@
<p>The corresponding entry in the <a href="#references">References</a> section should look like this in reStructuredText:</p>
<pre>.. [#snark] `The Hunting of the Snark &lt;<a href="https://www.gutenberg.org/files/29888/29888-h/29888-h.htm">https://www.gutenberg.org/files/29888/29888-h/29888-h.htm</a>&gt;`_. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.</pre>
<p>or like this in Markdown:</p>
<pre>[^snark] [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.</pre>
<pre>[^snark]: [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.</pre>
<p>Note that each entry must be on a single line regardless of how long that makes the line. In Markdown there must be a blank line between entries.</p>
<p>The current rendering of a Markdown ZIP reorders the references according to their first use; the rendering of a reStructuredText ZIP keeps them in the same order as in the References section.</p>
<p>To link to another section of the same ZIP, use "<code>`Section title`_</code>" in reStructuredText, or "<code>[Section title]</code>" in Markdown.</p>
Expand Down
5 changes: 4 additions & 1 deletion zips/zip-0325.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,12 +171,15 @@ valid hardened child index) within its key tree for this purpose.
most 252 bytes that identifies the desired private-use context.
- Return $\mathsf{CKDreg}(K, \mathtt{0x7FFFFFFF}, \mathsf{PrivateUseSubject})$

<div class=warning></div>
<div class="warning"></div>

It is the responsibility of wallet developers to ensure that they do not use
colliding $\mathsf{PrivateUseSubject}$ values, and to analyse their private use for
any security risks related to potential cross-protocol attacks (in the event that
two wallet developers happen to select a colliding $\mathsf{PrivateUseSubject}$).

<div class="warning-cont"></div>

Wallet developers that are unwilling to accept these risks SHOULD propose new
standardised metadata protocols instead, to benefit from ecosystem coordination
and review.
Expand Down
24 changes: 16 additions & 8 deletions zips/zip-guide-markdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,21 +158,29 @@ ZIP editors will catch any inconsistencies in review.

<div class="note"></div>

"`.. note::`" in reStructuredText or "`<div class="note"></div>`" in Markdown
(followed by a blank line in either case), can be used for an aside from the main
text. The rendering of notes is colourful and may be distracting, so they should
"`.. note::`" in reStructuredText, or "`<div class="note"></div>`" followed by a
blank line in Markdown, can be used for an aside from the main text.

<div class="note-cont"></div>

The rendering of notes is colourful and may be distracting, so they should
only be used for important points.

<div class="warning"></div>

"`.. warning::`" in reStructuredText or "`<div class="warning"></div>`" in
Markdown (followed by a blank line in either case), can be used for warnings.
"`.. warning::`" in reStructuredText, or "`<div class="warning"></div>`" followed
by a blank line in Markdown, can be used for warnings.

<div class="warning-cont"></div>

Warnings should be used very sparingly — for example to signal that a
entire specification, or part of it, may be inapplicable or could cause
significant interoperability or security problems. In most cases, a "MUST"
or "SHOULD" conformance requirement is more appropriate.

In Markdown, notes and warnings can currently only be a single paragraph.
In Markdown, notes and warnings can be extended across multiple paragraphs by
using "`<div class="note-cont"></div>`" or "`<div class="warning-cont"></div>`"
(preceded and followed by a blank line) between paragraphs.

## Valid markup

Expand Down Expand Up @@ -207,9 +215,9 @@ reStructuredText:
.. [#snark] `The Hunting of the Snark <https://www.gutenberg.org/files/29888/29888-h/29888-h.htm>_. Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
```

or like this in Markdown::
or like this in Markdown:
```markdown
[^snark] [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
[^snark]: [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
```

Note that each entry must be on a single line regardless of how long that makes the
Expand Down
13 changes: 7 additions & 6 deletions zips/zip-guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,23 +167,24 @@ Notes and warnings
------------------

.. note::
"``.. note::``" in reStructuredText or "``<div class="note"></div>``" in
Markdown (followed by a blank line in either case), can be used for an aside
from the main text.
"``.. note::``" in reStructuredText, or "``<div class="note"></div>``" followed
by a blank line in Markdown, can be used for an aside from the main text.

The rendering of notes is colourful and may be distracting, so they should
only be used for important points.

.. warning::
"``.. warning::``" in reStructuredText, or "``<div class="warning"></div>``"
in Markdown (followed by a blank line in either case), can be used for warnings.
followed by a blank line in Markdown, can be used for warnings.

Warnings should be used very sparingly — for example to signal that a
entire specification, or part of it, may be inapplicable or could cause
significant interoperability or security problems. In most cases, a "MUST"
or "SHOULD" conformance requirement is more appropriate.

In Markdown, notes and warnings can currently only be a single paragraph.
In Markdown, notes and warnings can be extended across multiple paragraphs by
using "``<div class="note-cont"></div>``" or "``<div class="warning-cont"></div>``"
(preceded and followed by a blank line) between paragraphs.

Valid markup
------------
Expand Down Expand Up @@ -221,7 +222,7 @@ reStructuredText::

or like this in Markdown::

[^snark] [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.
[^snark]: [The Hunting of the Snark](https://www.gutenberg.org/files/29888/29888-h/29888-h.htm). Lewis Carroll, with illustrations by Henry Holiday. MacMillan and Co. London. March 29, 1876.

Note that each entry must be on a single line regardless of how long that makes the
line. In Markdown there must be a blank line between entries.
Expand Down