Add new `invalid_markdown_table` rustdoc lint by GuillaumeGomez · Pull Request #159583 · rust-lang/rust

GuillaumeGomez · 2026-07-19T22:49:30Z

View all comments

Fixes #159186.

r? @Urgau

GuillaumeGomez · 2026-07-21T14:19:25Z

Applied comments.

Urgau

Implementation looks good to me.

View changes since this review

Urgau · 2026-07-21T20:35:29Z

2nd try. Let's do an FCP.

unescaped_pipe_in_table_cell details

`unescaped_pipe_in_table_cell`

This lint is warn-by-default. It detects unescaped pipes (|) in table rows which
lead to some row cells being ignored. For example:

//! | col1 |
//! | ---- |
//! | `code_with(|arg| arg)` |

Which will give:

error: table row has too many columns
  --> $DIR/unescaped_pipe_in_table_cell.rs:5:18
   |
5  | //! | `code_with(|arg| arg)` |
   |                  ^ help: any content after this column divider is discarded
   |
   = help: to escape `|` characters in tables, add a `\` before them like `\|`
note: the lint level is defined here
  --> $DIR/unescaped_pipe_in_table_cell.rs:1:9
   |
1  | #![deny(rustdoc::unescaped_pipe_in_table_cell)]
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

@rfcbot merge rustdoc-internals

rust-rfcbot · 2026-07-21T20:35:31Z

@Urgau has proposed to merge this. The next step is review by the rest of the tagged team members:

Concerns:

~~overly specific lint name~~ resolved by Add new invalid_markdown_table rustdoc lint #159583 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

camelid · 2026-07-21T20:40:16Z

+```rust
+//! | col1 |
+//! | ---- |
+//! | `code_with(|arg| arg)` |


Wow TIL that this is how GFM works. Very strange design...

View changes since the review

Yeah I was super confused as well.

notriddle · 2026-07-21T22:47:52Z

Minor nits about the implementation, but massive approval for the lint in concept!

camelid · 2026-07-23T20:32:26Z

