Suggestion Board

The Suggestion Board lets you collect feature ideas and feedback from your docs site visitors. Users can submit suggestions and vote on ideas — all without ever leaving your documentation site. Behind the scenes, each suggestion becomes a GitHub Issue on a dedicated Project board, where you manage priorities using a “Votes” column that surfaces the most-wanted ideas.

Pro plan required. The suggestion board is available on the Pro plan ($9/month).

How it works

1. A visitor opens the /suggestions page on your docs site
2. They browse existing ideas, sorted by vote count — the most popular ideas are at the top
3. They can vote on ideas they like (anonymous, one vote per idea)
4. They can submit a new suggestion with a title, description, and optional category
5. Scitor creates a GitHub Issue with a suggestion label and adds it to a dedicated Project board
6. You manage suggestions in the GitHub Project board — sort by votes, drag between status columns, add comments

Your docs site                Scitor                    GitHub
──────────────                ──────                    ──────
User submits idea    →    Creates Issue          →    Issue + "suggestion" label
                          Adds to Project board  →    Appears in "By Votes" view
User votes on idea   →    Records vote (D1)      →    Updates "Votes" field
                                                       ↕
                                                  You manage the board:
                                                  drag to "Planned", "In Progress",
                                                  "Shipped" — status reflected on
                                                  the docs page automatically

Setup

Add a suggestions section to your .github/scitor.yaml:

suggestions:
  enabled: true

That’s it. On the next docs build, Scitor will:

1. Create a GitHub Project board called “Suggestion Board” on your repository
2. Add custom fields: Votes (number), Status (single select), Category (single select)
3. Create three views: By Votes, By Status, and Recent
4. Add a /suggestions page to your docs site with a navigation link

Full configuration

suggestions:
  enabled: true
  project_title: "Feature Requests"       # Project board name (default: "Suggestion Board")
  categories:                              # Categories shown in the submit form
    - "Bug fix"
    - "New feature"
    - "Improvement"
    - "Documentation"
  moderation: false                        # Hide new suggestions until reviewed (default: false)
  placement: sidebar                       # Link placement: sidebar | footer | nav (default: sidebar)

Configuration options

The Project board

When you enable suggestions, Scitor creates a GitHub ProjectV2 board with everything pre-configured.

Custom fields

Status values

Pre-built views

Scitor creates three views so you can work with suggestions immediately:

1. By Votes (table) — Sorted by vote count, highest first. This is the primary view for identifying the most popular ideas.
2. By Status (board) — Kanban-style columns for each status. Drag suggestions between columns to update their status.
3. Recent (table) — Sorted by creation date, newest first. Useful for reviewing incoming suggestions.

Managing suggestions

All management happens in the GitHub Project board — no special commands needed:

• Prioritize: Open the “By Votes” view to see what your users want most
• Update status: Drag suggestions in the “By Status” board view, or click to edit the Status field
• Add comments: Click through to the linked Issue to comment or discuss
• Decline: Set status to “Declined” — the suggestion stays visible on the docs page with a “Declined” badge so users know it was reviewed
• Close: Close the GitHub Issue when a suggestion is shipped or declined

The docs page

The /suggestions page on your docs site shows:

• Suggestion list — sorted by vote count (most popular first) by default
• Vote buttons — visitors click ▲ to vote; the count updates immediately
• Status badges — color-coded: Under Review (gray), Planned (blue), In Progress (yellow), Shipped (green), Declined (red)
• Category badges — if categories are configured
• Filter tabs — All | Under Review | Planned | In Progress | Shipped
• Sort options — Most Voted | Newest
• Submit form — title, description, optional category selection

The page matches your docs site theme and is fully responsive.

Voting

Voting is anonymous and doesn’t require a GitHub account or any sign-in:

• Each visitor gets one vote per suggestion, identified by an anonymous hash of their IP address and browser fingerprint
• Votes are counted in real-time and synced to the “Votes” field on your Project board
• The vote button shows an “already voted” state if the visitor has voted (tracked in browser storage)
• Vote counts on the docs page update every 2 minutes (cached for performance)

Moderation

By default, all suggestions appear on the docs page immediately. If you want to review suggestions before they go public, enable moderation:

suggestions:
  enabled: true
  moderation: true

With moderation enabled:

• New suggestions still create a GitHub Issue and appear on your Project board
• But they are hidden from the docs page until you change their status from “Under Review” to any other value
• Once you set a suggestion to “Planned”, “In Progress”, “Shipped”, or even “Declined”, it becomes visible on the docs page

This is useful if you expect high volumes of submissions or want to filter out duplicates and spam before they become public.

Spam prevention

Suggestion submissions are protected by three layers:

1. Honeypot field — a hidden form field that catches simple bots
2. Turnstile CAPTCHA — Cloudflare’s privacy-preserving challenge (same as the contact form)
3. Rate limiting — maximum 5 submissions per IP address per hour

Categories

Categories help organize suggestions and make it easier for visitors to browse:

suggestions:
  categories:
    - "Bug fix"
    - "New feature"
    - "Improvement"
    - "Documentation"
    - "Integration"

When configured:

• The submit form shows a category dropdown
• Each suggestion displays a category badge on the docs page
• The Project board has a “Category” field you can filter and group by
• Adding new categories to the config automatically adds them to the Project field (existing categories are preserved)

Privacy

• Voter identity is stored as a SHA-256 hash of the visitor’s IP address and User-Agent string. No personal information is retained for voting.
• Suggestion author name and email are optional fields on the submit form. If provided, they are included in the GitHub Issue body (visible to your team) but not displayed on the public docs page.
• All suggestion data is scoped to your installation and never shared across organizations.

Tips

• Check “By Votes” regularly — it’s the fastest way to understand what your users actually want
• Use status updates — when you move a suggestion to “Planned” or “In Progress”, it builds trust with your users because they see their feedback being acted on
• Respond on the Issue — even if you decline a suggestion, leaving a comment explains your reasoning and shows you’re listening
• Enable moderation if you have a public-facing product with high traffic — it keeps the board clean
• Name categories clearly — they help users find similar suggestions before submitting duplicates