diff --git a/app.config.ts b/app.config.ts index efab2003..bf257301 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', diff --git a/components/content/ExternalLink.vue b/components/content/ExternalLink.vue new file mode 100644 index 00000000..87dc0dca --- /dev/null +++ b/components/content/ExternalLink.vue @@ -0,0 +1,32 @@ + + + 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..fbb90032 --- /dev/null +++ b/content/90.contributing-to-documentation/10.index.md @@ -0,0 +1,50 @@ +--- +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 +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 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..5ebbe733 --- /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. + +### NuxtUI + +:external-link{text="NuxtUI" href="https://ui.nuxt.com/components/"}, used for styling and layout, includes +:external-link{text="NuxtUI Pro" href="https://ui.nuxt.com/pro/components/aside"} features for development. + +For using NuxtUI 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. + +### Styling + +Styling relies on NuxtUI 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..954e641a --- /dev/null +++ b/content/90.contributing-to-documentation/30.documentation-styleguide.md @@ -0,0 +1,208 @@ +--- +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/"} + +## 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 Markdown and Vue component 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. +Place markdown for each tab in separate files for clarity. +Organize these files in a folder that matches the parent markdown file’s name, +preceded by an underscore. + +```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. +To show a piece, use its title in the partial prop. + +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. +It should not cause any confusion or changes to the other content around it if it gets updated. + +```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](/pro/prose/card). +:: + +#### 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](/pro/prose/card). +:: +``` + +## 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 NuxtUI 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. 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..894c2c76 --- /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. + +### **zkEVM** + +zkEVM 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 compatible 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/layouts/docs.vue b/layouts/docs.vue index dee5cd38..0091ef62 100644 --- a/layouts/docs.vue +++ b/layouts/docs.vue @@ -1,7 +1,7 @@