diff --git a/NUXT_README.md b/NUXT_README.md deleted file mode 100644 index f90638e4..00000000 --- a/NUXT_README.md +++ /dev/null @@ -1,126 +0,0 @@ -![nuxt-ui-docs-social-card](https://github.com/nuxt-ui-pro/docs/assets/739984/f64e13d9-9ae0-4e03-bf7f-6be4c36cd9ba) - -# Nuxt UI Pro - Docs template - -[![Nuxt UI Pro](https://img.shields.io/badge/Made%20with-Nuxt%20UI%20Pro-00DC82?logo=nuxt.js&labelColor=020420)](https://ui.nuxt.com/pro) -[![Nuxt Studio](https://img.shields.io/badge/Open%20in%20Nuxt%20Studio-18181B?&logo=nuxt.js&logoColor=3BB5EC)](https://nuxt.studio/themes/docs) - -- [Live demo](https://docs-template.nuxt.dev/) -- [Play on Stackblitz](https://stackblitz.com/github/nuxt-ui-pro/docs) -- [Documentation](https://ui.nuxt.com/pro/getting-started) -- [Clone on Nuxt Studio](https://nuxt.studio/themes/docs) - -## Quick Start - -```bash [Terminal] -npx nuxi init -t github:nuxt-ui-pro/docs -``` - -## Setup - -Make sure to install the dependencies: - -```bash -# npm -npm install - -# pnpm -pnpm install - -# yarn -yarn install - -# bun -bun install -``` - -## Development Server - -Start the development server on `http://localhost:3000`: - -```bash -# npm -npm run dev - -# pnpm -pnpm run dev - -# yarn -yarn dev - -# bun -bun run dev -``` - -## Production - -Build the application for production: - -```bash -# npm -npm run build - -# pnpm -pnpm run build - -# yarn -yarn build - -# bun -bun run build -``` - -Locally preview production build: - -```bash -# npm -npm run preview - -# pnpm -pnpm run preview - -# yarn -yarn preview - -# bun -bun run preview -``` - -Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information. - -## Nuxt Studio integration - -Add `@nuxthq/studio` dependency to your package.json: - -```bash -# npm -npm install --save-dev @nuxthq/studio - -# pnpm -pnpm add -D @nuxthq/studio - -# yarn -yarn add -D @nuxthq/studio - -# bun -bun add -d @nuxthq/studio -``` - -Add this module to your `nuxt.config.ts`: - -```ts -export default defineNuxtConfig({ - ... - modules: [ - ... - '@nuxthq/studio' - ] -}) -``` - -Read more on [Nuxt Studio docs](https://nuxt.studio/docs/projects/setup). - -## Renovate integration - -Install [Renovate GitHub app](https://github.com/apps/renovate/installations/select_target) on your repository and you -are good to go. diff --git a/README.md b/README.md index 105dbb92..361d3fbb 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,16 @@ Welcome to the ZK Sync Docs repository. This project serves as the community hub documentation for developers. Whether you're a beginner looking to get started with zkSync or an experienced developer seeking advanced guides, you'll find the resources you need here. -## Setup +## Tools used + +- [Vue](https://vuejs.org/) +- [Nuxt](https://nuxt.com/) +- [Nuxt Content](https://content.nuxt.com/) +- [Nuxt UI & Nuxt UI Pro](https://ui.nuxt.com/) +- [Tailwind](https://tailwindcss.com/) +- [Bun](https://bun.sh/) + +## Local Setup This project uses bun to run, follow the [bun installation instructions](https://bun.sh/docs/installation). Once bun is installed, run the following command to install all project dependencies: @@ -21,12 +30,6 @@ To run the project locally at `http://localhost:3000` bun run dev -o ``` -## Production - -```shell -bun run build -``` - ## Local Preview To locally preview the production build: @@ -56,3 +59,12 @@ The following commands are available to run linting on the project: bun run lint:prettier bun run lint:eslint ``` + +## Contributions + +We welcome contributions from the community to zkSync Docs. +If you're looking for ideas on where to start with contributing, check out the [Contribution Overview](./content/90.contributing-to-documentation/10.index.md). +To learn more on how to follow best practices when contributing to zkSync Docs, +refer to the [Contribution Guidelines](./content/90.contributing-to-documentation/20.contribution-guidelines.md). +If you are writing new content to add to the docs, the [Documentation Styleguide](./content/90.contributing-to-documentation/30.documentation-styleguide.md) +can provide additional guidance. diff --git a/app.config.ts b/app.config.ts index efab2003..5967e974 100644 --- a/app.config.ts +++ b/app.config.ts @@ -36,6 +36,11 @@ export default defineAppConfig({ }, }, }, + 'navigation-accordion': { + button: { + label: 'text-sm/6 font-semibold text-left text-pretty', + }, + }, }, seo: { siteName: 'zkSync Docs', @@ -91,8 +96,9 @@ export default defineAppConfig({ toc: { title: 'Table of Contents', bottom: { - title: 'Community', - edit: 'https://github.com/matter-labs/zksync-docs/edit/main/content', + title: '', + edit: 'https://github.com/matter-labs/zksync-docs/edit/staging/content', + feedback: 'https://github.com/matter-labs/zksync-docs/issues/new?labels=documentation', links: [ // { // icon: 'i-heroicons-star', diff --git a/components/content/ExternalLink.vue b/components/content/ExternalLink.vue new file mode 100644 index 00000000..7d6bb4d5 --- /dev/null +++ b/components/content/ExternalLink.vue @@ -0,0 +1,30 @@ + + + diff --git a/content/90.contributing-to-documentation/10.index.md b/content/90.contributing-to-documentation/10.index.md new file mode 100644 index 00000000..15d8043c --- /dev/null +++ b/content/90.contributing-to-documentation/10.index.md @@ -0,0 +1,51 @@ +--- +title: Overview +description: Explore how to contribute to zkSync's open-source projects and community. +--- + +zkSync is an open-source project. We champion community-driven development, which means you, +from any corner of the world, can contribute to shaping zkSync's future. + +This section outlines how you can enhance our documentation, engage with the zkSync community, +and contribute to our other open-source projects. + +### Edit Existing Content + +We welcome your edits to any content on the zkSync Docs website. To contribute changes, +you will need a [GitHub account](https://github.com/signup). + +For minor edits, use the "Edit this page" link found on pages within the Table of Contents on the right side of the page. + +To suggest changes without directly editing, submit a GitHub issue via the "Share feedback" link, +also located in the Table of Contents sidebar. + +The best way to contribute is by [forking the zkSync-docs repo](https://github.com/matter-labs/zksync-docs/fork), +making changes in a branch, and then submitting a PR. +To start, follow the README in the project repo and read the [Contribution Guidelines](/contributing-to-documentation/contribution-guidelines) +to familiarize yourself with the project structure and the documentation editing workflow. + +### Write New Content + +For the best experience in creating new content, [fork our zkSync-docs project](https://github.com/matter-labs/zksync-docs/fork) +and set up a local project on your machine. If you are unfamiliar with the forking workflow, you can learn more about it +from [GitHub's articles on Forking](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks). + +As you write new content, please adhere to our +[Contribution Guidelines](/contributing-to-documentation/contribution-guidelines) +and consult the [Documentation Style Guide](/contributing-to-documentation/documentation-styleguide) +to maintain consistency across our documentation. + +### Submit a Community Tutorial or Guide + +The zkSync-docs project primarily focuses on documentation that helps readers understand zkSync and develop in the ecosystem. +If your guide or tutorial includes using another tool or service with zkSync, consider submitting it to our Community content. +These documents, while adjacent to our technical documentation, are hosted in a separate project repo on GitHub. + +### Showcase Your Projects Built on zkSync + +We're excited to see new projects developed by our community within the zkSync ecosystem! +If you've released a project recently, we'd love to hear about it. +Our [zkSync Community Hub Discussions](https://github.com/zkSync-Community-Hub/zksync-developers) +has a section where you can +[submit your project](https://github.com/zkSync-Community-Hub/zksync-developers/discussions/new?category=show-and-tell) +for the community to discover. diff --git a/content/90.contributing-to-documentation/20.contribution-guidelines.md b/content/90.contributing-to-documentation/20.contribution-guidelines.md new file mode 100644 index 00000000..b83f0426 --- /dev/null +++ b/content/90.contributing-to-documentation/20.contribution-guidelines.md @@ -0,0 +1,90 @@ +--- +title: Contribution Guidelines +description: Learn how to contribute to zkSync Docs +--- + +## Environments + +**Production**: Visit :external-link{text="zkSync Docs" href="https://docs.zksync.io/"} for official documentation. + +**Staging**: Test and preview changes on the +:external-link{text="zkSync Docs Staging" href="https://zksync-docs-staging-5eb09.web.app/"} environment. + +## Git workflow + +- The `main` branch reflects the current production state. +- The `staging` branch is for previews in the staging environment. +- Contributors submit feature branches as PRs to the `staging` branch. + +## Contribution workflow + +To set up and run the project locally, consult the root [`README.md`](https://github.com/matter-labs/zksync-docs) file. + +### Tracking work + +Start your work by creating an :external-link{text="issue" href="https://github.com/matter-labs/zksync-docs/issues"} +in the repo to prevent overlap and keep track of contributions. +Use the `[DOC]` tag for content edits or `[BUG]` for fixes. +Connect your PR to the created issue following the :external-link{text="GitHub guide on linking" href="https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue"}. + +Submit your PR against the `staging` branch. + +## What the project uses + +zkSync docs is built with Vue and Nuxt framework, utilizing Nuxt Modules for content development. +Familiarize yourself with Nuxt and review documentation for primary plugins. + +### Nuxt + +Nuxt is a Vue framework for building applications. +Visit the :external-link{text="Nuxt documentation" href="https://nuxt.com/docs/getting-started/introduction"} +for an introduction to its structure and development process. + +Creating new landing pages involves adding a new component in the `/pages` directory, +though most documentation work will focus on using Nuxt Content. + +#### Debugging with Nuxt + +Use Nuxt's :external-link{text="DevTools" href="https://devtools.nuxt.com/"} for debugging. +A button with the Nuxt icon :u-icon{name="i-simple-icons-nuxtdotjs"} +appears at the bottom center of the viewport when running locally, opening a helpful panel. + +![Nuxt DevTools](/images/nuxt-debugger.png) + +### Nuxt Content + +Nuxt Content allows building with markdown files in a `/content` folder. +It supports :external-link{text="Common Markdown with additional features" href="https://content.nuxt.com/usage/markdown"}. + +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 :external-link{text="naming scheme" href="https://content.nuxt.com/usage/content-directory"} +that uses numbering to order pages. We use a double digit numbering scheme. + +#### Using Vue Components in MDC + +Vue components can be used within markdown files, identified with `::`. +For custom Vue components in documentation, place them in `/components/content`. +Components in this directory are automatically imported for use in markdown content. +Refer to the :external-link{text="Vue components section" href="https://content.nuxt.com/usage/markdown#vue-components"} +to learn how the Vue markdown syntax works. + +Vue components that are not within the `/components/content` directory +need to be globally configured to use in markdown content. + +### Nuxt UI + +:external-link{text="Nuxt UI" href="https://ui.nuxt.com/components/"}, used for styling and layout, includes +:external-link{text="Nuxt UI Pro" href="https://ui.nuxt.com/pro/components/aside"} features for development. + +For using Nuxt UI components within MDC, configure them in `nuxt.config.ts` in the `'components:extend'` property under `hooks`. + +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. +Configure styling through `app.config.ts` under `ui` or modify Tailwind settings in `tailwind.config.ts`. +Adhere to Tailwind's :external-link{text="Utility-First Fundamentals" href="https://tailwindcss.com/docs/utility-first"}, +avoiding custom styles in components with the use of the `@apply` feature. diff --git a/content/90.contributing-to-documentation/30.documentation-styleguide.md b/content/90.contributing-to-documentation/30.documentation-styleguide.md new file mode 100644 index 00000000..ce6e1eb2 --- /dev/null +++ b/content/90.contributing-to-documentation/30.documentation-styleguide.md @@ -0,0 +1,246 @@ +--- +title: Documentation Styleguide +description: A comprehensive guide on zkSync documentation standards, including writing style, Markdown conventions, code snippets, and documentation categorization. +--- + +This guide outlines the standards for creating zkSync documentation, +ensuring consistency in writing style, Markdown conventions, and code snippets. + +## Writing Style + +For readability across a diverse audience, including non-native English speakers, we adhere to industry best practices from: + +- :external-link{text="Google Developer Documentation Styleguide" href="https://developers.google.com/style"} +- :external-link{text="Microsoft Writing Styleguide" href="https://learn.microsoft.com/en-us/style-guide/welcome/"} + +It's crucial to create content that is inclusive, diverse, and timeless. Focus on: + +- :external-link{text="Inclusive documentation" href="https://developers.google.com/style/inclusive-documentation"} +- :external-link{text="Timeless documentation" href="https://developers.google.com/style/timeless-documentation"} +- :external-link{text="Bias-free communication" href="https://learn.microsoft.com/en-us/style-guide/bias-free-communication"} +- :external-link{text="Global communications" href="https://learn.microsoft.com/en-us/style-guide/global-communications/"} + +## Spelling + +Content in zkSync Docs are run through a linter for markdown formatting and spellchecking. +Some words may not pass the spellcheck linter and will need to be added to the dictionary list. +New words can be added to lists in `/cspell-config`. All words added to the dictionary are checked +for spelling only. + +## Time & Dates + +To minimize confusion due to global date format variations, adhere to the following in zkSync docs: + +- Start calendars on Mondays. +- Use the date format `month dd, yyyy`, avoiding numerals for months (e.g., January 5, 2018). + +## Kinds of zkSync Documentation + +Following the Diataxis framework, zkSync Docs categorizes content into: + +- **Tutorials**: Step-by-step instructions to teach general skills (e.g., Deploying your first contract on zkSync Era). +- **Guides**: Task completion instructions for readers with basic knowledge (e.g., Debugging with zksync-cli). +- **References**: Detailed technical descriptions (e.g., Ethereum JSON-RPC API). +- **Explanation**: Content to deepen subject understanding +(e.g., Differences between zkSync Native Account Abstraction and Ethereum's EIP 4337). + +### Choosing a category for writing + +Leverage the Diataxis system when crafting a new article for zkSync Docs. +Writing without a clear category often results in unfocused content. +A well-defined focus keeps the content streamlined and clarifies the takeaway for the reader. + +While adhering to this system, it may become evident that a single article +cannot encompass all aspects you wish to convey. +Feel encouraged to create multiple articles across different categories to comprehensively address your topic. + +## Markdown and Vue + +zkSync Docs combine Markdown with Vue components, available under `/components/content`. +Use Vue components in Markdown using `::` syntax and yaml frontmatter for props. +If the Vue component is an inline slot-less component, use the `{prop="val"}` format. + +Learn more about using Markdown and Vue components with Nuxt Content's page on [Markdown](https://content.nuxt.com/usage/markdown). + +### Content Switcher component + +For content organization into tabs, utilize the `ContentSwitcher` component. +Apply the `items` prop to distribute content across tabs. +Organize these partials in a folder that matches the parent markdown file’s name, +preceded by an underscore. + +Use the Content Switcher component in a situation where you have more than one +option to display for a subject depending on the reader's choices. For example, +use the Content Switcher component for a tutorial that provides a Remix and +Atlas option. + +```md +::content-switcher +--- +items: [{ + label: 'HardHat', + partial: '_getting-started/_aPartial' +}, { + label: 'Forge', + partial: '_getting-started/_anotherpartial' +}] +--- +:: +``` + +### Display Partial Component + +The Display Partial component lets you use the same piece of markdown content in different places. +Keep these pieces in the `/content/_partials` directory and reference the partial using its title. + +Be careful when picking what content to share this way. +Make sure that the content can make sense on its own, no matter where it's used. +The page the partial is placed in should not affect the understanding of the partial, and +same the other way. + +```md +::display-partial +--- +partial: 'Setting up your wallet' +--- +:: +``` + +### External Link + +The External Link component provides a Vue component option of displaying a link +with an icon to indicate the link will open in a new tab. +Please use only for links that do not direct to an internal zkSync Docs page. + +```md +:external-link{text="An External Link to Google" href="https://google.com"} +``` + +## Callouts + +Callouts present warnings, extra detail, or references to related topics. +A callout should not contain anything essential to understanding the main content. + +#### Example +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +This is a `callout` with full **markdown** support. It can be used to link to [another page](/getting-started/installation). +:: + +#### Code + +```md +::callout{icon="i-heroicons-exclamation-triangle" color="amber"} +This is a `callout` with full **markdown** support. It can be used to link to [another page](/getting-started/installation). +:: +``` + +## Code Samples + +Use code samples where it helps to explain technical concepts. Create concise examples that are easy to read and understand, +avoid pasting an entire file of code. +Use the `ProseCode` component to display code. +Always define the language the code is represented in next to the backticks. +Additionally, you can define the name of the file to display as a header on the block. + +#### Example + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + extends: ['@nuxt/ui-pro'], + modules: ['@nuxt/ui'] +}) +``` + +#### Code + +```ts + ```ts [nuxt.config.ts] + export default defineNuxtConfig({ + extends: ['@nuxt/ui-pro'], + modules: ['@nuxt/ui'] + }) + ``` +``` + +## Images + +Add images to the `public/images/` directory to use in zkSync docs. +Use the markdown format to display images. + +```md +![IMAGE](/images/example-image.png) +``` + +## Icons + +Utilize Nuxt UI icons with the `UIcon` component, following the naming pattern `i-{collection_name}-{icon_name}`. +The Icon Collections that can be used are configured in `nuxt.config.ts` +in the `ui.icons.collections` property. + +```md +:u-icon{name="i-heroicons-light-bulb"} +``` + +## Links + +Internal links are generated by the `/content` directory structure and the name of the markdown file. +For example, the file `/content/10.getting-started/20.overview.md` is defined as the path `/getting-started/overview`. + +Link to internal pages using markdown format. + +```md +[Getting Started](/getting-started/overview) +``` + +### Anchor Tags + +Every header has an anchor link that you can link to. +Link to the page the anchor point is located in and add +the name of the anchor tag separated by dashes. + +```md +[Getting Started](/getting-started/overview#learn-more) +``` + +### External Links + +Use the [`ExternalLink` component](/contributing-to-documentation/documentation-styleguide#external-link) +to create a link that opens a new tab. + +## Localization + +Currently, zkSync Docs does not offer localized documentation. +Updates to this section will be provided as localization features become available. + +## Use of AI + +While fully AI-generated content is not accepted for zkSync Docs, +the assistance of AI tools like ChatGPT in editing content is permitted. +These tools can enhance the editing process, +although they may occasionally produce inaccurate information. +Always carefully review any AI-assisted content before finalizing. + +You can use the following as a prompt for an AI tool to help with editing: + +```text +The content is written in common markdown format. +Use the Google Developer Documentation Style Guide and the Microsoft Style Guide, emphasizing Bias-free communication. +Write in an active voice. +Do not use the definite or indefinite article with “zkSync Era”. +Assume the reader may be an international person whose first language might not be English. +Don’t use overly complex words unless the technical description is lost if changed. +Ensure all communication is bias-free, following the Microsoft Style Guide's directives for inclusiveness and fairness in language. +If the article I submit has a Header1 at the beginning, move that into a yaml frontmatter for the 'title' property. +Include a short description of the article in the yaml frontmatter in the 'description' property. +``` + +If your content includes technical descriptions and code examples, you can add the following to your prompt +to assist with formatting. + +```text +Always use the word “function” and never the word “method” when referring to Solidity code. +Always use the word “function” for functions in JavaScript and TypeScript. +Always use the word “method” for attributes of an object in JavaScript and TypeScript. +When talking about Rust, always use the word “function” for functions defined on a type, and the word “method” for functions defined on an instance of a type. +When referring to a JSON RPC URL method, always use the word “method”. +``` diff --git a/content/90.contributing-to-documentation/_dir.yml b/content/90.contributing-to-documentation/_dir.yml new file mode 100644 index 00000000..95f834ec --- /dev/null +++ b/content/90.contributing-to-documentation/_dir.yml @@ -0,0 +1 @@ +title: Contributing diff --git a/content/95.resources/20.glossary.md b/content/95.resources/20.glossary.md new file mode 100644 index 00000000..aedd4268 --- /dev/null +++ b/content/95.resources/20.glossary.md @@ -0,0 +1,28 @@ +--- +title: Glossary +description: A dictionary of terms you'll encounter with zkSync +--- + +### **Account Abstraction** + +Account Abstraction enhances transaction authorizations by making them programmable, +offering more flexibility than Externally Owned Accounts (EOAs). +This innovation aims to enrich user experiences and broaden the scope of transaction authorizations, +differing from EIP-4337. + +### **zkSync VM** + +zkSync VM is the name of the architecture that enables zero-knowledge proof generation +for the execution trace of smart contracts originally written for EVM. + +### **EVM Equivalent** + +EVM Equivalent means that a given protocol supports every opcode +of Ethereum’s EVM down to the bytecode. +Thus, any EVM smart contract works with 100% assurance out of the box. + +### **EVM Compatible** + +EVM Compatible means that a percentage of the opcodes of Ethereum’s EVM are supported; +thus, a percentage of smart contracts work out of the box. +zkSync is optimized to be EVM source-code compatible (with a custom compiler), not EVM equivalent. diff --git a/content/95.resources/_dir.yml b/content/95.resources/_dir.yml new file mode 100644 index 00000000..35ad676c --- /dev/null +++ b/content/95.resources/_dir.yml @@ -0,0 +1 @@ +title: Resources diff --git a/cspell-config/cspell-blockchain.txt b/cspell-config/cspell-blockchain.txt index c855ab20..1a448907 100644 --- a/cspell-config/cspell-blockchain.txt +++ b/cspell-config/cspell-blockchain.txt @@ -1,3 +1,3 @@ -evm -merkle +EVM keccak +merkle diff --git a/cspell-config/cspell-dev.txt b/cspell-config/cspell-dev.txt index 079032b5..5c9d1f37 100644 --- a/cspell-config/cspell-dev.txt +++ b/cspell-config/cspell-dev.txt @@ -1,8 +1,13 @@ +Diataxis +fontaine +Nuxt +nuxi nuxt +nuxtdotjs nuxtjs +!NuxtUI +!NuxtContent +NVMe rocksdb -nuxi -otlp -nvme -nuxtdotjs -fontaine +Vue +!vue diff --git a/cspell-config/cspell-zksync.txt b/cspell-config/cspell-zksync.txt index a4b6547b..3d71559f 100644 --- a/cspell-config/cspell-zksync.txt +++ b/cspell-config/cspell-zksync.txt @@ -1,4 +1,5 @@ // zkSync-related words -matterlabs -zksync boojum +MatterLabs +zkSync +zksync-cli diff --git a/cspell.json b/cspell.json index f0f56c77..8ba6fe42 100644 --- a/cspell.json +++ b/cspell.json @@ -1,6 +1,17 @@ { "language": "en", - "ignorePaths": ["node_modules/**", ".github/**", ".firebase/**", ".yarn/**", "dist/**", ".vscode/**"], + "ignorePaths": [ + "node_modules/**", + ".github/**", + ".firebase/**", + ".yarn/**", + "dist/**", + ".vscode/**", + "cspell-config/**", + "package.json", + ".**.**" + ], + "caseSensitive": true, "dictionaries": [ "bash", "cpp", @@ -46,5 +57,6 @@ "path": "./cspell-config/cspell-dev.txt" } ], - "allowCompoundWords": true + "allowCompoundWords": true, + "flagWords": ["hte", "hve", "teh"] } diff --git a/layouts/docs.vue b/layouts/docs.vue index dee5cd38..0091ef62 100644 --- a/layouts/docs.vue +++ b/layouts/docs.vue @@ -1,7 +1,7 @@