Notation: إدارة الوثائق في Notion بسهولة

مقدمة

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

الميزات الرئيسية

• دمج الوثائق مع الكود: يتبع Notation فلسفة تصميم حيث يجب أن تعيش الوثائق مع الكود. لا يجب أن تكون الوثائق مديراة بشكل منفصل عن المستودع، بل يجب أن تكون جزءًا لا يتجزأ من الكود، كما يجب أن تكون متاحة في جميع مراحل العمل على الكود، سواء في الصباح أو المساء.

• استخدام Markdown: لا تحتاج إلى معرفة أي إطار عمل قمم الواجهة (frontend framework) آخر غير Markdown. يعتبر Markdown أسهل في استخدام وكتابة الوثائق، ولا تحتاج إلى قلق حول التعامل مع React أو نشر موقع ويب، كما هو الحال في بعض الأدوات الأخرى.

• استخدام Notion: بعد نشر الوثائق في Notion، يمكنك الاستفادة من جميع ميزات Notion. يمكنك أن تكون الوثائق شيئًا داخلية في مساحة عمل Notion الخاصة بك للفريق، أو يمكنك نشرها كصفحة عامة في Notion، أو حتى نشرها كموقع كامل باستخدام خدمات مثل super.so (مثل notation.so).

كيفية الاستخدام

1. كتابة الوثائق: ابدأ بكتابة الوثائق الخاصة بك باستخدام Markdown في أي محرر نصوص تفضل.

2. إنشاء صفحة في Notion: قم بإنشاء صفحة في Notion لتستضيف الوثائق الخاصة بك.

3. الحصول على مفتاح API: قم بالحصول على مفتاح API من Notion (يمكنك العثور على المساعدة في الأسفل).

4. تكوين Notation: قم بكتابة المفتاح API في ملف Notation.toml في المسار ~/.notation/Notation.toml (يمكنك العثور على التفاصيل في الأسفل).

5. نشر الوثائق: قم بتنفيذ الأمر notation ship --src </path/to/you/docs> لرصد الوثائق الخاصة بك في Notion. ستتمكن من استخدام البحث الذكاءي المدمج في Notion، والتشكيل الجيد، جدول المحتويات، وما إلى ذلك.

خيارات التنشيط

• يمكنك الحفاظ على الوثائق داخلية في مساحة عمل Notion الخاصة بك للفريق، وذلك عن طريق عدم نشرها كصفحة عامة في Notion أو كموقع كامل.

• يمكنك نشرها كصفحة في Notion، حيث ستظهر على الصفحة الرئيسية أو في صفحات فرعية حسب هيكل الملفات والصفحات التي قمت بإنشاءها في Notion.

• يمكنك نشرها كموقع كامل باستخدام خدمات مثل super.so، حيث ستكون الوثائق متاحة للجميع عبر الإنترنت، مثل في notation.so.

ميزات إضافية

• intro.md: إذا كنت تريد نشر محتوى مباشرة على الصفحة الرئيسية، يمكنك وضعه في ملف intro.md في الدليل. سيتم عرض هذا المحتوى مباشرة على الصفحة الرئيسية بدلاً من إنشاء صفحة فرعية لهذا المحتوى. على سبيل المثال، إذا كان لديك هيكل الملفات التالي: docs/ intro.md getting_started.md api/ endpoints.md، فسيتم عرضه في Notion على النحو التالي: Parent Page... whatever content is in intro.md... - Getting Started (Subpage) - API (Subpage) - Endpoints (Subpage).

• arguments: يدعم Notation هذه المدخلات التي يتم تمريرها كعلامات CLI في أعلى ملف Markdown: title - عنوان الصفحة في Notion، emoji - أيقونة الصفحة في Notion. على سبيل المثال: --title "Getting Started" --emoji 🚀 # My Title of my markdown file My content that will be rendered on a page titled "Get Started" with the rocket emoji.

الأسئلة الشائعة

• ما هي الميزات Markdown التي تدعمها؟: تدعم Notation عناوين (headers)، فقرات (paragraphs)، كتل الكود (code blocks)، قوائم (ordered، unordered)، جداول (tables)، روابط (links)، صور (although not local， you need to host yourself and put the link)， روابط الصفحات النسبية (to other pages in the same repo， which will turn into Notion page links)， هيكل الدليل العشوائي (will turn into subpages， subsubpages， etc.).

• كيفية تكوين Notation؟: قم بإنشاء ملف Notation.toml بجانب التنفيذية (binary) الخاصة بـ Notation (عادة في ~/.notation/). # ~/.notation/Notation.toml [notion] secret = "" # this is the title of the page that will host your new documentation parent_page = "".

• كيفية إعداد كل هذا؟: أولاً، تحتاج إلى حساب Notion. قم بالتسجيل هنا: Notion. ثم قم بإنشاء صفحة لتستضيف الوثائق الخاصة بك. الآن، أعط الصفحة اسمًا. في ملف Notation.toml، قم بكتابة هذا الاسم (تأكد من أن يكون اسمًا فريدًا في مساحة عملك): # Notation.toml [notion] secret = "" parent_page = "Your Notation Parent" # <----- this name. ثم قم بإنشاء تجميع (integration) في Notion. قم بذهاب إلى Settings & members في أعلى يمين الصفحة الرئيسية في Notion. ثم قم بضغط على Connections --> Develop or manage integrations. الآن قم بإنشاء تجميع جديد. أعطه اسمًا، قم بتخصيصه إلى أحد مساحات عملك، وحدد internal como el tipo de integración. الآن قم بالتقط_secret: And throw it in your Notation.toml! # Notation.toml [notion] secret = "your_new_integration_secret" # <----- right here parent_page = "Your Notation Parent" Last thing， you need to connect your Notion page to this integration. Back on your parent Notion page， click the three dots in the top right corner， and then go down to Connections， find your new Notion integration， and click it. That's it! Enjoy!

مساعدة

إذا كان لديك أي أسئلة، لا تتردد في إنشاء مشكلة في Github. سأكون في حالة مراقبة نشطة. شكرًا :)