diff --git a/great-docs.yml b/great-docs.yml
index 792706f..81f75fb 100644
--- a/great-docs.yml
+++ b/great-docs.yml
@@ -313,3 +313,10 @@ reference:
         - GreatDocs.build
         - GreatDocs.preview
         - GreatDocs.check_links
+
+    - title: Table Preview
+      desc: Generate styled HTML table previews from any tabular data source
+      contents:
+        - tbl_preview
+        - enable_tbl_preview
+        - disable_tbl_preview
diff --git a/great_docs/_tbl_preview.py b/great_docs/_tbl_preview.py
index 538f386..115b68e 100644
--- a/great_docs/_tbl_preview.py
+++ b/great_docs/_tbl_preview.py
@@ -482,24 +482,31 @@ def _compute_head_tail(
     n_head: int,
     n_tail: int,
     show_all: bool,
+    row_index_offset: int = 0,
 ) -> tuple[list[list], list[int], bool]:
     """Select head and tail rows, compute row numbers.
 
+    Parameters
+    ----------
+    row_index_offset
+        Starting number for row indices (default 0).
+
     Returns
     -------
     tuple
         (display_rows, row_numbers, is_full_dataset)
     """
     if show_all or n_head + n_tail >= total_rows:
-        row_numbers = list(range(1, total_rows + 1))
+        row_numbers = list(range(row_index_offset, row_index_offset + total_rows))
         return rows, row_numbers, True
 
     head_rows = rows[:n_head]
     tail_rows = rows[-n_tail:] if n_tail > 0 else []
     display_rows = head_rows + tail_rows
 
-    head_nums = list(range(1, n_head + 1))
-    tail_nums = list(range(total_rows - n_tail + 1, total_rows + 1)) if n_tail > 0 else []
+    head_nums = list(range(row_index_offset, row_index_offset + n_head))
+    tail_start = row_index_offset + total_rows - n_tail
+    tail_nums = list(range(tail_start, row_index_offset + total_rows)) if n_tail > 0 else []
     row_numbers = head_nums + tail_nums
 
     return display_rows, row_numbers, False
@@ -1108,46 +1115,199 @@ def tbl_preview(
     min_tbl_width: int = 500,
     caption: str | None = None,
     highlight_missing: bool = True,
+    row_index_offset: int = 0,
     id: str | None = None,
 ) -> TblPreview:
-    """Generate a beautiful table preview.
+    """
+    Generate a self-contained HTML table preview from almost any tabular data source.
+
+    The `tbl_preview()` function gives you a quick, polished look at a dataset without pulling in
+    heavy rendering dependencies. Pass it a Polars DataFrame, a Pandas DataFrame, a PyArrow Table,
+    a file path to a CSV / TSV / JSONL / Parquet / Feather file, a column-oriented dictionary, or a
+    list of row dictionaries—and get back a styled HTML table that renders identically in notebooks,
+    Quarto documents, and static HTML pages.
+
+    The preview shows a configurable number of rows from the top and bottom of the table, separated
+    by a blue divider line when the full dataset exceeds the requested row count. Each column header
+    displays the column name and, beneath it, a compact dtype label (e.g., `i64`, `str`, `f64`). A
+    header banner shows a colored badge identifying the data source type (Polars, Pandas, CSV,
+    Parquet, etc.) alongside row and column counts. Missing values (`None`, `NaN`, `NA`) are
+    highlighted in red so they stand out immediately.
+
+    The output is a :class:`TblPreview` object with `_repr_html_()` support, so it displays
+    automatically in Jupyter notebooks and Quarto code cells. All CSS is scoped to a unique id,
+    and the table includes full dark-mode support. No JavaScript is required.
 
     Parameters
     ----------
     data
-        The table data. Accepts a Polars DataFrame, Pandas DataFrame, PyArrow Table, file path (CSV,
-        TSV, JSONL, Parquet, Feather/Arrow IPC), column-oriented dict, or list of row dicts.
+        The table to preview. This can be a Polars DataFrame, a Pandas DataFrame, a PyArrow Table, a
+        file path (as a string or `pathlib.Path` object), a column-oriented dictionary, or a list of
+        row dictionaries. When providing a file path, the extension determines the loader: `.csv`,
+        `.tsv`, `.jsonl` (or `.ndjson`), `.parquet`, `.feather`, and `.arrow` (Arrow IPC) are all
+        supported. Read the *Supported Input Data Types* section for details on each accepted
+        format.
     columns
-        Subset of columns to display. `None` shows all columns.
+        The columns to display in the preview, by default `None` (all columns are shown). This
+        can be a list of column name strings. If any name does not match a column in the table, a
+        `KeyError` is raised. This is useful for focusing on a subset of a wide dataset.
     n_head
-        Number of rows to show from the start of the table.
+        The number of rows to show from the start of the table. Set to `5` by default. When the
+        table has fewer rows than `n_head + n_tail`, the full table is displayed without a
+        divider.
     n_tail
-        Number of rows to show from the end of the table.
+        The number of rows to show from the end of the table. Set to `5` by default.
     limit
-        Maximum allowed sum of `n_head` and `n_tail`.
+        The limit value for the sum of `n_head=` and `n_tail=` (the total number of rows shown).
+        If the sum of `n_head=` and `n_tail=` exceeds the limit, a `ValueError` is raised. The
+        default value is `50`. Increase this when you need to display more rows.
     show_all
-        If `True`, display the entire table (ignores `n_head`/`n_tail`).
+        Should the entire table be displayed? If `True`, all rows are shown regardless of the
+        `n_head=` and `n_tail=` settings. By default, this is `False`.
     show_row_numbers
-        Whether to show a row-number column on the left.
+        Should row numbers be shown? The numbers appear in a narrow gutter column on the left side
+        of the table, separated from the data columns by a subtle blue vertical line. By default,
+        this is set to `True`.
     show_dtypes
-        Whether to show dtype sublabels under column names.
+        Should data type labels be displayed beneath each column name? The labels use short
+        abbreviations (e.g., `i64` for 64-bit integer, `str` for string, `f64` for 64-bit float). By
+        default, this is set to `True`.
     show_dimensions
-        Whether to show the header banner with row/column counts.
+        Should the header banner be shown? The banner displays a colored badge identifying the data
+        source type alongside row and column counts in labeled pill badges. By default, this is set
+        to `True`.
     max_col_width
-        Maximum width of any column in pixels.
+        The maximum width of any single column in pixels. Column widths are computed automatically
+        to fit their content up to this ceiling, beyond which cell text is truncated with an
+        ellipsis. The default value is `250` pixels.
     min_tbl_width
-        Minimum total table width in pixels.
+        The minimum total width of the table in pixels. If the sum of the computed column widths is
+        less than this value, columns are proportionally widened to fill the available space. The
+        default value is `500` pixels.
     caption
-        Optional caption displayed below the header banner.
+        An optional caption string displayed below the header banner and above the column headers.
+        Useful for labeling a preview with a dataset name or description. By default, no caption is
+        shown.
     highlight_missing
-        Whether to highlight missing values (None/NaN/NA).
+        Should missing values (`None`, `NaN`, `NA`) be highlighted? When `True` (the default),
+        missing cells are displayed in red text on a light red background so they stand out at a
+        glance.
+    row_index_offset
+        The starting number for row indices. Defaults to `0`, matching the zero-based indexing
+        convention of Python, Polars, and Pandas. Set to `1` for one-based numbering (e.g., for
+        presentation to audiences unfamiliar with zero-based indexing).
     id
-        HTML id for the table container. Auto-generated if `None`.
+        An HTML `id` attribute for the outer `<div>` container. If `None` (the default), a unique ID
+        is auto-generated using `secrets.token_hex(4)`. Providing your own ID is useful when you
+        need to target the table with custom CSS or JavaScript.
 
     Returns
     -------
     TblPreview
-        Rendered table with `_repr_html_()`, `as_html()`, and `save()` methods.
+        A rendered table preview object. The object has `_repr_html_()` for automatic notebook
+        display.
+
+    Supported Input Data Types
+    --------------------------
+    The `data` parameter accepts any of the following:
+
+    - **Polars DataFrame** — displays a blue *Polars* badge
+    - **Pandas DataFrame** — displays a dark purple *Pandas* badge
+    - **PyArrow Table** — displays an indigo *Arrow* badge
+    - **CSV file** (`.csv`) — loaded automatically; displays a cream *CSV* badge
+    - **TSV file** (`.tsv`) — loaded automatically; displays a green *TSV* badge
+    - **JSONL file** (`.jsonl` or `.ndjson`) — loaded line-by-line; displays a blue *JSONL*
+      badge
+    - **Parquet file** (`.parquet`) — requires `polars`, `pandas`, or `pyarrow`; displays
+      a purple *Parquet* badge
+    - **Feather / Arrow IPC file** (`.feather` or `.arrow`) — requires `polars`, `pandas`,
+      or `pyarrow`; displays an orange *Feather* badge
+    - **Dictionary** (column-oriented, `dict[str, list]`) — displays a gray *Table* badge
+    - **List of dictionaries** (row-oriented, `list[dict]`) — displays a gray *Table* badge
+
+    For file-based inputs, pass a string or `pathlib.Path` object. The file extension is used to
+    determine the format. Polars is preferred for loading when available; Pandas and PyArrow are
+    used as fallbacks.
+
+    Examples
+    --------
+    The simplest way to preview a table is to pass a Python dictionary:
+
+    ```{python}
+    from great_docs import tbl_preview
+
+    tbl_preview({"city": ["Tokyo", "Paris", "New York"], "population": [13960000, 2161000, 8336000]})
+    ```
+
+    The result is a styled HTML table with a header banner showing the row and column count, dtype
+    labels beneath each column name, and row numbers on the left.
+
+    You can also pass a Polars DataFrame:
+
+    ```{python}
+    import polars as pl
+
+    df = pl.DataFrame({
+        "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
+        "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
+        "price": [29.99, 49.50, 12.00, 8.75, 199.99],
+        "in_stock": [True, False, True, True, False],
+    })
+
+    tbl_preview(df)
+    ```
+
+    For large tables, only the first `n_head=` and last `n_tail=` rows are shown, separated by a
+    blue divider line. Adjust the counts to show more or fewer rows:
+
+    ```{python}
+    tbl_preview(df, n_head=2, n_tail=1)
+    ```
+
+    Use `columns=` to focus on specific columns in a wide dataset:
+
+    ```{python}
+    tbl_preview(df, columns=["product", "price"])
+    ```
+
+    File paths work directly—no need to load the data yourself:
+
+    ```{python}
+    #| echo: false
+    #| output: false
+    import pathlib, json
+    _d = pathlib.Path("assets/tbl-preview-data")
+    _d.mkdir(parents=True, exist_ok=True)
+    (_d / "students.csv").write_text(
+        "name,subject,score,grade,passed\\n"
+        "Alice,Math,95.5,A,true\\n"
+        "Bob,Science,82.0,B,true\\n"
+        "Charlie,English,71.3,C,true\\n"
+        "Diana,History,60.0,D,true\\n"
+        "Eve,Art,55.8,F,false\\n"
+        "Frank,Math,88.2,B+,true\\n"
+        "Grace,Science,79.9,C+,true\\n"
+        "Hank,English,91.0,A-,true\\n"
+        "Iris,History,66.4,D+,true\\n"
+        "Jack,Art,73.7,C,true\\n"
+    )
+    ```
+
+    ```{python}
+    tbl_preview("assets/tbl-preview-data/students.csv")
+    ```
+
+    Add a caption to label the preview:
+
+    ```{python}
+    tbl_preview(df, caption="Product Catalog for Q1 2026")
+    ```
+
+    For a minimal look, turn off the header banner, dtype labels, and row numbers:
+
+    ```{python}
+    tbl_preview(df, show_dimensions=False, show_dtypes=False, show_row_numbers=False)
+    ```
     """
     if not show_all and n_head + n_tail > limit:
         raise ValueError(
@@ -1164,7 +1324,7 @@ def tbl_preview(
 
     # 3. Compute head/tail split
     display_rows, row_numbers, is_full = _compute_head_tail(
-        all_rows, total_rows, n_head, n_tail, show_all
+        all_rows, total_rows, n_head, n_tail, show_all, row_index_offset
     )
 
     # 4. Detect alignments
diff --git a/great_docs/_versioned_build.py b/great_docs/_versioned_build.py
index 18a41b8..e846509 100644
--- a/great_docs/_versioned_build.py
+++ b/great_docs/_versioned_build.py
@@ -115,7 +115,7 @@ def _sync_status_inline_script(dest_dir: Path) -> None:
 
     Instead of modifying the existing (large, SVG-laden) `__GD_STATUS_DATA__` script (which breaks
     when round-tripped through yaml12 due to nested quoting issues) we append a tiny new `<script>`
-    that only carries the lightweight `upcoming_pages` map.  The page-status-badges JS reads both
+    that only carries the lightweight `upcoming_pages` map. The page-status-badges JS reads both
     globals.
 
     Must be called AFTER `_update_page_status_json` so that the JSON file contains the
@@ -668,9 +668,9 @@ def _rebuild_api_from_snapshot(
     # --- Update or generate index page ---
     index_path = ref_dir / "index.qmd"
 
-    # Detect whether the existing index is a rich renderer-generated page (has Pandoc
-    # attribute classes like {.doc-label ...}) vs. a plain placeholder.  Rich pages are
-    # preserved and pruned; plain/missing pages are regenerated from the snapshot.
+    # Detect whether the existing index is a rich renderer-generated page (has Pandoc attribute
+    # classes like {.doc-label ...}) vs. a plain placeholder. Rich pages are preserved and pruned;
+    # plain/missing pages are regenerated from the snapshot.
     _has_rich_index = False
     if index_path.exists():
         _idx_content = index_path.read_text(encoding="utf-8")
@@ -755,40 +755,120 @@ def _is_valid_ref_name(name: str, valid_symbols: set[str], valid_classes: set[st
 def _prune_reference_index(
     index_qmd: Path, valid_symbols: set[str], valid_classes: set[str]
 ) -> None:
-    """Remove links/rows for symbols not in the snapshot from reference/index.qmd."""
+    """Remove links/rows for symbols not in the snapshot from reference/index.qmd.
+
+    This handles three levels of cleanup:
+    1. Remove link lines referencing symbols not in the snapshot.
+    2. Remove orphaned definition-list descriptions (`:   ...`) that followed a removed link.
+    3. Remove empty section headers (`## Title {.doc-group}` plus their `.doc-description` divs)
+       when all entries in the section have been removed.
+    """
+    import re
+
     content = index_qmd.read_text(encoding="utf-8")
     lines = content.split("\n")
-    new_lines: list[str] = []
 
-    for line in lines:
-        stripped = line.strip()
+    # --- Pass 1: mark link lines for removal and their trailing description lines ---
+    remove_indices: set[int] = set()
 
-        # Check for definition-list or link-style entries referencing a .qmd file
-        # Patterns: "- [SymbolName](SymbolName.qmd)" or link with anchor
-        import re
+    for i, line in enumerate(lines):
+        stripped = line.strip()
 
         qmd_ref = re.search(r"\(([^)]+)\.qmd(?:#[^)]*)?\)", stripped)
         if qmd_ref:
             symbol_name = qmd_ref.group(1)
             if not _is_valid_ref_name(symbol_name, valid_symbols, valid_classes):
-                continue  # Skip this line
+                remove_indices.add(i)
+                # Also remove the following definition-list description line(s)
+                # Pattern: `:   description text` (Pandoc definition list)
+                j = i + 1
+                while j < len(lines):
+                    next_stripped = lines[j].strip()
+                    if next_stripped == "":
+                        # Blank line between entries — remove it too
+                        remove_indices.add(j)
+                        j += 1
+                        continue
+                    if next_stripped.startswith(":"):
+                        remove_indices.add(j)
+                        j += 1
+                        continue
+                    break
+                continue
 
-        # Also check for bare .qmd references like "  - Name.qmd"
         bare_ref = re.match(r"^\s*-\s+(\S+)\.qmd\s*$", stripped)
         if bare_ref:
             symbol_name = bare_ref.group(1)
             if not _is_valid_ref_name(symbol_name, valid_symbols, valid_classes):
+                remove_indices.add(i)
+
+    filtered = [line for i, line in enumerate(lines) if i not in remove_indices]
+
+    # --- Pass 2: remove empty sections ---
+    # A section block looks like:
+    #   ## Title {.doc-group}
+    #   <blank>
+    #   ::: {.doc-description}
+    #   description text
+    #   :::
+    #   <blank>
+    #   (entries would follow here)
+    #
+    # If the next non-blank content after the closing ::: is another ## heading or EOF,
+    # the section is empty and should be removed entirely.
+    result: list[str] = []
+    idx = 0
+    while idx < len(filtered):
+        line = filtered[idx]
+        stripped = line.strip()
+
+        # Detect a section header with {.doc-group}
+        if stripped.startswith("##") and "{.doc-group}" in stripped:
+            # Collect the entire section header block (header + optional blank +
+            # description div + optional trailing blank)
+            block_start = idx
+            idx += 1
+
+            # Skip blank lines after header
+            while idx < len(filtered) and filtered[idx].strip() == "":
+                idx += 1
+
+            # If there's a ::: {.doc-description} div, consume it
+            if idx < len(filtered) and filtered[idx].strip().startswith("::: {.doc-description"):
+                idx += 1
+                # Consume lines until closing :::
+                while idx < len(filtered) and filtered[idx].strip() != ":::":
+                    idx += 1
+                if idx < len(filtered):
+                    idx += 1  # skip the closing :::
+
+            # Skip trailing blank lines
+            while idx < len(filtered) and filtered[idx].strip() == "":
+                idx += 1
+
+            # Now check if the section has any content: the next line should be
+            # something other than another ## heading or EOF
+            if idx >= len(filtered) or filtered[idx].strip().startswith("##"):
+                # Empty section — drop the entire block by not appending it
                 continue
+            else:
+                # Non-empty section — keep the block
+                result.extend(filtered[block_start:idx])
+        else:
+            result.append(line)
+            idx += 1
 
-        new_lines.append(line)
-
-    index_qmd.write_text("\n".join(new_lines), encoding="utf-8")
+    index_qmd.write_text("\n".join(result), encoding="utf-8")
 
 
 def _prune_quarto_sidebar(
     dest_dir: Path, section: str, valid_symbols: set[str], valid_classes: set[str]
 ) -> None:
-    """Remove sidebar entries for missing symbols/commands from _quarto.yml."""
+    """Remove sidebar entries for missing symbols/commands from _quarto.yml.
+
+    Handles both flat string entries (`reference/Name.qmd`) and nested section groups
+    (`section: Title` with `contents: [...]`). Empty section groups are removed entirely.
+    """
     quarto_yml = dest_dir / "_quarto.yml"
     if not quarto_yml.exists():
         return
@@ -808,32 +888,55 @@ def _prune_quarto_sidebar(
             if not contents:
                 continue
 
-            # Check if this sidebar references our section
-            has_section_ref = any(
-                (isinstance(c, str) and c.startswith(f"{section}/")) for c in contents
-            )
-            if not has_section_ref:
+            # Check if this sidebar has any reference to our section (flat or nested)
+            def _has_section_ref(items: list) -> bool:
+                for c in items:
+                    if isinstance(c, str) and c.startswith(f"{section}/"):
+                        return True
+                    if isinstance(c, dict):
+                        sub = c.get("contents", [])
+                        if sub and _has_section_ref(sub):
+                            return True
+                return False
+
+            if not _has_section_ref(contents):
                 continue
 
-            new_contents = []
-            for item in contents:
-                if isinstance(item, str) and item.startswith(f"{section}/"):
-                    # e.g. "reference/GreatDocs.qmd" → "GreatDocs"
-                    # e.g. "reference/cli/api_diff.qmd" → keep (handled by CLI pruning)
-                    if "/" in item.replace(f"{section}/", "", 1):
-                        # Sub-path like reference/cli/... — keep, CLI pruning handles it
-                        new_contents.append(item)
-                    else:
-                        stem = Path(item).stem
-                        if _is_valid_ref_name(stem, valid_symbols, valid_classes):
-                            new_contents.append(item)
+            def _prune_contents(items: list) -> tuple[list, bool]:
+                """Recursively prune items, returning (new_items, was_modified)."""
+                new_items: list = []
+                changed = False
+                for item in items:
+                    if isinstance(item, str) and item.startswith(f"{section}/"):
+                        if "/" in item.replace(f"{section}/", "", 1):
+                            # Sub-path like reference/cli/... — keep
+                            new_items.append(item)
                         else:
-                            modified = True
-                else:
-                    new_contents.append(item)
+                            stem = Path(item).stem
+                            if _is_valid_ref_name(stem, valid_symbols, valid_classes):
+                                new_items.append(item)
+                            else:
+                                changed = True
+                    elif isinstance(item, dict) and "section" in item:
+                        sub_contents = item.get("contents", [])
+                        pruned_sub, sub_changed = _prune_contents(sub_contents)
+                        if sub_changed:
+                            changed = True
+                        if pruned_sub:
+                            new_item = dict(item)
+                            new_item["contents"] = pruned_sub
+                            new_items.append(new_item)
+                        else:
+                            # All entries removed — drop the entire section group
+                            changed = True
+                    else:
+                        new_items.append(item)
+                return new_items, changed
 
-            if modified:
+            new_contents, was_modified = _prune_contents(contents)
+            if was_modified:
                 sidebar["contents"] = new_contents
+                modified = True
 
         if modified:
             yaml.dump(
diff --git a/great_docs/assets/_extensions/tbl-preview/_tbl_preview_shortcode.py b/great_docs/assets/_extensions/tbl-preview/_tbl_preview_shortcode.py
index 1cf4521..1d105cd 100644
--- a/great_docs/assets/_extensions/tbl-preview/_tbl_preview_shortcode.py
+++ b/great_docs/assets/_extensions/tbl-preview/_tbl_preview_shortcode.py
@@ -46,6 +46,7 @@ def main() -> None:
     parser.add_argument("--max_col_width", type=int, default=250)
     parser.add_argument("--min_tbl_width", type=int, default=500)
     parser.add_argument("--caption", default=None)
+    parser.add_argument("--row_index_offset", type=int, default=0)
     args = parser.parse_args()
 
     tbl_preview = _load_tbl_preview()
@@ -67,6 +68,7 @@ def _to_bool(s: str) -> bool:
         max_col_width=args.max_col_width,
         min_tbl_width=args.min_tbl_width,
         caption=args.caption,
+        row_index_offset=args.row_index_offset,
     )
 
     sys.stdout.write(result.as_html())
diff --git a/great_docs/assets/_extensions/tbl-preview/tbl-preview.lua b/great_docs/assets/_extensions/tbl-preview/tbl-preview.lua
index 54fc8b8..4c01541 100644
--- a/great_docs/assets/_extensions/tbl-preview/tbl-preview.lua
+++ b/great_docs/assets/_extensions/tbl-preview/tbl-preview.lua
@@ -54,6 +54,7 @@ return {
             "columns", "n_head", "n_tail", "show_all",
             "show_row_numbers", "show_dtypes", "show_dimensions",
             "max_col_width", "min_tbl_width", "caption",
+            "row_index_offset",
         }
         for _, key in ipairs(forwarded) do
             local val = kwarg_str(kwargs, key)
diff --git a/tests/test_tbl_preview.py b/tests/test_tbl_preview.py
index 773d3a1..0a37a8d 100644
--- a/tests/test_tbl_preview.py
+++ b/tests/test_tbl_preview.py
@@ -223,8 +223,8 @@ def test_large_dataset_split(self):
         display, nums, is_full = _compute_head_tail(rows, 100, 5, 5, False)
         assert is_full is False
         assert len(display) == 10
-        assert nums[:5] == [1, 2, 3, 4, 5]
-        assert nums[5:] == [96, 97, 98, 99, 100]
+        assert nums[:5] == [0, 1, 2, 3, 4]
+        assert nums[5:] == [95, 96, 97, 98, 99]
 
     def test_show_all(self):
         from great_docs._tbl_preview import _compute_head_tail
@@ -241,7 +241,7 @@ def test_zero_tail(self):
         display, nums, is_full = _compute_head_tail(rows, 20, 5, 0, False)
         assert is_full is False
         assert len(display) == 5
-        assert nums == [1, 2, 3, 4, 5]
+        assert nums == [0, 1, 2, 3, 4]
 
 
 # ---------------------------------------------------------------------------
@@ -1526,7 +1526,7 @@ def test_row_numbers_present(self):
 
         html = tbl_preview(_PARAM_DATA, show_all=True, show_row_numbers=True).as_html()
         nums = _extract_row_numbers(html)
-        assert nums == [str(i) for i in range(1, 11)]
+        assert nums == [str(i) for i in range(0, 10)]
 
     def test_row_numbers_absent(self):
         from great_docs._tbl_preview import tbl_preview
@@ -1543,6 +1543,22 @@ def test_row_numbers_head_tail(self):
 
         html = tbl_preview(_PARAM_DATA, n_head=2, n_tail=2).as_html()
         nums = _extract_row_numbers(html)
+        assert nums == ["0", "1", "8", "9"]
+
+    def test_row_index_offset_one(self):
+        from great_docs._tbl_preview import tbl_preview
+
+        html = tbl_preview(
+            _PARAM_DATA, show_all=True, show_row_numbers=True, row_index_offset=1
+        ).as_html()
+        nums = _extract_row_numbers(html)
+        assert nums == [str(i) for i in range(1, 11)]
+
+    def test_row_index_offset_head_tail(self):
+        from great_docs._tbl_preview import tbl_preview
+
+        html = tbl_preview(_PARAM_DATA, n_head=2, n_tail=2, row_index_offset=1).as_html()
+        nums = _extract_row_numbers(html)
         assert nums == ["1", "2", "9", "10"]
 
     # -- highlight_missing -------------------------------------------------
diff --git a/user_guide/30-table-previews.qmd b/user_guide/30-table-previews.qmd
index 559d757..dc16ed9 100644
--- a/user_guide/30-table-previews.qmd
+++ b/user_guide/30-table-previews.qmd
@@ -97,6 +97,19 @@ tbl_preview({
 
 The result is a styled HTML table with a header banner showing the row and column count, dtype labels beneath each column name, and row numbers on the left. This single function call is all it takes to go from raw data to a polished preview.
 
+:::{.callout-tip}
+## Hiding the Code Cell
+
+Most of the time you'll want to show just the table itself, not the underlying generation code. Add `#| echo: false` at the top of the code cell to hide the source and display only the rendered preview:
+
+````markdown
+```{{python}}
+#| echo: false
+tbl_preview({"city": ["Tokyo", "Paris"], "country": ["Japan", "France"]})
+```
+````
+:::
+
 ## Data Sources
 
 `tbl_preview()` accepts many different input types, so you can pass whatever data structure your project already uses. Each source type gets a distinct colored badge in the header banner, making it easy to tell at a glance what kind of data is being displayed.
@@ -353,7 +366,7 @@ Captions are useful when multiple previews appear on the same page, giving each
 
 ### Row Numbers
 
-Row numbers appear in a left-hand gutter by default. They reflect the original row positions, even when head/tail splitting is active. To hide them:
+Row numbers appear in a left-hand gutter by default, starting from 0 to match Python, Polars, and Pandas 0-based indexing. They reflect the original row positions, even when head/tail splitting is active. To hide them:
 
 ```{python}
 tbl_preview(
@@ -365,6 +378,20 @@ tbl_preview(
 
 Hiding row numbers is useful for small reference tables where the row position isn't meaningful.
 
+### Row Index Offset
+
+If you prefer 1-based numbering (or any other starting value), set `row_index_offset`:
+
+```{python}
+tbl_preview(
+    {"x": [1, 2, 3], "y": [4, 5, 6]},
+    show_all=True,
+    row_index_offset=1,
+)
+```
+
+The offset applies to all rows, including tail rows in head/tail splits. The default of `0` keeps row numbers consistent with what you see when inspecting a DataFrame in Python.
+
 ### Dtype Labels
 
 Compact dtype labels appear beneath each column name (e.g., `str`, `i64`, `f64`). To hide them:
@@ -487,6 +514,7 @@ The full set of shortcode parameters mirrors the Python function:
 | `max_col_width` | string | `"250"` | Maximum column width in pixels |
 | `min_tbl_width` | string | `"500"` | Minimum total table width in pixels |
 | `caption` | string | — | Caption text below the header banner |
+| `row_index_offset` | string | `"0"` | Starting row number (use `"1"` for 1-based) |
 
 The shortcode supports every file format listed in the [Supported File Extensions](#supported-file-extensions) table.
 
@@ -540,6 +568,7 @@ The table below lists every parameter available on the `tbl_preview()` function.
 | `min_tbl_width` | `int` | `500` | Minimum table width (px) |
 | `caption` | `str` | `None` | Caption text |
 | `highlight_missing` | `bool` | `True` | Highlight missing values |
+| `row_index_offset` | `int` | `0` | Starting row number (0-based by default) |
 | `id` | `str` | auto | Custom HTML `id` for the container |
 
 The return value is a `TblPreview` object with `_repr_html_()` (for notebook display), `as_html()` (returns the HTML string), and `save(path)` (writes HTML to a file) methods.