📈 Print file not found as debug instead of error

[Karreg]

This PR changes the message level from ERROR to DEBUG when a diagram file is not found.

WHY: The current behavior creates a D2 image processor for each folder. Each folder is scanned for the diagrams, and errors are raised even though the file is found. A small sample of a modified plugin, for a single included file:

ERROR   -  mkdocs-d2-plugin: File found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/posts/
ERROR   -  mkdocs-d2-plugin: File found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/posts/
ERROR   -  mkdocs-d2-plugin: File found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/posts/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/archive/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/archive/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/archive/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/category/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/category/
ERROR   -  mkdocs-d2-plugin: File not found: gitlab_runner_improved_registration/gitlab_runner_improved_registration_04.d2 in /workspaces/thoughts/docs/blog/category/

IMPROVEMENT: No more systematical false errors raised at compilation, hiding true errors.

REGRESSION: Errors aren't raised anymore when a file is not found anywhere.

There is space for improvement, if we can raise the error only where the file was not found in any scanned folder, but I'm not sure this can be done with the current architecture. This PR should be seen as a tactical improvement until a better fix is found.

To me, hiding true errors is less problematic than raising false errors everytime. WDYT?

[landmaj]

Can you please provide an example on how to reproduce this behavior? I would rather fix the underlying issue than change error logs to debug.

[Karreg]

I think this is related to the blog feature of material for mkdocs. I'll create a sample repo to validate my theory and give it to you. Thanks for your feedback :)

[Karreg]

I have set up a minimal, reproducible, MkDocs site here. You can open it directly in Codespaces if you want to quickly validate: https://github.com/Karreg/mkdocs-d2-plugin-playground

A single d2 file, 1 generation without error, 3 errors from different folders.

[landmaj]

So it seems like the blog plugin copies markdown files when generating excerpts for category and archive views but it does not copy other assets alongside them. The errors you listed are actual errors, it's just that your example is structured in such a way that the issue is not visible. Move the diagram above <!-- more --> and you will see alt text ("D2 diagram") instead of the rendered diagram in excerpts. Plus GET requests for some_diagram.d2.

This will need a proper fix but so far I could not find a solution.

[Karreg]

The errors you listed are actual errors

Yes, I know they are in technical domain, but not in functional domain. That's why I would like to hide them unless in debug mode.

Even MkDocs does not display errors when files are missing, but instead is showing a WARN. Either it should be WARN or DEBUG is debatable. I would prefer a proper fix with WARN level, but in the meantime, DEBUG would avoid missing real errors or warnings...

[Karreg]

Maybe a configurable behavior would help, without being too much permissive? It could be explicitely documented as workaround for the blog feature of material, it would be fair...

[landmaj]

I changed the log level from error to warning. Debug is out of the question as there would be no indication that something is wrong if you wanted a diagram in an excerpt.

Let's move further discussion here: https://github.com/landmaj/mkdocs-d2-plugin/issues/13