Add 345 Html Python files: General

html/arabic/python/general/convert-html-to-markdown-complete-programming-guide/_index.md

@@ -0,0 +1,283 @@
+---
+category: general
+date: 2026-05-28
+description: حوّل HTML إلى Markdown باستخدام Aspose.HTML للغة بايثون وتعلّم كيفية
+  تضمين الصور في Markdown باستخدام كود سهل خطوة بخطوة.
+draft: false
+keywords:
+- convert html to markdown
+- embed images in markdown
+- how to embed images markdown
+- Aspose.HTML Python
+- HTML to Markdown conversion
+language: ar
+og_description: تحويل HTML إلى markdown باستخدام Aspose.HTML Python. يوضح هذا البرنامج
+  التعليمي كيفية تضمين الصور في markdown ويجيب على سؤال كيفية تضمين الصور في markdown.
+og_title: تحويل HTML إلى Markdown – دليل كامل مع تضمين الصور
+schemas:
+- author: Aspose
+  dateModified: '2026-05-28'
+  description: Convert HTML to markdown using Aspose.HTML for Python and learn how
+    to embed images in markdown with easy step‑by‑step code.
+  headline: Convert HTML to Markdown – Complete Programming Guide
+  type: TechArticle
+- description: Convert HTML to markdown using Aspose.HTML for Python and learn how
+    to embed images in markdown with easy step‑by‑step code.
+  name: Convert HTML to Markdown – Complete Programming Guide
+  steps:
+  - name: Expected Output
+    text: 'Open `embedded_images.md` in any text editor. You should see something
+      like:'
+  - name: 1. Relative Image Paths
+    text: If your HTML uses relative paths like `src="images/pic.png"`, make sure
+      the working directory when you run the script is the same as the HTML file’s
+      folder, or provide an absolute path to the HTML file. The converter resolves
+      the paths relative to the HTML document’s location.
+  - name: 2. Large Images
+    text: 'Embedding very large images can bloat the markdown file (think megabytes
+      of Base64 text). If size becomes a concern, you can selectively embed only certain
+      images:'
+  - name: 3. Unsupported Formats
+    text: 'Aspose.HTML supports PNG, JPEG, GIF, and SVG out of the box. If you have
+      WebP or other exotic formats, convert them to PNG first:'
+  type: HowTo
+- questions:
+  - answer: Yes. Aspose.HTML is cross‑platform because it runs on .NET Core under
+      the hood. Just ensure you have the appropriate runtime (`dotnet` runtime) installed.
+    question: Does this work on Windows, macOS, and Linux?
+  - answer: Absolutely. Wrap the `convert_html_to_markdown` call in a loop that iterates
+      over `os.listdir()` and filters for `.html` extensions.
+    question: Can I convert a whole folder of HTML files at once?
+  - answer: 'Set `resource_opts.embed_images = False`. The converter will emit standard
+      markdown image links pointing to the original files. ## Wrap‑Up We’ve just covered
+      **how to convert HTML to markdown** using Aspose.HTML for Python, and we’ve
+      shown the exact steps to **embed images in markdown** so your docu'
+    question: What if I need to keep the original image files instead of embedding
+      them?
+  type: FAQPage
+tags:
+- Python
+- Aspose
+- Markdown
+- HTML
+title: تحويل HTML إلى Markdown – دليل برمجي شامل
+url: /ar/python/general/convert-html-to-markdown-complete-programming-guide/
+---
+
+{{< blocks/products/pf/main-wrap-class >}}
+{{< blocks/products/pf/main-container >}}
+{{< blocks/products/pf/tutorial-page-section >}}
+
+# تحويل HTML إلى Markdown – دليل برمجة كامل
+
+هل تساءلت يومًا كيف **تحويل HTML إلى markdown** دون فقدان أي من الصور المضمنة؟ لست الوحيد. يواجه العديد من المطورين مشكلة عندما تنتهي ملفات markdown بروابط صور مكسورة أو، والأسوأ، صور مفقودة تمامًا.  
+
+الأخبار السارة؟ ببضع أسطر من Python و Aspose.HTML يمكنك تحويل أي صفحة HTML إلى markdown نظيف *و* تضمين كل صورة مُشار إليها مباشرة داخل ملف الإخراج. في هذا الدليل سنستعرض العملية بالكامل، من تثبيت المكتبة إلى معالجة الحالات الخاصة مثل المسارات النسبية. بنهاية القراءة ستعرف بالضبط **كيف تُضمّن الصور بأسلوب markdown**، بحيث تظل وثائقك قابلة للنقل.
+
+## المتطلبات المسبقة – ما ستحتاجه
+
+- **Python 3.8+** – أي نسخة حديثة تعمل.
+- **pip** – مدير الحزم القياسي.
+- اتصال إنترنت لجلب حزمة Aspose.HTML.
+- ملف HTML تجريبي (`sample.html`) يحتوي على الأقل على وسم `<img>` واحد.
+
+إذا كان لديك كل ذلك، ممتاز. إذا لم يكن، افتح الطرفية واكتب:
+
+```bash
+pip install aspose-html
+```
+
+هذا الأمر الواحد يجلب مكتبة **Aspose.HTML for Python via .NET**، التي تقوم بالعمل الشاق خلف الكواليس.
+
+> **نصيحة احترافية:** استخدم بيئة افتراضية (`python -m venv venv`) للحفاظ على نظافة الاعتمادات.
+
+## الخطوة 1: تحميل مستند HTML المصدر
+
+أولاً، نحتاج إلى توجيه المحول إلى ملف HTML الذي نريد تحويله. فكر في `HTMLDocument` كغلاف يقرأ الملف ويبني شجرة DOM في الذاكرة.
+
+```python
+from aspose.html import Converter, HTMLDocument, MarkdownSaveOptions, ResourceHandlingOptions
+
+# Load the HTML file – replace the path with your actual file location
+html_path = "YOUR_DIRECTORY/sample.html"
+html_doc = HTMLDocument(html_path)
+
+print(f"Loaded HTML document from: {html_path}")
+```
+
+> **لماذا هذا مهم:** تحميل المستند يمنحنا الوصول إلى جميع الموارد المرتبطة (أوراق الأنماط، السكريبتات، الصور). بدون هذه الخطوة لن يكون لدى المحول ما يعمل عليه.
+
+## الخطوة 2: إخبار المحول بتضمين الصور
+
+بشكل افتراضي، يقوم Aspose.HTML بنسخ عناوين URL للصور إلى markdown، مما يتركك مع روابط مكسورة إذا لم تُستضاف الصور على الإنترنت. لت **تضمين الصور في markdown**، نقوم بتفعيل علم في `ResourceHandlingOptions`.
+
+```python
+# Create resource handling options
+resource_opts = ResourceHandlingOptions()
+resource_opts.embed_images = True   # This makes every <img> become a base64 data URI
+
+print("Resource handling configured: embed_images =", resource_opts.embed_images)
+```
+
+> **كيف يعمل:** عندما تكون `embed_images` مساوية لـ `True`، يقرأ المحول كل ملف صورة، يشفّرها بصيغة Base64، ويُدرجها كـ data URI داخل صيغة صورة markdown (`![](data:image/png;base64,…)`). هذا يضمن أن يكون markdown مستقلاً بذاته.
+
+## الخطوة 3: ربط خيارات حفظ markdown
+
+الآن نجمع إعدادات الموارد مع تكوين إخراج markdown. `MarkdownSaveOptions` يتيح لنا ربط `resource_opts` التي عرّفناها للتو.
+
+```python
+# Set up Markdown save options and attach the resource handling configuration
+markdown_opts = MarkdownSaveOptions()
+markdown_opts.resource_handling_options = resource_opts
+
+print("Markdown save options prepared with resource handling.")
+```
+
+> **ما الذي ستحصل عليه:** بربط `resource_handling_options`، يعرف المحول تطبيق قاعدة تضمين الصور أثناء مرحلة الحفظ.
+
+## الخطوة 4: تنفيذ التحويل
+
+أخيرًا، نستدعي الطريقة الساكنة `convert_html`. تأخذ ثلاث معطيات: مستند HTML المحمّل، خيارات الحفظ، ومسار ملف markdown الوجهة.
+
+```python
+# Destination markdown file – change the path as needed
+output_md = "YOUR_DIRECTORY/embedded_images.md"
+
+# Run the conversion
+Converter.convert_html(html_doc, markdown_opts, output_md)
+
+print(f"Conversion complete! Markdown saved to: {output_md}")
+```
+
+### النتيجة المتوقعة
+
+افتح `embedded_images.md` في أي محرر نصوص. يجب أن ترى شيئًا مثل:
+
+```markdown
+# Sample Title
+
+Here is a paragraph with an embedded image:
+
+![](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...)
+```
+
+كل وسم صورة من `sample.html` أصبح الآن data URI، مما يعني أن ملف markdown يمكن نقله دون فقدان الصور.
+
+## معالجة الحالات الشائعة
+
+### 1. مسارات الصور النسبية
+
+إذا كان HTML الخاص بك يستخدم مسارات نسبية مثل `src="images/pic.png"`، تأكد من أن دليل العمل عند تشغيل السكريبت هو نفسه دليل ملف HTML، أو قدم مسارًا مطلقًا لملف HTML. يقوم المحول بحل المسارات نسبةً إلى موقع مستند HTML.
+
+```python
+# Example: using an absolute path to avoid confusion
+import os
+base_dir = os.path.abspath("YOUR_DIRECTORY")
+html_doc = HTMLDocument(os.path.join(base_dir, "sample.html"))
+```
+
+### 2. الصور الكبيرة
+
+تضمين صور كبيرة جدًا قد يثقل ملف markdown (تفكر في ميغابايت من نص Base64). إذا أصبحت الحجم مشكلة، يمكنك اختيار تضمين صور معينة فقط:
+
+```python
+def should_embed(image_path):
+    # Embed only images smaller than 200KB
+    return os.path.getsize(image_path) < 200 * 1024
+
+resource_opts.embed_images = False  # Start with no embedding
+resource_opts.embed_images_filter = should_embed
+```
+
+*(ملاحظة: `embed_images_filter` هو نقطة توصيل افتراضية؛ إذا لم تُظهر نسخة المكتبة التي تستخدمها هذا الخيار، سيتعين عليك معالجة الصور مسبقًا بنفسك.)*
+
+### 3. الصيغ غير المدعومة
+
+يدعم Aspose.HTML صيغ PNG، JPEG، GIF، و SVG مباشرة. إذا كان لديك WebP أو صيغ أخرى غير شائعة، حوّلها إلى PNG أولًا:
+
+```python
+from PIL import Image
+Image.open("image.webp").save("image.png")
+```
+
+## السكريبت الكامل العامل
+
+بجمع كل ما سبق، إليك سكريبت جاهز للتنفيذ يمكنك وضعه في ملف اسمه `html_to_md.py`:
+
+```python
+# html_to_md.py
+import os
+from aspose.html import Converter, HTMLDocument, MarkdownSaveOptions, ResourceHandlingOptions
+
+def convert_html_to_markdown(input_html: str, output_md: str):
+    # Load HTML
+    html_doc = HTMLDocument(input_html)
+
+    # Configure resource handling to embed all images
+    resource_opts = ResourceHandlingOptions()
+    resource_opts.embed_images = True
+
+    # Set markdown options with the resource handling config
+    markdown_opts = MarkdownSaveOptions()
+    markdown_opts.resource_handling_options = resource_opts
+
+    # Perform conversion
+    Converter.convert_html(html_doc, markdown_opts, output_md)
+
+    print(f"✅ Conversion finished. Markdown with embedded images saved to: {output_md}")
+
+if __name__ == "__main__":
+    # Adjust these paths to match your environment
+    base_dir = os.path.abspath("YOUR_DIRECTORY")
+    html_path = os.path.join(base_dir, "sample.html")
+    md_path   = os.path.join(base_dir, "embedded_images.md")
+
+    convert_html_to_markdown(html_path, md_path)
+```
+
+شغّله باستخدام:
+
+```bash
+python html_to_md.py
+```
+
+إذا سارت الأمور بسلاسة، سترى رسالة ✅ وملف markdown يحتوي على **تضمين الصور في markdown** تلقائيًا.
+
+## الأسئلة المتكررة
+
+**س: هل يعمل هذا على Windows و macOS و Linux؟**  
+ج: نعم. Aspose.HTML متعدد المنصات لأنه يعمل على .NET Core في الخلفية. فقط تأكد من تثبيت بيئة التشغيل المناسبة (`dotnet` runtime).
+
+**س: هل يمكنني تحويل مجلد كامل من ملفات HTML مرة واحدة؟**  
+ج: بالتأكيد. ضع استدعاء `convert_html_to_markdown` داخل حلقة تتنقل عبر `os.listdir()` وتفلتر الملفات ذات الامتداد `.html`.
+
+**س: ماذا لو أردت الاحتفاظ بملفات الصور الأصلية بدلاً من تضمينها؟**  
+ج: عيّن `resource_opts.embed_images = False`. سيُصدر المحول روابط صور markdown عادية تشير إلى الملفات الأصلية.
+
+## الخلاصة
+
+لقد غطينا **كيفية تحويل HTML إلى markdown** باستخدام Aspose.HTML للـ Python، وأظهرنا الخطوات الدقيقة **لتضمين الصور في markdown** بحيث تظل مستنداتك قابلة للنقل. من تثبيت الحزمة، تحميل HTML، تكوين معالجة الموارد، إلى تشغيل التحويل—كل قطعة تتكامل مع الأخرى كقطعة أحجية.
+
+الآن يمكنك أخذ أي صفحة ويب، تدوينة، أو تقرير مُولَّد وتحويله إلى ملف markdown واحد متكامل. الخطوات التالية قد تشمل:
+
+- إضافة امتدادات markdown مخصصة (جداول، حواشي سفلية).
+- أتمتة التحويلات الجماعية لمولدات المواقع الثابتة.
+- استخدام نفس النهج **لتحويل HTML إلى صيغ أخرى** (PDF، DOCX).
+
+جرّبه، عدّل الخيارات لتناسب مشروعك، ودع الصور المضمّنة تحافظ على مظهر markdown حادًا أينما شاركته.
+
+--- 
+
+![مثال على تحويل HTML إلى Markdown](/images/convert-html-to-markdown.png "لقطة شاشة تُظهر نتيجة التحويل مع الصور المضمّنة")
+
+
+## دروس ذات صلة
+
+- [تحويل HTML إلى Markdown في Aspose.HTML للـ Java](/html/english/java/saving-html-documents/convert-html-to-markdown/)
+- [تحويل HTML إلى Markdown في .NET باستخدام Aspose.HTML](/html/english/net/html-extensions-and-conversions/convert-html-to-markdown/)
+- [Markdown إلى HTML Java - التحويل باستخدام Aspose.HTML](/html/english/java/conversion-html-to-other-formats/convert-markdown-to-html/)
+
+{{< /blocks/products/pf/tutorial-page-section >}}
+{{< /blocks/products/pf/main-container >}}
+{{< /blocks/products/pf/main-wrap-class >}}
+{{< blocks/products/products-backtop-button >}}