راهنمای مستندات

این دایرکتوری مالک نگارش مستندات، قواعد پیوند Mintlify و سیاست بین‌المللی‌سازی مستندات است.

قواعد Mintlify

• مستندات روی Mintlify میزبانی می‌شوند (https://docs.openclaw.ai).
• پیوندهای داخلی مستندات در docs/**/*.md باید بدون پسوند .md یا .mdx، نسبت به ریشه باقی بمانند (مثال: [Config](/gateway/configuration)).
• ارجاع‌های متقابل بخش‌ها باید از لنگرها روی مسیرهای نسبت به ریشه استفاده کنند (مثال: [Hooks](/gateway/configuration-reference#hooks)).
• در عنوان‌های مستندات باید از خط تیره بلند و آپاستروف پرهیز شود، زیرا تولید لنگر Mintlify در مواجهه با آن‌ها شکننده است.
• README و دیگر مستنداتی که GitHub رندر می‌کند باید URLهای مطلق مستندات را حفظ کنند تا پیوندها خارج از Mintlify نیز کار کنند.
• محتوای مستندات باید عمومی باقی بماند: بدون نام دستگاه‌های شخصی، نام میزبان‌ها یا مسیرهای محلی؛ از جای‌نگهدارهایی مانند user@gateway-host استفاده کنید.

قواعد محتوای مستندات

• در مستندات، متن رابط کاربری و فهرست‌های انتخاب‌گر، سرویس‌ها/ارائه‌دهندگان را به‌ترتیب الفبایی مرتب کنید، مگر اینکه بخش صراحتاً ترتیب زمان اجرا یا ترتیب تشخیص خودکار را توصیف کند.
• نام‌گذاری Pluginهای همراه را با قواعد اصطلاح‌شناسی Plugin در سراسر مخزن که در AGENTS.md ریشه آمده است، سازگار نگه دارید.
• مستندات تولیدشده را هرگز دستی ویرایش نکنید: docs/plugins/reference/**، docs/plugins/reference.md و docs/plugins/plugin-inventory.md از pnpm plugins:inventory:gen می‌آیند؛ docs/docs_map.md از pnpm docs:map:gen؛ و docs/maturity/** از pnpm maturity:render.

مستندات داخلی

• مستندات خصوصی و ماندگار اپراتورها به ~/Projects/manager/docs/ تعلق دارند.
• مستندات چرک‌نویس/آینه داخلی و محلی مخزن می‌توانند زیر docs/internal/ نادیده‌گرفته‌شده قرار گیرند.
• هرگز صفحه‌های docs/internal/** را به ناوبری docs/docs.json اضافه نکنید یا از مستندات عمومی به آن‌ها پیوند ندهید.
• scripts/docs-sync-publish.mjs، docs/internal/** را از مخزن انتشار عمومی openclaw/docs کنار می‌گذارد و حذف می‌کند، اگر صفحه‌ای بعداً به‌اجبار اضافه شود.
• مستندات داخلی می‌توانند مسیرهای مخزن، نام برنامه‌های خصوصی، نام آیتم‌های 1Password و راهنماهای عملیاتی را ذکر کنند، اما هرگز نباید شامل مقادیر محرمانه باشند.

ویرایش کارت امتیاز بلوغ

taxonomy.yaml و qa/maturity-scores.yaml ورودی‌های منبع هستند؛ مستندات بلوغ تولیدشده زیر docs/maturity/ نمایه‌هایی هستند و نباید برای امتیاز، LTS، رده‌بندی، نمایه QA یا جدول‌های شواهد به‌صورت دستی ویرایش شوند. scripts/qa/render-maturity-docs.ts مالک فرایند تولید است؛ برای تازه‌سازی مستندات ثبت‌شده از pnpm maturity:render و برای تأیید آن‌ها از pnpm maturity:check استفاده کنید. .github/workflows/maturity-scorecard.yml پیش‌نمایش مصنوعات را رندر می‌کند و می‌تواند PRهای مستندات تولیدشده را باز کند؛ .github/workflows/openclaw-release-checks.yml آن را برای QA انتشار اجرا می‌کند. داده‌های قطعی qa-evidence.json.scorecard را در مصنوعات GitHub Actions نگه دارید، مگر اینکه نگه‌دارنده‌ای صراحتاً یک نمایه پاک‌سازی‌شده و ثبت‌شده را درخواست کند. بازنویسی‌های انسانی باید وضعیت منبع را در یک PR تغییر دهند و دلیل را همراه با شواهد عمومی یا ویرایش‌شده توضیح دهند.

بین‌المللی‌سازی مستندات

• مستندات زبان‌های خارجی در این مخزن نگه‌داری نمی‌شوند. خروجی انتشار تولیدشده در مخزن جداگانه openclaw/docs قرار دارد (که اغلب به‌صورت محلی با نام ../openclaw-docs کلون می‌شود).
• در اینجا مستندات بومی‌سازی‌شده را زیر docs/<locale>/** اضافه یا ویرایش نکنید.
• مستندات انگلیسی این مخزن به‌همراه فایل‌های واژه‌نامه را منبع حقیقت در نظر بگیرید.
• پایپ‌لاین: مستندات انگلیسی را در اینجا به‌روزرسانی کنید، در صورت نیاز docs/.i18n/glossary.<locale>.json را به‌روزرسانی کنید، سپس اجازه دهید همگام‌سازی مخزن انتشار و scripts/docs-i18n در openclaw/docs اجرا شوند.
• پیش از اجرای دوباره scripts/docs-i18n، برای هر اصطلاح فنی، عنوان صفحه یا برچسب کوتاه ناوبری جدیدی که باید به انگلیسی بماند یا از ترجمه‌ای ثابت استفاده کند، مدخلی به واژه‌نامه اضافه کنید.
• pnpm docs:check-i18n-glossary محافظ عنوان‌های تغییریافته مستندات انگلیسی و برچسب‌های کوتاه مستندات داخلی است.
• حافظه ترجمه در فایل‌های تولیدشده docs/.i18n/*.tm.jsonl در مخزن انتشار قرار دارد.
• به docs/.i18n/README.md مراجعه کنید.