Contribution Guidelines

Fork the project

Make a fork of the zksync-docs project and create your branches from the default main branch.

If your PR is still a work in progress, consider putting it into a Draft status. Once your PR is ready for review, switch it back to an active PR request and any reviewers already attached will automatically get a notification.

Commit conventions

This project uses Conventional Commits standards. For changes that are code related, use the chore:, fix:, feat:, or docs: tags in your commits.

• chore tagged commits will not create a release. Use for changes that do not directly affect the end user.
• fix commits will create a patch release.
• feat commits will create a minor release.
• docs commits will create a minor release. Use for typo fixes or document related changes.

git commit -m "docs: fix typo in guide"

Signed git commits

Your git commits need to be signed with a verified signature.

1. Follow the instructions to generate a signing key.
2. Add the key to your GitHub account.
3. Tell git about your signing key.

Contribution workflow

To set up and run the project locally, consult the root README.md file.

Use VSCode

To take full advantage of linting and formatting features, it is highly recommended to use VSCode and install the recommended extensions. To manually install the recommended extensions, go to the Extensions tab in VSCode and search for @recommended.

What the project uses

ZKsync docs is built with Vue and Nuxt framework, utilizing various Nuxt Modules for content development. Familiarize yourself with their documentation to provide you with the full capability of contributing.

Nuxt

Nuxt is a Vue framework for building applications. Visit the Nuxt documentation for an introduction to its structure and development process.

Debugging with Nuxt

Use Nuxt's DevTools for debugging. A button with the Nuxt icon appears at the bottom center of the viewport when running locally, opening a helpful panel.

Nuxt Content

Nuxt Content allows building with markdown files in a /content folder. It supports Common Markdown with additional features.

A VSCode extension is recommended for proper syntax highlighting and is included in the workspace list of recommended plugins to install.

Navigation of markdown files is automatically generated according to a naming scheme that uses numbering to order pages. We use a double digit numbering scheme.

Using Vue Components in markdown

Vue components can be used within markdown files, although their syntax is different. Components placed in the /components/content are automatically imported for use in markdown files in /content. Refer to the Nuxt Content page on Vue components section to learn how the Vue markdown syntax works.

Nuxt UI

Nuxt UI along with Nuxt UI Pro are available to build UI.

While Nuxt UI components are a part of the project, they need to be configured in nuxt.config.ts to make them available in /content markdown files. See the current configuration to discover what components are already loaded.

Local development messages regarding NUXT_UI_PRO_LICENSE can be ignored, it will not affect local development and testing.

Styling

Styling relies on Nuxt UI and Tailwind. Adhere to Tailwind's Utility-First Fundamentals, avoiding custom styles in components with the use of the @apply feature.