الأدوات والإضافات

اختيار الأدوات والإضافات المناسبة يرفع كفاءة الكتابة وجودة الوثائق. هذا الدليل يعرض فئات الأدوات لبناء سير عمل متكامل لـ Markdown.

محررات مُوصى بها

محررات شيفرة احترافية

Visual Studio Code

الميزات: مجاني، متعدد الأنظمة، ثري بالإضافات

الإضافات المُوصى بها:
- Markdown All in One: دعم Markdown متكامل
- Markdown Preview Enhanced: ميزات معاينة محسّنة
- markdownlint: فحص بناء الكود والمعايير
- Paste Image: لصق صور سريع
- Table Editor: تحرير جداول مرئي
- Math to Image: تحويل الصيغ الرياضية إلى صور

مثال ضبط:

{
  "markdown.preview.fontSize": 14,
  "markdown.preview.lineHeight": 1.6,
  "markdown.extension.toc.levels": "1..6",
  "markdown.extension.print.absoluteImgPath": false,
  "[markdown]": {
    "editor.wordWrap": "on",
    "editor.lineNumbers": "on",
    "editor.quickSuggestions": false
  }
}

Typora

الميزات: WYSIWYG، واجهة بسيطة، سمات متعددة

الوظائف الرئيسية:
- تحرير بمعاينة مباشرة
- دعم الصيغ الرياضية
- تكامل رسم المخططات
- تصدير صيغ متعددة
- نسخ صور تلقائي
- تحرير جداول مرئي

Mark Text

الميزات: مفتوح المصدر، معاينة فورية، أداء ممتاز

الميزات الأساسية:
- عرض بمعاينة مباشرة
- وضع التركيز
- دعم الصيغ الرياضية
- دعم مخططات التدفق
- صيغ تصدير متعددة
- موضوعات مخصصة

محررات على الإنترنت

StackEdit

الميزات: عبر المتصفح، مزامنة سحابية، تعاون

نقاط القوة:
- مزامنة مباشرة إلى Google Drive و Dropbox
- نشر إلى GitHub ومنصات المدونات
- دعم التحرير دون اتصال
- الصيغ الرياضية والمخططات
- تحرير تعاوني
- سجل الإصدارات

Dillinger

الميزات: واجهة بسيطة، تكاملات متعددة

المنصات المتكاملة:
- GitHub
- Dropbox
- Google Drive
- OneDrive
- دعم تصدير HTML و PDF
- معاينة مباشرة

HackMD

الميزات: تعاون الفرق، وضع العروض

ميزات التعاون:
- تحرير مباشر متعدد المستخدمين
- نظام التعليقات
- تحكم بالإصدارات
- إدارة الصلاحيات
- وضع العرض
- وضع الكتاب

أدوات المعاينة والتحويل

مولدات مواقع ثابتة

VitePress

الميزات: بيئة Vue، أداء ممتاز، حداثة

// .vitepress/config.js
export default {
  title: 'My Documentation',
  description: 'A VitePress site',
  
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' }
    ],
    
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/introduction' },
            { text: 'Installation', link: '/guide/installation' }
          ]
        }
      ]
    }
  },
  
  markdown: {
    math: true,
    mermaid: true,
    lineNumbers: true
  }
}

GitBook

الميزات: واجهة جميلة، تعاون الفرق، إدارة نسخ

الميزات المميزة:
- تجربة قراءة حديثة
- تحرير تعاوني للفرق
- تصدير بصيغ متعددة
- وظيفة البحث
- تحليلات متكاملة
- توليد وثائق API

Docusaurus

الميزات: مفتوح المصدر من Facebook، بيئة React، دعم لغات متعددة

// docusaurus.config.js
module.exports = {
  title: 'My Site',
  tagline: 'The tagline of my site',
  url: 'https://your-docusaurus-test-site.com',
  
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/blog/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
  
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
    },
  },
};

أدوات تحويل الصيغ

Pandoc

الميزات: محول شامل، سطر أوامر، صيغ عديدة

# تحويل Markdown إلى PDF
pandoc document.md -o document.pdf

# تحويل Markdown إلى Word
pandoc document.md -o document.docx

# تحويل Markdown إلى HTML (أنماط مخصصة)
pandoc document.md -s --css=style.css -o document.html

# تحويل مجمع
find . -name "*.md" -exec pandoc {} -o {}.pdf \;

# استخدام قالب
pandoc document.md --template=template.html -o output.html

