The language '@example' is not loaded, falling back to 'txt' for syntax highlighting.

[Azzaare]

While building either locally or as a GitHub action, I have the following warning:

The language '@example' is not loaded, falling back to 'txt' for syntax highlighting.

If I clone DocumenterVitepress and build the doc, the @example blocks are built and interpreted correctly, though. I guess I am missing some configuration somewhere, any idea? My knowledge of nodejs is low, but I would have guessed it is related to this Shiki thing.

For the record, I am building the documentation website for the Julia Constraints org, and everything can be found there: https://github.com/JuliaConstraints/JuliaConstraints.github.io

[lazarusA]

maybe some things are missing here in the deploydocs as in here: https://github.com/LuxDL/DocumenterVitepress.jl/blob/ece320c028daab5b08780ae9cf07a565fd098ae6/docs/make.jl#L34

[asinghvi17]

Generally this happens when Documenter fails to execute the @example block.

[asinghvi17]

@Azzaare is this still an issue you're encountering? If so, please point me to the repo and I'll see what might be stuck.

[Azzaare]

Interestingly enough, it is almost solved. I was indeed missing a couple of things int the deploydocs. For some reason, the fix did not work first, but eventually did. Might be a cache issue in the browser.

In the current state, almost everything is working as intended, but I have a strange output coming out

I am trying to narrow down the issue.

[Azzaare]

@asinghvi17 Just solved it … My startup file was messing up the output. It is a bit difficult to narrow the culprit down because of the dependencies involved, but I include a few popular packages in my startup.jl:

• Revise
• LocalRegistry
• PackageCompatUI
• Term
• OhMyREPL
• DrWatson
• Coverage

/path/to/DocumenterVitepress.jl/docs$ julia --project --startup-file=no make.jl

Maybe including a warning about startup files in DocumenterVitePress.jl doc when building locally can help lost sheep like me :D

[asinghvi17]

Ah I guess it might be something from one of the terminal packages? I run OhMyREPL and never had that issue, but will double check just to be sure.

[Azzaare]

@asinghvi17 OK, I found out the original issue.

Currently, when a @example block in DocumenterVitePress errors (as in the julia code errors), it will throw this warning:

The language '@example' is not loaded, falling back to 'txt' for syntax highlighting.

I missed it at first, I was in the middle of refactoring code while writing the documentation, sorry :/

For what it is worth, I think it would be nice to have a better error/warning message if possible.

That being said, I've stumbled upon another issue while tackling this one. If I use the DocumenterVitePress @example block from a docstrings instead of directly in one of the doc's source file, it errors, and we fall back to this issue.

I have pushed a "MWE" on https://github.com/JuliaConstraints/JuliaConstraints.github.io Just building from the /docs folder (after instantiation) with

julia --project --startup-file=no make.jl

should work.

Code sample of what is working and not working can be found at https://github.com/JuliaConstraints/JuliaConstraints.github.io/blob/c3423359994a9eb120ad7b06775ce8cbdfcfd2e9/docs/src/constraints/generic_constraints.md And web output at:

• Working as intended: https://juliaconstraints.github.io/dev/constraints/generic_constraints#Test-for-DocumenterVitePress-Issue
• Failing: https://juliaconstraints.github.io/dev/constraints/generic_constraints#Specific-documentation

I will keep it in that state as long as necessary.

[asinghvi17]

Thanks! That is a bit strange, but it's probable that the code which renders documentation blocks does not correctly call out to the rendering code.

As for the example issue: I can have that changed to julia in the markdown renderer, and have it emit a warning then saying that it encountered an example block on some line and is transforming it to a julia block.

I am a bit confused on where the 2+2 came from, though?

[Azzaare]

That way to handle the error in the example block should work well. As long as the user has a warning message that is informative enough, it is fine.

I will try to find some time to find which package is involved in the 2+2 issue.

[Azzaare]

OK, I just found the culprit of the 2+2 output.

It comes from calling Term.Repr.install_term_repr before building the doc. This is a super edge case, so I don't think it needs any fix.

We could have a list of known incompatibilities somewhere in the docs, though.

Thanks! That is a bit strange, but it's probable that the code which renders documentation blocks does not correctly call out to the rendering code.

I don't have much time in the coming days to help solve this one. But I will have a look next week if it is an issue.

[Azzaare]

I did some tests, and you're correct. If we write a docstrings containing, for instance:

````@example test_docstr
3 + 3

Then this element is not parsed as a `Markdown.Code("@example ...","...")`

If it helps, I deved Documenter.jl and added the following bit of code to the parsedoc function:
```julia
for c in md.content
        if c isa Markdown.Code && occursin("@example", c.language)
            @info "debug" c.language c.code
        end
end

And we only get (using the DocumenterVitePress basic doc)

┌ Info: debug
│   c.language = "@example test2"
└   c.code = "2 + 2"

No traces of "3 + 3".

Debugging it further is a bit above my understanding of Documenter.jl. @asinghvi17 is it within your skills? Or should we open an issue in Documenter.jl ?

[asinghvi17]

Probably worth an issue in Documenter! Also, in this case, I suspect that Documenter is not expanding the example blocks in the docstring, which is not fixable in DocumenterVitepress...

[Azzaare]

Okay, I will open an issue there and refer to this one. I am a bit busy here, thank you for your patience.

[Azzaare]

Well, there is no easy solution, so I will do as suggested in the Documenter.jl issue.

Thanks for the help.