Sync docs from Markdown

Use Documentation → Sync docs to validate repository documentation and synchronize it with documentation posts on the dedicated documentation site.

Opening it

Open Documentation → Sync docs. The page displays the documentation source directory it will scan. Confirm that directory before running anything.

You need permission to edit and create documentation posts and to manage their categories. The screen refuses the operation when any required permission is missing.

Prerequisites

• The product has a numbered, public-safe docs tree.
• Every topic contains its index document.
• The product manifest uses schema version 1 and lists every Markdown basename exactly once.
• Directory and Markdown basenames do not collide with another maintained product.
• Source changes have been reviewed before synchronization, especially when they affect already published documents.
• Keep the source Markdown in English and configure the target languages in one active multilingual plugin: Polylang or POM Translate.
• Long documents can take several minutes to translate. Keep the synchronization tab open and use a hosting request timeout that supports the full 330-second document request. If a request times out, wait for any active synchronization to finish and run the tool again; completed translations are reused.
• For Polylang, enable Documentation and its categories, configure one English source language, and use Polylang Pro with shared slugs, pretty permalinks and language-specific URLs. Translation synchronization requires Polylang 3.7 or later.
• With POM Translate, configure English as the main language so the canonical document and its URLs represent the English source.
• Automatic translation must be configured by the site administrator. It uses DeepSeek and can incur provider charges.

What it does

For every Markdown file it finds:

• Creates a post if none matches it. New posts are created as drafts, so nothing is published without an editor's decision.
• Updates an existing post when it needs the canonical content. Existing posts keep their current status — a published document stays published.
• Creates the categories that mirror the directory structure, and normalizes their slugs.
• Applies the manifest order to each document.
• Sets the title from the first Markdown level-one heading and derives the post slug from the source filename.
• Stores a Markdown-rendering shortcode as the post content, so the repository file remains the canonical body.
• Translates the complete document into each active non-English language. Missing translations are generated; current translations are reused; a changed English source causes a fresh translation from the complete source. Image names, code, Markdown destinations and URL slugs are preserved.
• Creates language posts with Polylang, links their translations and assigns translated categories. Each language post has the same slug and reading order, with an explicit language in its shortcode. With POM Translate, one canonical post serves all languages. Its visible title and the document title used by WordPress and Rank Math follow the selected language.

Synchronization does not publish new documents, delete posts whose source disappeared or decide whether an orphaned post should remain public.

Translation jobs run sequentially, one provider request per document and target language. Documents up to 256 KB are supported. A failed or invalid response leaves the previous translation available. Run synchronization again to resume: accepted translations are reused even if their language post needs repair. Interrupted Polylang associations are repaired using the existing language copies; synchronization does not create replacements for copies in Trash. Keep the browser tab open; closing it stops the remaining queue. A failed request may still have incurred a provider charge.

Existing Polylang categories can be reused when their language, slug and parent match the documentation hierarchy, even if their translation links have not been set up yet. Synchronization links those categories and updates their translated names without changing their IDs or slugs. A category already associated with another source or an unrelated translation group requires an editor to resolve that association first.

The top-level pom-knowledge directory is intentionally excluded. Its business-knowledge Markdown is not product documentation, so the scan does not enter that directory, validate it as a product, or create synchronization tasks from its files.

Running it

1. Confirm the displayed source directory.
2. Select Scan and sync docs.
3. Keep the page open while Progress moves through scanning, task processing and the orphan check.
4. Read Tasks. Each file reports pending, create, update, created, updated, already synchronized or failed. A failure shows its reason immediately beside the task; the summary includes edit links for synchronized posts.
5. Read the final Summary and record any failure or post without a source.

Reading the summary

The last one is the most useful line on the screen. It finds documents left behind after a file was renamed or deleted — the quiet way a documentation site accumulates pages nobody maintains.

When there are none, it says so.

Failures

A failed task explains itself. Common cases include:

• The Markdown path is invalid — the file is outside the documentation source directory.
• Another Markdown file resolves to the same identity — two files would produce the same post and category. Resolve the basename or path collision in the source.
• Manifest validation failed — the manifest is missing, malformed, incomplete, duplicated or lists a file in the wrong directory. Correct it before trying again.
• A protected marker is missing, repeated or unknown, or code and links were reordered — the response was rejected. The previous translation remains available; retry synchronization.
• The translation changed Markdown structure — compare emphasis, table cells, lists and code formatting with the English source. The error identifies the first differing rendered element. Matching element names can indicate changed technical attributes or code content.
• The source changed during translation — run synchronization again to translate the latest complete source.
• A translated slug could not be kept — review the language configuration and conflicting post or category. Synchronization does not silently assign a different slug.
• Another item uses the same translated URL — resolve the conflicting URL in POM Translate and synchronize again. The document keeps its original slug and its accepted translation is reused.
• Several language copies belong to one source — review and correct the duplicate Polylang associations before retrying.
• An existing category belongs to another source or translation group — review its language and translation associations. Synchronization will not detach an unrelated category to reuse its slug.
• A document is in Trash — restore it before synchronizing its source or translation.

After synchronizing

1. Review every new draft. New documents are not published for you.
2. Review affected published posts. Their status is preserved, so a synchronized change can be public immediately.
3. Check "Posts without a Markdown source" and decide separately whether to restore the file, draft the post or move it to trash.
4. Check the reading order and navigation on the public site. They come from the source hierarchy and manifest.

Edit source content and translations

A synchronized document's content comes from its Markdown file. Editing it in the WordPress editor works right up until the next synchronization, which overwrites it.

Change the English Markdown and synchronize again. To correct a translation, open its documentation post, expand Document translations, edit the translated title or complete Markdown and save the post. The same translations are available when editing the canonical source post.

Keep code, link destinations and Markdown structure unchanged. Edits are validated before saving. The panel retains the previous accepted translation for copying and recovery. Manual corrections remain in use while the English source is unchanged; changing the source deliberately replaces them with a fresh translation during synchronization.

Keep the literal brand name POM Theme and the same number of references. Its position around inline code may follow the target language's natural grammar; code, links and interface paths must retain their original order.

If an edit is rejected or conflicts with a newer translation, the panel keeps a private recovery copy of your submitted edits for 24 hours. Copy and review it before retrying; the accepted translation continues to appear to readers.

After switching from Polylang to POM Translate, configure matching target locales and synchronize again. Stored translations are reused, canonical shortcodes become automatic, and former Polylang copies remain stored for editorial review while public documentation queries and Rank Math sitemaps use canonical posts. Review language URLs, publication status, navigation and links before making the switch public.

Expected result

Every valid source file is created, updated or reported as already synchronized; no task remains failed; and every source-less post is listed for an editor's decision. New posts remain drafts until explicitly published.

Order comes from the manifest

Each product's manifest lists its documents in reading order, and synchronization applies that order. Reordering a synchronized document by hand in the Docs library is undone the next time you synchronize.

Troubleshooting

• You are not allowed to synchronize: request the required documentation post and category permissions; do not share an administrator account.
• A post is unchanged: check whether the task says Already synchronized, then verify you edited the source file in the displayed source directory.
• A renamed file leaves two posts: synchronization does not delete the old post. Review it under Posts without a Markdown source.
• Order changes do not appear: confirm the manifest array changed, synchronize again and clear any relevant page cache.