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
For an example see the
connectrpc/eliza module by visiting
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
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
buf.md file is analogous to a GitHub repository's
currently supports all of the CommonMark syntax.
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.
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
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
List of options rendered in the generated documentation
Note: custom options are not rendered in the generated documentation at this time.