# توليد جدول المحتويات
pandoc document.md --toc --toc-depth=3 -o document.pdf

markdownlint

الميزات: فحص القواعد، توحيد النمط، إصلاح تلقائي

# التثبيت
npm install -g markdownlint-cli

# فحص ملف واحد
markdownlint README.md

# فحص مجلد
markdownlint docs/

# إصلاح تلقائي
markdownlint --fix *.md

# استخدام ملف التكوين
markdownlint --config .markdownlint.json docs/

مثال ضبط:

{
  "default": true,
  "MD013": {
    "line_length": 120,
    "code_blocks": false,
    "tables": false
  },
  "MD033": {
    "allowed_elements": ["div", "span", "img", "a"]
  },
  "MD041": false
}

أدوات الصور والوسائط

أدوات معالجة الصور

PicGo

الميزات: رفع تلقائي، دعم منصات متعددة، إضافات

المنصات المدعومة:
- Qiniu Cloud
- Tencent Cloud COS
- Upyun
- GitHub
- Alibaba Cloud OSS
- Imgur
- رفع مخصص

مثال ضبط:

{
  "picBed": {
    "uploader": "github",
    "github": {
      "repo": "username/image-repo",
      "token": "your_github_token",
      "path": "images/",
      "customUrl": "https://cdn.jsdelivr.net/gh/username/image-repo",
      "branch": "main"
    }
  },
  "settings": {
    "autoRename": true,
    "uploadNotification": true
  }
}

ImageOptim / TinyPNG

الميزات: ضغط الصور، تصغير الحجم، الحفاظ على الجودة

# استخدام ImageOptim CLI
imageoptim *.png *.jpg

# استخدام TinyPNG API
curl --user api:YOUR_API_KEY \
     --data-binary @original.png \
     --output compressed.png \
     https://api.tinify.com/shrink

أدوات توليد الرسوم

draw.io (diagrams.net)

الميزات: مجاني، قوي، تصدير بصيغ عديدة

حالات الاستخدام:
- مخططات بنية النظام
- تصميم مخططات التدفق
- مخططات UML
- مخططات طوبولوجيا الشبكة
- الخرائط الذهنية
- تصميم النماذج الأولية

Excalidraw

الميزات: أسلوب يدوي، تعاون، سهل الاستخدام

الميزات المميزة:
- مخططات بأسلوب الرسم اليدوي
- تعاون مباشر
- استخدام دون اتصال
- تصدير PNG/SVG
- إدارة المكتبات
- لوحة رسم غير محدودة

منصات إدارة الوثائق

أدوات تعاون الفرق

Notion

الميزات: مساحة عمل موحدة، قواعد بيانات، قوالب

وظائف الوثائق:
- هيكل صفحات هرمي
- تحرير تعاوني مباشر
- تكامل قاعدة البيانات
- نظام القوالب
- دعم الوسائط المتعددة
- تكامل API

Confluence

الميزات: على مستوى المؤسسات، صلاحيات، تكامل قوي

ميزات المؤسسات:
- تحكم متقدم بالصلاحيات
- سير عمل الموافقات
- تخصيص العلامة التجارية
- تكامل المؤسسات
- بحث متقدم
- تقارير التحليل

GitBook

الميزات: مناسب للمطورين، تحكم بالإصدارات، واجهة جميلة

المزايا الأساسية:
- تكامل Git
- سجل الإصدارات
- تعاون الفرق
- نطاق مخصص
- وظيفة البحث
- بيانات التحليل

منصات النشر

GitHub Pages

الميزات: استضافة مجانية، تحكم بالإصدارات، نطاق مخصص

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
        
    - name: Install dependencies
      run: npm install
      
    - name: Build
      run: npm run build
      
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

Netlify

الميزات: نشر سريع، CDN، معالجة نماذج

# netlify.toml
[build]
  publish = "dist"
  command = "npm run build"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[build.environment]
  NODE_VERSION = "16"

Vercel

الميزات: نشر بلا إعداد، CDN عالمي، استعراضات نشر

{
  "builds": [
    {
      "src": "package.json",
      "use": "@vercel/static-build",
      "config": {
        "distDir": "dist"
      }
    }
  ],
  "routes": [
    {
      "handle": "filesystem"
    },
    {
      "src": "/(.*)",
      "dest": "/index.html"
    }
  ]
}

أدوات الأتمتة

تكامل CI/CD

GitHub Actions

مثال سير عمل:

