Docusaurus Project Generator with Protobuffet Preset

Visit the landing page for Protobuffet documentation.

Executable project generator based on create-docusaurus. This generator enhances the common template by also initializing the @akurdyukov/docusaurus-protobuffet preset with recommended options and sample fixtures.

See @akurdyukov/docusaurus-protobuffet for details on this preset.

See Docusaurus docs for details on the common template.

Compatibility

| Version | Docusaurus | React | Node.js | |---------|-----------|-------|---------| | 1.x | 3.9+ | 18+ | 18+ | | 0.x | 2.x | 17 | 14+ |

Usage

This package scaffolds a new Docusaurus project with the @akurdyukov/docusaurus-protobuffet preset pre-configured. If you already have an existing Docusaurus project, use @akurdyukov/docusaurus-protobuffet directly instead.

Requirements: Node.js 18+, npm 9+

Registry Setup

This package is published to the GitHub npm registry. Configure npm to use it for the @akurdyukov scope by adding the following to an .npmrc file in your project directory or home directory (~/.npmrc):

@akurdyukov:registry=https://npm.pkg.github.com

If the repository is private, you also need to authenticate. Create a GitHub personal access token with read:packages scope and add it:

//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Quick Start

Run the generator from the parent directory where you want the project created:

npx @akurdyukov/docusaurus-protobuffet-init@1 init <project_name>

This will:

1. Scaffold a Docusaurus project using create-docusaurus with the classic template
2. Install @akurdyukov/docusaurus-protobuffet and @easyops-cn/docusaurus-search-local
3. Copy Protobuffet config, sample fixtures, and landing page templates
4. Run generate-proto-docs to generate documentation from the sample fixtures

Once complete, start the development server:

cd <project_name>
npm run start

Regenerating Proto Docs

Whenever you update the fileDescriptorsPath file (defaults to ./fixtures/proto_workspace.json), regenerate the documentation:

npx docusaurus generate-proto-docs

See the @akurdyukov/docusaurus-protobuffet CLI documentation for details.

Deployment

This is a standard Docusaurus project. Follow the Docusaurus deployment docs for production builds and hosting.

Configuration

The default setup configures fileDescriptorsPath to ./fixtures/proto_workspace.json. You can override this with your own Protobuf workspace file or update the options passed to @akurdyukov/docusaurus-protobuffet within your docusaurus.config.js file. Please see @akurdyukov/docusaurus-protobuffet documentation for details.

The navbar configuration within docusaurus.config.js points to one of the generated files of the sample fixture. You will need to update this route when using your own Protobuf workspace file.

Contributing

Contributions, issues and feature requests are always welcome!