افزودن ویوئر Docusaurus

یک پروژه‌ی Lore می‌تواند فقط با Markdown شروع شود و بعداً یک وب‌سایت قابل‌مرور بگیرد. /lore:add-docusaurus دقیقاً همین کار را می‌کند.

/lore:add-docusaurus

چه می‌کند

1. پیش‌شرط‌ها را بررسی می‌کند. به یک اتصال شبکه نیاز دارید، و پروژه باید فقط-مستندات باشد، یعنی مستندات دارد اما هنوز ویوئر ندارد.
2. آخرین Docusaurus را می‌گیرد. خود فریم‌ورک تازه با create-docusaurus@latest گرفته می‌شود و هرگز بسته‌بندی نمی‌شود، پس همیشه نسخه‌ی جاری را می‌گیرید.
3. فریم‌ورک را وارد و نمونه‌ها را دور می‌ریزد (مستندات، بلاگ و صفحه‌های شروع) تا با محتوای شما تداخل نکنند.
4. پیکربندی و استایل Lore را overlay می‌کند، شامل لایه‌ی RTL و فونت فارسی self-hosted وقتی زبان مستندات شما راست‌به‌چپ است.
5. می‌پرسد سایت کجا منتشر می‌شود. آن نشانی مبدأ هر لینک canonical و هر مدخل sitemap.xml می‌شود. اگر هنوز نمی‌دانید، همین را بگویید: http://localhost:3000 را می‌گذارد که آشکارا موقتی است، و به شما می‌گوید پیش از اولین انتشار عوضش کنید. هرگز یک دامنه‌ی نمونه‌ی باورپذیر جا نمی‌گذارد، چون آن یعنی انتشار یک sitemap برای نشانی‌ای که مالکش نیستید، و هیچ چیزی هم اعتراض نمی‌کند.
6. سایدبار را سیم‌کشی می‌کند تا درخت docs/ موجود شما را آینه کند، سپس نصب، build و شما را به پیش‌نمایش هدایت می‌کند.

نتیجه

یک سایت Docusaurus که به مستندات موجود شما سیم‌کشی شده و آماده‌ی پیش‌نمایش است:

npm start         # سرور توسعه روی http://localhost:3000
npm run build     # build تولید؛ باید پیش از تحویل سبز شود
npm run serve     # پیش‌نمایش build تولید

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

:::tip به‌روز نگه‌داشتن Docusaurus چون ویوئر یک پروژه‌ی معمولی npm است، Docusaurus یک وابستگی نسخه‌دار در package.json آن است. آن را آگاهانه به‌روز کنید: با npm update برای minor و patch، یا با بالابردن @docusaurus/* و اجرای npm install برای یک major، سپس اجرای دوباره‌ی build. :::