Cannot find level-three cross-references

[nathanrboyer]

I am getting this build error:

CrossReferences: building cross-references.
Error: Cannot resolve @ref for md"[Applying Multiple Operations per Manipulation](@ref)" in src/man/basics.md.
- No docstring found in doc for binding `Base.-`.
Error: Cannot resolve @ref for md"[Broadcasting Operation Pairs](@ref)" in src/man/basics.md.
- No docstring found in doc for binding `Base.-`.

However, the basics.md file contains these lines:
Line 2514:

### Applying Multiple Operations per Manipulation

Line 2649:

### Broadcasting Operation Pairs

Pull request here:
JuliaData/DataFrames.jl#3360 (comment)

[nathanrboyer]

The suggested workaround to use header @id's is not working either.

[ Info: CrossReferences: building cross-references.
┌ Error: Cannot resolve @ref for md"[Applying Multiple Operations per Manipulation](@ref multi_op_manipulations)" in src\man\basics.md.
│ - No docstring found in doc for binding `Main.multi_op_manipulations`.
└ @ Documenter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\utilities\utilities.jl:44
┌ Error: Cannot resolve @ref for md"[Broadcasting Operation Pairs](@ref broadcasting_operation_pairs)" in src\man\basics.md.
│ - No docstring found in doc for binding `Main.broadcasting_operation_pairs`.
└ @ Documenter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\utilities\utilities.jl:44

Line 1675:

See the later sections [Applying Multiple Operations per Manipulation](@ref multi_op_manipulations)
and [Broadcasting Operation Pairs](@ref broadcasting_operation_pairs) for more information.

Line 2514:

### [Applying Multiple Operations per Manipulation](@id multi_op_manipulations)

Line 2649:

### [Broadcasting Operation Pairs](@id broadcasting_operation_pairs)

[nathanrboyer]

Is it because they are referred to above where they are defined?

[mortenpi]

I just tested with

[link](@ref an_index_of_docstrings)

[`link`](@ref an_index_of_docstrings)

### [An index of docstrings](@id an_index_of_docstrings)

and so does

[another link](@ref "Multiple uses of the same symbol")

[Multiple uses of the same symbol](@ref)

### Multiple uses of the same symbol

actually. So everything should work.. It would be good if we could reduce the issue down to an MWE.

[nathanrboyer]

Well it's not minimum yet, but I ran into some strange behavior. If I delete everything but the headers and references, then the cross-references build okay. Somewhere in between it fails. I am testing by running julia --project make.jl from the docs folder.

Here is my smaller failing example.
https://github.com/nathanrboyer/DataFrames.jl/tree/doc_MWE

make.jl

using Documenter
using DataFrames

makedocs(
    modules = [DataFrames],
    doctest = false,
    clean = true,
    sitename = "DataFrames.jl",
    format = Documenter.HTML(
        canonical = "https://juliadata.github.io/DataFrames.jl/stable/",
        assets = ["assets/favicon.ico"],
        edit_link = "main",
        size_threshold_ignore = ["man/basics.md", "lib/functions.md"],
    ),
    pages = Any[
        "Introduction" => "index.md",
        "First Steps with DataFrames.jl" => "man/basics.md",
    ],
)

index.md

# DataFrames.jl

## Package Manual

```@contents
Pages = ["man/basics.md"]
Depth = 2
```

basics.md
basics.md

basics.md Edits

As uploaded, the cross-references fail:

┌ Error: Cannot resolve @ref for md"[Applying Multiple Operations per Manipulation](@ref)" in src\man\basics.md.
│ - No docstring found in doc for binding `Base.-`.
└ @ Documenter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\utilities\utilities.jl:44
┌ Error: Cannot resolve @ref for md"[Broadcasting Operation Pairs](@ref)" in src\man\basics.md.
│ - No docstring found in doc for binding `Base.-`.

If I delete from line 9 (just after the references) to line to line 843 (just before the definitions), then the cross-reference error disappears.

# First Steps with DataFrames.jl

## Manipulation Functions

*The manipulation functions also have methods for applying multiple operations.
See the later sections [Applying Multiple Operations per Manipulation](@ref)
and [Broadcasting Operation Pairs](@ref) for more information.*

### Applying Multiple Operations per Manipulation

### Broadcasting Operation Pairs
.
.
.

$ julia --project make.jl
  Activating project at `C:\Users\nboyer.AIP\Documents\Julia\Forks\DataFrames\docs`
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: skipped.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Error: Generated HTML over size_threshold limit: lib\functions.md
│     Generated file size: 454.43 (KiB)
│     size_threshold_warn: 100.0 (KiB)
│     size_threshold:      200.0 (KiB)
│     HTML file:           lib\functions/index.html
└ @ Documenter.HTMLWriter C:\Users\nboyer.AIP\.julia\packages\Documenter\CJeWX\src\html\HTMLWriter.jl:1821
ERROR: LoadError: HTMLSizeThresholdError: Some generated HTML files are above size_threshold.
See logged errors for details.

Alternatively, if I keep the previous lines, and instead delete from line 848 to the end (the "Approach Comparison" section), then the cross-reference error also disappears, and I get the same output as above.

This leaves me somewhat stumped because there are at least two distinct paths to remove the error, neither of which appear to have anything to do with the headers or references themselves.

[nathanrboyer]

I was able to trim the basics.md file down to 17 lines. It seems to have something to do with code blocks and/or admonitions as well as the order in which they appear.

CrossReferences Fail:
Original

# Header 1

## Header 2

Reference [Header 3](@ref).

!!! Note
      ```julia
      "hello"
      ```

### Header 3

```julia
"hello"
```

CrossReferences Pass:
Remove code block.

# Header 1

## Header 2

Reference [Header 3](@ref).

!!! Note
      ```julia
      "hello"
      ```

### Header 3

hello

CrossReferences Pass:
Remove code block in note.

# Header 1

## Header 2

Reference [Header 3](@ref).

!!! Note
      hello

### Header 3

```julia
"hello"
```

CrossReferences Pass:
Remove note.

# Header 1

## Header 2

Reference [Header 3](@ref).

```julia
"hello"
```

### Header 3

```julia
"hello"
```

CrossReferences Pass:
Move note to bottom.

# Header 1

## Header 2

Reference [Header 3](@ref).

### Header 3

```julia
"hello"
```

!!! Note
      ```julia
      "hello"
      ```

CrossReferences Pass:
Move code block to top.

# Header 1

## Header 2

Reference [Header 3](@ref).

!!! Note
      ```julia
      "hello"
      ```

```julia
"hello"
```

### Header 3

CrossReferences Pass:
Reference Header 2 instead of 3.

# Header 1

## Header 2

Reference [Header 2](@ref).

!!! Note
      ```julia
      "hello"
      ```

### Header 3

```julia
"hello"
```

Hopefully you can make something of this. I don't think I can take it any further myself.

[nathanrboyer]

"Note" needs to be lowercase. It rendered fine in VSCode, so I didn't notice. Not sure what that has to do with the thrown cross-reference error, but at least that fixed it.