Contributing to Documentation

Use this page if you want to improve ZKsync Docs. It covers small edits in the browser, larger changes in a local checkout, documentation-specific writing rules, and the checks to run before you open a pull request.

Choose how to contribute

You can contribute in two ways:

• For quick fixes, use the Edit this page link on a docs page and submit a small change in GitHub.
• For larger edits, fork the zksync-docs repository, create a branch from main, and open a pull request.

If you want to report a problem without preparing a patch, use the Share feedback link in the docs sidebar or open an issue in GitHub.

If your pull request is not ready for review yet, open it as a draft pull request.

Set up the docs locally

Follow the root README.md to install dependencies and run the site locally. The basic workflow is:

bun install
bun run dev

The local development server runs at http://localhost:3000.

For the best editing experience, use VS Code and install the recommended workspace extensions from .vscode/extensions.json.

Understand the docs structure

Most documentation changes happen in the /content directory.

• File and directory names use a two-digit numeric prefix to control navigation order.
• When you create a new directory, create 00.index.md as the landing page for that route.
• Use _dir.yml to set the navigation title for a section.
• Every page must include frontmatter with title and description.

Internal links are generated from the /content path. Do not include the numeric prefix or file extension in the URL.

Example:

[Getting Started](/zksync-network/guides/zksync-101#install-docker)

Write for documentation

Keep documentation direct, clear, and easy to scan.

• Write in active voice.
• Prefer inclusive and global language.
• Keep content focused on the reader's task.
• Use the Diataxis model to decide whether a page is a tutorial, guide, reference, or explanation.

When you add or update a page:

• Use concise headings and keep one topic per section.
• Add code fences with language identifiers.
• Keep examples short and realistic.
• Add images under public/images/ and reference them from /images/....
• Always include descriptive alt text for images.
• If spellcheck flags a valid project term, add it to the appropriate list in /cspell-config.

Use the docs toolchain

ZKsync Docs is built with Nuxt, Nuxt Content, Nuxt UI, and Tailwind.

Use standard markdown for most changes. When you need richer layouts, use the markdown component syntax supported by Nuxt Content. Components are available in markdown pages.

Example inline component syntax:

:u-icon{name="i-heroicons-light-bulb"}

If you are adding tabs, callouts, or similar structured content, check existing pages first and follow the same patterns.

Validate your changes

Before you open a pull request, run the checks that match your change.

For docs content changes, run:

bun run lint:spelling
bun run lint:markdown
bun run lint:prettier

If your change also touches code or configuration, run the full check suite:

bun run ci:check

Open the pull request

Create your branch from main and use Conventional Commits. For documentation changes, docs: is usually the right prefix.

git commit -m "docs: update contributing to documentation page"

Important: Git commits for this project should be signed with a verified signature. If you have not configured this yet, follow GitHub's guides to generate a signing key, add the key to your account, and tell Git about the key.

Need help?

If you are unsure how to structure or word a docs change, open an issue in GitHub.