Add a way to ignore the source link file present in the SUMMARY.md while including the link.

[AdrienDerobert]

Problem

I want to add an auto generated part of a documentation that I am writing but the tool I am using generates HTML so i want to have a link to the page generated by the tool in the sidebar. Problem the book won't build because the source doesn't exist.

Proposed Solutions

Solution 1: Add a syntax to the SUMMARY parser to make it so it will ignore the file behind the link but generate the the link .

Solution 2: If the link is not a md file it inserts the link into the sidebar without checking for a file in the source directory and leave it to the user to ensure the file at the link destination is present in the output directory.

Solution 3: Add a way to hook into the serve process to have a post build script run before the files are served where i can fix the generated part with a bash script.

Notes

Currently to include my generated part i put an empty index.md file where the index.html would end up in the finished build but the problem arise when running mdbook serve where the generated HTML is systematically replaced by the empty file.

[szabgab]

How do you combine the autogenerated part today?

If I understand you correctly you could include empty md-files as placeholders for the html files and once mdbook generated the html you could replace the html file generated by mdbook by the ones that tool generates.
Would this solve the problem?

[AdrienDerobert]

Yes it would solve my issue but the problem arise when i do a mdbook serve as it systematically replaces the generated HTML by the empty file in the output directory, which is very annoying. My suggestion to ignore the file in the summary would fix this issue ... Also there is no way to hook into the serve process to fix the generated part with a script myself.

[AdrienDerobert]

I made a pr that adds a way for me to hook into the serve process and run a script. Works perfectly 😄 Now we wait for a review...

[ehuss]

Thanks for the suggestion! However, this seems like a duplicate of #919.

I don't think making the webserver hookable is an approach I would want to take. The webserver is intended only for local development, and thus any integration wouldn't be appropriate for deployment.

[szabgab]

If I understand correctly, this should not make the webserver hookable. This would add a post-processing step that runs after all the output-processors ran.

[AdrienDerobert]

If I understand correctly, this should not make the webserver hookable. This would add a post-processing step that runs after all the output-processors ran.

Yes that is the intended use.

I don't think making the webserver hookable is an approach I would want to take. The webserver is intended only for local development, and thus any integration wouldn't be appropriate for deployment.

To be more clear, the problem with the serve command is i can't easily make my post process step run after the watcher rebuilds the book. But its way simpler for build mdbook build && ./post-build.sh
In my pr #2620 I added a way to do exactly that only for the serve command. I might also add pre-build command.

This would allow use cases like including generated markdown and html in the book:

./include-generated-md-files.sh && \ # include md files in the src directory
mdbook build && \
./include-generate-html-files.sh # patch the html files in the book

and

mdbook serve --pre-build "./include-generated-md-file.sh" --post-build "./include-generated-html-files.sh"

[szabgab]

I actually have a case that might be similar to this. In the https://mdbooks.code-maven.com/ project all the md files are generated by an external program. Because of that the src folder is listed in .gitignore the watch does not get triggered.

So I run cargo run -- --report && mdbook build report

Where cargo run -- --report builds the md files in the report/src folder.

This conversation now encouraged me to try to setup a different way so I ran

cargo watch -s "cargo run -- --report && mdbook build report"

and this seem to solve the problem for me.

(And I just noticed that cargo watch is now archived: https://github.com/watchexec/cargo-watch so maybe I'll need another solution.)