name: Documentation Build and Deploy

on:
  push:
    branches: [ main ]
    paths: [ 'docs/**' ]
  pull_request:
    branches: [ main ]
    paths: [ 'docs/**' ]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Lint Markdown
      uses: articulate/actions-markdownlint@v1
      with:
        config: .markdownlint.json
        files: 'docs/**/*.md'

  build:
    needs: lint
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    
    - name: Setup Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
        cache: 'npm'
        
    - name: Install dependencies
      run: npm ci
      
    - name: Build VitePress
      run: npm run docs:build
      
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v1
      with:
        path: docs/.vitepress/dist

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v1

خطافات Pre-commit

ملف الضبط .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.32.2
    hooks:
      - id: markdownlint
        args: ['--fix']
        
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
        language_version: python3
        
  - repo: local
    hooks:
      - id: docs-build
        name: Build documentation
        entry: npm run docs:build
        language: system
        files: '^docs/.*\.md$'
        pass_filenames: false

أدوات توليد الوثائق

توليد وثائق API تلقائياً

// استخدام JSDoc لتوليد وثائق API
/**
 * إنشاء مستخدم جديد
 * @param {Object} userData - بيانات المستخدم
 * @param {string} userData.name - اسم المستخدم
 * @param {string} userData.email - عنوان البريد الإلكتروني
 * @param {string} [userData.role=user] - دور المستخدم
 * @returns {Promise<Object>} كائن المستخدم الذي تم إنشاؤه
 * @example
 * const user = await createUser({
 *   name: 'أحمد محمد',
 *   email: 'ahmed@example.com'
 * });
 */
async function createUser(userData) {
  // كود التنفيذ...
}

# توليد الوثائق
jsdoc src/ -d docs/api/ -c jsdoc.conf.json

وثائق OpenAPI/Swagger

# openapi.yaml
openapi: 3.0.0
info:
  title: API إدارة المستخدمين
  version: 1.0.0
  description: RESTful API لنظام إدارة المستخدمين

paths:
  /users:
    post:
      summary: إنشاء مستخدم جديد
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: تم إنشاء المستخدم بنجاح
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: "12345"
        name:
          type: string
          example: "أحمد محمد"
        email:
          type: string
          format: email
          example: "ahmed@example.com"
    
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          default: "user"

أدوات تحسين الأداء

تحسين البناء

سكربت تحسين الصور

// optimize-images.js
const sharp = require('sharp');
const fs = require('fs');
const path = require('path');

async function optimizeImages(dir) {
  const files = fs.readdirSync(dir);
  
  for (const file of files) {
    const filePath = path.join(dir, file);
    const stat = fs.statSync(filePath);
    
    if (stat.isDirectory()) {
      await optimizeImages(filePath);
    } else if (/\.(jpg|jpeg|png)$/i.test(file)) {
      const outputPath = filePath.replace(/\.(jpg|jpeg|png)$/i, '.webp');
      
      await sharp(filePath)
        .webp({ quality: 80 })
        .toFile(outputPath);
        
      console.log(`مُحسّن: ${file} -> ${path.basename(outputPath)}`);
    }
  }
}

optimizeImages('./docs/assets/images');

سكربت بناء الوثائق

// build-docs.js
const { execSync } = require('child_process');
const fs = require('fs');
const path = require('path');

function buildDocs() {
  console.log('📝 بدء بناء الوثائق...');
  
  // 1. فحص بناء Markdown
  console.log('🔍 فحص بناء Markdown...');
  execSync('markdownlint docs/', { stdio: 'inherit' });
  
  // 2. تحسين الصور
  console.log('🖼️ تحسين الصور...');
  execSync('node optimize-images.js', { stdio: 'inherit' });
  
  // 3. بناء الموقع الثابت
  console.log('🏗️ بناء الموقع الثابت...');
  execSync('vitepress build docs', { stdio: 'inherit' });
  
  // 4. توليد خريطة الموقع
  console.log('🗺️ توليد خريطة الموقع...');
  generateSitemap();
  
  console.log('✅ اكتمل بناء الوثائق!');
}

