[Bug]: html2text后图片的顺序不对

[anylayer]

crawl4ai version

lastest

Expected Behavior

这是请求的url. https://act.quark.cn/apps/qknewsiflow/routes/article?item_id=2810176666376552078&entry=share_search_result&recom=true

Current Behavior

图片顺序不一致

Is this reproducible?

Yes

Inputs Causing the Bug

Steps to Reproduce

Code snippets

OS

macOS

Python version

3.13.5

Browser

vscode markdown preview

Browser version

No response

Error logs & Screenshots (if applicable)

No response

[anylayer]

html2text

origin:

[Ahmed-Tawfik94]

root cause

the issue is that the HTML input provided to the html2text converter contains tags in an incorrect order. The html2text processing preserves the document order of elements as they appear in the HTML source, so if the images are out of sequence in the input HTML, they will appear in the same incorrect order in the markdown output.

This can happen when:

The web page's HTML is dynamically modified by JavaScript after initial load, inserting images in a different order than intended
The page uses lazy loading or asynchronous image insertion that doesn't maintain the desired sequence
The HTML cleaning or scraping process inadvertently reorders elements (though testing shows this doesn't occur in the current implementation)
The html2text library processes elements sequentially as it parses the HTML string, outputting markdown for each tag when encountered. It does not perform any reordering or sorting of images based on visual position, CSS layout, or other factors.

Context

• The issue occurs during HTML-to-markdown conversion in the CustomHTML2Text.handle_tag() method
• Images are processed when <img> tags are encountered during HTML parsing
• The conversion happens after HTML cleaning but before citation processing
• No reordering occurs in the convert_links_to_citations() function for image elements

Solution

The image ordering issue stems from the sequential processing of HTML elements. Since html2text processes elements in document order, ensure the input HTML has images in the correct sequence. If the HTML source has images in the wrong order due to dynamic loading or DOM manipulation, consider preprocessing the HTML to reorder <img> tags before markdown conversion.

Proposed fix: Modify the HTML preprocessing step to sort images by their intended order before passing to html2text. For example:

def reorder_images_in_html(html_content: str) -> str:
    """Reorder img tags in HTML based on custom logic (e.g., data-order attribute)"""
    soup = BeautifulSoup(html_content, 'lxml')
    images = soup.find_all('img')
    # Implement custom ordering logic here
    # For example, sort by a data-order attribute or position
    ordered_images = sorted(images, key=lambda img: img.get('data-order', 0))
    # Reconstruct HTML with ordered images
    # This is a simplified example - actual implementation would need to preserve structure
    return str(soup)

Then integrate this into the markdown generation pipeline before calling h.handle(input_html).

References

• html2text library documentation: https://github.com/Alir3z4/html2text
• crawl4ai CustomHTML2Text implementation in init.py
• DefaultMarkdownGenerator in markdown_generation_strategy.py

[anylayer]

Thank you for sharing the solution ideas! This is really helpful, I appreciate it.

[ntohidi]

@anylayer , hi.

Based on our analysis, image ordering inconsistencies are most likely caused by the page itself rather than Crawl4AI, for example:

• Lazy loading: Images loaded dynamically via JavaScript may appear in the DOM in a different order depending on scroll timing
• CSS reordering: CSS order, flex, or grid properties can visually reorder images without changing DOM order
• Dynamic rendering: JavaScript may insert or reorder image elements after initial page load

To help us investigate further, could you provide:

1. The actual image order you're getting vs the expected order
2. A saved copy of the page HTML (or at least the relevant section), so we can inspect the DOM order directly
3. Whether the issue is consistent across multiple crawls of the same page, or intermittent
4. your code snippet

This will help us determine if there's a specific scenario where Crawl4AI's extraction diverges from the visible page order.