Skip to content

After upgrading to 0.0.55, build fails with false-positive "unresolved link reference" warnings for code and diagram blocks #866

Closed

Description

@pan-marchewka

Context

Zensical: 0.0.55 (0.0.54 unaffected)
OS: macOS (Darwin 25.6.0)
Command: zensical build --clean --strict

Bug description

After upgrading from zensical 0.0.54 to 0.0.55, zensical build --strict fails with unresolved link reference warnings.

In my repo, it means hundreds of warnings. Every single one is false, since before the update the same build passed cleanly.

The flagged text is square-bracket syntax inside inline code spans, fenced code blocks, or diagram code blocks.

Some anonymized examples:

Inline code with brackets is flagged:

const credentials = await httpAuth.credentials(request, { allow: ['user'] });

A fenced JS block is flagged:

const MOCK_TODO = [                                                                                                                                                                                                       
  { id: '1', title: 'Todo 1' },                                                                                                                                                                                           
];                                                                                                                                                                                                                        

A Mermaid diagram is flagged:

graph TD                                                                                                                                                                                                                  
    subgraph Config[<strong>Configuration</strong>]                                                                                                                                                                       
        YAML[YAML configuration files<br/><code>data/bot_protection.yaml</code>]                                                                                                                                          
    end                                                                                                                                                                                                                   
Loading

A Graphviz/dot (kroki) block is flagged:

digraph {                                                                                                                                                                                                                 
  node [fontname="Helvetica-Bold", fontsize=15];                                                                                                                                                                          
}                                                                                                                                                                                                                         

A PlantUML state-diagram block is flagged:

[*] --> Access_request_submission #lightgrey                                                                                                                                                                              

Related links

Reproduction

zensical-strict-repro.zip

Steps to reproduce

  1. Upgrade to 0.0.55.
  2. Run zensical build --clean --strict against a docs tree containing Markdown like the minimal examples shown.
  3. Observe warnings pointing at bracketed content inside backticks or fenced/diagram code blocks.
  4. Downgrade to 0.0.54 and rebuild the same tree. The build succeeds.

Browser

No response

Before submitting

Activity

  1. squidfunk commented on Aug 17, 2026

    @squidfunk
    Member

    Thanks for reporting! Fixed in 9973ac9. Please note that unresolved_references is deprecated, so we can't guarantee that further false positives are still present. We investigate each false positive for viability, and fix those that are relatively contained. Zensical Studio contains our new production-grade Rust-based Python Markdown compatible parser, which we'll also release later this year.

  2. added
    bugIssue reports a bug
    resolvedIssue is resolved, yet unreleased if open
    on Aug 17, 2026
  3. pan-marchewka commented on Aug 17, 2026

    @pan-marchewka
    Author

    @squidfunk Thank you! Looking forward to the new parser. As for Zensical Studio, I use IntelliJ IDEA, so it's not for me, I'm afraid :-).

  4. squidfunk commented on Aug 17, 2026

    @squidfunk
    Member

    @pan-marchewka we'll bring Zensical Studio to JetBrains IDEs soon ☺️

  5. squidfunk commented on Aug 18, 2026

    @squidfunk
    Member

    Released as part of Zensical 0.0.56.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugIssue reports a bugresolvedIssue is resolved, yet unreleased if open

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions