پروتکل: یک نقطه شروع زیبا برای سایت مستندسازی API بعدی شما

ماه ها از ساخت آن می گذرد، اما من هیجان زده هستم که بالاخره الگوی وب سایت بعدی خود را منتشر می کنم – پروتکل، یک کیت شروع زیبا برای ساخت وب سایت های مرجع API شگفت انگیز.

با پشتیبانی از Next.js و MDX و سبک‌دهی شده با Tailwind CSS، دقیقاً به روشی ساخته شده است که ما مستندات مرجع API خود را می‌سازیم.

اگر مجوز دسترسی کامل به Tailwind UI دارید، با نسخه نمایشی زنده بازی کنید یا کد منبع را دانلود کنید – البته، این یک به‌روزرسانی رایگان برای مشتریان با دسترسی کامل است.

طبق معمول ما بسیار لذت بردیم که با طراحی و قرار دادن آن لایه اضافی از پولیش روی چیزها برای لذت بردن از مرور سایت لذت بردیم.

ما بلوک‌های کد چسبناکی داریم که با پیمایش در جزئیات درخواست و پاسخ برای این نقطه پایانی قابل مشاهده باقی می‌مانند:

همچنین این جلوه مکان‌نمای زیبا در نقشه‌های صفحه اصلی وجود دارد – نشانگر ماوس را با این درخشش گرادیان دنبال می‌کند که یک الگوی پس‌زمینه ظریف را نشان می‌دهد:

با این حال، جزئیات مورد علاقه من باید ناوبری نوار کناری باشد که محتوای قابل مشاهده صفحه را دنبال می کند، اما از نوعی استراتژی “نقشه حداقل” استفاده می کند. همه بخش های قابل مشاهده صفحه مشخص شده اند:

تماشای این انیمیشن در حین پیمایش در صفحه واقعاً یک منظره قابل مشاهده است – برای Framer Motion برای انجام کارهای سنگین در اینجا طبق معمول. حتی اگر من کاملاً از React متنفر بودم، مطمئنم که فقط برای استفاده از این کتابخانه دوباره از آن استفاده خواهم کرد، واقعاً خیلی خوب است.

ما زمان زیادی را صرف تصمیم گیری در مورد نحوه پیوند دادن محتوای واقعی این یکی کردیم. ما مجموعه ای از گزینه های مختلف را برای تولید خودکار اسناد با استفاده از استانداردهای مختلف بررسی کردیم، اما به هر حال همه اینها برای سلیقه من کمی محدود کننده به نظر می رسید.

من شخصاً می‌خواهم بتوانم مستندات دقیقی را که می‌خواهم بنویسم. بنابراین برای پروتکل، ما برای حداکثر کنترل بهینه‌سازی شده‌ایم، اما با بسیاری از امکانات نویسندگی که نوشتن دقیقاً همان چیزی را که می‌خواهید بسیار آسان می‌کند. به سرعت.

شما مستندات نقطه پایانی خود را در MDX می نویسید، و چند مؤلفه کوچک را که برای ساختار سریع چیزها ارائه می دهیم، با هم ترکیب می کنید:

## Create a message {{ tag: 'POST', label: '/v1/messages' }}Row>  Col>    Publishes a new message to a specific conversation.    ### Required attributes    Properties>      Property name="conversation_id" type="string">        Unique identifier for the conversation the message belongs to.      Property>      Property name="message" type="string">        The message content.      Property>    Properties>  Col>  Col sticky>    CodeGroup title="Request" tag="POST" label="/v1/messages">    ```bash {{ title: 'cURL' }}    curl https://api.protocol.chat/v1/messages \      -H "Authorization: Bearer {token}" \      -d conversation_id="xgQQXg3hrtjh7AvZ" \      -d message="You're what the French call 'les incompetents.'"    ```    ```js    import ApiClient from '@example/protocol-api'    const client = new ApiClient(token)    await client.messages.create({      conversation_id: 'xgQQXg3hrtjh7AvZ',      message: 'You're what the French call 'les incompetents.'',    })    ```    CodeGroup>    ```json {{ title: 'Response' }}    {      "id": "gWqY86BMFRiH5o11",      "conversation_id": "xgQQXg3hrtjh7AvZ",      "message": "You're what the French call 'les incompetents.'",      "reactions": [],      "created_at": 692233200,    }    ```  Col>Row>

با این کار اسنادی به شکل زیر ایجاد می شود:

برای بهبود تجربه نگارش، ما حتی annotations mdx را ایجاد کرده‌ایم، یک کتابخانه جدید که ویژگی حاشیه‌نویسی را که هنگام کار با Markdoc دوست داشتیم به MDX می‌آورد.

