Ignore mathjax link
ZakCodes opened this issue · comments
As shown in the mdBook documentation, Mathjax blocks are written this way: \\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\] . The temporary solution is to only use the inline Mathjax syntax which doesn't interfere with this tool and looks like this: \\( \mu = \frac{1}{N} \sum_{i=0} x_i \\).
The good side of it is that it only gives out a warning so it doesn't prevent the site from compiling.
Here's the output from mdbook build:
2019-12-15 11:19:28 [INFO] (mdbook::book): Book building has started
2019-12-15 11:19:28 [INFO] (mdbook::book): Running the html backend
2019-12-15 11:19:28 [INFO] (mdbook::book): Running the linkcheck backend
2019-12-15 11:19:28 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer
warning: Potential incomplete link
┌── etude/module-controle/index.md:20:3 ───
│
20 │ \\[ \int x dx = \frac{x^2}{2} + C \\]
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Did you forget to define a URL for ` \int x dx = \frac{x^2}{2} + C \\`?
│
= hint: declare the link's URL. For example: `[ \int x dx = \frac{x^2}{2} + C \\]: http://example.com/`
I am also using mdBook v0.3.5 and mdbook-linkcheck v0.5.0 if that can be of any help.
If you don't want to see those warnings you can always set warning-policy = "ignore" under [output.linkcheck].
I don't think it would really be possible to (reliably) detect if a potentially incomplete link is actually meant to be mathjax. I'm also questioning whether it'd be a good idea because that then couples us to mdbook's mathjax handling (but only when mathjax-support = true is set!) and adding extra flags for edge-cases tends to make things harder to maintain in the long run.
Sorry if this sounds pessimistic. I just don't want to add unnecessary maintenance burden to the project.
I get that you don't want to depend on the html backend. Maybe a property like ignore-mathjax could be added to linkcheck's configuration. This property would then be independent of the html backend's configuration, but would still depend on the syntax used for mathjax statements.
Another possibility would be to add a second exclude property, it could be named exclude-content, that would filter links based on their content rather than their URL. Users could then manually exclude mathjax statements. This solution would not depend on anything.
For right now, the solution than I've found is to add a special URL to my mathjax statements and then exclude it from linkcheck's configuration like this:
- markdown file:
\\[
\mu = \frac{1}{N} \sum_{i=0} x_i
...
\\](mathjax)- linkcheck's configuration
[output.linkcheck]
exclude = ["mathjax"]Having some sort of ignore-link-by-text key sounds like a pretty good alternative.
Are there any patterns which are "obviously" mathjax? For your use case, we could probably get away with matching a \.
The only thing obvious is the \ at the very end of the expression. It shouldn't be a problem since valid links don't include any \ characters.
It's also important to note that mathjax expression can be on multiple lines and therefore a regex like .*\\ wouldn't work, because the . doesn't match newlines. We would therefore have to use something like this [^]*\\.
It would probably be a little complex to get the content of a link, since links can contain pretty much any markdown inside them. The content of the links will therefore probably have to be converted back to markdown, maybe using pulldown-cmark-to-cmark, before they can be used.
Merry Christmas btw!
For me it was solved by just using \\( expression... \\). Parentheses are also okay under the current version of mdbook and they don't conflict with linkcheck.
I use $$...$$ for block equations and \((...\)) for inline equations.