Currently Available: Need a skilled Software Developer for your next project?
Categories
WordPress

Converting WordPress Handbooks to Markdown for LLMs

Choose the Handbook Content and Define the Markdown Output

Choose one named WordPress handbook and decide which pages belong in its export before converting anything. WordPress documentation spans different collections and audiences, including user documentation and developer handbooks. Mixing them without labels makes the Markdown harder to navigate and can blur which guidance belongs to which handbook. The WordPress documentation index and Developer Resources help distinguish these collections.

Set a clear boundary between public pages and restricted material. Public pages available through the WordPress REST API are a practical export source; the API follows the site’s access restrictions, so a public export does not include content a visitor cannot access. If the handbook includes restricted pages, identify an authorized source for them and keep them separate from a public export unless readers should see both. For custom WordPress content types, check whether REST API support is enabled through show_in_rest, the setting that exposes that content type through the API. WordPress’s REST API guidance describes that setting.

Preserve the handbook’s page hierarchy and order. WordPress page records include a parent page and menu_order, a value used to order pages within a parent. Use those fields to arrange chapters and child pages, rather than sorting titles alphabetically. A working handbook exporter uses parent and menu-order relationships to build its table of contents and page sequence.

Choose one Markdown file per handbook when readers need a portable snapshot that is easy to load as a single document. Choose separate files when pages need independent updates, links, or retrieval. The exporter demonstrates the single-file approach by creating separate Markdown outputs for different documentation collections. A per-page layout can use stable, lowercase filenames based on page slugs, with directories that mirror chapter groups. Whichever layout you choose, retain the handbook name and page titles so the file paths and headings remain understandable outside WordPress.

For a single file, use one H1 for the handbook title, H2 headings for top-level pages, and lower heading levels for nested pages and their internal sections. For separate files, use one H1 for each page title and preserve the parent-child relationship in the directory structure or a short breadcrumb. Keep each page’s canonical URL and, when available, its last-modified date. Add the export date at the handbook level; it records when the Markdown copy was made, while page-level dates indicate when WordPress last changed the source. The WordPress pages reference documents the page fields used to preserve this structure and source information.

Set the handbook boundary

Choose the pages that belong to the handbook before exporting. A clear boundary might be all published child pages beneath a handbook’s root page. If the handbook shares a WordPress site with unrelated documentation, select its root or an explicit set of page IDs instead of exporting every page.

Keep public and restricted material separate. Include published pages intended for public readers. Exclude drafts and private pages, along with content restricted by membership or another access rule. An authenticated export can retrieve material that public readers cannot access, so apply the same permission checks as the source site. If restricted pages belong in the output, put them in a separate file set and preserve the access controls around that set.

Decide how to handle pages outside the boundary, such as landing pages or supporting reference pages. Record exclusions when they explain gaps in the hierarchy, and avoid adding unrelated material simply because it appears in the same menu.

Extract WordPress Handbook Pages and Convert Them to Markdown

Choose the extraction method based on access and scale. The WordPress REST API suits repeatable exports: it returns page data, including rendered content and page fields, as structured JSON. If the handbook uses a custom content type, its owner must expose that type through the API, for example with WordPress’s show_in_rest setting. The API paginates large collections, so request every page of results rather than saving only the first response. See the REST API pages reference, pagination guidance, and instructions for custom content types.

A WordPress export works well when you have authorized site access and need a snapshot. It gives you source content to parse, but you still need to convert that content to Markdown. A crawler, which visits public pages and extracts their content, is useful when the API or an export is unavailable. Crawlers depend on page layout, so theme changes can disrupt extraction. A public project demonstrates the API approach by converting WordPress documentation into Markdown files. Its exporter provides a reference for a repeatable conversion.

Whichever method you use, isolate each page’s article body before converting it. With the REST API, start from the page’s content field. With a crawler, identify the main article region and exclude menus, sidebars, footers, cookie notices, and other repeated theme elements. Compare a few extracted pages with their live versions: a selector that captures the title and article but excludes navigation is more reliable than removing elements by broad tag names.

