rust-lang / rust-lang/mdBook

Anchor parsing ignores ANCHOR_END, making it behave the same as a starting ANCHOR tag.

Open
#2,778 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-link-preprocessor C-bug
Dominant language
Rust
Stars
22.2k
Forks
1.9k
Avg merge
2d 21h
Merged PRs (30d)
12

Description

Problem

Hello,

First, thank you for this excellent project! I've found a potential bug or a mismatch between the documentation and the implementation of the file inclusion anchor feature.

The documentation states that an anchor is a "pair of matching lines" that must begin with ANCHOR: name and end with ANCHOR_END: name. This implies that the ANCHOR_END tag is required to correctly close a named block.

However, in my testing, the parsing logic does not seem to distinguish between ANCHOR: name and ANCHOR_END: name. Using a second starting anchor tag (/* ANCHOR: all /) seems to close the block in the same way an end tag (/ ANCHOR_END: all */) does.

Steps
  1. According to the documentation, this is the expected structure, and it works correctly:
/* ANCHOR: all */
struct Paddle {
    hello: f32,
}
/* ANCHOR_END: all */
  1. However, the following example, which incorrectly uses a starting ANCHOR tag at the end, produces the exact same output:
/* ANCHOR: all */
struct Paddle {
    hello: f32,
}
/* ANCHOR: all */
Possible Solution(s)

This could be either a bug in the parsing logic or an area where the documentation could be updated to clarify this behavior.

Thank you for your time and consideration!

Notes

No response

Version

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the file-inclusion anchor parser and the documentation describing matching ANCHOR and ANCHOR_END lines. Check whether parser tests cover a second starting anchor as a closing marker. Done means the implementation and documentation agree, with tests distinguishing the two forms.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.