How syncs work

Every push to main that touches your docs folder runs the workflow, and the workflow syncs the whole folder to your knowledge base.

The repository is the whole truth#

A sync makes the knowledge base match the folder:

• A new file creates an article or FAQ.
• A changed file updates it.
• A deleted file removes it. Records the folder no longer has are deleted.

There is nowhere else to edit articles and FAQs, so nothing is lost: the dashboard only lists what synced.

All or nothing#

Each sync runs as one transaction. If anything in the folder is invalid — two files that land on the same URL, a site.json link to an article that doesn't exist — the run fails and nothing changes. The live docs stay exactly as they were until the folder is fixed and pushed again.

Safe to repeat#

A sync is idempotent: running it twice does the same thing as running it once. Unchanged files produce no writes, so re-running a workflow is always fine.

Out-of-order runs#

The workflow queues runs so they land in commit order. As a second guard, a commit older than the one already live is skipped rather than published, so a slow run can never roll your docs back. The run says so in its log.

Renaming and reordering#

Renumbering is safe. Moving 01-install.md to 03-install.md keeps the same article and the same URL.

Renaming the part that becomes the URL is a new article. install.md to setup.md removes /install and creates /setup. Rename deliberately, or set slug: in frontmatter to keep the old URL — see Project layout.

Checking a change before it publishes#

The workflow from the GitHub tab runs on pushes to main only. To check changes in review, add pull_request to its triggers:

on:
  push:
    branches: [main]
    paths: ["docs/**", ".github/workflows/askvoro.yml"]
  pull_request:
    paths: ["docs/**"]

Pull request runs are dry runs. They check the folder (duplicate URLs, broken site.json links) and report a +N ~N -N =N line (created, updated, deleted, unchanged), and they never publish.

When something goes wrong#

The run says the token was rejected. It was revoked or belongs to another workspace. Create a new one on the knowledge base's GitHub tab and update the ASKVORO_TOKEN secret.

The workflow didn't run. It only runs for changes inside the docs folder (or to the workflow file). Check the paths filter matches INPUT_DIRECTORY.

The run passed but nothing changed. Check INPUT_WORKSPACE and INPUT_KNOWLEDGE_BASE. A handle that doesn't exist yet creates a new knowledge base, so a typo publishes somewhere new rather than failing.