پرش به مطلب اصلی

پایگاه مستندات فارسی

· خواندن 4 دقیقه
علیرضا
علیرضا
AI and Software Engineer, AlizٔNet founder

AlizNet – Persian Computer Science Documentation​

این مخزن با هدف تولید، توسعه و نگهداری مستندات فارسیِ باکیفیت در حوزه‌های برنامه‌نویسی، علوم کامپیوتر، امنیت، شبکه و فناوری ایجاد شده است.
هدف ما ایجاد یک کتابخانه‌ی جامع و استاندارد فارسی است تا افرادی که تسلط کافی روی منابع انگلیسی ندارند نیز بتوانند به شکل حرفه‌ای یاد بگیرند.

این پروژه با Docusaurus ساخته شده و با کمک جامعه توسعه می‌یابد. 🙌
اگر قصد مشارکت دارید، لطفاً این README را کامل مطالعه کنید. ❤️

🌟 انواع مشارکت (Contribution Types)

در این پروژه می‌توانید در سه بخش مشارکت کنید:

  1. 🚀 بهبود کد سایت
  2. 📚 افزودن مستندات جدید (Docs)
  3. 📝 نوشتن پست بلاگ (Blog Posts)

هر بخش قوانین دقیقس دارد که در ادامه توضیح داده شده‌اند.

🚀 ۱. مشارکت در بهبود کد سایت (Development)

اگر می‌خواهید در توسعه Docusaurus، UI، تنظیمات یا ساختار پروژه کمک کنید:

✔ مراحل:​

  1. مخزن را Fork کنید.
  2. یک Branch جدید ایجاد کنید.
  3. تغییرات را انجام دهید.
  4. پروژه را محلی اجرا کنید:
npm install
npm run start
  1. قبل از ارسال PR حتماً Build بگیرید:
npm run build

سپس درخواست Pull را ارسال کنید و دقیقا توضیح دهید:

  • چه چیزی تغییر کرده؟
  • چرا؟
  • چه تستی انجام شده؟

📚 ۲. افزودن مستندات جدید (Docs)

🟢 ۱.۲. قوانین کلی محتوا​

✔ محتوا حتماً باید فارسی باشد.

✔ کیفیت محتوا مهم است: غلط‌های زیاد، ترجمهٔ تحت‌اللفظی یا محتوای ضعیف پذیرفته نمی‌شود.

✔ فایل باید با فرمت‌های زیر باشد: (اطلاعات بیشتر)

  • .md
  • .mdx

🟦 ۲.۲. مسیر قرارگیری درست فایل‌ها​

تمام محتوا داخل فولدر docs/ قرار می‌گیرد.

مثال:​

اگر درباره کاربردهای پایتون می‌نویسید:

docs/python/basics/introduction.mdx

پوشه‌ها باید مطابق ساختار استاندارد باشند.

🟡 ۳.۲. مقداردهی frontmatter (الزامی)​

در ابتدای هر فایل اضافه کنید:

---
sidebar_position: 1
slug: /python/basics/introduction
---

✔ متغییر slug باید با ساختار فولدر شما همخوانی کامل داشته باشد.

✔ آدرس نهایی صفحه:

https://aliznet.ir/docs/python/basics/introduction

🟣 ۴.۲. ساخت دسته‌بندی جدید (Category)​

اگر موضوع از قبل وجود ندارد:

  1. فولدر بسازید (مثلاً: docs/web-security/)
  2. در فولدر ساخته شده فایل زیر را ایجاد کنید: (category_.json_)
{
  "label": "امنیت وب",
  "position": 3,
  "collapsed": true,
  "link": {
    "type": "generated-index",
    "slug": "/category/web-security"
  }
}

✔ متغییر slug باید شامل category + نام فولدر باشد.

✔ متغییر position ترتیب دسته در سایدبار را مشخص می‌کند.

🟩 ۵.۲. افزودن دسته به صفحه اصلی سایت​

در فایل:

docs/export_courses.js

کد مشابه زیر اضافه کنید:

import python_category from './python/_category_.json';

const cardsList = [
    {
        title: python_category.label,
        url: `docs/${python_category.link.slug.split("/").slice(-1)[0]}`,
    },
];

export default cardsList;

این مورد باعث نمایش دسته‌بندی به‌صورت کارت (Course) در صفحه اول می‌شود. 🎉

📝 ۳. قوانین نوشتن پست بلاگ (Blog)

پست‌های بلاگ در مسیر زیر قرار می‌گیرند:

blog/

👤 ۱.۳. افزودن نویسنده (Author)​

دو فایل مهم وجود دارد:

✔ authors.yaml → اجباری​

اگر نام شما در این فایل نباشد، امکان انتشار پست ندارید ❗

✔ authors.json → اختیاری​

اگر اینجا نباشید، فقط در صفحه اصلی سایت نمایش داده نمی‌شوید.

مثال:​

authors.yaml:

alireza:
  name: Alireza
  title: Software Engineer
  url: https://github.com/aliz-f
  image_url: https://arfadaei.ir/assets/images/aliz-photo.JPG

authors.json:

{
  "alireza": {
    "name": "Aliz",
    "title": "Software Engineer",
    "image_url": "https://arfadaei.ir/assets/images/aliz-photo.JPG"
  }
}

📝 ۲.۳. ساخت فایل پست​

نام فایل باید مطابق الگو باشد:

year-month-day-name.md
year-month-day-name.mdx

مثال:

2025-01-06-first-blog-post.mdx

🔖 ۳.۳. بخش frontmatter برای پست های بلاگ (الزامی):​

---
slug: mdx-blog-post
title: پست وبلاگ MDX
authors: [alireza]
tags: [docusaurus]
---

✔ نام نویسنده باید در لیست شناسه‌های موجود در authors.yaml باشد.

✔ تگ ها باید از tags.yaml انتخاب شده باشد.

⚠️ قوانین مهم کیفیت محتوا

برای حفظ استاندارد پروژه:

  • لغت انگلیسی تخصصی ترجمه شده در متن حتما در پرانتز بعد از معادل ترجمه شده قرار گیرد.
  • ساختار نوشتار باید تمیز، خوانا و یکپارچه باشد
  • تصاویر باید در static/img قرار گیرند
  • مثال‌ها باید قابل اجرا باشند

هدف ما ایجاد یک مرجع فارسی باکیفیت است، نه انبوهی از محتواهای پراکنده و ضعیف.

🔧 راهنمای توسعه‌دهندگان (Developers)

اجرای پروژه:

npm install
npm run start

ساخت نسخه production:

npm run build

پیش‌نمایش نسخهٔ ساخته‌شده:

npm run serve

❤️ قدردانی

از تمام دوستانی که در توسعه این مخزن کمک می‌کنند، سپاس‌گزاریم. شما باعث رشد کیفیت منابع فارسی در حوزه کامپیوتر می‌شوید. 🌱

اگر پیشنهاد یا ایرادی دارید، لطفاً Issue باز کنید. ❤️