feat: create documentation guideline articles

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.

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

components/content/ExternalLink.vue

@@ -0,0 +1,30 @@
+<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">
+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,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.

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.