Definitely in favor of the lint itself, but I wonder if we should have a more generic lint name and then we group together this and any related (current or future) lints about Markdown gotchas? E.g. we have rustdoc::invalid_html_tags that groups together anything related to that, including (soon: #158709) issues when HTML is interleaved with Markdown.

For example, it could be rustdoc::invalid_markdown, or rustdoc::markdown_gotchas, or a Better Name (TM). I could even imagine us renaming rustdoc::invalid_html_tags to something more general like rustdoc::invalid_markdown and including this as part of it.

On a related note, my feeling with #158709 is that additions of new cases to an existing warn-by-default lint do not require FCP since they are not part of stability guarantees, but please let me know if you disagree.

camelid · 2026-07-23T20:33:00Z

@rfcbot reviewed
@rfcbot concern overly specific lint name

… lint

GuillaumeGomez · 2026-07-24T14:02:37Z

@camelid: Very fair point. I think having a lint group for all such lints is a good idea. As for the current lint name, I'll rename it as invalid_markdown_table.

rustbot · 2026-07-24T15:59:53Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

GuillaumeGomez · 2026-07-24T16:02:21Z

Ok all done.

notriddle · 2026-07-24T21:10:14Z

I noticed that this lint scans the entire row to count pipes, but it only actually needs to scan the part between the end of the last cell and the end of the row. Worse, this scanning has a corner case where it gives less-than-perfect results.

Here's a commit that implements the fixes. notriddle@3c70378ff60

The essential problem is that, with this table:

one |
----|
  a | b | c
  a | b |
  a | b
  a |

And this logic:

let too_many_pipes = divider_count > expected_cells + 1;

expected_cells + 1 winds up as 2, so you get this warning:

error: unused content after last table cell
  --> $DIR/invalid_markdown_table.rs:81:14
   |
LL |     //!   a | b | c
   |              ^^^^^^ this content is discarded

error: unused content after last table cell
  --> $DIR/invalid_markdown_table.rs:83:14
   |
LL |     //!   a | b |
   |              ^^^^ this content is discarded

error: unused content after last table cell
  --> $DIR/invalid_markdown_table.rs:85:14
   |
LL |     //!   a | b
   |              ^^ this content is discarded

We really want our warning to give the suggest-escaping flow, like this:

error: table row has too many columns
  --> $DIR/invalid_markdown_table.rs:81:13
   |
LL |     //!   a | b | c
   |             ^ any content after this column divider is discarded
   |
   = help: to escape `|` characters in tables, add a `\` before them like `\|`

error: table row has too many columns
  --> $DIR/invalid_markdown_table.rs:83:13
   |
LL |     //!   a | b |
   |             ^ any content after this column divider is discarded
   |
   = help: to escape `|` characters in tables, add a `\` before them like `\|`

error: unused content after last table cell
  --> $DIR/invalid_markdown_table.rs:85:14
   |
LL |     //!   a | b
   |              ^^ this content is discarded

The essential problem is that, with this table: ```text one | ----| a | b | c a | b | a | b a | ``` And this logic: ```rust let too_many_pipes = divider_count > expected_cells + 1; ``` `expected_cells + 1` winds up as 2, so you get this warning: ```text error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:81:14 | LL | //! a | b | c | ^^^^^^ this content is discarded error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:83:14 | LL | //! a | b | | ^^^^ this content is discarded error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:85:14 | LL | //! a | b | ^^ this content is discarded ``` We really want our warning to give the suggest-escaping flow, like this: ```text error: table row has too many columns --> $DIR/invalid_markdown_table.rs:81:13 | LL | //! a | b | c | ^ any content after this column divider is discarded | = help: to escape `|` characters in tables, add a `\` before them like `\|` error: table row has too many columns --> $DIR/invalid_markdown_table.rs:83:13 | LL | //! a | b | | ^ any content after this column divider is discarded | = help: to escape `|` characters in tables, add a `\` before them like `\|` error: unused content after last table cell --> $DIR/invalid_markdown_table.rs:85:14 | LL | //! a | b | ^^ this content is discarded ``` By only scanning the text between the end of the last cell and the row, instead of doing the entire row, we don't have to re-implement as much of pulldown-cmark's logic.

GuillaumeGomez · 2026-07-24T21:51:52Z

@notriddle Please push it to my branch, don't want to steal ownership for your work. :)

notriddle · 2026-07-24T23:53:06Z

Sure.

GuillaumeGomez · 2026-07-25T10:16:54Z

Nice, thanks!

@camelid: Is your concern resolved?

camelid · 2026-07-25T17:27:46Z

Well, I would prefer the lint name to be even more general like invalid_markdown, and maybe be merged with invalid_html_tags (superseding it). What do you think?

I can't think of a case where people would want to control them separately. It seems more likely they'd want all these lints to be either enabled or disabled rather than one-by-one controlling them.

notriddle · 2026-07-25T18:47:20Z

I can’t think of a case where anyone would want to disable this table lint at all.

The HTML lint, however, you might disable it if you intentionally rely on HTML tag correction. The rules are spelled out in the spec, after all, and they allow you to write more terse markup.

GuillaumeGomez · 2026-07-25T20:35:25Z

invalid_markdown should be a lint group, I donnt think we should merge both lints.

camelid · 2026-07-25T21:03:59Z

Based on @notriddle's comment, I propose we rename this lint to just invalid_markdown (rather than having it be a lint group) but leave it separate from the invalid_html_tags lint.

GuillaumeGomez · 2026-07-25T21:19:11Z

It's too general: we already have other "invalid markdown" specialized lints. If we want to make a group out of them, that's a good name for the group. But otherwise I think it's too general.

camelid · 2026-07-25T22:10:18Z

What other invalid markdown lints do we have? All of the lints I see are either specific to rustdoc features (like invalid Rust code blocks) or stylistic issues (redundant explicit links). https://doc.rust-lang.org/rustdoc/lints.html

That said, I'm not going to block on this since ultimately it's a matter of taste. I would just prefer not creating too many overly specific lints -- like I can't imagine why someone would want to control linting of tables separately from other markdown features, unless they were doing something really unusual.

GuillaumeGomez · 2026-07-25T22:21:19Z

I see at least bare_urls and invalid_html_tags. And once we're done with #137858, there will be a new one.

EDIT: copied the wrong lint name, replaced it.

camelid · 2026-07-25T22:35:07Z

Right, but bare_urls doesn't actually indicate invalid Markdown. The other two are closer to that though. Anyway, I'll resolve my concern. I'm fine with doing a lint group for these like you proposed, even though I'd rather not separate them at all.

@rfcbot resolve overly specific lint name

rustbot assigned Urgau Jul 19, 2026

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Jul 19, 2026

GuillaumeGomez mentioned this pull request Jul 19, 2026

Markdown tables can silently discard content containing | #159186

Open

This comment has been minimized.

Sign in to view

Urgau reviewed Jul 20, 2026

View reviewed changes

Urgau added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 20, 2026

GuillaumeGomez force-pushed the unescaped_pipe_in_table_cell branch from 045f5a3 to 6fd9b1b Compare July 21, 2026 12:16

Urgau approved these changes Jul 21, 2026

View reviewed changes

Urgau added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 21, 2026

This comment was marked as outdated.

Sign in to view

This comment was marked as resolved.

Sign in to view

rust-rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Jul 21, 2026

Urgau added S-waiting-on-fcp Status: PR is in FCP and is awaiting for FCP to complete. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jul 21, 2026

camelid reviewed Jul 21, 2026

View reviewed changes

notriddle reviewed Jul 21, 2026

View reviewed changes

Comment thread src/librustdoc/passes/lint/table_pipe_escape.rs Outdated

Comment thread tests/rustdoc-ui/lints/invalid_markdown_table.rs

Comment thread tests/rustdoc-ui/lints/unescaped_pipe_in_table_cell.rs Outdated

GuillaumeGomez added 3 commits July 24, 2026 14:21

Add new unescaped_pipe_in_table_cell rustdoc lint

a88bf04

Add ui regression test for new rustdoc unescaped_pipe_in_table_cell…

014aa81

… lint

Add documentation for rustdoc unescaped_pipe_in_table_cell lint

6b55c9a

Rename lint unescaped_pipe_in_table_cell into invalid_markdown_table

fe253df

GuillaumeGomez force-pushed the unescaped_pipe_in_table_cell branch from 6fd9b1b to 52c8615 Compare July 24, 2026 15:59

Also warn in case there is content after the last table cell

a88e74a

GuillaumeGomez force-pushed the unescaped_pipe_in_table_cell branch from 52c8615 to a88e74a Compare July 24, 2026 16:00

GuillaumeGomez changed the title ~~Add new unescaped_pipe_in_table_cell rustdoc lint~~ Add new invalid_markdown_table rustdoc lint Jul 24, 2026

Uh oh!

Uh oh!

Conversation

GuillaumeGomez commented Jul 19, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GuillaumeGomez commented Jul 21, 2026

Uh oh!

Urgau left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

This comment was marked as resolved.

Urgau commented Jul 21, 2026

unescaped_pipe_in_table_cell

Uh oh!

rust-rfcbot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camelid Jul 21, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

notriddle commented Jul 21, 2026

Uh oh!

camelid commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camelid commented Jul 23, 2026

Uh oh!

GuillaumeGomez commented Jul 24, 2026

Uh oh!

rustbot commented Jul 24, 2026

Uh oh!

GuillaumeGomez commented Jul 24, 2026

Uh oh!

notriddle commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GuillaumeGomez commented Jul 24, 2026

Uh oh!

notriddle commented Jul 24, 2026

Uh oh!

GuillaumeGomez commented Jul 25, 2026

Uh oh!

camelid commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

notriddle commented Jul 25, 2026

Uh oh!

GuillaumeGomez commented Jul 25, 2026

Uh oh!

camelid commented Jul 25, 2026

Uh oh!

GuillaumeGomez commented Jul 25, 2026

Uh oh!

camelid commented Jul 25, 2026

Uh oh!

GuillaumeGomez commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camelid commented Jul 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

GuillaumeGomez commented Jul 19, 2026 •

edited by rustbot

Loading

Urgau left a comment •

edited by rustbot

Loading

`unescaped_pipe_in_table_cell`

rust-rfcbot commented Jul 21, 2026 •

edited

Loading

camelid Jul 21, 2026 •

edited by rustbot

Loading

camelid commented Jul 23, 2026 •

edited

Loading

notriddle commented Jul 24, 2026 •

edited

Loading

camelid commented Jul 25, 2026 •

edited

Loading

GuillaumeGomez commented Jul 25, 2026 •

edited

Loading

camelid commented Jul 25, 2026 •

edited

Loading