Docs as code

Site navigation

Your articles are the content of a docs site. site.json is everything around them: the links in the header, the footer, and where to find you elsewhere.

Put it next to .askvoro, at the root of your docs folder. It is optional — without one you get today's header (your workspace mark plus a Get support button) and no footer.

json

{
  "header": {
    "links": [
      { "label": "Pricing", "href": "https://example.com/pricing" },
      { "label": "Sign in", "href": "https://example.com/login", "variant": "secondary" },
      { "label": "Get started", "href": "https://example.com/signup", "variant": "primary" }
    ]
  },
  "footer": {
    "groups": [
      {
        "title": "Product",
        "links": [
          { "label": "Install", "href": "/install" },
          { "label": "CLI", "href": "/cli-install" }
        ]
      },
      {
        "title": "Company",
        "links": [{ "label": "Blog", "href": "https://example.com/blog" }]
      }
    ],
    "note": "© Example Inc."
  },
  "links": {
    "website": "https://example.com",
    "github": "https://github.com/example"
  }
}

Links#

label and href are required. Everything else has a sensible default.

An href can be:

/relative — an article in this same knowledge base. /install resolves to /~/<workspace>/<knowledge-base>/install. Use these for anything inside your docs: they survive a workspace or knowledge-base rename, and the same site.json works if you push it somewhere else.
https://… — anywhere on the web.
mailto:… — an email address.

Nothing else is accepted. A relative link that doesn't match any article in the folder you're pushing fails the push, so your navigation can't quietly rot into 404s.

Variant#

variant picks the style: link (the default, plain text), secondary (an outlined button), primary (a filled button in your brand color), or ghost.

There is deliberately no className and no custom CSS. Every option resolves to a design token from your workspace's appearance settings, so your docs site can't drift off-brand or break its own layout.

Target#

Absolute links open in a new tab and relative ones don't, so you rarely write target. Set "target": "self" or "target": "blank" to override.

Up to 8 links. The built-in Get support button stays unless you turn it off:

json

{ "header": { "support": false } }

Up to 6 groups of up to 8 links each, plus a note — the copyright line, which defaults to your workspace name.

Site links#

links is a fixed set of well-known keys, all absolute https:// URLs: website, documentation, support, contact, github, twitter, linkedin, discord, youtube. Unknown keys are ignored.

Where it lives#

site.json is pushed into the knowledge base itself, in the same transaction as your articles — so the CLI and the dashboard are two editors of one value, the way article SEO already works.

That means:

Push with a site.json, and it replaces whatever is stored.
Push without one, and the stored value is left alone. A repo that never adopts navigation won't wipe out chrome someone set in the dashboard.
Set "site": false in .askvoro to explicitly clear it.
askvoro pull writes dashboard edits back into site.json.

To keep it somewhere else, point at it: "site": "config/chrome.json". A configured path that doesn't exist fails the push; the default site.json is allowed to be missing.