The BSR comes with complete documentation for your Protobuf files through a browsable UI with syntax highlighting, one click navigation between definitions and references. Every push to the BSR generates documentation. You may browse the documentation section of a repository by navigating to the Docs tab.

For an example see the bufbuild/eliza module by visiting https://buf.build/bufbuild/eliza.

Module documentation

Most documentation comes directly from comments associated with your Protobuf definitions. But there also needs to be a way for authors to describe their module for others to understand its functionality.

To accomplish this, you add a buf.md file to the same directory as your module's buf.yaml file and push it to the BSR like normal. Since documentation is part of your module, any updates to your buf.md result in new commits in the BSR.

The buf.md file is analogous to a GitHub repository's README.md and currently supports all of the CommonMark syntax.

Package documentation

The package level documentation provides Protobuf type definitions and comments for all package files. Clicking through the type definitions takes you to the referenced item.

You can quickly navigate from the docs to the Protobuf file by clicking the filename on the right-hand side.

Each type definition has a unique placeholder within the page, an anchor tag, enabling you to share links to the exact item.

Package description

When sharing packages it is often useful to provide an overview of the package. You can do so by adding comments above the package directive in your .proto file.

Comments on the package directive are not merged across files. Files are parsed alphabetically, and only the first file with a non-empty comment is displayed in the generated documentation.

Annotated Protobuf options

The generated documentation renders annotated Protobuf options. A list of options has been selected for rendering at this time. Not all options are included in the generated documentation.

You can find the complete list of Protobuf's built-in options available in the descriptor.proto.

List of options rendered in the generated documentation:

Message Options

• deprecated

Field options

• deprecated
• packed
• ctype
• jstype

Enum options

• allow_alias
• deprecated

EnumValue options

• deprecated

Service options

• deprecated

Method options

• deprecated
• idempotency_level

Note: custom options are not rendered in the generated documentation at this time.