feat(html): add default_content_layer option to HTMLBackendOptions

[M-Hassan-Raza]

Summary

• Adds a default_content_layer option to HTMLBackendOptions that allows users to explicitly set the starting content layer, bypassing the automatic inference based on infer_furniture and header presence
• When None (default), the existing behavior is preserved
• When set (e.g., ContentLayer.BODY), all content starts in that layer regardless of heading presence

This is useful for HTML content from API endpoints that may lack headings but should have all content in the BODY layer.

Closes #2487

Test plan

• pre-commit run --all-files passes (Ruff, MyPy, uv-lock)
• pytest tests/test_backend_html.py — all 20 tests pass (including new test_html_backend_default_content_layer)
• New test verifies that with default_content_layer=ContentLayer.BODY, content before a heading stays in BODY instead of being inferred as FURNITURE

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[dosubot]

Related Documentation

1 document(s) may need updating based on files changed in this PR:

Docling

Content Layers

View Suggested Changes

@@ -94,6 +94,42 @@
 
 Currently, the ability to include furniture in exports is only available via the Python API. The `docling-serve` API and CLI exports do not support specifying content layers and will always export with the default (BODY only).
 
+## HTML Backend Content Layer Options
+
+When processing HTML documents, Docling provides fine-grained control over content layer assignment through `HTMLBackendOptions`. The `default_content_layer` parameter allows you to explicitly set the starting content layer for HTML documents, overriding the automatic inference behavior.
+
+### Automatic Content Layer Inference
+
+By default, when `default_content_layer` is `None`, Docling determines the starting content layer based on:
+1. The `infer_furniture` setting (default: `True`)
+2. The presence of headers in the HTML document
+
+If `infer_furniture` is enabled and headers are present, content before the first header is assigned to the `FURNITURE` layer. Otherwise, all content starts in the `BODY` layer.
+
+### Explicit Content Layer Override
+
+The `default_content_layer` parameter allows you to bypass this inference logic entirely. When set to a specific `ContentLayer` value (e.g., `ContentLayer.BODY`), all content starts in that layer regardless of heading presence or the `infer_furniture` setting.
+
+This is particularly useful for HTML content from API endpoints that may lack headings but should have all content in the `BODY` layer.
+
+**Example:**
+
+```python
+from docling import DocumentConverter
+from docling.datamodel.backend_options import HTMLBackendOptions
+from docling_core.types.doc.document import ContentLayer
+
+# Force all HTML content to start in the BODY layer
+options = HTMLBackendOptions(default_content_layer=ContentLayer.BODY)
+converter = DocumentConverter()
+result = converter.convert(source, options=options)
+```
+
+**Configuration summary:**
+- `default_content_layer=None` (default): Starting layer is determined by `infer_furniture` and header presence
+- `default_content_layer=ContentLayer.BODY`: All content starts in the BODY layer
+- `default_content_layer=ContentLayer.FURNITURE`: All content starts in the FURNITURE layer
+
 ## Customization and Post-processing
 
 Headers and footers are detected automatically by Docling’s layout model for `.docx` files. There is currently no rule-based mechanism to customize their detection during processing. However, you can manually remove or further process these elements after extraction if needed.

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[github-actions]

✅ DCO Check Passed

Thanks @M-Hassan-Raza, all your commits are properly signed off. 🎉

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!