diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index d569c3ca..00000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -name: Bug report -about: Use this template for reporting issues -title: "" -labels: bug -assignees: '' - ---- - -### 🐛 Bug Report for zkSync Docs - -#### 📝 Description - -Provide a clear and concise description of the bug. - -#### 🔄 Reproduction Steps - -1. Step 1 -2. Step 2 -3. ... - -#### 🤔 Expected Behavior - -Describe what you expected to happen. - -#### 😯 Current Behavior - -Describe what actually happened. - -#### 🖥️ Environment - -- **Node version**: [e.g., v18.17.0] -- **Operating System & Version**: [e.g., Ubuntu 20.04] -- **Other relevant environment details**: - -#### 📋 Additional Context - -Add any other context about the problem here. If applicable, add screenshots to help explain. - -#### 📎 Log Output - -``` -Paste any relevant log output here. -``` diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..f8e11bc9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,47 @@ +name: Bug Report +description: File a bug report. +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! Please fill out as much as you can, the more details the better we can help to resolve the issue. + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Also tell us, what did you expect to happen? + placeholder: Tell us what you see! + value: "" + validations: + required: true + - type: textarea + id: expected + attributes: + label: What did you expect to happen? + placeholder: Tell us what you expected! + value: "" + - type: textarea + id: environment + attributes: + label: Environment + description: Please share any relevant information about your environment. + placeholder: | + - Operating System: [e.g. macOS] + - Node version: [e.g., v18.17.0] + - Other relevant environment details: + - type: textarea + id: logs + attributes: + label: Relevant log output + description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. + render: shell + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/matter-labs/zksync-docs/blob/main/CODE_OF_CONDUCT.md). + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 61fd4b71..60f25512 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -2,4 +2,4 @@ blank_issues_enabled: true contact_links: - name: zksync-developers Discussion url: https://github.com/zkSync-Community-Hub/zkync-developers/discussions - about: Please provide feedback, and ask questions here. + about: These forms are for zkSync Docs related issues. If you have questions or need help, please visit the zksync-developers Discussion. diff --git a/.github/ISSUE_TEMPLATE/feature_report.md b/.github/ISSUE_TEMPLATE/feature_report.md deleted file mode 100644 index 4e30b239..00000000 --- a/.github/ISSUE_TEMPLATE/feature_report.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -name: Feature request -about: Use this template for requesting features -title: "" -labels: feat -assignees: '' - ---- - -### 🌟 Feature Request - -#### 📝 Description - -Provide a clear and concise description of the feature you'd like to see. - -#### 🤔 Rationale - -Explain why this feature is important and how it benefits the project. - -#### 🖼️ Mockups/Examples - -If applicable, provide mockups or examples of how the feature would work. - -#### 📋 Additional Context - -Add any other context or information about the feature request here. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..ff72656f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,31 @@ +name: Feature Request +description: Is there a feature missing you would like to see? Let us know! +title: "[Feature]: " +labels: ["feature", "triage"] +body: + - type: markdown + attributes: + value: | + If you have a feature you'd like to see, please fill out this form. + - type: textarea + id: description + attributes: + label: Description + description: Please provide a brief description of the feature you would like to see. + placeholder: Tell us what you would like to see! + value: "" + - type: textarea + id: rationale + attributes: + label: Rationale + description: Why do you think this feature would be beneficial to the project? + placeholder: Tell us why you think this feature would be beneficial! + value: "" + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/matter-labs/zksync-docs/blob/main/CODE_OF_CONDUCT.md). + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/ISSUE_TEMPLATE/feedback.yml b/.github/ISSUE_TEMPLATE/feedback.yml new file mode 100644 index 00000000..d955af83 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feedback.yml @@ -0,0 +1,31 @@ +name: Feedback +description: Please share any feedback for us on our content! +title: "[Feedback]: " +labels: ["feedback", "triage"] +body: + - type: markdown + attributes: + value: | + If you have feedback on our content, please fill out this form. + - type: input + id: page + attributes: + label: Page + description: If this is related to a specific page, please provide the URL. + placeholder: https://docs.zksync.io/page + value: "" + - type: textarea + id: description + attributes: + label: Description + description: Please provide a brief description of the feedback you would like to share. + placeholder: Tell us what you would like to share! + value: "" + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/matter-labs/zksync-docs/blob/main/CODE_OF_CONDUCT.md). + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9edb5bc9..d7df2fbd 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,17 +1,26 @@ -# What :computer: -* First thing updated with this PR -* Second thing updated with this PR -* Third thing updated with this PR + +- Update your PR title to follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) +- Read the [Contributing Guide](https://github.com/matter-labs/zksync-docs/blob/main/CONTRIBUTING.md). +- Understand our [Code of Conduct](https://github.com/matter-labs/zksync-docs/blob/main/CODE_OF_CONDUCT.md) +- Please delete any unused parts of the template when submitting your PR - +--> + +# Description + + + +## Linked Issues + + + + +## Additional context diff --git a/.lintstagedrc.yml b/.lintstagedrc.yml index 073a6061..f6b2abef 100644 --- a/.lintstagedrc.yml +++ b/.lintstagedrc.yml @@ -2,7 +2,7 @@ - prettier --list-different - eslint '*.md': - - cspell check - markdownlint-cli2 + - cspell check '*.{json,yml}': - prettier --list-different diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index e69de29b..00000000 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..b0ab6ead --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,87 @@ +# Code of Conduct + +Version: 1.1 + +Apache 2.0 license, derived from the Apache Foundation Code of Conduct. +Also, CC BY-SA 3.0 derived from the Mozilla Community Participation Guidelines. + +Our goal is to cultivate a safe, friendly, and inclusive space that benefits all participants in the zkSync ecosystem. +This Code of Conduct outlines our shared values and expectations to help ensure that the community remains a positive and enriching environment for everyone. + +## When and how to use this Code of Conduct + +This is your guide for engaging as a participant in the zkSync ecosystem. +It applies to all physical and digital spaces related to zkSync. + +## Expected behaviors + +**Be ethical**: +We endeavor to enrich the zkSync ecosystem, while not infringing on the rights and wellbeing of others. +We also endeavor to enrich ourselves without causing harm to the zkSync community. +We do not encourage tax evasion, promoting information leaks, speculating on tokens or token prices, or otherwise breaking the law. + +**Be kind and respectful**: +Treat everyone with kindness, empathy, and respect. +We all come from different backgrounds, perspectives and experiences, +so let's celebrate our differences and foster a culture of openness and understanding. +We may have strong feelings about other layer 1 and layer 2 blockchains, +but that is no reason to disparage, defame, or slander any competitor to zkSync or what other chains are doing. +Feel free to compare metrics and features, but keep to the facts and be respectful of all the builders in web3 +trying to advance freedom through blockchain technology! + +**Share and learn**: +Our community is a space for sharing knowledge, experiences, and ideas. +Positively contribute to discussions, offer helpful feedback, +be willing to educate others on your work and remain open to learning from others. + +**Give credit**: +When sharing content or ideas that aren't your own, ensure you give proper credit to the original creator. +Plagiarism and intellectual property infringement are strictly prohibited. + +**Respect privacy**: +Always seek consent before sharing personal information about yourself or others. +Respecting each other's privacy is vital to building trust within our community. + +**Be inquisitive and embrace continuous improvement**: +We strive to improve from each experience, and are open to constructive criticism. +We encourage questions, and redirect them to the appropriate channel if we do not have the answer. + +**Mind your language**: +Communication is key. +Use clear and considerate language in your interactions. +We aim to create a welcoming environment for users of all ages, so please avoid excessive profanity or explicit content. +Remember that zkSync community members are a diverse bunch. +English is our primary working language, but to help others where English is not their first language, +be succinct and avoid acronyms where possible. + +**Stay on topic**: +While we encourage friendly conversations, please ensure your discussions remain relevant to the community's purpose. +To keep our space focused and valuable, off-topic or irrelevant content may be redirected or removed. +Specific topics that are not appropriate include offering to buy or sell any cryptocurrency or engage in price speculation. + +**No hate speech or harassment**: +Let's maintain a constructive and uplifting atmosphere in all interactions. +We have a zero-tolerance policy for any form of hate speech, bullying, harassment, or discrimination. +This includes, but is not limited to: + +- Violent threats or language directed against another person. +- Sexist, racist, or otherwise discriminatory jokes and language. +- Posting sexually explicit or violent material. +- Posting (or threatening to post) other people's personally identifying information ("doxing"). +- Sharing private content without explicit consent, such as messages sent privately or non-publicly. +- Personal insults. +- Unwelcome sexual attention. +- Excessive or unnecessary profanity. +- Repeated harassment of others. In general, if someone asks you to stop, then stop. +- Advocating for, or encouraging, any of the above behavior. + +**Have fun and connect**: +Finally, remember that ZK Squad and the zkSync community is a place to connect, learn, and enjoy. +Participate in a manner that encourages positive interactions and enhances the experiences of all. + +## Managing violations + +If you come across inappropriate content or behavior, please report it without delay. +By working together, we can maintain a positive and safe environment. + +If you are the subject of, or witness to, any violations of this Code of Conduct, please contact us at community@zksync.io. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..15944456 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,3 @@ +# Contributing + +Our primary contributing documentation is available on our site at [Contribution Guidelines](https://docs.zksync.io/build/contributing-to-documentation). diff --git a/README.md b/README.md index 8853cd43..4fe944ec 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # 🌟 zkSync Developer Documentation -![Build Status](https://img.shields.io/badge/build-passing-brightgreen) -![License](https://img.shields.io/badge/license-MIT-blue) -![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-orange) -![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-orange) +[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE-MIT) +[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-orange)](LICENSE-APACHE) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://www.contributor-covenant.org/) +[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-orange)](CONTRIBUTING.md) +[![X (formerly Twitter) Follow](https://badgen.net/badge/twitter/@zksyncDevs/1DA1F2?icon&label)](https://x.com/zksyncDevs) Welcome to the **zkSync Docs** repository! This is your go-to hub for all things zkSync. Dive into our comprehensive documentation whether you're just starting out or looking for advanced guides. @@ -29,7 +30,7 @@ Unlock the full potential of zkSync with our comprehensive resources: - **🛠️ Build:** Learn how to develop and deploy your smart contracts and applications on zkSync Era. Our step-by-step guides and tutorials will help you get started quickly and efficiently. - + - **🔗 ZK Stack:** Dive into the Zero-Knowledge (ZK) Stack to discover how to configure and build a ZK chain tailored for your application. Explore the architecture, components, and best practices. @@ -93,11 +94,6 @@ bun run lint:prettier bun run lint:eslint ``` -## 📜 Conventional Commits - -We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) specification. -Make sure your commit messages adhere to these guidelines. - ## 🤝 Contributions We welcome contributions from the community! Check out the following resources to get started: diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..073c3ed3 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,31 @@ +# Support + +Are you having trouble with our documentation or having some issues with a guide? +We have multiple channels available for you to request help. + +## Where to get help + +If you're in need of help with authoring your content for zkSync Docs, +first read through the [Contribution Guidelines](https://docs.zksync.io/build/contributing-to-documentation/contribution-guidelines) +to see if it may help answer some questions. +If the content there does not solve your problem, submit an [issue in GitHub](https://github.com/matter-labs/zksync-docs/issues) +and we can try to help resolve the issue. + +### Help with developer related issues +If you are referencing the documentation for a project as a developer and run into issues, +you can go to the [zksync-developers Discussions](https://github.com/zkSync-Community-Hub/zksync-developers/discussions) +where you can submit a question. We also have a [Discord community](https://join.zksync.dev/) +that may help with any troubleshooting. + +If you have questions related to any of our zkSync tools, +we recommend that you submit an Issue related to that project. +You can find the list of our open-source repositories in the [Contribution Track](https://docs.zksync.io/build/resources/contribution-track) +on our zkSync Docs site. + +## 🪲 Submit a bug report + +Have you come across a bug while going through our documentation? +Perhaps the versions are out of date or a particular tool is broken when trying to run a project. +Submit an [issue in GitHub](https://github.com/matter-labs/zksync-docs/issues) using our Bug Issue form +or submit feedback directly from the page! In the right sidebar on the site, there is a link below the Table of Contents +for "Share feedback" which will set up a pre-filled Issue form for the page you're on. diff --git a/components/layout/Toc.vue b/components/layout/Toc.vue index 27d704b5..baadc15d 100644 --- a/components/layout/Toc.vue +++ b/components/layout/Toc.vue @@ -18,7 +18,7 @@ const links = computed(() => { icon: 'i-heroicons-chat-bubble-oval-left-ellipsis', label: 'Share feedback', - to: `https://github.com/matter-labs/zksync-docs/issues/new?&title=Feedback for ${props.page?.title}&body=Page: ${props.page?._path}`, + to: `https://github.com/matter-labs/zksync-docs/issues/new?&template=feedback&page=https://docs.zksync.io${props.page?._path}`, target: '_blank', }, ...(toc?.bottom?.links || []), diff --git a/content/00.build/90.contributing-to-documentation/20.contribution-guidelines.md b/content/00.build/90.contributing-to-documentation/20.contribution-guidelines.md index 8656ad50..3f73807c 100644 --- a/content/00.build/90.contributing-to-documentation/20.contribution-guidelines.md +++ b/content/00.build/90.contributing-to-documentation/20.contribution-guidelines.md @@ -5,19 +5,33 @@ description: Learn how to contribute to zkSync Docs ## Environments +We have two environments available for zkSync Docs. + **Production**: Visit [zkSync Docs](https://docs.zksync.io/) for official documentation. -**Staging**: [zKsync Docs Staging](https://staging-docs.zksync.io/) environment. +**Staging**: [zKsync Docs Staging](https://staging-docs.zksync.io/) for use with larger work that may not be merged immediately to main. + +## Fork the project + +Make a [fork of the zksync-docs project](https://github.com/matter-labs/zksync-docs/fork) and create your branches from the default `main` branch. + +If your PR is still a work in progress, consider putting it into a [Draft status](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft). +Once your PR is ready for review, switch it back to an active PR request +and any reviewers already attached will automatically get a notification. -## Git workflow +## Commit conventions -- 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. +This project uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standards. +For changes that are **code related**, use the `fix:`, `feat:`, or `chore:` tags in your commits. +For typo or document related changes, please use the `docs:` tag. + +```sh +git commit -m "docs: fix typo in guide" +``` ### Signed git commits -Your git commits need to be signed with a verified signature. +Your git commits need to be [signed with a verified signature](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification). 1. Follow the instructions to [generate a signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). @@ -26,21 +40,20 @@ Your git commits need to be signed with a verified signature. ## Contribution workflow -To set up and run the project locally, consult the root [`README.md`](%%zk_git_repo_zksync-docs%%) file. - -### Tracking work +To set up and run the project locally, consult the root [`README.md`](%%zk_git_repo_zksync-docs%%?tab=readme-ov-file#-zksync-developer-documentation) file. -Start your work by creating an [issue](%%zk_git_repo_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 [GitHub guide on linking](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). +### Use VSCode -Submit your PR against the `staging` branch. +To take full advantage of linting and formatting features, it is highly +recommended to use [VSCode](https://code.visualstudio.com/) and install the recommended extensions. +To manually install the recommended extensions, go to the Extensions tab +in VSCode and search for `@recommended`. +--- ## 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. +zkSync docs is built with Vue and Nuxt framework, utilizing various Nuxt Modules for content development. +Familiarize yourself with their documentation to provide you with the full capability of contributing. ### Nuxt @@ -48,9 +61,6 @@ Nuxt is a Vue framework for building applications. Visit the [Nuxt documentation](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 [DevTools](https://devtools.nuxt.com/) for debugging. @@ -68,14 +78,15 @@ 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 [naming scheme](https://content.nuxt.com/usage/content-directory) -that uses numbering to order pages. We use a double digit numbering scheme. +that uses numbering to order pages. +We use a double digit numbering scheme. -#### Using Vue Components in MDC +#### Using Vue Components in markdown -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 [Vue components section](https://content.nuxt.com/usage/markdown#vue-components) +Vue components can be used within markdown files, although their syntax is different. +Components within markdown are identified with `::`. +Components placed in the `/components/content` are automatically imported for use in markdown files in `/content`. +Refer to the Nuxt Content page on [Vue components section](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 @@ -83,16 +94,18 @@ need to be globally configured to use in markdown content. ### Nuxt UI -[Nuxt UI](https://ui.nuxt.com/components/), used for styling and layout, includes -[Nuxt UI Pro](https://ui.nuxt.com/pro/components/aside) features for development. +[Nuxt UI](https://ui.nuxt.com/components/) along with +[Nuxt UI Pro](https://ui.nuxt.com/pro/components) are available to build UI. -For using Nuxt UI components within MDC, configure them in `nuxt.config.ts` in the `'components:extend'` property under `hooks`. +While Nuxt UI components are a part of the project, they need to be configured in +`nuxt.config.ts` to make them available in `/content` markdown files. +See [the current configuration](https://github.com/matter-labs/docs-nuxt-template/blob/main/nuxt.config.ts#L35) +to discover what components are already loaded. 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`. +Styling relies on Nuxt UI and [Tailwind](https://tailwindcss.com/). Adhere to Tailwind's [Utility-First Fundamentals](https://tailwindcss.com/docs/utility-first), avoiding custom styles in components with the use of the `@apply` feature. diff --git a/content/00.build/90.contributing-to-documentation/30.documentation-styleguide.md b/content/00.build/90.contributing-to-documentation/30.documentation-styleguide.md index 6801fcd3..453f2ba2 100644 --- a/content/00.build/90.contributing-to-documentation/30.documentation-styleguide.md +++ b/content/00.build/90.contributing-to-documentation/30.documentation-styleguide.md @@ -34,7 +34,7 @@ To minimize confusion due to global date format variations, adhere to the follow - Start calendars on Mondays. - Use the date format `month dd, yyyy`, avoiding numerals for months (e.g., January 5, 2018). -## Kinds of zkSync Documentation +## Types of documentation Following the [Diataxis](https://diataxis.fr/) framework, zkSync Docs categorizes content into @@ -44,7 +44,7 @@ Following the [Diataxis](https://diataxis.fr/) framework, zkSync Docs categorize - **Explanation**: Content to deepen subject understanding (e.g., Differences between zkSync Native Account Abstraction and Ethereum's EIP 4337). -### Choosing a category for writing +### Choosing a category Leverage the [Diataxis](https://diataxis.fr/) system when crafting a new article for zkSync Docs. Writing without a clear category often results in unfocused content. @@ -54,15 +54,99 @@ 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 +## Add new documentation -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. +To add new pages to our documentation, create new files under the `/content` directory. + +### Naming scheme + +File and folder names are prefixed with a number that Nuxt uses to handle what order pages are displayed in navigation. +We use a two-digit numbering system to allow for easier re-ordering of files. + +If you are creating a new directory, **name your first file `00.index.md`**. +This ensures there is a root path to the page. +The display name will be defined by the title in the frontmatter. + +### _dir.yml + +The `_dir.yml` allows for further configuration of the directory. +The `title` defined in this file is what defines the header for the dropdown panel in navigation. + +### Frontmatter + +All pages must have frontmatter with a `title` and `description`. +If you do not want a description for your page, simply leave the `description` value blank. + +## Images + +Add images to the `public/images/` directory to use in zkSync docs +and reference them from the `/images` path, do not include the `public/`. +Use the markdown format to display images. + +```md +![Image Alt Text](/images/example-image.png) +``` + +- Keep your image size to 600-960px wide. +- If you are displaying visual diagrams with text, use svg format for best clarity. +- Avoid using images to display only text, code or data output, use actual text. +- Every image should have a descriptive alt text. +- Optimize your image using a service like [TinyPNG](https://tinypng.com/). + +## Icons + +Utilize Nuxt UI icons with the [`UIcon` component](https://ui.nuxt.com/components/icon), following the naming pattern `i-{collection_name}-{icon_name}`. +The icon collections pre-configured for this project are `heroicons`, `simple-icons`, `devicon` and `logos`. + +You can browse the icons available in each collection on [Icones](https://icones.js.org/). This browser is also available from the Nuxt Debug tools. + +```md +:u-icon{name="i-heroicons-light-bulb"} +``` + +## Links + +Internal links are generated in relation to the `/content` directory and the name of the markdown file. + +For example, the file `/content/1.quick-start/2.deploy-contract.md` is defined as the path `/quick-start/deploy-contract`. +**Do not** add the number or file extension on the link. + +Example link to an internal page using markdown format, with an anchor tag. + +```md +[Getting Started](/build/zksync-101#install-docker) +``` + +## Markdown and Vue components + +zkSync Docs combine Markdown with Vue components though the syntax is different. +For example, if you use a [Nuxt UI Button component](https://ui.nuxt.com/components/button), the html syntax would be the following: + +```html + + I am a button + +``` + +In markdown, the syntax changes to the following: + +```md +::u-button{ color="primary" variant="solid" } + I am a button +:: +``` + +If the Vue component is an inline slot-less component, you can use a simplified inline format. + +```html + + +:u-button{ label="button" } +``` Learn more about using Markdown and Vue components with Nuxt Content's page on [Markdown](https://content.nuxt.com/usage/markdown). -### Content Switcher component +### Content Switcher For content organization into tabs, utilize the `ContentSwitcher` component. Apply the `items` prop to distribute content across tabs. @@ -88,35 +172,21 @@ items: [{ :: ``` -### Display Partial Component - -The Display Partial component lets you use the same piece of markdown content in different places. -Keep highly reusable pieces in the `/content/_partials` directory and reference the partial by its path. - -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{path="_partials/setting-up-your-wallet"} -``` - -## Callouts +### 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](/build/zksync-101). +This is a `callout` with full **markdown** support. It can have markdown content like a link to [another page](/build/zksync-101). :: #### 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](/build/zksync-101). +This is a `callout` with full **markdown** support. It can have markdown content like a link to [another page](/build/zksync-101). :: ``` @@ -124,7 +194,6 @@ This is a `callout` with full **markdown** support. It can be used to link to [a 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. @@ -148,52 +217,6 @@ export default defineNuxtConfig({ ``` ``` -## Images - -Add images to the `public/images/` directory to use in zkSync docs. -Use the markdown format to display images. - -```md -![Image Alt Text](/images/example-image.png) -``` - -- Keep your image size to 600-960px wide. -- If you are displaying visual diagrams with text, use svg format for best clarity. -- Avoid using images to display only text, code or data output, use actual text. -- Every image should have a descriptive alt text. -- Optimize your image using a service like [TinyPNG](https://tinypng.com/). - -## 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/1.quick-start/2.deploy-contract.md` is defined as the path `/quick-start/deploy-contract`. - -Link to internal pages using markdown format. - -```md -[Getting Started](/build/zksync-101) -``` - -### 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](/build/zksync-101) -``` - ## Localization Currently, zkSync Docs does not offer localized documentation. diff --git a/cspell-config/cspell-misc.txt b/cspell-config/cspell-misc.txt index 91c8efe1..734aec30 100644 --- a/cspell-config/cspell-misc.txt +++ b/cspell-config/cspell-misc.txt @@ -3,6 +3,7 @@ Consensys Cyfrin GRVT Hola +Icones Immunefi initializable Initializable