Handling Headings and Sections

Why headings matter when chunking WooCommerce content

Headings are structural signals, not just visual formatting. In WooCommerce documentation, a heading often identifies the product, workflow, API resource, or failure condition that gives the following paragraphs their meaning. A paragraph about stock status means something different under “REST API response fields” than under “Checkout troubleshooting.”

If a chunk contains body text without its parent headings, retrieval may return technically correct text with the wrong context. A support assistant could retrieve instructions for updating a product but omit whether the instructions apply to the block editor, the REST API, or a custom integration.

Preserve the heading hierarchy during parsing

When processing documents with LlamaParse, retain the heading text and its level in the parsed representation whenever the selected output format supports that structure. Markdown output commonly represents headings with # characters, while HTML output uses elements such as <h1>, <h2>, and <h3>. The exact output depends on the parser configuration and source document, so the ingestion pipeline should normalize the result rather than assume that every heading is detected perfectly.

A normalized section record can look like this:

{
  "level": 2,
  "title": "Configure backorders",
  "path": ["Products", "Inventory", "Configure backorders"],
  "content": "Enable backorders when customers should be allowed to purchase..."
}

The path is especially useful. It gives every chunk the complete structural context without requiring the retrieval system to reconstruct that context later.

Use sections as the primary chunk boundary

For most WooCommerce guides, begin a new chunk at a meaningful section heading rather than splitting at an arbitrary character count. A section about configuring payment retries should normally stay together, including its prerequisites, steps, code samples, and warnings.

For example, a document might be organized as follows:

• Payments
  • Configure retry behavior
  • Handle failed renewal payments
• Subscriptions
  • Change the renewal date

The resulting chunks should carry their heading path as metadata:

{
  "section_path": [
    "Payments",
    "Configure retry behavior"
  ],
  "text": "Configure the retry interval in...",
  "source": "payment-operations-guide.pdf"
}

This approach improves both retrieval precision and result presentation. A search result can display the section path, and the generated answer can cite the exact operational area instead of showing an isolated paragraph.

Keep parent context with child sections

Many documents use short child headings such as “Requirements,” “Example,” or “Troubleshooting.” Those labels are ambiguous without their parents. A chunk titled only “Example” could refer to a checkout hook, an order query, or a subscription renewal process.

When a child section is chunked independently, prepend a compact context header to the chunk:

<context>
Documentation area: WooCommerce > Orders > Retrieve orders with the REST API
Section: Example
</context>

Use the <code>status parameter to limit the response to processing orders.

The context can be stored as metadata, added to the text sent to the embedding model, or both. Avoid duplicating large parent sections in every child chunk; preserve the heading path and include only the concise information needed to disambiguate the child.

Do not split operational steps from their conditions

Procedural sections need special handling. A numbered sequence often depends on an introductory condition, a note, or a warning immediately before or after the list. Splitting those elements into separate chunks can produce unsafe or incomplete instructions.

For a WooCommerce agency handoff, keep the following together when possible:

• The scenario or prerequisite, such as testing in staging.
• The ordered steps for changing the setting or calling the endpoint.
• Required permissions, dependencies, and version constraints.
• Warnings about cache invalidation, webhooks, stock reservations, or customer data.
• The expected result and a way to verify it.

If the complete procedure exceeds the target chunk size, split at a step boundary and repeat the procedure title and relevant conditions in each continuation chunk. Do not divide a code sample, an API request and its explanation, or a warning from the step it qualifies.

Handle heading levels defensively

Source files often contain inconsistent formatting. A visual heading may be represented as bold text, a larger font, a numbered paragraph, or a line that resembles a heading but is actually part of a sentence. Parser output should therefore be validated before it is used to create sections.

Useful normalization rules include:

1. Trim repeated whitespace and normalize line breaks in heading text.
2. Remove purely decorative numbering only if the original number is not meaningful to the reader.
3. Preserve product names, endpoint paths, hook names, and version numbers exactly.
4. Repair skipped levels for navigation purposes, but retain the original level in source metadata when auditability matters.
5. Reject very long “headings” that contain several sentences and are more likely to be body text.
6. Detect repeated headers and footers so they do not become sections in every page.

Do not blindly convert every bold line into an h2. A heading detector should consider typography, position, repetition, punctuation, surrounding content, and the document’s existing outline.

