···11# Contribute
2233-> 👉 **Important**: this project has a [code of conduct][coc].
33+> 👉 **Important**:
44+> this project has a [code of conduct][coc].
45> By interacting with this repository and community you agree to abide by its
56> terms.
67···37383839## Submitting an issue
39404040-* the issue tracker is for issues, discussions are for questions
4141-* search the issue tracker (including closed issues) before opening a new
4242- issue
4343-* ensure you’re using the latest versions of packages and other tools
4444-* use a clear and descriptive title
4545-* include as much information as possible: steps to reproduce the issue,
4646- error message, version, operating system, etcetera
4747-* the more time you put into an issue, the better help you can get
4848-* the best issue report is a failing test] proving it
4141+* the issue tracker is for issues, discussions are for questions
4242+* search the issue tracker (including closed issues) before opening a new
4343+ issue
4444+* ensure you’re using the latest versions of packages and other tools
4545+* use a clear and descriptive title
4646+* include as much information as possible: steps to reproduce the issue,
4747+ error message, version, operating system, etcetera
4848+* the more time you put into an issue, the better help you can get
4949+* the best issue report is a failing test] proving it
49505051## Submitting a pull request
51525252-* run `cargo fmt` and `cargo test` locally to format and test your changes
5353-* non-trivial changes are often best discussed in an issue first, to prevent
5454- you from doing unnecessary work
5555-* for ambitious tasks, you should try to get your work in front of the
5656- community for feedback as soon as possible
5757-* new features should be accompanied by tests and documentation
5858-* don’t include unrelated changes
5959-* write a convincing description of why your pull request should land:
6060- it’s your job to be convincing
5353+* run `cargo fmt` and `cargo test` locally to format and test your changes
5454+* non-trivial changes are often best discussed in an issue first, to prevent
5555+ you from doing unnecessary work
5656+* for ambitious tasks, you should try to get your work in front of the
5757+ community for feedback as soon as possible
5858+* new features should be accompanied by tests and documentation
5959+* don’t include unrelated changes
6060+* write a convincing description of why your pull request should land:
6161+ it’s your job to be convincing
61626263## Project (for maintainers)
6364···66676768### Release
68696969-* update the `version` field in `Cargo.toml`
7070-* search for the previous version in `readme.md`, replace with new one
7171-* `git commit --all --message 1.2.3 && git tag 1.2.3 && git push && git push --tags`
7272-* `cargo publish`
7070+* update the `version` field in `Cargo.toml`
7171+* search for the previous version in `readme.md`, replace with new one
7272+* `git commit --all --message 1.2.3 && git tag 1.2.3 && git push && git push --tags`
7373+* `cargo publish`
73747475(similar for `mdast_util_to_markdown`)
75767677## Resources
77787878-* [how to contribute to open source](https://opensource.guide/how-to-contribute/)
7979-* [making your first contribution](https://medium.com/@vadimdemedes/making-your-first-contribution-de6576ddb190)
8080-* [using pull requests](https://help.github.com/articles/about-pull-requests/)
8181-* [GitHub help](https://help.github.com)
7979+* [how to contribute to open source](https://opensource.guide/how-to-contribute/)
8080+* [making your first contribution](https://medium.com/@vadimdemedes/making-your-first-contribution-de6576ddb190)
8181+* [using pull requests](https://help.github.com/articles/about-pull-requests/)
8282+* [GitHub help](https://help.github.com)
82838384## License
8485
+14-14
.github/support.md
···1616Spending the extra time up front helps save everyone time in the long run.
1717Here are some tips:
18181919-* see [*How do I ask a good question* by `StackOverflow`][how-to-ask] for a
2020- good guide
2121-* [talk to a duck][rubberduck]!
2222-* don’t fall for the [XY problem][xy]
2323-* search to find out if a similar question has been asked
2424-* try to define what you need help with:
2525- * is there something in particular you want to do?
2626- * what problem are you encountering and what steps have you taken to try
2727- and fix it?
2828- * is there a concept you don’t understand?
2929-* provide sample code, if possible
3030-* screenshots can help, but if there’s important text such as code or error
3131- messages in them, please also provide those as text
3232-* the more time you put into asking your question, the better we can help you
1919+* see [*How do I ask a good question* by `StackOverflow`][how-to-ask] for a
2020+ good guide
2121+* [talk to a duck][rubberduck]!
2222+* don’t fall for the [XY problem][xy]
2323+* search to find out if a similar question has been asked
2424+* try to define what you need help with:
2525+ * is there something in particular you want to do?
2626+ * what problem are you encountering and what steps have you taken to try
2727+ and fix it?
2828+ * is there a concept you don’t understand?
2929+* provide sample code, if possible
3030+* screenshots can help, but if there’s important text such as code or error
3131+ messages in them, please also provide those as text
3232+* the more time you put into asking your question, the better we can help you
33333434## Contributions
3535
+1-1
generate/src/main.rs
···152152///
153153/// ## References
154154///
155155-/// * [*§ 2.1 Characters and lines* in `CommonMark`](https://spec.commonmark.org/0.31.2/#unicode-punctuation-character)
155155+/// * [*§ 2.1 Characters and lines* in `CommonMark`](https://spec.commonmark.org/0.31.2/#unicode-punctuation-character)
156156pub static PUNCTUATION: [char; {}] = [
157157{}
158158];
+172-138
readme.md
···1414[![docs.rs][docs-badge]][docs]
1515[![crates.io][crate-badge]][crate]
16161717-> 👉 **Note**: this is a new crate that reuses an old name.
1717+> 👉 **Note**:
1818+> this is a new crate that reuses an old name.
1819> The old crate (`0.3.0` and lower) has a bunch of problems.
1919-> Make sure to use the new crate, currently in alpha at `1.0.0-alpha.23`.
2020+> Make sure to use the new crate,
2121+> currently in alpha at `1.0.0-alpha.23`.
20222123CommonMark compliant markdown parser in Rust with ASTs and extensions.
22242325## Feature highlights
24262525-* [x] **[compliant][commonmark]** (100% to CommonMark)
2626-* [x] **[extensions][]** (100% GFM, 100% MDX, frontmatter, math)
2727-* [x] **[safe][security]** (100% safe Rust, also 100% safe HTML by default)
2828-* [x] **[robust][test]** (2300+ tests, 100% coverage, fuzz testing)
2929-* [x] **[ast][mdast]** (mdast)
2727+* [x] **[compliant][commonmark]**
2828+ (100% to CommonMark)
2929+* [x] **[extensions][]**
3030+ (100% GFM, 100% MDX, frontmatter, math)
3131+* [x] **[safe][security]**
3232+ (100% safe Rust, also 100% safe HTML by default)
3333+* [x] **[robust][test]**
3434+ (2300+ tests, 100% coverage, fuzz testing)
3535+* [x] **[ast][mdast]**
3636+ (mdast)
30373138## When should I use this?
32393333-* If you *just* want to turn markdown into HTML (with maybe a few extensions)
3434-* If you want to do *really complex things* with markdown
4040+* if you *just* want to turn markdown into HTML (with maybe a few extensions)
4141+* if you want to do *really complex things* with markdown
35423643## What is this?
37443845`markdown-rs` is an open source markdown parser written in Rust.
3946It’s implemented as a state machine (`#![no_std]` + `alloc`) that emits
4040-concrete tokens, so that every byte is accounted for, with positional info.
4141-The API then exposes this information as an AST, which is easier to work with,
4747+concrete tokens,
4848+so that every byte is accounted for,
4949+with positional info.
5050+The API then exposes this information as an AST,
5151+which is easier to work with,
4252or it compiles directly to HTML.
43534454While most markdown parsers work towards compliancy with CommonMark (or GFM),
4555this project goes further by following how the reference parsers (`cmark`,
4646-`cmark-gfm`) work, which is confirmed with thousands of extra tests.
5656+`cmark-gfm`) work,
5757+which is confirmed with thousands of extra tests.
47584848-Other than CommonMark and GFM, this project also supports common extensions
4949-to markdown such as MDX, math, and frontmatter.
5959+Other than CommonMark and GFM,
6060+this project also supports common extensions to markdown such as
6161+MDX, math, and frontmatter.
50625151-This Rust crate has a sibling project in JavaScript: [`micromark`][micromark]
6363+This Rust crate has a sibling project in JavaScript:
6464+[`micromark`][micromark]
5265(and [`mdast-util-from-markdown`][mdast-util-from-markdown] for the AST).
53665454-P.S. if you want to *compile* MDX, use [`mdxjs-rs`][mdxjs-rs].
6767+P.S. if you want to *compile* MDX,
6868+use [`mdxjs-rs`][mdxjs-rs].
55695670## Questions
57715858-* to learn markdown, see this [cheatsheet and tutorial][cheat]
5959-* for the API, see the [crate docs][docs]
6060-* for questions, see [Discussions][chat]
6161-* to help, see [contribute][] or [sponsor][] below
7272+* to learn markdown,
7373+ see this [cheatsheet and tutorial][cheat]
7474+* for the API,
7575+ see the [crate docs][docs]
7676+* for questions,
7777+ see [Discussions][chat]
7878+* to help,
7979+ see [contribute][] or [sponsor][] below
62806381## Contents
64826565-* [Install](#install)
6666-* [Use](#use)
6767-* [API](#api)
6868-* [Extensions](#extensions)
6969-* [Project](#project)
7070- * [Overview](#overview)
7171- * [File structure](#file-structure)
7272- * [Test](#test)
7373- * [Version](#version)
7474- * [Security](#security)
7575- * [Contribute](#contribute)
7676- * [Sponsor](#sponsor)
7777- * [Thanks](#thanks)
7878-* [Related](#related)
7979-* [License](#license)
8383+* [Install](#install)
8484+* [Use](#use)
8585+* [API](#api)
8686+* [Extensions](#extensions)
8787+* [Project](#project)
8888+ * [Overview](#overview)
8989+ * [File structure](#file-structure)
9090+ * [Test](#test)
9191+ * [Version](#version)
9292+ * [Security](#security)
9393+ * [Contribute](#contribute)
9494+ * [Sponsor](#sponsor)
9595+ * [Thanks](#thanks)
9696+* [Related](#related)
9797+* [License](#license)
80988199## Install
821008383-With [Rust][] (rust edition 2018+, ±version 1.56+), install with `cargo`:
101101+With [Rust][]
102102+(rust edition 2018+, ±version 1.56+),
103103+install with `cargo`:
8410485105```sh
86106cargo add markdown@1.0.0-alpha.23
87107```
881088989-> 👉 **Note**: this is a new crate that reuses an old name.
9090-> The old crate (`0.3.0` and lower) has a bunch of problems.
9191-> Make sure to use the new crate, currently in alpha at `1.0.0-alpha.23`.
109109+> 👉 **Note**:
110110+> this is a new crate that reuses an old name.
111111+> The old crate (`0.3.0` and lower)
112112+> has a bunch of problems.
113113+> Make sure to use the new crate,
114114+> currently in alpha at `1.0.0-alpha.23`.
9211593116## Use
94117···168191These extensions are maintained in this project.
169192They are not enabled by default but can be turned on with options.
170193171171-* frontmatter
172172-* GFM
173173- * autolink literal
174174- * footnote
175175- * strikethrough
176176- * table
177177- * tagfilter
178178- * task list item
179179-* math
180180-* MDX
181181- * ESM
182182- * expressions
183183- * JSX
194194+* GFM
195195+ * autolink literal
196196+ * footnote
197197+ * strikethrough
198198+ * table
199199+ * tagfilter
200200+ * task list item
201201+* MDX
202202+ * ESM
203203+ * expressions
204204+ * JSX
205205+* frontmatter
206206+* math
184207185208It is not a goal of this project to support lots of different extensions.
186209It’s instead a goal to support very common and mostly standardized extensions.
···206229207230The files in `src/` are as follows:
208231209209-* `construct/*.rs`
210210- — CommonMark, GFM, and other extension constructs used in markdown
211211-* `util/*.rs`
212212- — helpers often needed when parsing markdown
213213-* `event.rs`
214214- — things with meaning happening somewhere
215215-* `lib.rs`
216216- — public API
217217-* `mdast.rs`
218218- — syntax tree
219219-* `parser.rs`
220220- — turn a string of markdown into events
221221-* `resolve.rs`
222222- — steps to process events
223223-* `state.rs`
224224- — steps of the state machine
225225-* `subtokenize.rs`
226226- — handle content in other content
227227-* `to_html.rs`
228228- — turns events into a string of HTML
229229-* `to_mdast.rs`
230230- — turns events into a syntax tree
231231-* `tokenizer.rs`
232232- — glue the states of the state machine together
233233-* `unist.rs`
234234- — point and position, used in mdast
232232+* `construct/*.rs`
233233+ — CommonMark, GFM, and other extension constructs used in markdown
234234+* `util/*.rs`
235235+ — helpers often needed when parsing markdown
236236+* `event.rs`
237237+ — things with meaning happening somewhere
238238+* `lib.rs`
239239+ — public API
240240+* `mdast.rs`
241241+ — syntax tree
242242+* `parser.rs`
243243+ — turn a string of markdown into events
244244+* `resolve.rs`
245245+ — steps to process events
246246+* `state.rs`
247247+ — steps of the state machine
248248+* `subtokenize.rs`
249249+ — handle content in other content
250250+* `to_html.rs`
251251+ — turns events into a string of HTML
252252+* `to_mdast.rs`
253253+ — turns events into a syntax tree
254254+* `tokenizer.rs`
255255+ — glue the states of the state machine together
256256+* `unist.rs`
257257+ — point and position, used in mdast
235258236259### Test
237260238261`markdown-rs` is tested with the \~650 CommonMark tests and more than 1k extra
239262tests confirmed with CM reference parsers.
240263Then there’s even more tests for GFM and other extensions.
241241-These tests reach all branches in the code, which means that this project has
242242-100% code coverage.
264264+These tests reach all branches in the code,
265265+which means that this project has 100% code coverage.
243266Fuzz testing is used to check for things that might fall through coverage.
244267245268The following bash scripts are useful when working on this project:
246269247247-* generate code (latest CM tests and Unicode info):
248248- ```sh
249249- cargo run --manifest-path generate/Cargo.toml
250250- ```
251251-* run examples:
252252- ```sh
253253- RUST_BACKTRACE=1 RUST_LOG=trace cargo run --example lib --features log
254254- ```
255255-* format:
256256- ```sh
257257- cargo fmt && cargo fix --all-features --all-targets --workspace
258258- ```
259259-* lint:
260260- ```sh
261261- cargo fmt --check && cargo clippy --all-features --all-targets --workspace
262262- ```
263263-* test:
264264- ```sh
265265- RUST_BACKTRACE=1 cargo test --all-features --workspace
266266- ```
267267-* docs:
268268- ```sh
269269- cargo doc --document-private-items --examples --workspace
270270- ```
271271-* fuzz:
272272- ```sh
273273- cargo install cargo-fuzz
274274- cargo install honggfuzz
275275- cargo +nightly fuzz run markdown_libfuzz
276276- cargo hfuzz run markdown_honggfuzz
277277- ```
270270+* generate code (latest CM tests and Unicode info):
271271+ ```sh
272272+ cargo run --manifest-path generate/Cargo.toml
273273+ ```
274274+* run examples:
275275+ ```sh
276276+ RUST_BACKTRACE=1 RUST_LOG=trace cargo run --example lib --features log
277277+ ```
278278+* format:
279279+ ```sh
280280+ cargo fmt && cargo fix --all-features --all-targets --workspace
281281+ ```
282282+* lint:
283283+ ```sh
284284+ cargo fmt --check && cargo clippy --all-features --all-targets --workspace
285285+ ```
286286+* test:
287287+ ```sh
288288+ RUST_BACKTRACE=1 cargo test --all-features --workspace
289289+ ```
290290+* docs:
291291+ ```sh
292292+ cargo doc --document-private-items --examples --workspace
293293+ ```
294294+* fuzz:
295295+ ```sh
296296+ cargo install cargo-fuzz
297297+ cargo install honggfuzz
298298+ cargo +nightly fuzz run markdown_libfuzz
299299+ cargo hfuzz run markdown_honggfuzz
300300+ ```
278301279302### Version
280303···286309(XSS)][xss] attacks.
287310Markdown itself is safe if it does not include embedded HTML or dangerous
288311protocols in links/images (such as `javascript:`).
289289-`markdown-rs` makes any markdown safe by default, even if HTML is embedded or
290290-dangerous protocols are used, as it encodes or drops them.
312312+`markdown-rs` makes any markdown safe by default,
313313+even if HTML is embedded or dangerous protocols are used,
314314+as it encodes or drops them.
291315292316Turning on the `allow_dangerous_html` or `allow_dangerous_protocol` options for
293317user-provided markdown opens you up to XSS attacks.
294318295295-Additionnally, you should be able to set `allow_any_img_src` safely.
319319+Additionnally,
320320+you should be able to set `allow_any_img_src` safely.
296321The default is to allow only `http:`, `https:`, and relative images,
297297-which is what GitHub does. But it should be safe to allow any value on `src`.
322322+which is what GitHub does.
323323+But it should be safe to allow any value on `src`.
298324299325The [HTML specification][whatwg-html-image] prohibits dangerous scripts in
300326images and all modern browsers respect this and are thus safe.
301327Opera 12 (from 2012) is a notable browser that did not respect this.
302328303303-An aspect related to XSS for security is syntax errors: markdown itself has no
304304-syntax errors.
305305-Some syntax extensions (specifically, only MDX) do include syntax errors.
306306-For that reason, `to_html_with_options` returns `Result<String, Message>`, of
307307-which the error is a struct indicating where the problem happened, what
308308-occurred, and what was expected instead.
329329+An aspect related to XSS for security is syntax errors:
330330+markdown itself has no syntax errors.
331331+Some syntax extensions
332332+(specifically, only MDX)
333333+do include syntax errors.
334334+For that reason,
335335+`to_html_with_options` returns `Result<String, Message>`,
336336+of which the error is a struct indicating where the problem happened,
337337+what occurred,
338338+and what was expected instead.
309339Make sure to handle your errors when using MDX.
310340311341Another security aspect is DDoS attacks.
312312-For example, an attacker could throw a 100mb file at `markdown-rs`, in which
313313-case it’s going to take a long while to finish.
314314-It is also possible to crash `markdown-rs` with smaller payloads, notably when
315315-thousands of links, images, emphasis, or strong are opened but not closed.
342342+For example,
343343+an attacker could throw a 100mb file at `markdown-rs`,
344344+in which case it’s going to take a long while to finish.
345345+It is also possible to crash `markdown-rs` with smaller payloads,
346346+notably when thousands of
347347+links, images, emphasis, or strong
348348+are opened but not closed.
316349It is wise to cap the accepted size of input (500kb can hold a big book) and to
317350process content in a different thread so that it can be stopped when needed.
318351319319-For more information on markdown sanitation, see
352352+For more information on markdown sanitation,
353353+see
320354[`improper-markup-sanitization.md`][improper] by [**@chalker**][chalker].
321355322356### Contribute
···330364331365Support this effort and give back by sponsoring:
332366333333-* [GitHub Sponsors](https://github.com/sponsors/wooorm)
334334- (personal; monthly or one-time)
335335-* [OpenCollective](https://opencollective.com/unified) or
336336- [GitHub Sponsors](https://github.com/sponsors/unifiedjs)
337337- (unified; monthly or one-time)
367367+* [GitHub Sponsors](https://github.com/sponsors/wooorm)
368368+ (personal; monthly or one-time)
369369+* [OpenCollective](https://opencollective.com/unified) or
370370+ [GitHub Sponsors](https://github.com/sponsors/unifiedjs)
371371+ (unified; monthly or one-time)
338372339373### Thanks
340374341375Special thanks go out to:
342376343343-* [Vercel][] for funding the initial development
344344-* [**@Murderlon**][murderlon] for the design of the logo
345345-* [**@johannhof**][johannhof] for the crate name
377377+* [Vercel][] for funding the initial development
378378+* [**@Murderlon**][murderlon] for the design of the logo
379379+* [**@johannhof**][johannhof] for the crate name
346380347381## Related
348382349349-* [`micromark`][micromark]
350350- — same as `markdown-rs` but in JavaScript
351351-* [`mdxjs-rs`][mdxjs-rs]
352352- — wraps `markdown-rs` to *compile* MDX to JavaScript
383383+* [`micromark`][micromark]
384384+ — same as `markdown-rs` but in JavaScript
385385+* [`mdxjs-rs`][mdxjs-rs]
386386+ — wraps `markdown-rs` to *compile* MDX to JavaScript
353387354388## License
355389
+5-5
src/configuration.rs
···979979 ///
980980 /// ## References
981981 ///
982982- /// * [*§ 6.1 Disallowed Raw HTML (extension)* in GFM](https://github.github.com/gfm/#disallowed-raw-html-extension-)
983983- /// * [`cmark-gfm#extensions/tagfilter.c`](https://github.com/github/cmark-gfm/blob/master/extensions/tagfilter.c)
982982+ /// * [*§ 6.1 Disallowed Raw HTML (extension)* in GFM](https://github.github.com/gfm/#disallowed-raw-html-extension-)
983983+ /// * [`cmark-gfm#extensions/tagfilter.c`](https://github.com/github/cmark-gfm/blob/master/extensions/tagfilter.c)
984984 pub gfm_tagfilter: bool,
985985}
986986···10061006///
10071007/// You can use this:
10081008///
10091009-/// * To control what markdown constructs are turned on and off
10101010-/// * To control some of those constructs
10111011-/// * To add support for certain programming languages when parsing MDX
10091009+/// * To control what markdown constructs are turned on and off
10101010+/// * To control some of those constructs
10111011+/// * To add support for certain programming languages when parsing MDX
10121012///
10131013/// In most cases, you will want to use the default trait or `gfm` method.
10141014///
···113113//! Two main bugs are not present in this project.
114114//! The issues relating to autolink literals are:
115115//!
116116-//! * [GFM autolink extension (`www.`, `https?://` parts): links don’t work when after bracket](https://github.com/github/cmark-gfm/issues/278)\
117117-//! fixed here ✅
118118-//! * [GFM autolink extension (`www.` part): uppercase does not match on issues/PRs/comments](https://github.com/github/cmark-gfm/issues/280)\
119119-//! fixed here ✅
120120-//! * [GFM autolink extension (`www.` part): the word `www` matches](https://github.com/github/cmark-gfm/issues/279)\
121121-//! present here for consistency
116116+//! * [GFM autolink extension (`www.`, `https?://` parts): links don’t work when after bracket](https://github.com/github/cmark-gfm/issues/278)\
117117+//! fixed here ✅
118118+//! * [GFM autolink extension (`www.` part): uppercase does not match on issues/PRs/comments](https://github.com/github/cmark-gfm/issues/280)\
119119+//! fixed here ✅
120120+//! * [GFM autolink extension (`www.` part): the word `www` matches](https://github.com/github/cmark-gfm/issues/279)\
121121+//! present here for consistency
122122//!
123123//! ## Tokens
124124//!
125125-//! * [`GfmAutolinkLiteralEmail`][Name::GfmAutolinkLiteralEmail]
126126-//! * [`GfmAutolinkLiteralMailto`][Name::GfmAutolinkLiteralMailto]
127127-//! * [`GfmAutolinkLiteralProtocol`][Name::GfmAutolinkLiteralProtocol]
128128-//! * [`GfmAutolinkLiteralWww`][Name::GfmAutolinkLiteralWww]
129129-//! * [`GfmAutolinkLiteralXmpp`][Name::GfmAutolinkLiteralXmpp]
125125+//! * [`GfmAutolinkLiteralEmail`][Name::GfmAutolinkLiteralEmail]
126126+//! * [`GfmAutolinkLiteralMailto`][Name::GfmAutolinkLiteralMailto]
127127+//! * [`GfmAutolinkLiteralProtocol`][Name::GfmAutolinkLiteralProtocol]
128128+//! * [`GfmAutolinkLiteralWww`][Name::GfmAutolinkLiteralWww]
129129+//! * [`GfmAutolinkLiteralXmpp`][Name::GfmAutolinkLiteralXmpp]
130130//!
131131//! ## References
132132//!
133133-//! * [`micromark-extension-gfm-autolink-literal`](https://github.com/micromark/micromark-extension-gfm-autolink-literal)
134134-//! * [*§ 6.9 Autolinks (extension)* in `GFM`](https://github.github.com/gfm/#autolinks-extension-)
133133+//! * [`micromark-extension-gfm-autolink-literal`](https://github.com/micromark/micromark-extension-gfm-autolink-literal)
134134+//! * [*§ 6.9 Autolinks (extension)* in `GFM`](https://github.github.com/gfm/#autolinks-extension-)
135135//!
136136//! > 👉 **Note**: `mailto:` and `xmpp:` protocols before email autolinks were
137137//! > added in `cmark-gfm@0.29.0.gfm.5` and are as of yet undocumented.
+23-23
src/construct/gfm_footnote_definition.rs
···115115//! These are not present in this project.
116116//! The issues relating to footnote definitions are:
117117//!
118118-//! * [Footnote reference call identifiers are trimmed, but definition identifiers aren’t](https://github.com/github/cmark-gfm/issues/237)\
119119-//! — initial and final whitespace in labels causes them not to match
120120-//! * [Footnotes are matched case-insensitive, but links keep their casing, breaking them](https://github.com/github/cmark-gfm/issues/239)\
121121-//! — using uppercase (or any character that will be percent encoded) in identifiers breaks links
122122-//! * [Colons in footnotes generate links w/o `href`](https://github.com/github/cmark-gfm/issues/250)\
123123-//! — colons in identifiers generate broken links
124124-//! * [Character escape of `]` does not work in footnote identifiers](https://github.com/github/cmark-gfm/issues/240)\
125125-//! — some character escapes don’t work
126126-//! * [Footnotes in links are broken](https://github.com/github/cmark-gfm/issues/249)\
127127-//! — while `CommonMark` prevents links in links, GitHub does not prevent footnotes (which turn into links) in links
128128-//! * [Footnote-like brackets around image, break that image](https://github.com/github/cmark-gfm/issues/275)\
129129-//! — images can’t be used in what looks like a footnote call
130130-//! * [GFM footnotes: line ending in footnote definition label causes text to disappear](https://github.com/github/cmark-gfm/issues/282)\
131131-//! — line endings in footnote definitions cause text to disappear
118118+//! * [Footnote reference call identifiers are trimmed, but definition identifiers aren’t](https://github.com/github/cmark-gfm/issues/237)\
119119+//! — initial and final whitespace in labels causes them not to match
120120+//! * [Footnotes are matched case-insensitive, but links keep their casing, breaking them](https://github.com/github/cmark-gfm/issues/239)\
121121+//! — using uppercase (or any character that will be percent encoded) in identifiers breaks links
122122+//! * [Colons in footnotes generate links w/o `href`](https://github.com/github/cmark-gfm/issues/250)\
123123+//! — colons in identifiers generate broken links
124124+//! * [Character escape of `]` does not work in footnote identifiers](https://github.com/github/cmark-gfm/issues/240)\
125125+//! — some character escapes don’t work
126126+//! * [Footnotes in links are broken](https://github.com/github/cmark-gfm/issues/249)\
127127+//! — while `CommonMark` prevents links in links, GitHub does not prevent footnotes (which turn into links) in links
128128+//! * [Footnote-like brackets around image, break that image](https://github.com/github/cmark-gfm/issues/275)\
129129+//! — images can’t be used in what looks like a footnote call
130130+//! * [GFM footnotes: line ending in footnote definition label causes text to disappear](https://github.com/github/cmark-gfm/issues/282)\
131131+//! — line endings in footnote definitions cause text to disappear
132132//!
133133//! ## Tokens
134134//!
135135-//! * [`DefinitionMarker`][Name::DefinitionMarker]
136136-//! * [`GfmFootnoteDefinition`][Name::GfmFootnoteDefinition]
137137-//! * [`GfmFootnoteDefinitionLabel`][Name::GfmFootnoteDefinitionLabel]
138138-//! * [`GfmFootnoteDefinitionLabelMarker`][Name::GfmFootnoteDefinitionLabelMarker]
139139-//! * [`GfmFootnoteDefinitionLabelString`][Name::GfmFootnoteDefinitionLabelString]
140140-//! * [`GfmFootnoteDefinitionMarker`][Name::GfmFootnoteDefinitionMarker]
141141-//! * [`GfmFootnoteDefinitionPrefix`][Name::GfmFootnoteDefinitionPrefix]
142142-//! * [`SpaceOrTab`][Name::SpaceOrTab]
135135+//! * [`DefinitionMarker`][Name::DefinitionMarker]
136136+//! * [`GfmFootnoteDefinition`][Name::GfmFootnoteDefinition]
137137+//! * [`GfmFootnoteDefinitionLabel`][Name::GfmFootnoteDefinitionLabel]
138138+//! * [`GfmFootnoteDefinitionLabelMarker`][Name::GfmFootnoteDefinitionLabelMarker]
139139+//! * [`GfmFootnoteDefinitionLabelString`][Name::GfmFootnoteDefinitionLabelString]
140140+//! * [`GfmFootnoteDefinitionMarker`][Name::GfmFootnoteDefinitionMarker]
141141+//! * [`GfmFootnoteDefinitionPrefix`][Name::GfmFootnoteDefinitionPrefix]
142142+//! * [`SpaceOrTab`][Name::SpaceOrTab]
143143//!
144144//! ## References
145145//!
146146-//! * [`micromark-extension-gfm-footnote`](https://github.com/micromark/micromark-extension-gfm-footnote)
146146+//! * [`micromark-extension-gfm-footnote`](https://github.com/micromark/micromark-extension-gfm-footnote)
147147//!
148148//! > 👉 **Note**: Footnotes are not specified in GFM yet.
149149//! > See [`github/cmark-gfm#270`](https://github.com/github/cmark-gfm/issues/270)
···3434//! The angle brackets can be encoded as a character reference, character
3535//! escape, or percent encoding:
3636//!
3737-//! * `<` as `<`, `\<`, or `%3c`
3838-//! * `>` as `>`, `\>`, or `%3e`
3737+//! * `<` as `<`, `\<`, or `%3c`
3838+//! * `>` as `>`, `\>`, or `%3e`
3939//!
4040//! The grammar for raw destinations (`x`) prohibits space (` `) and all
4141//! [ASCII control][u8::is_ascii_control] characters, which thus must be
···4343//! Unbalanced parens can be encoded as a character reference, character escape,
4444//! or percent encoding:
4545//!
4646-//! * `(` as `(`, `\(`, or `%28`
4747-//! * `)` as `)`, `\)`, or `%29`
4646+//! * `(` as `(`, `\(`, or `%28`
4747+//! * `)` as `)`, `\)`, or `%29`
4848//!
4949//! There are several cases where incorrect encoding of URLs would, in other
5050//! languages, result in a parse error.
···7272//!
7373//! ## References
7474//!
7575-//! * [`micromark-factory-destination/index.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-factory-destination/dev/index.js)
7575+//! * [`micromark-factory-destination/index.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-factory-destination/dev/index.js)
7676//!
7777//! [definition]: crate::construct::definition
7878//! [string]: crate::construct::string
···33//! This module exposes primarily [`to_html()`][].
44//! It also exposes [`to_html_with_options()`][] and [`to_mdast()`][].
55//!
66-//! * [`to_html()`][]
77-//! — safe way to transform (untrusted?) markdown into HTML
88-//! * [`to_html_with_options()`][]
99-//! — like `to_html` but lets you configure how markdown is turned into
1010-//! HTML, such as allowing dangerous HTML or turning on/off different
1111-//! constructs (GFM, MDX, and the like)
1212-//! * [`to_mdast()`][]
1313-//! — turn markdown into a syntax tree
66+//! * [`to_html()`][]
77+//! — safe way to transform (untrusted?) markdown into HTML
88+//! * [`to_html_with_options()`][]
99+//! — like `to_html` but lets you configure how markdown is turned into
1010+//! HTML, such as allowing dangerous HTML or turning on/off different
1111+//! constructs (GFM, MDX, and the like)
1212+//! * [`to_mdast()`][]
1313+//! — turn markdown into a syntax tree
1414//!
1515//! ## Features
1616//!
1717-//! * **`default`**
1818-//! — nothing is enabled by default
1919-//! * **`serde`**
2020-//! — enable serde to serialize the AST (includes `dep:serde`)
2121-//! * **`log`**
2222-//! — enable logging (includes `dep:log`);
2323-//! you can show logs with `RUST_LOG=debug`
1717+//! * **`default`**
1818+//! — nothing is enabled by default
1919+//! * **`serde`**
2020+//! — enable serde to serialize the AST (includes `dep:serde`)
2121+//! * **`log`**
2222+//! — enable logging (includes `dep:log`);
2323+//! you can show logs with `RUST_LOG=debug`
24242525#![no_std]
2626#![deny(clippy::pedantic)]
+1-1
src/util/char.rs
···8686///
8787/// ## References
8888///
8989-/// * [`micromark-util-classify-character` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-util-classify-character/dev/index.js)
8989+/// * [`micromark-util-classify-character` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-util-classify-character/dev/index.js)
9090pub fn classify(char: char) -> Kind {
9191 // Unicode whitespace.
9292 if char.is_whitespace() {
+4-4
src/util/character_reference.rs
···3434///
3535/// ## References
3636///
3737-/// * [`wooorm/decode-named-character-reference`](https://github.com/wooorm/decode-named-character-reference)
3838-/// * [*§ 2.5 Entity and numeric character references* in `CommonMark`](https://spec.commonmark.org/0.31/#entity-and-numeric-character-references)
3737+/// * [`wooorm/decode-named-character-reference`](https://github.com/wooorm/decode-named-character-reference)
3838+/// * [*§ 2.5 Entity and numeric character references* in `CommonMark`](https://spec.commonmark.org/0.31/#entity-and-numeric-character-references)
3939pub fn decode_named(value: &str, html5: bool) -> Option<String> {
4040 let mut iter = if html5 {
4141 CHARACTER_REFERENCES.iter()
···7777///
7878/// ## References
7979///
8080-/// * [`micromark-util-decode-numeric-character-reference` in `micromark`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-decode-numeric-character-reference)
8181-/// * [*§ 2.5 Entity and numeric character references* in `CommonMark`](https://spec.commonmark.org/0.31/#entity-and-numeric-character-references)
8080+/// * [`micromark-util-decode-numeric-character-reference` in `micromark`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-decode-numeric-character-reference)
8181+/// * [*§ 2.5 Entity and numeric character references* in `CommonMark`](https://spec.commonmark.org/0.31/#entity-and-numeric-character-references)
8282pub fn decode_numeric(value: &str, radix: u32) -> String {
8383 if let Some(char) = char::from_u32(u32::from_str_radix(value, radix).unwrap()) {
8484 if !matches!(char,
+7-7
src/util/constant.rs
···8686///
8787/// ## References
8888///
8989-/// * [*§ 6.1 Disallowed Raw HTML (extension)* in GFM](https://github.github.com/gfm/#disallowed-raw-html-extension-)
8989+/// * [*§ 6.1 Disallowed Raw HTML (extension)* in GFM](https://github.github.com/gfm/#disallowed-raw-html-extension-)
9090pub const GFM_HTML_TAGFILTER_NAMES: [&str; 9] = [
9191 "iframe",
9292 "noembed",
···129129///
130130/// ## References
131131///
132132-/// * [*§ 4.6 HTML blocks* in `CommonMark`](https://spec.commonmark.org/0.31/#html-blocks)
133133-/// * [*Remove source element as HTML block start condition* as `commonmark/commonmark-spec#710`](https://github.com/commonmark/commonmark-spec/pull/710)
132132+/// * [*§ 4.6 HTML blocks* in `CommonMark`](https://spec.commonmark.org/0.31/#html-blocks)
133133+/// * [*Remove source element as HTML block start condition* as `commonmark/commonmark-spec#710`](https://github.com/commonmark/commonmark-spec/pull/710)
134134///
135135/// [html_flow]: crate::construct::html_flow
136136pub const HTML_BLOCK_NAMES: [&str; 62] = [
···222222///
223223/// ## References
224224///
225225-/// * [*§ 4.6 HTML blocks* in `CommonMark`](https://spec.commonmark.org/0.31/#html-blocks)
225225+/// * [*§ 4.6 HTML blocks* in `CommonMark`](https://spec.commonmark.org/0.31/#html-blocks)
226226///
227227/// [html_flow]: crate::construct::html_flow
228228pub const HTML_RAW_NAMES: [&str; 4] = ["pre", "script", "style", "textarea"];
···244244///
245245/// ## References
246246///
247247-/// * [*§ 5.2 List items* in `CommonMark`](https://spec.commonmark.org/0.31/#ordered-list-marker)
247247+/// * [*§ 5.2 List items* in `CommonMark`](https://spec.commonmark.org/0.31/#ordered-list-marker)
248248///
249249/// [list-item]: crate::construct::list_item
250250pub const LIST_ITEM_VALUE_SIZE_MAX: usize = 10;
···303303///
304304/// ## References
305305///
306306-/// * [*§ 2.5 Entity and numeric character references* in `CommonMark`](https://spec.commonmark.org/0.31/#entity-and-numeric-character-references)
306306+/// * [*§ 2.5 Entity and numeric character references* in `CommonMark`](https://spec.commonmark.org/0.31/#entity-and-numeric-character-references)
307307///
308308/// [character_reference]: crate::construct::character_reference
309309pub static CHARACTER_REFERENCES: [(&str, &str); 2125] = [
···24462446///
24472447/// ## References
24482448///
24492449-/// * [*§ 1.5.2 HTML Character References* in `JSX`](https://facebook.github.io/jsx/#sec-HTMLCharacterReference)
24492449+/// * [*§ 1.5.2 HTML Character References* in `JSX`](https://facebook.github.io/jsx/#sec-HTMLCharacterReference)
24502450pub const CHARACTER_REFERENCES_HTML_4: [(&str, &str); 252] = [
24512451 ("AElig", "Æ"),
24522452 ("Aacute", "Á"),
+1-1
src/util/encode.rs
···2222///
2323/// ## References
2424///
2525-/// * [`micromark-util-encode` in `micromark`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-encode)
2525+/// * [`micromark-util-encode` in `micromark`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-encode)
2626pub fn encode(value: &str, encode_html: bool) -> String {
2727 // It’ll grow a bit bigger for each dangerous character.
2828 let mut result = String::with_capacity(value.len());
+2-2
src/util/gfm_tagfilter.rs
···2121///
2222/// ## References
2323///
2424-/// * [*§ 6.1 Disallowed Raw HTML (extension)* in GFM](https://github.github.com/gfm/#disallowed-raw-html-extension-)
2525-/// * [`cmark-gfm#extensions/tagfilter.c`](https://github.com/github/cmark-gfm/blob/master/extensions/tagfilter.c)
2424+/// * [*§ 6.1 Disallowed Raw HTML (extension)* in GFM](https://github.github.com/gfm/#disallowed-raw-html-extension-)
2525+/// * [`cmark-gfm#extensions/tagfilter.c`](https://github.com/github/cmark-gfm/blob/master/extensions/tagfilter.c)
2626pub fn gfm_tagfilter(value: &str) -> String {
2727 let bytes = value.as_bytes();
2828 // It’ll grow a bit bigger for each encoded `<`.