This is using https://pkg.go.dev/go/doc#Package.Synopsis, which returns a string rather than markdown.

I'm not convinced we should change this. Synopses are served in many places where markdown/html doesn't work. IMO it may be better to avoid it in the first sentence of a package doc. We could of course add special handling to pkgsite, but then that would be enabling a convention that is problematic for other tools.

Synopses are served in many places where markdown/html doesn't work. IMO it may be better to avoid it in the first sentence of a package doc.

That's fair enough, but is that convention documented anywhere? It's the first time I hear of a package godoc synopsis, and https://go.dev/doc/comment doesn't say anything about them or about avoiding links in them :)

@rsc suspected that this may simply be a bug in go/doc: the Synopsis function should correctly translate link syntax into plaintext, dropping the '[]'s.

The tests in src/go/doc/comment_test.go look like doc.(*Package).Synopsis already drops the [ ] but the old top-level doc.Synopsis does not, because it doesn't have accurate information about which [ ] correspond to links. Perhaps pkgsite is using the old doc.Synopsis and should migrate to doc.(*Package).Synopsis?

In pkgsite, I found

// DocInfo returns information extracted from the package's documentation.
// This destroys p's AST; do not call any methods of p after it returns.
func (p *Package) DocInfo(ctx context.Context, innerPath string, sourceInfo *source.Info, modInfo *ModuleInfo) (
	synopsis string, imports []string, api []*internal.Symbol, err error) {
	// This is mostly copied from internal/fetch/fetch.go.
	defer derrors.Wrap(&err, "godoc.Package.DocInfo(%q, %q, %q)", modInfo.ModulePath, modInfo.ResolvedVersion, innerPath)

	p.renderCalled = true
	d, err := p.docPackage(innerPath, modInfo)
	if err != nil {
		return "", nil, nil, err
	}

	api, err = dochtml.GetSymbols(d, p.Fset)
	if err != nil {
		return "", nil, nil, err
	}
	return doc.Synopsis(d.Doc), cleanImports(d.Imports, d.ImportPath), api, nil
}

It looks like doc.Synopsis(d.Doc) should be d.Synopsis(d.Doc).

@rsc thanks for looking into it. That looks right.

Want to send a CL, or shall I?

I'll leave the CL to you - it'll get done faster. Thanks.

@findleyr Did this get fixed?

@dolmen no changes since 2021 https://github.com/golang/pkgsite/blame/f26e1ab5cf5bf4cbc49868e8ff3e37b54bc89acb/internal/godoc/render.go#L59