المبادئ التوجيهية الحية - MDX والأطر الأخرى

قد يكون لديك مشروع مفتوح المصدر أفضل ، ولكن إذا لم يكن لديه وثائق جيدة ، فمن المحتمل أنه لن ينجح أبدًا. في المكتب ، ستمنعك الوثائق الجيدة من الإجابة على نفس الأسئلة مرارًا وتكرارًا. يضمن التوثيق أيضًا أن يتمكن الأشخاص من فهم المشروع إذا ترك الموظفون الرئيسيون الشركة أو تغيرت الأدوار. تساعد الإرشادات المباشرة في ضمان تكامل البيانات.

إذا كنت بحاجة إلى كتابة نص طويل ، فإن Markdown هو بديل رائع لـ HTML. أحيانًا لا تكون صيغة Markdown كافية. في هذه الحالة ، يمكننا استخدام HTML بداخلها. على سبيل المثال ، العناصر المخصصة. لذلك ، إذا كنت تقوم ببناء نظام تصميم بمكونات ويب أصلية ، فمن السهل تضمينها في الوثائق النصية. إذا كنت تستخدم React (أو أي إطار عمل JSX آخر مثل Preact أو Vue) ، يمكنك فعل الشيء نفسه مع MDX.

هذه المقالة هي نظرة عامة واسعة على أدوات كتابة الوثائق وإنشاء مبادئ توجيهية. لا تستخدم جميع الأدوات المدرجة هنا MDX ، ولكن يتم تضمينها بشكل متزايد في أدوات التوثيق.

ما هو MDX؟

ملف .mdx له نفس صيغة Markdown ولكنه يسمح لك باستيراد مكونات JSX التفاعلية وتضمينها في المحتوى الخاص بك. يتوفر دعم مكونات Vue بلغة ألفا. لبدء العمل مع MDX ، ما عليك سوى تثبيت "إنشاء تطبيق React". توجد مكونات إضافية لـ Next.js و Gatsby. سيحتوي الإصدار التالي من Docusaurus (الإصدار 2) أيضًا على دعم مدمج.

كتابة الوثائق مع Docusaurus

كتب Docusaurus على Facebook. يستخدمونها في كل مشروع مفتوح المصدر باستثناء React. خارج الشركة ، يستخدمه Redux و Prettier و Gulp و Babel.

المشاريع التي تستخدم Docusaurus.

يمكن استخدام Docusaurus في الكتابة أي الوثائق ، ليس فقط لوصف الواجهة الأمامية. يحتوي على React تحت الغطاء ، لكن ليس عليك أن تكون على دراية به لاستخدامه. إنه يأخذ ملفات Markdown الخاصة بك ، وهي عبارة عن القليل من الوثائق الرائعة والمنسقة والقابلة للقراءة مع تصميم جميل جاهزة.

يمكنك رؤية قالب Docusaurus الافتراضي على موقع Redux على الويب.

يمكن أن تتضمن المواقع التي تم إنشاؤها باستخدام Docusaurus أيضًا مدونة قائمة على Markdown. لإبراز بناء الجملة ، يتم تضمين Prism.js على الفور. على الرغم من ظهور Docusaurus مؤخرًا نسبيًا ، فقد تم التعرف عليه كأفضل أداة لعام 2018 على StackShare.

خيارات إنشاء المحتوى الأخرى

تم تصميم Docusaurus خصيصًا لإنشاء الوثائق. بالطبع ، هناك مليون طريقة لإنشاء موقع ويب - يمكنك نشر الحل الخاص بك بأي لغة ، أو CMS ، أو استخدام منشئ موقع ثابت.

على سبيل المثال ، تستخدم وثائق React ونظام تصميم IBM و Apollo و Ghost CMS Gatsby ، وهو مولد موقع ثابت غالبًا ما يستخدم للمدونات. إذا كنت تعمل مع Vue ، فإن VuePress يعد خيارًا جيدًا لك. خيار آخر هو استخدام مولد مكتوب بلغة Python - MkDocs. إنه مفتوح ومجهز بملف YAML واحد. يعد GitBook أيضًا خيارًا جيدًا ، ولكنه مجاني فقط للفرق المفتوحة وغير التجارية. يمكنك أيضًا تحميل ملفات mardown باستخدام git والعمل معها في Github.

توثيق المكونات: Docz و Storybook و Styleguidist

المبادئ التوجيهية ، وتصميم النظام ، ومكتبات المكونات ، وكل ما تريد تسميته ، أصبحت شائعة جدًا مؤخرًا. لقد أتاح ظهور أطر عمل المكونات مثل React والأدوات المذكورة هنا تحويلها من مشاريع الغرور إلى أدوات مفيدة.

يقوم Storybook و Docz و Styleguidist بفعل الشيء نفسه: عرض العناصر التفاعلية وتوثيق واجهة برمجة التطبيقات الخاصة بهم. يمكن أن يحتوي المشروع على العشرات أو حتى المئات من المكونات ، وكلها بحالات وأنماط مختلفة. إذا كنت تريد إعادة استخدام المكونات ، فيجب أن يعرف الناس أنها موجودة. للقيام بذلك ، يكفي فهرسة المكونات. توفر الإرشادات نظرة عامة سهلة البحث عن جميع المكونات الخاصة بك. هذا يساعد في الحفاظ على التناسق البصري وتجنب العمل المتكرر.

