markup/goldmark: Enhance footnote extension with auto-prefixing option

[jmooring]

This commit introduces a new option, enableAutoIDPrefix, to the Goldmark footnote extension. When enabled, it prepends a unique prefix to footnote IDs, preventing clashes when multiple documents are rendered together. This prefix is unique to each logical path, which means that the prefix is not unique across content dimensions such as language. This change also refactors the extension's configuration from a boolean to a struct.

Closes #8045

[jmooring]

I was initially concerned that the footnote links would change if the page path changed, as the document ID is derived from it. However, I realized this is already the case whenever you insert a new footnote before an existing one—the numbering shifts, and the links change. Given that content changes are much more frequent than path changes, I believe this is an acceptable trade-off.

And how often does one link to a footnote in another document? Never, or close to it.

[bep]

And how often does one link to a footnote in another document? Never, or close to it.

I have never seen it.

[jmooring]

Pages created via content adapters will have the same file ID (I assume)

I have verified that this is true and will add some test cases.

[jmooring]

creates a new ID

I have done this, and everything works fine, but having two IDs in the converter.DocumentContext struct isn't satisfying. Can we leave the f.UniqueID method as is, and simply change how DocumentID is set? For example, change this:

var id string
var filename string
var path string
if p.f != nil {
    id = p.f.UniqueID()
    filename = p.f.Filename()
    path = p.f.Path()
} else {
    path = p.Path()
}

cpp, err := cp.New(
    converter.DocumentContext{
	    Document:       doc,
	    DocumentLookup: documentLookup,
	    DocumentID:     id,
	    DocumentName:   path,
	    Filename:       filename,
    },
)

to this

var filename string
var path string
if p.f != nil {
    filename = p.f.Filename()
    path = p.f.Path()
} else {
   path = p.Path()
}

cpp, err := cp.New(
    converter.DocumentContext{
	    Document:       doc,
	    DocumentLookup: documentLookup,
	    DocumentID:     hashing.XxHashFromStringHexEncoded(p.Path()),
	    DocumentName:   path,
	    Filename:       filename,
    },
)

As you noted, DocumentID doesn't appear to be used anywhere, so it seems like changing its derivation should not be a problem.

[jmooring]

@bep Please see my previous comment when you have a moment.

[bep]

to this

Yes, that was how I imagined it in tthe first place, so please do.