← Back to blog

Building a Support Knowledge Base with GitHub Markdown

· Scitor Team

After a few months of running customer support through GitHub, you notice patterns. The same questions appear again and again. Customers ask how to configure OAuth, how to handle rate limits, or what happens when a webhook fails. Your team writes good answers, but they are buried in closed Issues, invisible to the next person who needs them.

You need a knowledge base. But the last thing you want is another tool to maintain—a separate documentation site with its own login, its own deployment pipeline, and its own drift from reality.

The solution is simpler than you think: GitHub Markdown as your knowledge base. Your docs live in the same repository as your support tickets, version-controlled, searchable, and automatically deployed.

Here is how to set it up.

Step 1: Create a docs folder

Start with a docs/ folder in your repository. This is where all your customer-facing documentation lives. The structure is up to you, but a typical layout looks like:

docs/
  getting-started.md
  authentication.md
  webhooks.md
  api/
    rate-limits.md
    error-handling.md
  guides/
    oauth-setup.md
    troubleshooting-common-issues.md
  faq.md

Each file is plain Markdown. No special syntax, no CMS, no metadata beyond what you want to include. Write your docs the same way you write README files.

Step 2: Convert support answers into docs

The best documentation comes from real support conversations. When a customer asks a good question and you write a thorough answer, extract that into a doc.

Example: A customer asks about webhook retries

Your GitHub Issue might look like this:

Customer: “If our webhook endpoint is down, does Scitor retry?”

Your reply: “Yes, Scitor retries failed webhooks with exponential backoff: 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours. After 5 failures, the webhook is marked as failed and you’ll see a label on the issue. You can manually retry with /webhook retry. Webhooks time out after 30 seconds, so make sure your endpoint responds quickly or processes async.”

That is good information. Turn it into a doc:

docs/webhooks.md

# Webhooks

## Retry behavior

When a webhook delivery fails, Scitor automatically retries with exponential backoff:

- 1 minute
- 5 minutes
- 15 minutes
- 1 hour
- 6 hours

After 5 consecutive failures, the webhook is marked as failed and the issue receives a `webhook:failed` label.

## Manual retry

Use the `/webhook retry` command on any issue to manually retry a failed webhook.

## Timeout

Webhook requests time out after 30 seconds. If your endpoint takes longer than this, return a 202 response immediately and process the webhook asynchronously.

Now when the next customer asks about webhooks, you link to the doc instead of rewriting the explanation.

Step 3: Use frontmatter for metadata

Add YAML frontmatter to control how docs are organized and displayed:

---
title: Webhook Configuration
description: Set up and troubleshoot webhook integrations
order: 3
---

# Webhook Configuration

Your content here...

This metadata helps when you auto-generate a documentation site (covered below). The order field controls navigation ordering.

Step 4: Create saved replies for common responses

Some questions are so common they need instant responses. Use saved replies to turn a command into a formatted answer.

Create .github/scitor/replies/ in your repository:

.github/scitor/replies/rate-limits.md

Hi {{customer_name}},

API rate limits depend on your plan:

- **Free**: 100 requests/hour
- **Pro**: 1,000 requests/hour
- **Enterprise**: 10,000 requests/hour

You can check your current usage at https://app.yourcompany.com/usage.

If you're hitting limits, consider:
- Caching responses that don't change frequently
- Using batch endpoints instead of individual requests
- Upgrading your plan