توفر هذه الأدوات طريقة ملائمة لعرض الحالات المختلفة. قد يكون من الصعب تكرار كل حالة من مكونات في سياق تطبيق حقيقي. بدلاً من النقر فوق التطبيق الفعلي ، من المفيد تطوير مكون منفصل. من الممكن نمذجة الحالات التي يصعب الوصول إليها (على سبيل المثال ، حالة التحميل).

إلى جانب العرض التوضيحي المرئي للحالات المختلفة وقائمة الخصائص ، غالبًا ما يكون من الضروري كتابة وصف عام للمحتوى - مبررات التصميم أو حالات الاستخدام أو وصف نتائج اختبار المستخدم. Markdown سهل التعلم للغاية - من الناحية المثالية ، يجب أن تكون الإرشادات مصدرًا مشتركًا للمصممين والمطورين. تقدم Docz و Styleguidist و Storybook طريقة لمزج Markdown بسهولة مع المكونات.

دوكز

حاليًا ، يعمل Docz فقط مع React ، ولكنه يعمل بنشاط على دعم مكونات Preact و Vue والويب. Docz هي الأحدث من بين الأدوات الثلاثة ، ولكنها تمكنت من جمع أكثر من 14 نجمة على Github. يقدم Docz عنصرين - <Playground> и < Props >. يتم استيرادها واستخدامها في الملفات .mdx.

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<Button>click</Button>

يمكنك تغليف مكونات React الخاصة بك بـ <Playground>لإنشاء نظير من CodePen أو CodeSandbox المدمجين - أي أنك ترى المكون الخاص بك ويمكنك تحريره.

<Playground>
  <Button>click</Button>
</Playground>

<Props> سيعرض جميع الخصائص المتاحة لمكون React المحدد والقيم الافتراضية وما إذا كانت الخاصية مطلوبة.

<Props of={Button} />

أنا شخصياً أجد أن هذا النهج القائم على MDX هو الأسهل للفهم والأسهل للعمل معه.

إذا كنت من محبي موقع Gatsby الثابت ، فإن Docz يقدم عمليات تكامل رائعة.

دليل أسلوب

كما هو الحال في Docz ، تتم كتابة الأمثلة باستخدام صيغة Markdown. يستخدم Styleguidist كتل كود Markdown (علامات الاقتباس الثلاثية) في الملفات العادية .md الملفات ، وليس في MDX.

```js
<Button onClick={() => console.log('clicked')>Push Me</Button>

عادةً ما تعرض كتل التعليمات البرمجية في Markdown الكود فقط. عند استخدام Styleguidist ، أي جزء من التعليمات البرمجية مع علامة اللغة js, jsx أو javascript سيتم تقديمه كمكون React. مثل Docz ، الكود قابل للتحرير - يمكنك تغيير الخصائص ورؤية النتيجة على الفور.

سيقوم Styleguidist تلقائيًا بإنشاء صحيفة خصائص من تعريفات PropTypes أو Flow أو Typescript.

يدعم Styleguidist الآن React و Vue.

القصص القصيرة

كتاب القصص يعتبر نفسه "بيئة تطوير مكون واجهة المستخدم". بدلاً من كتابة أمثلة للمكونات داخل ملفات Markdown أو MDX ، يمكنك كتابة قصص داخل ملفات جافا سكريبت. قصة توثيق الحالة المحددة للمكون. على سبيل المثال ، قد يكون للمكون سجلات لحالة تحميل وحالة معطلة (معاق).

storiesOf('Button', module)
  .add('disabled', () => (
    <Button disabled>lorem ipsum</Button>
  ))

القصص القصيرة أكثر تعقيدًا من Styleguidist و Docz. ولكن في الوقت نفسه ، هذا هو الخيار الأكثر شيوعًا ، في Github يحتوي المشروع على أكثر من 36 نجمة. هذا مشروع مفتوح المصدر مع 000 مساهمًا ومرافقة الموظفين. يتم استخدامه من قبل Airbnb و Algolia و Atlassian و Lyft و Salesforce. يدعم Storybook إطارات أكثر من المنافسين - React و React Native و Vue و Angular و Mithril و Ember و Riot و Svelte و HTML عادي.

في إصدار مستقبلي ، سيكون هناك شرائح من Docz ويتم تقديم MDX.

# Button

Some _notes_ about your button written with **markdown syntax**.

<Story name="disabled">
  <Button disabled>lorem ipsum</Button>
</Story>

سيتم طرح ميزات Storybook الجديدة تدريجيًا خلال الأشهر القليلة المقبلة ، ويبدو أنها ستكون خطوة كبيرة إلى الأمام.

نتائج

تم الإشادة بفوائد مكتبة الأنماط في ملايين المقالات على Medium. عندما يتم إجراؤها بشكل جيد ، فإنها تسهل إنشاء المنتجات ذات الصلة والحفاظ على الهوية. بالطبع ، لن تُنشئ أي من هذه الأدوات نظام تصميم بطريقة سحرية. هذا يتطلب تصميم دقيق وتصميم CSS. ولكن عندما يحين وقت إتاحة نظام التصميم للشركة بأكملها ، فإن Docz و Storybook و Styleguidist هي خيارات رائعة.

من مترجم. هذه هي تجربتي الأولى مع حبري. إذا وجدت أي معلومات غير دقيقة ، أو لديك اقتراحات لتحسين المقالة - فاكتب بشكل شخصي.

المصدر: www.habr.com