repository·master·Indexed 19 days ago
https://github.com/princjef/gomarkdocA command-line tool for generating Markdown documentation from Go source code by extracting comments and structures from Go packages. It includes a formatting package with support for multiple Markdown flavors, including GitHub Flavored Markdown, Azure DevOps Markdown, and Plain Markdown, providing a consistent interface for creating headers, code blocks, accordions, and links.
To generate collapsible content in GFM, you can use the high-level Accordion method, or manually compose an accordion using AccordionHeader and AccordionTerminator if you need to render the body content independently.
Manual Composition Pattern:
accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator()func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error)
func (f *GitHubFlavoredMarkdown) AccordionHeader(title string) (string, error)
func (f *GitHubFlavoredMarkdown) AccordionTerminator() (string, error)When using the --output option with a custom template, the PackageSpec struct provides the data available to that template. This information is recomputed for every package processed.
Key fields include:
Dir: The local filesystem path where the package is located. For remote packages, this defaults to ..ImportPath: A unique representation of the package. For local packages, this matches Dir. For remote packages, this is the import string used in Go code (e.g., encoding/json).type PackageSpec struct {
// Dir holds the local path where the package is located. If the package is
// a remote package, this will always be ".".
Dir string
// ImportPath holds a representation of the package that should be unique
// for most purposes. If a package is on the filesystem, this is equivalent
// to the value of Dir. For remote packages, this holds the string used
// to import that package in code (e.g. "encoding/json").
ImportPath string
}The format package provides different implementations for emitting documentation information in various Markdown flavors.
Each format implementation provides a consistent set of formatting functions (like Bold, CodeBlock, Header, etc.), allowing you to write documentation generation logic that is decoupled from the specific Markdown dialect being used.
Note on Feature Support: While all formats share the same function signatures, not all formats support every feature natively. When a feature is not supported by a specific format, a fallback mechanism is used. Check the documentation for your specific format (e.g., AzureDevOpsMarkdown, GitHubFlavoredMarkdown, or PlainMarkdown) to understand its capabilities.
import "github.com/princjef/gomarkdoc/format"The Format interface is a generic contract for formatting documentation contents. Any implementation (like AzureDevOpsMarkdown) must provide methods for bolding, code blocks, anchors, headers, links, lists, accordions, and escaping.
type Format interface {
Bold(text string) (string, error)
CodeBlock(language, code string) (string, error)
Anchor(anchor string) string
AnchorHeader(level int, text, anchor string) (string, error)
Header(level int, text string) (string, error)
RawAnchorHeader(level int, text, anchor string) (string, error)
RawHeader(level int, text string) (string, error)
LocalHref(headerText string) (string, error)
RawLocalHref(anchor string) string
Link(text, href string) (string, error)
CodeHref(loc lang.Location) (string, error)
ListEntry(depth int, text string) (string, error)
Accordion(title, body string) (string, error)
AccordionHeader(title string) (string, error)
AccordionTerminator() (string, error)
Escape(text string) string
}The gomarkdoc command processes Go packages and generates markdown documentation. By default, it prints to stdout. You can specify an output file using the --output (or -o) flag.
Basic usage for a local package:
gomarkdoc --output doc.md .To generate documentation for all subpackages in a directory and save them to individual README.md files using a template:
gomarkdoc --output '{{.Dir}}/README.md' ./...gomarkdoc --output doc.md .You can customize how different parts of the documentation are rendered by overriding specific templates using the --template (for strings) or --template-file (for files) flags.
Available template names to override:
file: The root template for the entire generation.package: Documentation for an entire package.type: Documentation for a type and its related functions/methods.func: Documentation for a single function or method.value: Documentation for variable or constant declarations.index: The symbol index (similar to godoc.org).example: Documentation for Go examples.doc: The freeform documentation block.import: The import code block.Example using --template-file to override package and doc templates:
gomarkdoc --template-file package=custom-package.gotxt --template-file doc=custom-doc.gotxt .gomarkdoc --template-file package=custom-package.gotxt --template-file doc=custom-doc.gotxt .Use the --embed (or -e) flag to blend generated documentation with existing hand-written markdown.
If the target file exists, gomarkdoc will look for specific markers to determine where to place the content:
<!-- gomarkdoc:embed --> (replaces the whole file or appends).<!-- gomarkdoc:embed:start -->
This content is replaced with the embedded documentation
<!-- gomarkdoc:embed:end -->If no markers are found, the documentation is appended to the end of the file.
gomarkdoc -o README.md -e .To use gomarkdoc as a command-line tool, install it using go install.
For Go 1.16+:
go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latestFor older versions of Go:
GO111MODULE=on go get -u github.com/princjef/gomarkdoc/cmd/gomarkdocgo install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latestTo skip documentation generation for specific directories (e.g., test data), use the --exclude-dirs flag. You can provide multiple expressions separated by commas or use the flag multiple times. Use the same pathing syntax as package specifiers.
Example excluding a ./testData directory:
gomarkdoc --exclude-dirs ./testData/... ./...gomarkdoc --exclude-dirs ./testData/... ./...To use the formatting utilities, import the formatcore package in your Go project:
import "github.com/princjef/gomarkdoc/format/formatcore"import "github.com/princjef/gomarkdoc/format/formatcore"To ensure that documentation stays up to date with code changes, use the --check (or -c) flag in your CI pipeline. This mode compares the current output against the existing file specified by --output.
Note: --output must be specified for --check to work.
gomarkdoc -o README.md -c .gomarkdoc -o README.md -c .