More details in our [rate limits documentation](https://yourcompany.com/docs/api/rate-limits).

Let me know if you have questions!

.github/scitor/replies/billing-faq.md

Hi {{customer_name}},

Here's a quick billing overview:

**Billing cycle**: Monthly, starting from your signup date  
**Payment methods**: Credit card or invoice (Enterprise only)  
**Prorated charges**: If you upgrade mid-cycle, you're charged the difference immediately  
**Downgrades**: Take effect at the end of the current billing cycle

Full details: https://yourcompany.com/docs/billing

Questions about a specific charge? Let me know the invoice number and I'll look it up.

Now when a customer asks about rate limits, you type:

/reply rate-limits

Scitor expands the template, replaces {{customer_name}} with the customer’s name, and sends the formatted email. The customer receives a professional response in seconds, and you avoided retyping the same answer for the 47th time.

Step 5: Auto-deploy your docs as a website

GitHub Markdown is useful on its own, but most customers do not browse your repository. They want a website. With Scitor’s knowledge base feature, your docs/ folder becomes a live website automatically.

Add this to .github/scitor.yaml:

docs:
  path: docs
  title: "Your Company Support Docs"
  logo: images/logo.png
  domain: support.yourcompany.com
  theme: default
  search: true
  footer: "© 2026 Your Company"
  
  contact:
    placement: [footer, floating]
    title: "Need help?"
    description: "Can't find what you're looking for? Send us a message."

On every commit to your default branch, Scitor rebuilds your docs site. Changes go live in under a minute. No separate CI/CD pipeline, no manual deploys, no static site generator to configure.

The generated site includes:

  • Automatic navigation based on your folder structure
  • Client-side search across all docs
  • Responsive design that works on mobile
  • Custom domain support (bring your own DNS)
  • Contact form so customers can email you directly from the docs

Once your docs site is live, reference it constantly in support responses:

Hi there,

The authentication flow is documented here: https://yourcompany.com/docs/authentication

The short version:
1. Request an OAuth token
2. Include it in the `Authorization` header
3. Refresh tokens expire after 7 days

Let me know if you hit any issues!

/send

Over time, more customers find answers in the docs before emailing. Your support volume drops, and the questions you do receive are more nuanced (which is where you add the most value).

Step 7: Version your docs

If you support multiple versions of your API or product, use Git branches or tags to version your docs.

In .github/scitor.yaml:

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

Customers can switch between versions in the docs UI. Each version reflects the docs in that Git ref, so historical documentation stays accurate.

Real examples

Example 1: Troubleshooting guide

docs/guides/troubleshooting-common-issues.md

---
title: Troubleshooting Common Issues
description: Solutions to frequently reported problems
order: 1
---

# Troubleshooting Common Issues

## API returns 401 Unauthorized

**Cause**: Invalid or expired API token.

**Solution**:
1. Check that your token is included in the `Authorization` header: `Authorization: Bearer YOUR_TOKEN`
2. Verify the token hasn't expired (tokens are valid for 90 days)
3. Generate a new token at https://app.yourcompany.com/tokens

## Webhook deliveries failing

**Cause**: Your endpoint is unreachable or timing out.

**Solution**:
1. Verify your endpoint is publicly accessible
2. Check that it responds within 30 seconds
3. Review failed deliveries in your dashboard
4. Use `/webhook retry` to manually retry

## Emails not arriving as Issues

**Cause**: Email forwarding misconfiguration or spam filtering.

**Solution**:
1. Verify forwarding is active in your email provider
2. Check your spam folder for the Scitor confirmation email
3. Ensure your Scitor email address is correct (find it in the setup issue)
4. Test with `/test-email` on any issue

Example 2: FAQ

docs/faq.md

---
title: Frequently Asked Questions
description: Quick answers to common questions
order: 100
---

# Frequently Asked Questions

## Do customers need a GitHub account?

No. Customers interact entirely via email. They never see GitHub and don't need an account.

## Can I use this with GitHub Organizations?

Yes. Install the Scitor app at the org level and choose which repositories receive support.

## What happens to email attachments?

Attachments are uploaded to cloud storage (Azure Blob or GitHub Releases) and linked in the issue body. Images are embedded inline.

## Can I customize the email sender address?

Yes. With a verified custom domain, you can send replies from your own domain (e.g., `support@yourcompany.com`) instead of the default Scitor address.

## Is there a limit on email size?

Emails up to 10MB (including attachments) are accepted. Larger messages are rejected with a bounce notification.

## How is spam handled?

Every inbound email includes a SpamAssassin score. Messages are labeled `spam:clean`, `spam:low`, `spam:medium`, or `spam:high`. You can auto-close high-scoring messages with a GitHub Action.

Why this works

A Markdown-based knowledge base in GitHub has advantages that separate documentation tools cannot match:

Version control: Every change is tracked. You can see who wrote what, when, and why. Rollbacks are trivial.

Pull request workflow: Documentation improvements go through code review. Your team can suggest edits, catch errors, and approve changes before they go live.

Single source of truth: Docs live in the same repository as your product code. When you ship a feature, you update the code and the docs in the same PR. Drift becomes harder.

Low maintenance: No CMS to update, no database to back up, no separate authentication system. Your docs are plain text files that deploy automatically on commit.

Searchable by default: GitHub’s search works across Markdown files. When auto-deployed, client-side search makes every word instantly findable.

Getting started

  1. Create a docs/ folder in your repository
  2. Write a few docs in Markdown (start with FAQ and Getting Started)
  3. Extract answers from support Issues into docs
  4. Create saved replies in .github/scitor/replies/
  5. Configure auto-deployment in .github/scitor.yaml

Your knowledge base is live. As your support history grows, so does your documentation—automatically, incrementally, and without leaving GitHub.

See it in action. Install Scitor from the GitHub Marketplace and turn your repository into a knowledge base with automatic doc deployment included in the Pro plan.