Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

[Bug]: Markdown export loses heading hierarchy and table structure

オープン
  • 何か問題がありますか？
#1,964 コメント 3 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
42/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
静か
技術スタック
python
領域
content

調査の方向性

Start by reproducing the issue with the documented crwl ... -o markdown and -o html commands on a page containing nested headings and an HTML table, then compare the outputs. Identify the markdown conversion entry point and existing tests, and define done as preserving heading levels and producing valid table structure, or documenting an explicit alternative and configuration behavior.

索引モデルが issue の本文から書いたものです。

説明

❓ Question
crawl4ai version

0.8.6

Expected Behavior

When converting a page with clear document structure in HTML, the markdown output should preserve:

  1. Heading hierarchy — h1 through h6 levels mapped to # through ###### consistently
  2. Table structure — HTML <table> elements converted to valid GitHub-flavored markdown tables (or documented alternative)

Alternatively, provide explicit configuration options or separate commands so users can choose between:

  • Fast/minimal markdown (current behavior, smaller output)
  • Structure-preserving markdown (accurate headings, proper tables)

Suggested naming:

  • Config approach: markdown.mode: "compact" | "semantic" or markdown.preserve_structure: true
  • Separate commands: md-lite / md-semantic (CLI), crawl4ai_md / crawl4ai_md_semantic (MCP)

Suggested resolution

Option A — Configuration flags:

{
  "crawler_config": {
    "markdown": {
      "mode": "semantic",
      "preserve_headings": true,
      "preserve_tables": "gfm"
    }
  }
}

Option B — Separate commands/endpoints:

Use case CLI flag MCP tool name
Fast, minimal -o markdown or -o md-lite crawl4ai_md
Structure-preserving -o md-semantic crawl4ai_md_semantic
Current Behavior

For the same URL and crawl settings, markdown output loses or degrades structural information that is preserved in HTML:

Element HTML Output Markdown Output
Headings Clear h1 > h2 > h3 nesting Levels flattened or inconsistent
Tables Valid <table> with rows/columns Flattened to lists, paragraphs, or lost entirely

Users must switch to HTML output and manually extract structure, defeating markdown's purpose as a readable, structured format.

Is this reproducible?

Yes

Inputs Causing the Bug
- **Documentation pages** with hierarchical sections (single `h1`, multiple `h2`/`h3` levels)
- **Data pages** with comparison tables, specification tables, or course lists in `<table>` markup
- **Any public URL** (or local HTML fixture) containing structured content
Steps to Reproduce
1. Identify a page with known heading hierarchy (`h1` → `h2` → `h3`) and at least one HTML table
2. Crawl with **markdown** output:
   
   crwl 'https://example.invalid/test-page' -o markdown
   
3. Crawl the **same page** with **HTML** output:
   
   crwl 'https://example.invalid/test-page' -o html
   
4. Compare:
   - Count heading levels in markdown vs HTML DOM
   - Check if table structure is preserved as `|` delimited markdown
5. Observe: markdown flattens headings and loses table formatting
Code snippets
**CLI comparison:**

# Markdown - structure loss visible here
crwl 'https://example.invalid/test-page' -o markdown > output.md

# HTML - structure preserved
crwl 'https://example.invalid/test-page' -o html > output.html


**HTTP API:**

# Markdown request
curl -sS 'http://localhost:PORT/crawl' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": ["https://example.invalid/test-page"],
    "crawler_config": { "cache_mode": "bypass" }
  }' | jq -r '.results[0].markdown.raw_markdown'

# HTML request for comparison
curl -sS 'http://localhost:PORT/crawl' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": ["https://example.invalid/test-page"],
    "crawler_config": { "cache_mode": "bypass" }
  }' | jq -r '.results[0].html'
OS

Debian GNU/Linux 12 (bookworm)

Python version

3.12.13

Browser

No response

Browser version

No response

Error logs & Screenshots (if applicable)

No response

主要言語
Python
スター
84.5k
フォーク
8.7k
平均マージ
3日 20時間
マージ済み PR（30日）
15

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

unclecode/crawl4ai のほかの issue

unclecode/crawl4ai の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。