Knowledge Base

Scitor’s knowledge base feature lets you build a professional help center or documentation website directly from markdown files in your GitHub repository. Every time you push changes, the site is automatically rebuilt and deployed.

Quick start

1. Create a docs/ folder in your repository
2. Add an index.md file with your homepage content
3. Add a docs configuration to your .github/scitor.yaml:

docs:
  path: docs
  title: "My Product Docs"
  theme: default
  color: "#4F46E5"
  search: true

4. Push to your default branch — Scitor builds and deploys your site automatically

Your documentation is available at:

https://docs.scitor.io/{owner}/{repo}

Writing documentation

Markdown files

Create .md files in your docs folder. Each file becomes a page on your site.

docs/
├── index.md              → yoursite.com/
├── getting-started.md    → yoursite.com/getting-started/
├── guides/
│   ├── index.md          → yoursite.com/guides/
│   ├── installation.md   → yoursite.com/guides/installation/
│   └── configuration.md  → yoursite.com/guides/configuration/
└── api/
    ├── index.md          → yoursite.com/api/
    └── webhooks.md       → yoursite.com/api/webhooks/

Frontmatter

Add YAML frontmatter at the top of each file to control metadata and navigation:

---
title: Installation Guide
description: How to install and configure the product
order: 1
category: Getting Started
tags: [setup, install, quickstart]
icon: 🔧
hidden: false
featured: true
related: [configuration, quickstart]
---

# Installation Guide

Your content here...

Navigation ordering

Pages in the sidebar are sorted by:

1. Frontmatter order — Explicit numeric order (lowest first)
2. Numeric prefix — Files like 01-intro.md, 02-setup.md are sorted by number
3. Alphabetical — Remaining files sorted by name

Callout blocks

Use callout containers to highlight important information:

The syntax uses triple-colon fences:

:::tip Optional custom title
Your callout content here.
:::

:::warning
Default title is used if none provided.
:::

Code blocks with syntax highlighting

Code blocks are automatically syntax-highlighted when you specify a language:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Renders as:

function greet(name) {
  return `Hello, ${name}!`;
}

A Copy button appears on hover for easy clipboard copying. Supported languages include JavaScript, TypeScript, Python, Go, Rust, Ruby, Java, C#, Shell, YAML, JSON, HTML, CSS, and many more.

Themes

Three built-in themes are available:

Default

The standard documentation theme with a sidebar, table of contents, and clean typography. Suitable for most projects.

Minimal

A focused, centered layout without a sidebar. Uses serif typography for a clean, blog-like reading experience. Great for smaller documentation sets.

docs:
  theme: minimal

Corporate

A professional theme with a branded header, wider sidebar, and corporate styling. The header uses your primary color as the background.

docs:
  theme: corporate

Homepage layout

The homepage of your docs site can be displayed in two layouts:

Cards (default)

The card-grid layout turns your docs homepage into a help center with category cards, article counts, and a suggested articles section — similar to support portals like Zendesk or Intercom.

Each top-level folder in your docs becomes a category card. The card shows:

• The folder’s icon and title from its index.md frontmatter
• The description from the folder’s index.md
• A count of articles in that folder

docs:
  homepage: cards   # This is the default

To get the best results with the cards layout:

1. Organize your docs into top-level folders (one per category)
2. Give each folder an index.md with a title, description, and icon in the frontmatter
3. Mark your most important articles with featured: true (up to 5)

Classic

The classic layout renders your root index.md content as a regular article page with the standard sidebar and table of contents. This is the original layout and is useful for smaller documentation sets.

docs:
  homepage: classic

Featured articles

Mark articles with featured: true in their frontmatter to promote them in a “Suggested Articles” section on the cards homepage:

---
title: Getting Started
description: Set up your account in under 5 minutes.
featured: true
---

Up to 5 featured articles are shown on the homepage. If more than 5 articles have featured: true, the first 5 (by navigation order) are used.

Featured articles display the article’s title and description. Articles without a description are still shown but without the subtitle.

Related articles

Link articles together by adding related slugs to the frontmatter. Related articles appear as a card grid at the bottom of the article page:

---
title: Email Setup
related: [getting-started, custom-email-domain, commands]
---

The slug is the URL path of the target article (e.g., getting-started/email-setup or just email-setup). Unknown slugs or hidden articles are silently skipped.

Related articles show the target’s title and description, linking directly to the page. This is a powerful way to guide readers to relevant content and reduce support requests.

Contact form

You can embed a contact form directly in your docs site, allowing visitors to reach out when they can’t find what they’re looking for. The form creates a GitHub Issue or Discussion through the same pipeline as emails and web forms.

See Web Forms for full details on the contact form configuration and placement options.

docs:
  contact:
    placement: [footer, floating]

Site features

Search

Client-side search is enabled by default. Press ⌘K (or Ctrl+K) to open the search dialog. Features include:

• Multi-word fuzzy matching
• Title matches ranked higher than content matches
• Keyboard navigation with arrow keys
• Instant results with debounced input

Dark mode

A theme toggle in the header lets visitors switch between light and dark modes. The preference is saved in the browser.

Responsive design

The site is fully responsive with:

• Collapsible sidebar on mobile
• Hamburger menu for navigation
• Optimized code block scrolling

SEO

Each page includes:

• <title> and meta description from frontmatter
• Open Graph tags for social sharing
• robots.txt and sitemap.xml (with custom domain)
• Semantic HTML structure

Custom domains

Host your docs on your own domain instead of docs.scitor.io/{owner}/{repo}.

Option 1: Configure in scitor.yaml (recommended)

The simplest approach — add the domain field to your docs configuration:

docs:
  path: docs
  title: "My Docs"
  domain: support.yourcompany.com

Then add a CNAME DNS record pointing your domain to Scitor:

support.yourcompany.com  CNAME  docs.scitor.io

On the next push (or manual /docs build), Scitor automatically registers the domain and starts serving your documentation at https://support.yourcompany.com.

When you set a custom domain:

• All navigation links use root-relative paths (no /owner/repo prefix)
• A sitemap.xml and robots.txt are generated with your domain
• SSL is handled automatically via Cloudflare

To remove the custom domain, simply delete the domain line from your scitor.yaml and push.

Option 2: Configure via slash command

You can also manage domains with slash commands in any issue or discussion:

1. Register your domain:

   /docs domain add support.yourcompany.com
   

2. Add a DNS CNAME record:

   support.yourcompany.com  CNAME  docs.scitor.io
   

3. Wait for DNS propagation (5-15 minutes), then verify:

   /docs domain verify
   

To remove:

/docs domain remove

DNS setup details

Most DNS providers propagate changes within 5-15 minutes. During this time, the domain may not resolve. After propagation, Scitor automatically provisions an SSL certificate via Cloudflare.

Automatic builds

Scitor monitors your repository for changes. When you push to the default branch and the push includes changes in your docs folder (or scitor.yaml), a rebuild is triggered automatically.

To manually trigger a rebuild:

/docs build

To check the current build status:

/docs status

Analytics

Track visitor behavior by adding analytics to your docs:

docs:
  analytics:
    google: G-XXXXXXXXXX
    plausible: yourdomain.com

Both Google Analytics and Plausible are supported.

Versioning

Serve multiple versions of your documentation from different branches:

docs:
  versions:
    - label: "v2.0 (Latest)"
      ref: main
    - label: "v1.0"
      ref: v1-stable

A version switcher dropdown appears in the header.