Header `@id` syntax does not support dashes

[asinghvi17]

┌ Warning: Cannot resolve @ref for md"[advanced users guide](@ref advanced-guide)" in src/somefile.md.
│ - No docstring found in doc for binding `Base.-`.
└ @ Documenter ~/.julia/packages/Documenter/iRt2s/src/utilities/utilities.jl:49

Maybe it's trying to parse as Julia? I guess the simple solution is to use a String or something. But I thought it would match first, that's what the docs say.

[goerz]

This seems related to https://github.com/JuliaDocs/Documenter.jl/issues/2677

[asinghvi17]

Looks like it's the same issue, yep...but this particular problem wasn't mentioned there.

[odunbar]

Hi folks,

I don't think this issue is correct here, I actually think it is a whitespace issue, and removing it fixed it on my end. That may work for you folks?

My situation

I have many @id blocks that work with dash

In the following however i did obtain issues as you have:

The headers:
## [How do I build good observational noise covariances] (@id building-covariances)
## [Observations] (@id observations)

The call backs:
... the [section below](@ref building-covariances) ...
... or [minibatching](@ref observations) ...

etc. Recently this gave me errors:

┌ Error: Cannot resolve @ref for md"[section below](@ref building-covariances)" in docs/src/observations.md.
│ - No docstring found in doc for binding `Base.-`.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[Observations](@ref observations)" in docs/src/ensemble_kalman_inversion.md.
│ - No docstring found in doc for binding `Main.observations`.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[here](@ref building-covariances)" in docs/src/ensemble_kalman_inversion.md.
│ - No docstring found in doc for binding `Base.-`.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[minibatching](@ref observations)" in docs/src/troubleshooting.md.
│ - No docstring found in doc for binding `Main.observations`.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[here](@ref building-covariances)" in docs/src/unscented_kalman_inversion.md.
│ - No docstring found in doc for binding `Base.-`.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[How do I build good observational noise covariances](@ref building-covariances)" in docs/src/index.md.
│ - No docstring found in doc for binding `Base.-`.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:47
┌ Error: Cannot resolve @ref for md"[How do I build my observations and encode batching?](@ref observations)" in docs/src/index.md.
│ - No docstring found in doc for binding `Main.observations`.
└ @ Documenter ~/.julia/packages/Documenter/xvqbW/src/utilities/utilities.jl:47

As we see the error is for both of these headings regardless of the dash

The Fix

The fix was to remove whitespace between the [...] and (@id ...) blocks

from
## [How do I build good observational noise covariances] (@id building-covariances)
## [Observations] (@id observations)

to
## [How do I build good observational noise covariances](@id building-covariances)
## [Observations](@id observations)

For me - prior to v1.16.1's new strict policies, the whitespace never gave me warning or error, and also gave me correct behaviour. But now it causes an error.

Maybe this is also true in your case?

I

[fingolfin]

Note: the stricter parsing there is not due to a change in Documenter, but rather due to a bugfix in the Markdown stdlib in Julia.