An asciidoctor extension that adds support for a godoc macro. The macro allows you to reference types and functions in a Go package by name, and links to their documentation on pkg.go.dev.

For example, given the following:

Input
The godoc:http[] package provides
godoc:net/http#ServeMux[] for request routing.
Register zero or more godoc:net/http#Handler[handlers] against it,
and specify it as a godoc:net/http#Server.Handler[]
in your server's configuration.
Output

The http package provides http.ServeMux for request routing. Register zero or more handlers against it, and specify it as a Server.Handler in your server’s configuration.

Installation

With Bundler

To install the extension with bundler, add the following to your Gemfile.

Gemfile
gem 'asciidoctor-godoc'

Then run the following command:

$ bundle install

With gem

To install the extension with the gem command, run the following:

$ gem install asciidoctor-godoc

Usage

You may use the extension with the asciidoctor CLI or as a library.

CLI

To use with the asciidoctor CLI, request the module with -r.

$ asciidoctor -r asciidoctor-godoc mydoc.adoc

Library

To use the extension as a library, require asciidoctor/godoc. This will register the extension with asciidoctor.

Use via API
require 'asciidoctor'
require 'asciidoctor/godoc'

Asciidoctor.convert_file 'mydoc.adoc'

If you don’t want the extension automatically registered, import the inline macro implementation manually from asciidoctor/godoc/inline_macro.

Use with a scoped registry
require 'asciidoctor/extensions'
require 'asciidoctor/godoc/inline_macro'

registry = Asciidoctor::Extensions.create
registry.inline_macro Asciidoctor::Godoc::InlineMacro
Asciidoctor.convert_file 'mydoc.adoc', extension_registry: registry

Syntax

The inline macro supports the following formats:

godoc:$importPath[$display] (1)
godoc:$importPath#$name[$display] (2)
godoc:$importPath#$name.$child[$display] (3)
1 Package reference
2 Top-level entity reference
3 Entity child reference

Where each of the $-variables are:

importPath

full import path of a Go package
name

name of a type or function defined in that package
subname

name of a method or field if $name references a type
display

text to display — leave this empty for a default value

If $display is empty, asciidoctor-godoc fills in a default value for it based on the format used.

Format Default $display

$display

$importPath

$display

$packageName.$name [1]

1. This isn’t always accurate. See Specifying package names.

$display

$name.$child
The default $display is an inline literal (`…​`) for all forms except the package reference format.
Table 1. Examples
Input Output 
Check out the godoc:net/http[] package

Check out the net/http package

 
For more, click godoc:bytes[here].

For more, click here.

 
Use godoc:encoding/json#Unmarshal[] to parse JSON.

Use json.Unmarshal to parse JSON.

 
Use a godoc:encoding/json#Decoder[decoder] to parse JSON from a stream.

Use a decoder to parse JSON from a stream.

 
Set godoc:net/http#Server.Handler[] to your preferred handler.

Set Server.Handler to your preferred handler.

 
Pass in the godoc:net/http#Request.Context[request context].

Pass in the request context.

Specifying package names

When using the top-level entity format without display text, e.g. http.ServeMux, the extension includes the name of the Go package in the generated text, e.g. http.ServeMux.

The name of the package is assumed to be the last component of the import path.

Import path Assumed package name

github.com/golang/mock/gomock

gomock

net/http

http

gopkg.in/yaml.v3

yaml.v3 (oops!)

example.com/client-go

client-go (oops!)

As evident by the third and fourth cases, our guess isn’t always correct.

To work around this, the extension supports providing import path to package name mappings with the gopkgs attribute. The value of the attribute should be a ;-separated collection of $importPath = $packageName mappings.

= My document
:gopkgs: gopkg.in/yaml.v3 = yaml; example.com/client-go = client

Split these across multiple lines by escaping newlines:

= My document
:gopkgs: gopkg.in/yaml.v3 = yaml; \
         example.com/client-go = client

For import paths specified in this mapping, the extension will prefer the provided package name.

License

This software is available as open source under the terms of the MIT License.