feat: create documentation guideline articles

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',

components/content/ExternalLink.vue

@@ -0,0 +1,32 @@
+<template>
+  <a
+    :href="href"
+    :target="target"
+    :rel="rel"
+    class="inline"
+  >
+    {{ text }}
+    <UIcon
+      name="i-heroicons-arrow-top-right-on-square-16-solid"
+      class="-mb-0.5"
+    />
+  </a>
+</template>
+
+<script setup lang="ts">
+import { defineProps } from 'vue';
+
+export interface Props {
+  text: string;
+  href: string;
+  target?: string;
+  rel?: string;
+}
+
+withDefaults(defineProps<Props>(), {
+  text: '',
+  href: '',
+  target: '_blank',
+  rel: 'noopener noreferrer',
+});
+</script>

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.

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.

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.

content/90.contributing-to-documentation/_dir.yml

@@ -0,0 +1 @@
+title: Contributing