[Evian-Zhang]

Follow up the discussion in this thread in Rust Internal Forums. More and more academic papers tend to cite official Rust books, and I think it would be better if the HTML version can directly give people the citation files.

In this PR, a new configuration key "citation" is added to the [output.html]. This key points to a file, and a new button will be added to the up right corner, which will link to the pointed file for user to download.

For now, the download button simply link to the original file given by book authors. In the future, this functionality can become: author provide either bib or cff, user can download bib, plaintext, APA, etc.. But since there is no such a mature crate for this functionality, I think we can temporarily keep it simple, and such functionality should not reside in this crate, but in an individual crate.

[GuillaumeGomez]

Please add a screenshot of what the page looks like with the citation button. Otherwise seems like a good idea to me overall.

[Evian-Zhang]

It looks like this, in the upper right corner.

[GuillaumeGomez]

I think you need to rebase on top of main to fix CI.

[Evian-Zhang]

I guess I have rebased to the latest main. As suggested in CI, pulldown_cmark has a vulnerability in 0.13.5, which is what current Cargo.toml depends on. Maybe the maintainer needs to bump the pulldown_cmark dependency first.

[GuillaumeGomez]

I opened #3263.

[rustbot]

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.

[Evian-Zhang]

I have rebased the PR to latest main, and passed the CI. Thank you! ❤️

[GuillaumeGomez]

Coming back to this: what prevents you to add a citations page in the book directly? I don't really see what adding a new button for this feature brings that the current mdbook cannot already do.

[Evian-Zhang]

I think adding a configurable button is more like a standardized best practice for book authors to suggest them providing citations, and to suggest readers how they can cite this book.

Like what I said in the forum post linked in this PR description, there are already citations file in some of the official Rust books' github repos, but none of them has a dedicated citation page in the book.

Also, we have the "git-repository-url" configurable button. Although the author could provide the link in the content of the book, we still provide it. I know this does not mean that we need to add a configurable button to every metadata of a book, but I do think citation is worth it considering even the official book lacks it and how readers want it.