Skip HTML nodes in SUMMARY.md

[tatsuya6502]

This pull request changes mdBook 0.4.x to skip any HTML node (such as HTML comment) in SUMMARY.md.

Here is an example SUMMARY.md from rust-lang-ja/book-ja repository. This repository is for a Japanese translation of "The Rust Programming Language" book.

 1: <!--
 2: # The Rust Programming Language
 3: -->
 4: # Rustプログラミング言語
 5:
 6: <!--
 7: [The Rust Programming Language](title-page.md)
 8: [Foreword](foreword.md)
 9: [Introduction](ch00-00-introduction.md)
10: -->
11: [The Rust Programming Language 日本語版](title-page.md)
12: [まえがき](foreword.md)
13: [導入](ch00-00-introduction.md)
14:
15: <!--
16: ## Getting started
17: -->
18: ## 事始め
19: 
20: <!--
21: - [Getting Started](ch01-00-getting-started.md)
22:     - [Installation](ch01-01-installation.md)
23:     - [Hello, World!](ch01-02-hello-world.md)
24:     - [Hello, Cargo!](ch01-03-hello-cargo.md)
25: -->
26: - [事始め](ch01-00-getting-started.md)
27:     - [インストール](ch01-01-installation.md)
...

(We are keeping the original English texts in HTML comments to track future updates in the original)

Without this change, mdBook 0.4.x will fail as the followings:

$ mdbook build
[ERROR] (mdbook::utils): Error: Summary parsing failed
[ERROR] (mdbook::utils): 	Caused By: There was an error parsing the suffix chapters
[ERROR] (mdbook::utils): 	Caused By: failed to parse SUMMARY.md line 26, column 1: 
Suffix chapters cannot be followed by a list

Note that mdBook 0.3.7 can parse the same SUMMARY.md without problem.

[ehuss]

Thanks for the PR! It looks like the problem is a little more complex thank how first is handled. From what I can see, the problem is that parse_title is exiting early because of the comment appearing before the H1 tag. Everything after that gets a little confused because it is out of order.

I think at a minimum parse_title would need to skip over leading Html events.

As for the first handling, do you know why it is there? Under what circumstances does a paragraph event happen as the first event in parse_numbered? Why do you handle html_node differently than other things that are ignored?

[tatsuya6502]

I think at a minimum parse_title would need to skip over leading Html events.

As for the first handling, do you know why it is there? Under what circumstances does a paragraph event happen as the first event in parse_numbered? Why do you handle html_node differently than other things that are ignored?

@ehuss — Thanks for your feedback. I realized that my change in parse_numbered was not necessary, so I reverted them in my latest commit (#30ce7e79). I verified that the unit test skip_html_comments (added by my first commit) still passes.

When I started to work on this PR, I changed parse_numbered first and it solved some of my problems with SUMMARY.md. But then I realized parse_title needed a change too. So I changed parse_title but I did not check if my change in parse_numbered was still necessary. That was why my first commit still had the both changes.

Please review this PR again and let me know if you have any questions.

[ehuss]

Looks good, thanks!

[y-yu]

@ehuss
Now, we are using our fork version of mdBook due to this issue.

• https://github.com/tatsuya6502/rust-by-example-ja/blob/774c8c5d47d45242795b197395f29f4df743ea8c/.circleci/config.yml#L6
• https://github.com/rust-lang-ja/book-ja/blob/da2746a91c73176890fec185978b3ff04c924717/.circleci/config.yml#L6
• https://github.com/rust-lang-ja/book-ja-pdf/blob/fad13f7a5b7f2c6bffc22d5a9fc8faa0ed077f23/docker/Dockerfile#L92-L93

So we would be very happy if you release version 0.4.8, which includes this fix. Please 🙏

[ehuss]

@y-yu, sure! 0.4.8 should be published now.

[y-yu]

Thanks!👍