Preserve the structure readers need to follow technical instructions. Map HTML heading levels to matching Markdown headings; keep numbered and bulleted lists. Retain fenced code blocks with language labels when the source provides them. Convert simple tables to Markdown tables. For tables with merged cells or complicated layouts, use a clear text representation or retain the HTML rather than producing a misleading table. Keep descriptive link text and preserve useful destinations. Include an image’s alt text or caption when it conveys information. For an informative diagram, retain a source link or add a concise description. Keep an embed’s URL, caption, or transcript when it contains handbook material.

For example, a short HTML passage can become:

<h3>Register a stylesheet</h3>
Use <code>wp_enqueue_style() to load the stylesheet.
Learn about styles
### Register a stylesheet

Use <code>wp_enqueue_style() to load the stylesheet.

[Learn about styles](/themes/styles/)

Check the converted output for lost code, broken links, and content accidentally pulled from the theme. Store each page’s source URL alongside its Markdown so readers can trace the text to the maintained handbook.

Preserve Page Context, Links, and Metadata for LLM Use

Keep each handbook page identifiable after conversion. Record its title and canonical source URL. Add its parent page or chapter and its position in the handbook. Include the last-modified date when WordPress provides one. Store the export date separately: it shows when the Markdown copy was created, while a page’s modification date describes the source. WordPress page records expose fields such as parent, menu_order, link, and modified, and the wp-docs-md exporter uses parent and menu-order data to preserve page sequence.

Keep pages as separate files when you need to update or retrieve them independently. If you combine them into one file, mark each page boundary and retain its title and metadata so a model can distinguish one source page from the next. A table of contents should reflect the handbook’s parent-child structure rather than sort pages alphabetically. For example, place a chapter’s child pages beneath that chapter in the contents, following the ordering recorded by WordPress.

Preserve cross-references as links. Include each page’s canonical URL so readers can check it against the maintained source, and point links between exported pages to stable local targets. Use a page’s slug or another stable identifier to generate those targets consistently; title-derived anchors can break when titles change or when Markdown renderers handle headings differently. Keep external links pointed at their original destinations. The WordPress page fields provide the source URL and hierarchy information needed to build these relationships.

Remove repeated site chrome, such as the same header, footer, cookie notice, or global navigation repeated on every page. Keep context that explains where the page belongs: its title, parent chapter, breadcrumb path, and links to related handbook pages. Repeated chrome adds noise; page ancestry and cross-references help a model interpret the content.

Validate and Prepare the Markdown Corpus for LLM Workflows

Check the exported WordPress handbook against its page inventory before using it with an LLM. Compare each page’s canonical URL or stable identifier with the export to find missing pages and duplicates. Then inspect heading levels for skipped or repeated structure. Test internal and external links. Compare representative pages with the live handbook to catch code examples or tables that conversion dropped or damaged. The wp-docs-md exporter shows one way to preserve page order and separate page content.

Check file encoding as well. Save files as UTF-8 and look for replacement characters such as � or garbled text such as ’, which can indicate that characters were decoded incorrectly. Review code fences, table rows, and punctuation around any suspicious text against the source page.

Split long pages without losing context

A chunk is a smaller passage that an LLM workflow searches or supplies to a model. Split a page when its full text exceeds the workflow’s input limit or when a long page combines sections that answer distinct questions. Split at heading boundaries where possible, so each chunk covers a coherent topic.

Give every chunk enough context to identify its origin: include the handbook and page title, canonical URL, and heading path, such as Theme Handbook > Templates > Template Parts. Keep code examples and tables intact when they explain the same topic as the surrounding text. If a section must span multiple chunks, preserve its heading context in each chunk rather than leaving later passages detached from their subject.

Choose chunk size and format by testing them in the intended LLM workflow. A setup that searches passages before answering has different needs from one that loads a whole handbook into a prompt, so a universal chunk size would not fit both.

Test retrieval with real handbook questions

Test the prepared corpus with representative queries readers are likely to ask. Include questions about a named feature, a procedure, a code example, and a cross-reference to another page. For each query, record the source page or passage that should answer it, then check whether retrieval returns that passage with enough surrounding context to be useful.

Try alternate wording for the same question. If results omit the relevant section, return an unrelated duplicate, or cut off a code sample, adjust the chunk boundaries or stored context and run the tests again. Keep a small set of these queries as a regression check when you regenerate the handbook export.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com

Email updates

Usually a new article and a few links I found interesting.

No spam. Unsubscribe with one click.

Leave a Reply

Your email address will not be published. Required fields are marked *