function generateSitemap() {
  const baseUrl = 'https://yoursite.com';
  const pages = findMarkdownFiles('./docs');
  
  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${pages.map(page => `  <url>
    <loc>${baseUrl}${page}</loc>
    <lastmod>${new Date().toISOString().split('T')[0]}</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>`).join('\n')}
</urlset>`;

  fs.writeFileSync('./docs/.vitepress/dist/sitemap.xml', sitemap);
}

function findMarkdownFiles(dir, basePath = '') {
  const files = [];
  const items = fs.readdirSync(dir);
  
  for (const item of items) {
    const fullPath = path.join(dir, item);
    const relativePath = path.join(basePath, item);
    
    if (fs.statSync(fullPath).isDirectory()) {
      files.push(...findMarkdownFiles(fullPath, relativePath));
    } else if (item.endsWith('.md') && item !== 'README.md') {
      const urlPath = relativePath
        .replace(/\.md$/, '.html')
        .replace(/\\/g, '/');
      files.push('/' + urlPath);
    }
  }
  
  return files;
}

buildDocs();

دليل اختيار الأدوات

اختر الأدوات حسب الحاجة

## كتابة مدونة شخصية
مجموعة مُوصى بها:
- المحرر: Typora أو Mark Text
- النشر: GitHub Pages + Jekyll
- الصور: PicGo + GitHub
- الإصدارات: Git

## تعاون فرق على الوثائق
مجموعة مُوصى بها:
- المنصة: Notion أو GitBook
- المحرر: VS Code + إضافات
- الإصدارات: Git + GitHub
- الأتمتة: GitHub Actions

## موقع وثائق تقنية
مجموعة مُوصى بها:
- المولد: VitePress أو Docusaurus
- المحرر: VS Code
- النشر: Netlify أو Vercel
- المخططات: Mermaid + draw.io

## وثائق API
مجموعة مُوصى بها:
- الأداة: Swagger/OpenAPI
- التوليد: Redoc أو SwaggerUI
- التكامل: Postman
- الاختبار: Newman

## الأوراق الأكاديمية
مجموعة مُوصى بها:
- المحرر: Typora + Pandoc
- الصيغ: MathJax/KaTeX
- الاقتباسات: Zotero
- التحويل: Pandoc LaTeX

مقارنة التكاليف

نوع الأداة	الخيارات المجانية	الخيارات المدفوعة	النسخة المؤسسية
المحرر	VS Code، Mark Text	Typora (¥89)	-
الاستضافة	GitHub Pages	Netlify Pro (¥190/شهر)	مخصص للمؤسسات
التعاون	GitHub	Notion (¥64/شهر/شخص)	Confluence (¥42/شهر/شخص)
استضافة الصور	GitHub	Qiniu Cloud (¥0.1/GB)	سحابة خاصة للمؤسسات
النطاق	github.io	نطاق مخصص (¥60/سنة)	نطاق مؤسسي

قواعد ذات صلة

• تضمين HTML - ميزات HTML
• الصيغ الرياضية - تعبيرات LaTeX
• المخططات - رسم المخططات
• أفضل الممارسات - نصائح كتابة

توصيات ختامية

إعدادات مُقترحة للمبتدئين

🚀 مجموعة البدء السريع:
1. المحرر: VS Code + Markdown All in One
2. المعاينة: إضافة معاينة مباشرة
3. الإصدارات: Git + GitHub
4. النشر: GitHub Pages
5. الصور: رفع مباشر إلى المستودع

💰 التكلفة: مجاني تماماً
⏱️ زمن التعلم: 1-2 ساعة
🎯 مناسب لـ: مدونات شخصية، وثائق مشاريع صغيرة

إعدادات مُقترحة للمتمرسين

⚡ مجموعة احترافية:
1. المحرر: Typora + VS Code
2. المولد: VitePress
3. استضافة الصور: PicGo + تخزين سحابي
4. التعاون: GitHub + Issues
5. الأتمتة: GitHub Actions
6. المراقبة: Google Analytics

💰 التكلفة: ¥200-500/سنة
⏱️ زمن التعلم: 1-2 يوم
🎯 مناسب لـ: فرق تقنية، مشاريع مفتوحة المصدر

إعدادات على مستوى المؤسسات

🏢 مجموعة المؤسسات:
1. المنصة: Confluence أو GitBook
2. التحرير: VS Code + إضافات الفريق
3. الإصدارات: Git على مستوى المؤسسات
4. النشر: سحابة خاصة + CDN
5. التعاون: إدارة صلاحيات كاملة
6. التكامل: CI/CD + مراقبة وإنذارات

💰 التكلفة: ¥5000-20000/سنة
⏱️ زمن النشر: 1-2 أسبوع
🎯 مناسب لـ: مؤسسات كبيرة، وثائق المنتجات

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