Bring back "draft chapters"

[azerupi]

Hi there, it has been a while since I contributed. 😅

For this PR I want to brink back an old feature I miss: "draft chapters"
Draft chapters are chapters that don't have any content, no file associated with them and only show up in the table of contents. They were previously (a long time ago) supported by mdBook but at some point there was a regression and they were never brought back.

I found them particularly useful in two situations:

1. When I wanted to show that a specific chapter was planned for the future. It has no content, no file, but as it shows up in the TOC, users know that I plan to write it.
2. When I am playing with the structure of a new book or a series of new chapters. In this case, as the structure still changes a lot and I only want an overview, I don't want the files to be created. Having the possibility to first freely map out the structure of the table of contents before worrying about the actual files on disk is a huge advantage to me.

So with this PR I implemented draft chapters explicitly, they are a new kind of item in the summary and book. This means that the changes are breaking changes.

This is what it looks like:

As you can see in the image:

• Draft chapters can be used wherever a chapter can be used
• Draft chapters are rendered in the TOC but are not clickable
• Draft chapters can be the first chapter of the book, in that case the index page will be blank
• Navigation skips over draft chapters

It has been a while since I have been involved in the project and since I have actively programmed with Rust so feel free to point out anything that could be improved. 👍

[ehuss]

Looks pretty good to me.

I was wondering, there seems to be a lot of duplication between Chapter and DraftChapter and Link and DraftLink. Might it be a much smaller impact if Chapter::path and Link::location were just changed to Option<PathBuf> instead of adding new types?

[azerupi]

Might it be a much smaller impact if Chapter::path and Link::location were just changed to Option instead of adding new types?

That is how it worked in the past 😉 But apparently it wasn't documented, tested and explicit enough and got removed in a refactoring pass at some point. It is for that reason that I decided to encode it explicitly in the types.

But I agree with you, there is a lot of duplication. At some point I thought about making a common trait for chapters. So that some functions can just return an impl Link or something. But it would require a little bit more thought.

[azerupi]

Hi @ehuss,
Any idea on how to move forward with this? I am open to rework this PR if needed 🙂

[ehuss]

I would be more comfortable landing this if the duplication was removed. Using an Option seems reasonable, and with appropriate tests and documentation, shouldn't regress.

[azerupi]

Ok, I will change it 🙂

[azerupi]

Closed in favor of #1153