For WooCommerce agencies, a useful chunking strategy should preserve the structure that gives a document meaning. A returns policy, shipping guide, or product implementation manual is not just a sequence of paragraphs: headings define the scope of the content that follows. Unstructured’s title-based chunking strategy uses those section boundaries when creating chunks.
What title-based chunking does
Unstructured first partitions a source document into semantic elements such as titles, paragraphs, list items, and tables. The by_title strategy then groups those elements into chunks while avoiding unnecessary movement across section boundaries.
This is useful for retrieval systems because a chunk headed International Returns is more meaningful than a character window that begins halfway through a section and ends inside a different topic.
Basic implementation
The following example processes an HTML document and groups its elements by title:
from unstructured.partition.html import partition_html
from unstructured.chunking.title import chunk_by_title
elements = partition_html(filename="returns-policy.html")
chunks = chunk_by_title(
elements,
max_characters=1800,
new_after_n_chars=1400,
combine_text_under_n_chars=300,
)
for index, chunk in enumerate(chunks):
print(f"Chunk {index}:\n{chunk.text}\n")max_characters is the hard size limit for a chunk. new_after_n_chars is a preferred size at which Unstructured starts a new chunk when a suitable boundary is available. combine_text_under_n_chars allows small adjacent sections to be combined rather than producing many very short chunks.
Why this works well for WooCommerce content
WooCommerce stores and agency-managed projects commonly contain structured documentation, including:
- Shipping and delivery policies
- Returns, refunds, and warranty pages
- Product installation and configuration guides
- Subscription and renewal documentation
- Marketplace or vendor onboarding instructions
- Internal runbooks for checkout, payments, and fulfillment
When these documents are indexed for search or used in a retrieval-augmented support workflow, preserving headings helps keep related facts together. For example, payment instructions under Apple Pay should not be mixed with an unrelated section describing bank transfer refunds.
Choosing the chunking parameters
max_characters
Set this according to the context limits and retrieval behavior of the downstream system. A value between 1,200 and 2,000 characters is often a practical starting point for support documentation, but the correct value depends on the embedding model, language, and average section length.
new_after_n_chars
This is a soft target rather than an unconditional split point. A section can exceed this value if splitting it would damage its structure, but Unstructured will generally start another chunk at a title or another suitable boundary once the target is reached.
combine_text_under_n_chars
Small headings and short introductory paragraphs can create fragments that are poor search results by themselves. Combining short sections reduces this problem, especially in documents with many headings such as product setup guides.
Preserving metadata for retrieval
Unstructured elements carry metadata such as the source filename, page number, and coordinates when the partitioning method provides them. Chunk metadata can be inspected and copied into the records sent to a vector store:
records = []
for index, chunk in enumerate(chunks):
records.append({
"id": f"returns-policy-{index}",
"text": chunk.text,
"metadata": {
"source": "returns-policy.html",
"chunk_index": index,
"category": "store-policy",
"element_types": [
type(element).__name__
for element in chunk.metadata.orig_elements or []
],
},
})The exact metadata available depends on the partitioner and document type. In production, treat the source URL, document version, locale, product category, and publication status as first-class metadata. This lets an agency filter retrieval results so that a United Kingdom shopper does not receive a policy intended for the United States.
Partitioning different source formats
The chunking step is independent of the initial partitioning step. For example, an agency can use the appropriate partitioner and then apply the same title-based strategy:
from unstructured.partition.pdf import partition_pdf
from unstructured.partition.docx import partition_docx
from unstructured.chunking.title import chunk_by_title
pdf_elements = partition_pdf(filename="fulfillment-guide.pdf")
pdf_chunks = chunk_by_title(pdf_elements, max_characters=1800)
docx_elements = partition_docx(filename="operations-runbook.docx")
docx_chunks = chunk_by_title(docx_elements, max_characters=1800)For PDFs, title detection quality depends on the document layout and the partitioning options used. Scanned documents may require OCR, and visually prominent text is not always classified as a title. Always inspect representative elements before relying on heading boundaries in an automated pipeline.
Handling long sections and nested headings
A single section can be much longer than the configured maximum. In that case, title-based chunking still needs to split the content. The resulting chunks retain the section context, but a very long section may benefit from additional context enrichment before indexing.
One practical approach is to prepend the active heading path to each chunk:
def add_heading_context(chunk, heading_path):
context = " > ".join(heading_path)
return f"Section: {context}\n\n{chunk.text}"
# Example heading path:
heading_path = ["Shipping", "International Delivery"]
text_for_index = add_heading_context(chunks[0], heading_path)In a real pipeline, build the heading path while iterating through the partitioned elements, updating it whenever a title element is encountered. This is especially valuable for nested WooCommerce documentation such as Payments > Failed Payments > Manual Review.
Operational checks for an agency pipeline
- Log the number of source elements and generated chunks for every document.
- Record the source URL and content revision so stale policy text can be removed from the index.
- Inspect chunks that contain tables, short headings, or lists because these structures can affect retrieval quality.
- Test documents with missing, inconsistent, or incorrectly classified headings.
- Measure retrieval quality using real support questions, such as refund timing or subscription cancellation rules.
- Keep tenant, store, language, and publication-status metadata available for filtering.
Title-based chunking is most effective when the source documents already have meaningful headings. If a client’s content is poorly structured, improving the document templates or adding a normalization step can produce a larger quality improvement than changing the embedding model.