docs: Clarify inline vs inline_fragment behavior

Stranger6667 · Stranger6667 · commit 7620ae935f39 · 2026-04-02T11:03:16.000+02:00
Signed-off-by: Dmitry Dygalo &lt;dmitry@dygalo.dev&gt;
diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ fn main() -> css_inline::Result<()> {
 
 Note that `css-inline` automatically adds missing `html` and `body` tags, so the output is a valid HTML document.
 
-Alternatively, you can inline CSS into an HTML fragment, preserving the original structure:
+Alternatively, you can inline CSS into an HTML fragment. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output; only their contents are preserved. Use `inline` if you need to keep the full document structure:
 
 ```rust
 const FRAGMENT: &str = r#"<main>
diff --git a/bindings/c/README.md b/bindings/c/README.md
@@ -88,7 +88,7 @@ The inline function, `css_inline_to()`, doesn't allocate, so you must provide an
 
 Note that `css-inline` automatically adds missing `html` and `body` tags, so the output is a valid HTML document.
 
-Alternatively, you can inline CSS into an HTML fragment, preserving the original structure:
+Alternatively, you can inline CSS into an HTML fragment. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output; only their contents are preserved. Use `css_inline_to` if you need to keep the full document structure:
 
 ```c
 #include "css_inline.h"
diff --git a/bindings/java/README.md b/bindings/java/README.md
@@ -160,7 +160,7 @@ public class ConfigExample {
 
 ### HTML Fragments
 
-Alternatively, you can inline CSS into an HTML fragment, preserving the original structure:
+Alternatively, you can inline CSS into an HTML fragment. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output; only their contents are preserved. Use `CssInline.inline` if you need to keep the full document structure:
 
 ```java
 import org.cssinline.CssInline;
diff --git a/bindings/javascript/README.md b/bindings/javascript/README.md
@@ -78,7 +78,7 @@ var inlined = inline(
 
 Note that `css-inline` automatically adds missing `html` and `body` tags, so the output is a valid HTML document.
 
-Alternatively, you can inline CSS into an HTML fragment, preserving the original structure:
+Alternatively, you can inline CSS into an HTML fragment. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output; only their contents are preserved. Use `inline` if you need to keep the full document structure:
 
 ```javascript
 import { inlineFragment } from "@css-inline/css-inline";
diff --git a/bindings/php/README.md b/bindings/php/README.md
@@ -105,7 +105,7 @@ $inlined = CssInline\inline($html);
 
 Note that `css_inline` automatically adds missing `html` and `body` tags, so the output is a valid HTML document.
 
-Alternatively, you can inline CSS into an HTML fragment, preserving the original structure:
+Alternatively, you can inline CSS into an HTML fragment. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output; only their contents are preserved. Use `CssInline\inline` if you need to keep the full document structure:
 
 ```php
 <?php
diff --git a/bindings/python/README.md b/bindings/python/README.md
@@ -90,7 +90,7 @@ inlined = css_inline.inline(HTML)
 
 Note that `css-inline` automatically adds missing `html` and `body` tags, so the output is a valid HTML document.
 
-Alternatively, you can inline CSS into an HTML fragment, preserving the original structure:
+Alternatively, you can inline CSS into an HTML fragment. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output; only their contents are preserved. Use `inline` if you need to keep the full document structure:
 
 ```python
 FRAGMENT = """<main>
diff --git a/bindings/ruby/README.md b/bindings/ruby/README.md
@@ -71,7 +71,7 @@ puts inlined
 
 Note that `css-inline` automatically adds missing `html` and `body` tags, so the output is a valid HTML document.
 
-Alternatively, you can inline CSS into an HTML fragment, preserving the original structure:
+Alternatively, you can inline CSS into an HTML fragment. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output; only their contents are preserved. Use `CSSInline.inline` if you need to keep the full document structure:
 
 ```ruby
 require 'css_inline'
diff --git a/css-inline/src/lib.rs b/css-inline/src/lib.rs
@@ -589,6 +589,14 @@ impl<'a> CSSInliner<'a> {
 
     /// Inline CSS into an HTML fragment.
     ///
+    /// Unlike [`inline`](CSSInliner::inline), this method does not wrap the output in `<html>` and
+    /// `<body>` tags. Structural tags (`<html>`, `<head>`, `<body>`) are stripped from the output;
+    /// only their contents are preserved. CSS from `<style>` tags within the input is also
+    /// processed and inlined.
+    ///
+    /// If you need to preserve the full HTML document structure, use [`inline`](CSSInliner::inline)
+    /// instead.
+    ///
     /// # Errors
     ///
     /// Inlining might fail for the following reasons:
@@ -609,6 +617,8 @@ impl<'a> CSSInliner<'a> {
 
     /// Inline CSS into an HTML fragment and write the result to a generic writer.
     ///
+    /// See [`inline_fragment`](CSSInliner::inline_fragment) for details on fragment handling.
+    ///
     /// # Errors
     ///
     /// Inlining might fail for the following reasons:
@@ -939,6 +949,8 @@ pub fn inline_to<W: Write>(html: &str, target: &mut W) -> Result<()> {
 
 /// Shortcut for inlining CSS into an HTML fragment with default parameters.
 ///
+/// See [`CSSInliner::inline_fragment`] for details on fragment handling.
+///
 /// # Errors
 ///
 /// Inlining might fail for the following reasons:
