Missing source position of Links

[WhyNotHugo]

• goldmark is fully compliant with the CommonMark. Before submitting issue, you must read CommonMark spec and confirm your output is different from CommonMark online demo.
  • Extensions(Autolink without < >, Table, etc) are not part of CommonMark spec. You should confirm your output is different from other official renderers correspond with an extension.
• goldmark is not dedicated for Hugo. If you are Hugo user and your issue was raised by your experience in Hugo, you should consider create issue at Hugo repository at first .
• goldmark is a CommonMark parser. I do not discuss about specs here. Please post your questions about CommonMark specs at CommonMark spec repository.

---

Please answer the following before submitting your issue:

1. What version of goldmark are you using? : v1.4.12
2. What version of Go are you using? : go1.25.7
3. What operating system and processor architecture are you using? : linux/amd64
4. What did you do? : Tried to obtain the source location of a Link
5. What did you expect to see? : The location should be available via the source tree.
6. What did you see instead? : Did not find the location, it's lost during parsing
7. Did you confirm your output is different from CommonMark online demo or other official renderer correspond with an extension?: n/a

---

When parsing links, the AST loses information on the source location of the entire link.

The Link node has descendants from which we can infer a portion of the link, but the rest of it is lost during parsing.

At first I considered that this might be out-of-scope, but then I noticed that README.md mentions one of the core motivations behind goldmark is to preserves source position of nodes. This is exactly what I'm missing in this case.

Because links themselves don't have any position information, the best we can do is extract the "visible" portion from their text descendants:

[example](https://example.com)
^       ^^^^^^^^^^^^^^^^^^^^^^ range missing from AST
 ^^^^^^^ text node descendant

[example][ref]
^       ^^^^^^ range missing from AST
 ^^^^^^^ text node descendant

[example] where the ref is further below.
^       ^ range missing from AST
 ^^^^^^^ text node descendant

In my particular use case, I'm using goldmark for zk's LSP. User trigger "go to definition" to follow a link on their editor. But the entire source position of the Link is not available from the AST, so I have to extract it with some hack scanning:

// calculateLinkPositions calculates the byte offsets for a Link node.
// Returns (start of '[', end after ')').
func (t *linkPositionTransformer) calculateLinkPositions(link *ast.Link, source []byte) (int, int) {
	// ast.Link node doesn't store position information for delimiters. The
	// parser knows these positions internally (in linkLabelState.Segment),
	// but only transfers the URL and title to the final node. We need to
	// scan for the exact positions.

	textStart, textEnd := findFirstAndLastTextPositions(link)
	if textStart < 0 {
		return -1, -1
	}

	// Scan backwards from textStart to find '['.
	linkStart := -1
	for i := textStart - 1; i >= 0; i-- {
		if source[i] == '[' {
			linkStart = i
			break
		}
		if source[i] == ']' || source[i] == '(' {
			break
		}
	}

	linkEnd := -1
	i := textEnd

	if source[i] != ']' {
		// TODO: Should warn here? Is this even reachable?
		return linkStart, textEnd
	}
	i++ // skip ']'

	if i >= len(source) {
		// Link of the style [link].
		return linkStart, textEnd
	}

	if source[i] == '(' {
		// Inline link: scan to find matching parenthesis.
		i++ // skip '('
		parenDepth := 1
		for i < len(source) && parenDepth > 0 {
			// Ignore escaped characters (potentially, parenthesis).
			if source[i] == '\\' && i+1 < len(source) {
				i += 2
				continue
			}
			if source[i] == '(' {
				parenDepth++
			} else if source[i] == ')' {
				parenDepth--
				if parenDepth == 0 {
					linkEnd = i + 1
					break
				}
			}
			i++
		}
	} else if source[i] == '[' {
		// Reference link: [text][label]. Scan to find matching brace.
		i++ // skip '['
		for i < len(source) {
			// Ignore escaped characters (potentially, parenthesis).
			if source[i] == '\\' && i+1 < len(source) {
				i += 2
				continue
			}
			if source[i] == ']' {
				linkEnd = i + 1
				break
			}
			i++
		}
	} else {
		// Unexpected character after ']'. Include the ']' in the range.
		// TODO: I don't think this can happen.
		linkEnd = textEnd + 1
	}

	return linkStart, linkEnd
}

This is ugly, hacky and inefficient. It would be immensely useful if the Link AST node could include the entire Segment for its source, or at least a Start and End fields.

A previous related issue exits, but it "expired": #138

[yuin]

goldmark is designed with the goal of balancing a relatively easy-to-work-with AST and performance.

At least in v1, I do not think it will be changed to preserve the positions of all elements, because that would likely have a small performance impact.

It could be possible in the future when building v2.

By the way, I have also created another CommonMark parser called rushdown (written in Rust). Rushdown uses Rust’s flexible conditional compilation to meet your requirements. If you compile it with the inline-pos feature enabled, you can obtain the positions of all inline elements. It is also possible to get from the AST whether a link is inline, reference, or auto, and, in the case of reference links, whether it is shortcut, full, and so on.

[WhyNotHugo]

I'm not sure how to interpret this.

The README says that one of the motivations for goldmark was the need for a parser that "preserves source position of nodes".

But goldmark doesn't preserve source positions, in favour of performance?

I have also created another CommonMark parser called rushdown (written in Rust).

I have no experience using use a Rust library from a Go project. Do you have any example reference? Can it really work as a drop-in replacement, or would it require a large-scale rewrite?