search

Michael-F-Bryan / mdbook-epub

An experimental mdbook backend for creating EPUB documents.
https://michael-f-bryan.github.io/mdbook-epub/
Mozilla Public License 2.0
371 stars 46 forks source link

Markdown images break the plugin invoking errors #115

Open NuLL3rr0r opened 1 month ago

NuLL3rr0r commented 1 month ago

For example:

![FXRMotionControllerData Blueprint representation](fxrmotioncontrollerdata-blueprint-representation.png "FXRMotionControllerData Blueprint representation")

Produces:

2024-07-18 14:00:54 [INFO] (mdbook::book): Book building has started
2024-07-18 14:00:55 [INFO] (mdbook::book): Running the epub backend
2024-07-18 14:00:55 [INFO] (mdbook::renderer): Invoking the "epub" renderer
Running mdbook-epub as plugin...
[2024-07-18T12:00:55Z ERROR mdbook_epub::generator] Failed finding/fetch resource taken from content? Look up content for possible error... Caused by: Asset was not found: 'fxrmotioncontrollerdata-blueprint-representation.png' by '/SomeProject/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-representation.png', error = No such file or directory (os error 2)
[2024-07-18T12:00:55Z ERROR mdbook_epub] Asset was not found: 'fxrmotioncontrollerdata-blueprint-representation.png' by '/SomeProject/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-representation.png', error = No such file or directory (os error 2)
2024-07-18 14:00:55 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2024-07-18 14:00:55 [ERROR] (mdbook::utils): Error: Rendering failed
2024-07-18 14:00:55 [ERROR] (mdbook::utils):    Caused By: The "epub" renderer failed
make: *** [GNUmakefile:282: serve] Error 101

This however works fine with the HTML backend as intended.

dieterplex commented 1 month ago

According to the path '/SomeProject/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-representation.png', I'm curious what's the directory structure you placing this image? Or could you provide a minimum reproducible source example?

blandger commented 1 month ago

Agree. @NuLL3rr0r Could you please provide an link to your book sources? Or may be you could create such sources with 'minimum reproducible example' as @dieterplex suggests. I would be very helpful to check and test then.

NuLL3rr0r commented 1 month ago

Sure, I've created a new branch in our project to reproduce the issue. It can be found here. The repository is a few GBs, I've just removed everything else and kept the MDBook, so you could use the Download button from the hamburger menu.

Inside the book.toml if we comment the following config everything works as expected:

# Disabling this line everything works as expected
[output.epub]

But, here's the error:

[2024-07-19T07:54:16Z ERROR mdbook_epub::generator] Failed finding/fetch resource taken from content? Look up content for possible error... Caused by: Asset was not found: 'fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png' by '/home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png', error = No such file or directory (os error 2)
[2024-07-19T07:54:16Z ERROR mdbook_epub] Asset was not found: 'fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png' by '/home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png', error = No such file or directory (os error 2)
2024-07-19 09:54:16 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2024-07-19 09:54:16 [ERROR] (mdbook::utils): Error: Rendering failed
2024-07-19 09:54:16 [ERROR] (mdbook::utils):    Caused By: The "epub" renderer failed
make: *** [GNUmakefile:281: serve] Error 101

If I remove the following lines from this file with the mdbook-epub backend enabled, everything works:

![FXRMotionControllerData Blueprint representation](fxrmotioncontrollerdata-blueprint-representation.png "FXRMotionControllerData Blueprint representation")

![Get a joint position and rotation from FXRMotionControllerData in Blueprint](fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png "Get a joint position and rotation from FXRMotionControllerData in Blueprint")

As suggested by the mdbook example in their own book we keep images at the same level as the .md file since easier to address. But, for example if we move the assets to /assets/ and try to link with absolute paths it breaks the mdbook-pdf backend with images not showing up, but the PDF generation works there.

I hope that helps demonstrate the issue.

blandger commented 1 month ago

Thanks a lot @NuLL3rr0r !

[output.epub]

That disables mdbook-epub completely, only mdbook works in this case.

If I remove the following lines from this file with the mdbook-epub backend enabled, everything works:

Thank you. That is most interested case.

NuLL3rr0r commented 1 month ago

Yes, I meant disabling the epub backend makes everything else work (HTML, PDF backends generate their expected output) when there are markdown images inside the project. Sorry, if my wording was not clear.

Thank you for taking caring of the issue!

dieterplex commented 1 month ago

What's the version of mdbook-epub you using? Download and build with code of master branch or 0.4.37 tag are both working. There is no ../index.md/.. in the image path from the logs of these two builds.

NuLL3rr0r commented 1 month ago

Well, I've just made the following change in our GNUmakefile

-       @cargo install mdbook-epub --locked
+       @cargo install --git https://github.com/Michael-F-Bryan/mdbook-epub --locked

