New rustdoc rendering common errors

Since a few weeks, it's possible to use pulldown instead of hoedown in order the render the markdown from the documentation comments with the following command:

rustdoc -Z unstable-options --enable-commonmark

You can take a look at the tracking issue here.

This switch is really important for Rust for a few reasons:

• hoedown isn't maintained anymore
• hoedown is written in C
• pulldown is maintained
• pulldown is written in Rust
• pulldown is following the commonmark specification, which is more recent than the one used in hoedown.

As you can see, a lot of advantages come from using pulldown! We'll move to pulldown by default in a few releases.

However, this switch brought a few rendering differences which we'll try to describe here in order to help you fix them if you encounter them.

So here is a list of common differences you might encounter while using the new rustdoc markdown generator pulldown:

Requires HTML tags for superscript

If you try to run rustdoc over this documentation comment:

Run/// text with x^2
pub fn sup() {}

You'll get as a warning:

WARNING: documentation for this crate may be rendered differently using the new Pulldown renderer.
    See https://github.com/rust-lang/rust/issues/44229 for details.
WARNING: rendering difference in `text with x^2`
   --> diff.rs:2:0
    /html[0]/body[1]/p[0] Text differs:
        expected: `text with x^2`
        found:    `text with x`
    /html[0]/body[1]/p[0] Unexpected element `sup`: found: `<sup>2</sup>`

With hoedown it would have rendered as follows:

<p>text with x<sup>2</sup></p>

In order to do so with pulldown, you need to put the superscript text between sup html tags:

Run/// text with x<sup>2</sup>
pub fn sup() {}

More code blocks are interpreted as such

If you try to run rustdoc over this documentation comment:

Run/// 1.       let x = 2;
pub fn some_code_block() {}

You'll get as a warning:

WARNING: rendering difference in `1.       let x = 2;`
   --> diff.rs:5:0
    /html[0]/body[1]/ol[0]/li[0] Types differ: expected: `pre`, found: ``

The issue is that pulldown considers that let x = 2; is codeblock because of the indentation on the contrary of hoedown.

This difference can be problematic if new code blocks are tested and failing.

pulldown identifies block codes way more easily based on indentation so be careful!

Lists can be created right after a paragraph

If you try to run rustdoc over this documentation comment:

Run///some text
/// * elem 1
/// * elem 2
pub fn list() {}

You'll get as a warning:

WARNING: documentation for this crate may be rendered differently using the new Pulldown renderer.
    See https://github.com/rust-lang/rust/issues/44229 for details.
WARNING: rendering difference in `some text`
   --> diff.rs:10:0
    /html[0]/body[1] One element is missing: expected: `ul`

pulldown doesn't need an empty line before the beginning of a list to consider it as a list. On the same note, you'll get the same error with a numbered list:

Run///some text
/// 1. elem 1
/// 2. elem 2
pub fn list() {}

Italic rule changes

If you try to run rustdoc over this documentation comment:

Run/// 30*60*12 = 47
pub fn emphasis() {}

You'll get as a warning:

WARNING: rendering difference in `30*60*12 = 47`
   --> diff.rs:13:0
    /html[0]/body[1]/p[0] Text differs:
        expected: `30`
        found:    `30*60*12 = 47`
    /html[0]/body[1]/p[0] One element is missing: expected: `em`
    /html[0]/body[1]/p[0] One element is missing: expected: `2`

hoedown requires a whitespace after a * to make the rule work on the opposite of pulldown. If you want the same rendering, just add whitespaces around 60:

Run/// 30* 60 *12 = 47
pub fn emphasis() {}

If you want to display asterisks though (to have the same rendering as hoedown), just escape them as follow:

Run/// 30\*60\*12 = 47
pub fn emphasis() {}

Emphasis rule changes

Just the same as Italic rule changes.

Link changes

If you try to run rustdoc over this documentation comment:

Run/// the [link] (foo)
pub fn link() {}

You'll get as a warning:

WARNING: rendering difference in `the [link] (foo)`
   --> diff.rs:16:0
    /html[0]/body[1]/p[0] Text differs:
        expected: `the [link] (foo)`
        found:    `the`
    /html[0]/body[1]/p[0] Unexpected element `a`: found: `<a href="foo">link</a>`

pulldown will link even with a whitespace between the text and the url. If you want the same rendering as hoedown, just escape the ( as follow:

Run/// the [link] \(foo)
pub fn link() {}

Conclusion

Other issues might be encountered and will be added to this list. You can follow the issue here.