Code with pipe character in table is impossible to write correctly

Open
#2,000 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
38/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Stale
Tech stack
rust
Domain
documentation

Research direction

Reproduce the issue with the table in chapter_1.md and compare the generated HTML with the expected output in the report. Start by tracing mdBook's table and inline-code parsing, then verify the GFM escape behavior for pipes inside code spans and other inline spans. Done means the minimal example renders a code cell containing | without changing the table structure.

Written by the indexing model from the issue text.

Description

A-Markdown C-bug S-Blocked-Upstream
Problem

This was discovered in NixOS/nix#7770

We have a table with all operators, but || doesn't get rendered correctly:

image

I thought that maybe removing the \ from the markdown would solve this, but no. Comparing a few types of spans:

| code | bold   | ital |
| ---- | ------ | ---- |
|  `|` |  __|__ |  *|* |
| `\|` | __\|__ | *\|* |

Screenshot 2023-01-28 at 20 06 06

The documentation claims that tables are implemented according to the GFM tables extension.

However, this is not the case. From the GFM spec, Example 200:

Include a pipe in a cell’s content by escaping it, including inside other inline spans:

| f\|oo  |
| ------ |
| b `\|` az |
| b **\|** im |
Steps
  1. Create a new mdbook
  2. Paste this code into chapter_1.md: 
    | code | bold   | ital |
| ---- | ------ | ---- |
|  `|` |  __|__ |  *|* |
| `\|` | __\|__ | *\|* |
  3. Serve or build the mdbook and observe that either way of putting a pipe symbol inside a code span inside a table doesn't work:
    Screenshot 2023-01-28 at 20 06 06
Possible Solution(s)

It seems mdbook treats the code span as a self-contained unit, so \| does not have special meaning inside the table as it should.

While IMO it would be more intuitive to just have the non-escaped pipe symbol work inside code spans, adhering to the GFM spec would be best in terms of compatibility, so that's what I'd suggest.

Notes

In the end, this minimal markdown

| | |
| - | - |
| `\|` | |

should produce this HTML

<table>
  <thead>
    <tr>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code class="hljs">|</code></td>
      <td></td>
    </tr>
  </tbody>
</table>

While right now it produces this:

<table>
  <thead>
    <tr>
      <th></th>
      <th></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code class="hljs">\|</code></td>
      <td></td>
    </tr>
  </tbody>
</table>
Version
mdbook v0.4.25
Dominant language
Rust
Stars
22.2k
Forks
1.9k
Avg merge
2d 21h
Merged PRs (30d)
12

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from rust-lang/mdBook

All issues in rust-lang/mdBook

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.