And it seems v0.4.40:

   Compiling mdbook-epub v0.4.40 (/home/mamadou/.cargo/git/checkouts/mdbook-epub-bd1aa49df9dbc8c0/bea2901)
    Finished `release` profile [optimized] target(s) in 49.79s
   Replacing /home/mamadou/.cargo/bin/mdbook-epub
    Replaced package `mdbook-epub v0.4.40` with `mdbook-epub v0.4.40 (https://github.com/Michael-F-Bryan/mdbook-epub#bea29011)` (executable `mdbook-epub`)
Preparing the handbook source dir /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src...
Preparing the handbook target dir /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Documentation...
Preparing the handbook /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook...
Serving /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook...
2024-07-19 10:48:02 [INFO] (mdbook::book): Book building has started
2024-07-19 10:48:02 [INFO] (mdbook::book): Running the epub backend
2024-07-19 10:48:02 [INFO] (mdbook::renderer): Invoking the "epub" renderer
Running mdbook-epub as plugin...
[2024-07-19T08:48:02Z ERROR mdbook_epub::generator] Failed finding/fetch resource taken from content? Look up content for possible error... Caused by: Asset was not found: 'fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png' by '/home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png', error = No such file or directory (os error 2)
[2024-07-19T08:48:02Z ERROR mdbook_epub] Asset was not found: 'fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png' by '/home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png', error = No such file or directory (os error 2)
2024-07-19 10:48:02 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2024-07-19 10:48:02 [ERROR] (mdbook::utils): Error: Rendering failed
2024-07-19 10:48:02 [ERROR] (mdbook::utils):    Caused By: The "epub" renderer failed
make: *** [GNUmakefile:281: serve] Error 101
NuLL3rr0r commented 1 month ago

And, I've just realized crates.io has version v4.40.0 while I cannot find this tag on the repo. I feel a bit confused.

NuLL3rr0r commented 1 month ago

OK, even tried this for the latest commit on the master branch:

-       @cargo install mdbook-epub --locked
+       @cargo install --git https://github.com/Michael-F-Bryan/mdbook-epub --rev bea29011abc66978737342320a8e539fade23413 --locked
   Compiling mdbook-epub v0.4.40 (/home/mamadou/.cargo/git/checkouts/mdbook-epub-bd1aa49df9dbc8c0/bea2901)
    Finished `release` profile [optimized] target(s) in 46.84s
   Replacing /home/mamadou/.cargo/bin/mdbook-epub                                                                 
    Replaced package `mdbook-epub v0.4.40 (https://github.com/Michael-F-Bryan/mdbook-epub#bea29011)` with `mdbook-epub v0.4.40 (https://github.com/Michael-F-Bryan/mdbook-epub?rev=bea29011abc66978737342320a8e539fade23413#bea29011)` (executable `mdbook-epub`)
Preparing the handbook source dir /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src...
Preparing the handbook target dir /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Documentation...
Preparing the handbook /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook...
Serving /home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook...
2024-07-19 10:57:50 [INFO] (mdbook::book): Book building has started
2024-07-19 10:57:50 [INFO] (mdbook::book): Running the epub backend
2024-07-19 10:57:50 [INFO] (mdbook::renderer): Invoking the "epub" renderer
Running mdbook-epub as plugin...
[2024-07-19T08:57:50Z ERROR mdbook_epub::generator] Failed finding/fetch resource taken from content? Look up content for possible error... Caused by: Asset was not found: 'fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png' by '/home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png', error = No such file or directory (os error 2)
[2024-07-19T08:57:50Z ERROR mdbook_epub] Asset was not found: 'fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png' by '/home/mamadou/dev/SGBasicDemo/Plugins/SenseGlove/Handbook/src/advanced-topics/openxr/consuming-fxrmotioncontrollerdata/index.md/fxrmotioncontrollerdata-blueprint-get-joint-position-rotation.png', error = No such file or directory (os error 2)
2024-07-19 10:57:50 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2024-07-19 10:57:50 [ERROR] (mdbook::utils): Error: Rendering failed
2024-07-19 10:57:50 [ERROR] (mdbook::utils):    Caused By: The "epub" renderer failed
make: *** [GNUmakefile:281: serve] Error 101
dieterplex commented 1 month ago

Default link preprocessor will rename README.md to index.md, that's why the image path is unexpected. In standalone mode, the page name is keeping as README.html, but the image is embedding to root level directory and could not be found in page.

I strongly suggest use filename other than "README.md" that is special to link preprocessor causing this kind of issue. And we should explicitly tell user this situation when using README.md as filename.

NuLL3rr0r commented 1 month ago

Well, that's what the mdbook source themselves are doing. For every folder they have a REAMDE.md treated as index.html.

dieterplex commented 1 month ago

Before a fix landed, downgrade to 0.4.27 to workaround this for now to produce a valid epub for reading.

cargo install --version 0.4.27 mdbook-epub

Look deep into it, something happened when refactoring before. Even build pass, the image is embed to wrong path and not visible when reading ePub file.

This bug is introduced in commit and error only occurs when running as a preprocessor and links preprocessor enabled. The issue, image is not found when reading, is happened whether how the book is built.