https://github.com/matze/protoc-gen-mdbook

protoc plugin to generate mdBook pages
https://github.com/matze/protoc-gen-mdbook

mdbook protobuf protoc rust

Last synced: 7 months ago
JSON representation

protoc plugin to generate mdBook pages

• Host: GitHub
• URL: https://github.com/matze/protoc-gen-mdbook
• Owner: matze
• License: mit
• Created: 2022-12-13T21:29:38.000Z (almost 3 years ago)
• Default Branch: master
• Last Pushed: 2024-01-11T21:51:16.000Z (almost 2 years ago)
• Last Synced: 2025-02-09T13:41:57.880Z (8 months ago)
• Topics: mdbook, protobuf, protoc, rust
• Language: Rust
• Homepage:
• Size: 71.3 KB
• Stars: 2
• Watchers: 2
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# protoc-gen-mdbook

A protoc plugin to generate [mdBook](https://rust-lang.github.io/mdBook/) pages

documenting services and related messages.

## Build

Install a recent Rust toolchain and build the binary with

    $ cargo b --release

## Usage

Like every protoc plugin, `protoc-gen-mdbook` must be in your `PATH` and can be

called by passing the `mdbook_out` parameter. Hence you can render Markdown

pages with

    $ protoc --mdbook_out=. path/to/*.proto

Note that you need a custom version of [highlight.js](https://highlightjs.org)

that includes support for protocol buffers if you want the rendered message

types to be syntax highlighted.

## Options

You can control the output behavior of `protoc-gen-mdbook` using `mdbook_opt`

option passed to `protoc` driver. The option is a comma-separated list of

key-value pairs separated by a colon. The following keys are understood:

* `output`: a filename for the entire output. If not set, multiple files will be

  generated.

* `optimize`: right now can be `doxygen` to optimize for inclusion in Doxygen

  Markdown documentation, most importantly to fix header links. All other values

  are ignored.

A call to output to a single file optimized for Doxygen would look like this:

    $ protoc --mdbook_out=. --mdbook_opt=output:single.md,optimize:doxygen path/to/*.proto