Fiaz Technologies
docscommunitycontribution-guide

Docs Contribution Guide

How to contribute to the Fiaz Technologies documentation.

Welcome to the Fiaz Technologies Docs Contribution Guide!

We’re thrilled to have you here and appreciate your interest in contributing to our documentation. This guide provides instructions on how to edit the Fiaz Technologies documentation, ensuring that everyone can contribute effectively and improve our docs.

Why Contribute?

Open-source work is never done, and neither is documentation. Contributing to docs is a valuable way for beginners to get involved and for experienced developers to share their knowledge with the community. By contributing to the Fiaz Technologies docs, you help us build a more robust resource for all developers.

How to Contribute

The documentation content is stored in our repository. You can contribute by editing files directly on GitHub or by cloning the repo and making changes locally.

GitHub Workflow

If you’re new to GitHub, we recommend reading the GitHub Open Source Guide to learn how to fork a repository, create a branch, and submit a pull request.

Good to know: The docs code is synced from a private codebase to the public repository. You won’t be able to preview the docs locally, but your changes will be visible on our site once your pull request is merged.

Writing MDX

Our documentation is written in MDX, which combines markdown with JSX syntax. This allows us to embed React components in the docs. Refer to the GitHub Markdown Guide for markdown syntax basics.

VSCode

To preview MDX files locally in VSCode, follow these steps:

  1. Open the command palette (⌘ + ⇧ + P on Mac or Ctrl + Shift + P on Windows) and select Preferences: Open User Settings (JSON).

  2. Add the following line to your settings.json file:

    {
  "files.associations": {
    "*.mdx": "markdown"
  }
}

  3. Use the command palette to select Markdown: Preview File or Markdown: Open Preview to the Side to see your changes.

Extensions

We recommend the following extensions for VSCode:

  • MDX: Provides IntelliSense and syntax highlighting for MDX.
  • Prettier: Formats MDX files on save.

Review Process

Once you submit your contribution, the Fiaz Technologies team will review your changes, provide feedback, and merge the pull request when it's ready. Please feel free to ask any questions in the PR comments.

Tip: Run pnpm prettier-fix to format your code before submitting your PR.

File Structure

Our docs use file-system routing. Each folder and file inside /docs represents a route segment for generating URLs, navigation, and breadcrumbs.

For example, if you want to contribute to a section about "Authentication," place the file in:

/docs/authentication.mdx

Metadata

Each page has a metadata block at the top of the file.

Required Fields:

  • title: The page's <h1> title, used for SEO and OG Images.
  • description: The page's description, used in the <meta name="description"> tag for SEO.

Example metadata:

---
title: Authentication
description: How to configure authentication in Fiaz Technologies.
---

Optional Fields:

  • nav_title: Overrides the page's title in the navigation.
  • source: Pulls content into a shared page.
  • related: Lists related pages at the bottom of the document.

Page Types

Docs pages are categorized into:

  • Conceptual Pages: Explain concepts or features in detail. Found in sections like /docs/concepts.
  • Reference Pages: Focus on specific APIs or functions. Found in sections like /docs/reference.

Style Guide

Voice and Tone:

  • Write clear, concise sentences.
  • Use active voice and avoid passive constructions.
  • Keep language simple and avoid subjective terms.

Code Blocks:

  • Include a minimum working example.
  • Use language-specific headers (e.g., tsx, jsx).
  • Highlight lines as needed to draw attention to specific parts of the code.

Icons:

  • Use the available icons in the docs.

Custom Components and HTML

We use React components like <Image /> and <Check /> in the docs. Avoid raw HTML except for the <details> tag.

Thank You!

Thank you for contributing to the Fiaz Technologies docs. Your input helps us build better resources for everyone. If you have any questions or need assistance, please don’t hesitate to reach out.

Happy documenting!