Separate navigation headings from content headings

Web pages and exported PDFs may contain menus, breadcrumbs, sidebars, table-of-contents entries, and repeated page headers. These elements can look like valid headings but do not provide useful document content. Filter or label them separately before chunking.

For WordPress and WooCommerce documentation, distinguish the following:

• Content headings: headings that introduce instructions, explanations, reference material, or troubleshooting information.
• Navigation labels: menu items, breadcrumbs, related-content links, and table-of-contents entries.
• Template headings: repeated labels such as “Related articles” or “Was this helpful?”

Keeping navigation data may still be useful for page reconstruction, but it should not be embedded as if it were substantive guidance.

Chunk headings with tables, lists, and code

A heading frequently governs more than paragraphs. It may introduce a settings table, a list of supported order statuses, a PHP hook example, or a JSON response. Treat these elements as part of the section until the next peer or ancestor heading appears.

For example, a section describing a custom order status should keep the status name, registration code, usage instructions, and limitations in the same structural group. If a table is too large for one chunk, repeat its column headings in each continuation chunk and preserve the table’s relationship to the parent section.

Code should remain textually intact. A chunking process should not split a PHP function, REST request, JSON object, or shell command in the middle of a syntax unit. Store the language when it is known:

<section>
  <heading level="2">Register a custom order status</heading>
  <code language="php">
    add_action( 'init', 'register_custom_order_status' );
  </code>
</section>

Use heading-aware overlap instead of arbitrary overlap

Fixed token overlap is useful, but it should not be the only continuity mechanism. A practical strategy is to carry the section path into every chunk and apply small overlap only within a section. When a section ends, start the next section cleanly rather than copying unrelated text across the boundary.

For long sections, use a hierarchy-aware algorithm:

1. Parse the document into heading and content nodes.
2. Build a stack of active parent headings as each node is read.
3. Group paragraphs, lists, tables, and code under the current heading path.
4. Accumulate nodes until the token target is reached.
5. Split only between semantic blocks, preferably after a paragraph or list item.
6. Attach the heading path and source location to every resulting chunk.

A chunk may therefore contain a repeated context prefix while its body contains only one portion of a long section. This is generally safer than allowing a high-level heading to become detached from the instructions it governs.

Validate section boundaries before indexing

Before sending chunks to an embedding or search index, run structural checks. These checks are particularly important when an agency processes client-specific manuals, implementation runbooks, and exported ticket histories.

• Confirm that every chunk has a nonempty source identifier.
• Check that the section path is ordered from broadest to narrowest.
• Flag chunks containing a child heading without its parent context.
• Detect code blocks, tables, and lists that were split unexpectedly.
• Compare the combined chunk text with the parsed source to identify dropped content.
• Record page, paragraph, or character offsets for citation and review.

In retrieval testing, ask targeted questions such as “How do we retry a failed subscription payment?” and “Which permission is required to update an order through the API?” Inspect whether the returned chunks include the correct parent heading, prerequisites, version details, and complete procedure.

Store useful heading metadata

A compact metadata model makes the same chunks useful for semantic search, filtering, navigation, and answer citations. Common fields include:

• heading: the immediate section title.
• section_path: the complete hierarchy of parent headings.
• heading_level: the normalized level.
• document_type: such as API reference, implementation guide, or support runbook.
• source_url or source_file: the canonical origin.
• page_start and page_end: useful for PDF review.
• version: the WooCommerce, WordPress, extension, or API version where applicable.

For agency projects, also consider storing the client, site, environment, and access scope as controlled metadata rather than embedding those values in the section text. That supports filtering while reducing accidental cross-client retrieval.

Practical implementation pattern

A reliable pipeline for heading-aware chunking can be organized into five stages:

1. Parse: use LlamaParse to extract structured text from PDFs and other supported documents.
2. Normalize: convert headings, paragraphs, lists, tables, and code into a consistent internal node model.
3. Outline: build the heading tree and assign each content node a section path.
4. Chunk: group semantic blocks to the target token size while protecting procedures and code.
5. Index: store the text, heading metadata, source location, and version information for retrieval.

The key design decision is to make section context part of the data model from the beginning. Reconstructing it after arbitrary chunking is unreliable, especially when multiple documents contain headings with the same short names.