این به شما اجازه می دهد تا با حاشیه نویسی با یک شیء، مانند این عنوان، عناصر را در برچسب های محتوای MDX ارسال کنید:

## Create a message { tag: 'POST', label: '/v1/messages' }

… که به این JSX ترجمه شده است:

Heading level={2} tag="POST" label="/v1/messages">  Create a messageHeading>

این به شما امکان می‌دهد خیلی سریع‌تر حرکت کنید زیرا می‌توانید به نوشتن در Markdown ادامه دهید و مجبور نیستید فقط برای ارسال اطلاعات اضافی وارد JSX خام شوید.

من فکر می‌کنم این الگو فوراً برای بسیاری از افراد مفید خواهد بود، بنابراین برای ما مهم بود که سفارشی‌سازی طرح را برای مطابقت با برند شما آسان کنیم.

ما عمداً الگوی پس‌زمینه مصور را طراحی کرده‌ایم که در سایت استفاده می‌کنیم تا تقریباً برای همه احساس «برند» داشته باشد – می‌توانید بگویید که این کار یک طراح حرفه‌ای است، اما ساده است و به سمت موتیف «فنی» متمایل است، چیزی که به هر حال همه سایت‌های مرجع API خواهند داشت.

ما الگو را به‌جای اینکه به‌عنوان یک دارایی با تمام رنگ‌های داخلی صادر کنیم، به صورت کد ساخته‌ایم، بنابراین به راحتی می‌توان آن را تغییر داد تا با طرح رنگ خود مطابقت داشته باشد.

برای برجسته سازی نحو، از شیکی با استفاده می کنیم css-variables موضوعی که تنها با انتخاب 9 رنگ، به‌روزرسانی برجسته‌سازی نحو برای برند شما را آسان می‌کند:

:root {  --shiki-color-text: theme("colors.white");  --shiki-token-constant: theme("colors.emerald.300");  --shiki-token-string: theme("colors.emerald.300");  --shiki-token-comment: theme("colors.zinc.500");  --shiki-token-keyword: theme("colors.sky.300");  --shiki-token-parameter: theme("colors.pink.300");  --shiki-token-function: theme("colors.violet.300");  --shiki-token-string-expression: theme("colors.emerald.300");  --shiki-token-punctuation: theme("colors.zinc.200");}

این کار بسیار کمتر از تلاش برای ایجاد تم خود از ابتدا است!

علاوه بر چهار نمادی که در نسخه ی نمایشی خود استفاده کرده ایم، 24 نماد دیگر را برای دسته ای از انواع منابع API رایج قرار داده ایم:

این اسکرین شات را ببینید که در آن الگوی پروتکل را طوری تطبیق داده ایم که گویی توسط دوستان ما در ConvertKit برای تقویت مرجع API آنها استفاده می شود:

در یک نگاه سریع بسیار متفاوت به نظر می رسد، اما زمانی که شما واقعاً در اینجا جستجو می کنید، در واقع چیز زیادی در اینجا تغییر نکرده است – فقط به روز رسانی برخی از رنگ های دکمه و پیوند، لوگو، تنظیم گرادیان در اثر هنری، و انتخاب چند رنگ مختلف برای برجسته کردن نحو.

طبیعتاً این سایت دارای پشتیبانی از حالت تاریک است – برای توسعه دهندگان طراحی شده است، آیا واقعاً فکر می کنید ما می توانیم اینقدر نادان باشیم؟ شما هرگز ما را نمی بخشید.

نسخه حالت تاریک نیز بسیاری از جزئیات طراحی جالب خود را دارد – به عنوان مثال، من رفتار متفاوت دکمه های اصلی را دوست دارم.

ما Algolia را برای جستجوی اسناد دوست داریم و از آن برای وب سایت Tailwind CSS و همچنین الگوی نحوی خود استفاده می کنیم.

ما آن را برای پروتکل نیز پیوند دادیم، اما این بار از کتابخانه تکمیل خودکار بدون سر Algolia استفاده کردیم تا کنترل کاملی بر رابط کاربری جستجو داشته باشیم:

نکته خوب در مورد این رویکرد این است که ما می‌توانیم از کلاس‌های کمکی ساده برای استایل دادن به همه چیز به جای نوشتن CSS سفارشی برای استایل دادن به یک ویجت از قبل استایل‌داده‌شده استفاده کنیم، که احساس بسیار بیشتری دارد. دقیقا در یک پروژه Tailwind CSS.

و تمام – آخرین الگوی Tailwind UI برای پایان سال 2022! ما داریم یکی دیگر تقریباً آماده راه اندازی است، بنابراین در سال جدید مراقب آن باشید. همچنین به زودی اخبار بسیار هیجان انگیزی در مورد Tailwind CSS v4.0 وجود خواهد داشت!