{"_id":"@akurdyukov/docusaurus-protobuffet","name":"@akurdyukov/docusaurus-protobuffet","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@akurdyukov/docusaurus-protobuffet","version":"1.0.0","description":"Protobuf documentation toolset for Docusaurus","repository":{"type":"git","url":"git+https://github.com/akurdyukov/docusaurus-protobuffet.git"},"homepage":"https://github.com/akurdyukov/docusaurus-protobuffet/tree/master/packages/docusaurus-protobuffet","keywords":["docusaurus","protobuf","documentation","api","protocol buffers","grpc","microservices","markdown","mdx"],"engines":{"node":">=18.0.0"},"main":"dist/index.js","scripts":{"build":"tsc","test":"echo \"Error: no test specified\" && exit 1"},"author":{"name":"Anthony Bobsin"},"license":"ISC","dependencies":{"@akurdyukov/docusaurus-protobuffet-plugin":"^1.0.0"},"devDependencies":{"@docusaurus/types":"^3.9.2"},"publishConfig":{"access":"public"},"gitHead":"13ea1a31c27835bb08f903dd9fb7ad8fe51066bf","_id":"@akurdyukov/docusaurus-protobuffet@1.0.0","bugs":{"url":"https://github.com/akurdyukov/docusaurus-protobuffet/issues"},"_nodeVersion":"24.12.0","_npmVersion":"lerna/9.0.3/node@v24.12.0+arm64 (darwin)","dist":{"integrity":"sha512-vAJblqdyHz9LHJ0bjnhv+hKAMx4FIK6DnOjPmy8K+GQL7uxYxYYd5TR3Mp1yO3n6IJAjJGRjS7lSXrQh5X6x4A==","shasum":"58647ad8bcdada55e8d53dfae9346a8fd978b203","tarball":"https://registry.npmjs.org/@akurdyukov/docusaurus-protobuffet/-/docusaurus-protobuffet-1.0.0.tgz","fileCount":6,"unpackedSize":12469,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBuhrykHHfMEqrmIJdcFqu5fOEE45Q2HHJ3OPCupFaPAAiEA/ccOy0W+b7HmdhF7b0o56XCjVZWz29Y/cKi+5ZcUawQ="}]},"_npmUser":{"name":"akurdyukov","email":"akurdyukov@gmail.com"},"directories":{},"maintainers":[{"name":"akurdyukov","email":"akurdyukov@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/docusaurus-protobuffet_1.0.0_1770673826632_0.6642599448498112"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-09T21:50:26.577Z","1.0.0":"2026-02-09T21:50:26.787Z","modified":"2026-02-09T21:50:26.956Z"},"maintainers":[{"name":"akurdyukov","email":"akurdyukov@gmail.com"}],"description":"Protobuf documentation toolset for Docusaurus","homepage":"https://github.com/akurdyukov/docusaurus-protobuffet/tree/master/packages/docusaurus-protobuffet","keywords":["docusaurus","protobuf","documentation","api","protocol buffers","grpc","microservices","markdown","mdx"],"repository":{"type":"git","url":"git+https://github.com/akurdyukov/docusaurus-protobuffet.git"},"author":{"name":"Anthony Bobsin"},"bugs":{"url":"https://github.com/akurdyukov/docusaurus-protobuffet/issues"},"license":"ISC","readme":"# Docusaurus Protobuf Toolset\n\n#### Visit the [landing page](https://protobuffet.com/) for Protobuffet documentation.\n\n[Docusaurus](https://docusaurus.io/) toolset for Protobuf contract documentation. Provides a set of components and MDX doc file generators for Docusaurus sites.\n\n## Compatibility\n\n| Version | Docusaurus | React | Node.js |\n|---------|-----------|-------|---------|\n| 1.x     | 3.9+      | 18+   | 18+     |\n| 0.x     | 2.x       | 17    | 14+     |\n\nFor upgrading from 0.x to 1.x, see the [migration guide](../../MIGRATION.md).\n\n![Protodocs Overview](../../screenshots/overview.png)\n\n---\n\n## Installation\n\nThis section assumes an existing Docusaurus project. For those without an existing setup, you can use [`@akurdyukov/docusaurus-protobuffet-init`](https://github.com/akurdyukov/docusaurus-protobuffet/tree/master/packages/docusaurus-protobuffet-init#usage) to scaffold a Docusaurus project with this preset installed.\n\nNOTE: These commands should be run from your Docusaurus project directory.\n\nInstall this preset.\n\n```sh\nnpm install --save @akurdyukov/docusaurus-protobuffet\n```\n\nGenerate a JSON representation of your Protobuf files. This depends on the [`protoc-gen-doc`](https://github.com/pseudomuto/protoc-gen-doc) compiler plugin. Find details and installation steps in the [usage section](#generating-the-filedescriptorspath-file).\n\n```sh\nprotoc --doc_out=./fixtures --doc_opt=json,proto_workspace.json --proto_path=protos protos/**/*.proto\n```\n\nAdd the preset to your project's `docusaurus.config.js` file. View the [configuration section](#configuration) for all available options.\n\n```js\n// file: docusaurus.config.js\nmodule.exports = {\n  // ...\n  presets: [\n    [\n      '@akurdyukov/docusaurus-protobuffet',\n      {\n        protobuffet: {\n          fileDescriptorsPath: './fixtures/proto_workspace.json'\n        }\n      }\n    ]\n  ],\n  // ...\n}\n```\n\nInvoke the CLI command [`generate-proto-docs`](#generate-proto-docs) to generate your MDX doc files.\n\n```sh\nnpx docusaurus generate-proto-docs\n```\n\nUpdate your `docusaurus.config.js` to link to your new documentation from the navbar. You will need to configure one of the generated doc files as the route. A homepage will be introduced to replace this in the future.\n\n```js\n// file: docusaurus.config.js\nmodule.exports = {\n  themeConfig: {\n    navbar: {\n      items: [\n        // ...\n        {\n          to: 'protodocs/Booking.proto',\n          activeBasePath: 'protodocs',\n          label: 'Protodocs',\n          position: 'left',\n        }\n        // ...\n      ]\n    }\n  }\n}\n```\n\nBoot up your Docusaurus server to view the new Protobuf documentation space.\n\n```sh\nnpm run start\n```\n\n---\n\n##  Configuration\n\n```js\n// file: docusaurus.config.js\nmodule.exports = {\n  // ...\n  presets: [\n    [\n      '@akurdyukov/docusaurus-protobuffet',\n      {\n        protobuffet: {\n          fileDescriptorsPath: './fixtures/proto_workspace.json',\n          protoDocsPath: './protodocs',\n          sidebarPath: './generatedSidebarsProtodocs.js'\n        },\n        docs: {\n          routeBasePath: 'protodocs',\n          sidebarPath: './sidebarsProtodocs.js',\n        }\n      }\n    ]\n  ],\n  // ...\n}\n```\n\n#### `protobuffet`\nPass in all plugin options. See [`@akurdyukov/docusaurus-protobuffet-plugin`](https://github.com/akurdyukov/docusaurus-protobuffet/tree/master/packages/docusaurus-protobuffet-plugin) for the plugin library. This preset assigns some recommended defaults for missing options.\n\n| Option | Description | Required | Default |\n| --- | --- | --- | --- |\n| `fileDescriptorsPath` | Path to JSON file containing generated proto documentation through [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc). See [usage section](#generating-the-filedescriptorspath-file) for details. | ✅ | N/A |\n| `protoDocsPath` | Directory where CLI will create doc files. |  | `./protodocs` |\n| `sidebarPath` | Path to file where CLI will write the generated Sidebar object. |  | `./sidebarsProtodocs.js` |\n---\n\n#### `docs`\nPass in options for the [`@docusaurus/plugin-content-docs`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs) plugin. This preset assigns some recommended defaults for missing options.\n\n| Option | Description | Required | Default |\n| --- | --- | --- | --- |\n| `routeBasePath` | URL base route for the Protobuffet docs section of your site. |  | `protodocs` |\n| `sidebarPath` | Path to file where docs plugin will read the Sidebar object. |  | `./sidebarsProtodocs.js` |\n---\n\n## Usage\n\nThis toolset provides a suite of CLI commands to generate and manage documentation files for your Protobuf workspace. These generated files follow the Docusaurus convention of using MDX files and React components.\n\n### CLI Commands\n\n#### generate-proto-docs\n\n```sh\nnpx docusaurus generate-proto-docs\n```\n\nGenerate documentation for all Protobuf files within the configured `fileDescriptorsPath` JSON file. The generated files are written to `protoDocsPath`. A sidebar object is written to the configured `sidebarPath`. View the [configuration section](#configuration) for details of these options.\n\nThis command must be run for every content change of `fileDescriptorsPath`. This will overwrite all previously generated files, so they should not be modified manually. Extension support for these generated files will be coming in the future, so please reach out with your use cases.\n\nYou can view some [generated doc files in the landing page](https://github.com/akurdyukov/docusaurus-protobuffet/tree/master/website/protodocs).\n\n### Generating the `fileDescriptorsPath` File\nThis project depends on a snapshot of all the files within your Protobuf workspace. The formatting and generation of this snapshot currently depends on the [`protoc-gen-doc`](https://github.com/pseudomuto/protoc-gen-doc) Protobuf compiler plugin. `protoc-gen-doc` can generate a JSON representation of your Protobuf files, which we parse to build an enhanced view of your documentation.\n\nTo use `protoc-gen-doc` we must install golang and protoc. These are already common dependencies when working with Protobuf files, but I'm happy to investigate alternatives if we decide this is a barrier for users.\n\n```sh\n# install protoc. change for your OS as necessary.\nbrew install protobuf\n\n# install protoc-gen-doc. this depends on golang.\ngo get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc\n\n# use protoc to generate the JSON representation of your Protobuf workspace.\nprotoc --doc_out=./fixtures --doc_opt=json,proto_workspace.json --proto_path=protos protos/**/*.proto\n```\n\n### Recommended Extensions\n\n#### [`docusaurus-search-local`](https://github.com/easyops-cn/docusaurus-search-local)\n\nThis plugin enables search bar functionality based on a generated local index of your Protobuf documentation. It depends on `@docusaurus/preset-classic` or any preset that leverages the `@theme/SearchBar` component. You can read more about how Docusaurus handles search [here](https://docusaurus.io/docs/search).\n\nThis must be installed within your project, so add the plugin to your `docusaurus.config.js` file. Make sure `docsRouteBasePath` and `docsDir` are configured to match your `protoDocsPath` option.\n\nFor Docusaurus 3.x, use `@easyops-cn/docusaurus-search-local` version `^0.54.0` or later.\n\n```js\n// file: docusaurus.config.js\nmodule.exports = {\n  // ...\n  plugins: [\n    [\n      require.resolve(\"@easyops-cn/docusaurus-search-local\"),\n      {\n        hashed: true,\n        docsRouteBasePath: 'protodocs',\n        docsDir: 'protodocs',\n        indexBlog: false,\n      },\n    ]\n  ],\n}\n```\n\n---\n\n## Contributing\n\nContributions, issues and feature requests are always welcome!\n","readmeFilename":"README.md","_rev":"1-4e8cf6ac6a415077269c22a6d526f8bb"}