Pipe character in rustdoc markdown tables can not be escaped

[m4rw3r]

Attempting to use the pipe symbol in tables in doc-comments does not work as it will be interpreted as a table-separator even when attempting to escape it. Attempts to use html-entities also fails (ie. |) and they end up escaped.

Example:

Test  | Table
------|-----------
t = b | id = |x| x

This causes only f = to be rendered in the right cell instead of the expected f = |x| x.

Looking at Hoedown it seems like they fixed this in commit hoedown/hoedown@e7bcbe3 , which would enable us to write this:

Test  | Table
------|-------------
t = b | id = \|x\| x

[alexcrichton]

I think all we probably need to do here is update the hoedown submodule and double-check the FFI bindings didn't change, other than that it should just work after that!

[greyblake]

In 2023, I seem still to experience this issue.

[vallentin]

I just encountered this as well, which confused me, as it is mentioned in the rustdoc book

[vallentin]

Correction. In my case, it rendered incorrectly due to pulldown-cmark not supporting tables being indented.

Issue: pulldown-cmark/pulldown-cmark#656

E.g. if I had the following doc comment:

//! Foo
//!
//! | A | B |
//! |---|---|
//! | 1 | 2 |

Then the table renders correctly:

However, if the table is indented, then it renders as plain text. This can occur if another line is not indented correctly, e.g.:

//!Foo
//!
//! | A | B |
//! |---|---|
//! | 1 | 2 |

Notice how Foo is not indented with 1 space. Thus the table is indented by 1 space relative to the "Foo" text. This caused the table to render incorrectly for me: