Drawing 001 — Docs · Community · Blog

Your knowledge, where every stream converges.

Forumulate runs your documentation, your community forum and your editorial blog on one managed platform — one account, one search, one identity.

ProjectForumulate
Surfaces03
DeployManaged cloud
RevisionC
FIG. 01Forumulate — unified workspaceREV. C
Surfaces
Docs412
Guides118
API reference94
Community128
Blog36
Registry
Members3.4k
Roles12
Audit log
Community / Enterprise / SSO
How do I rotate SAML signing certificates without downtime?
ssosamlenterprise
Priya NairTL3 · Regular2h
We have SAML wired up for ~400 people. The IdP certificate expires next month and I can’t take authentication down. Is there a way to stage the new one first?
Record
StatusOPEN
Replies6
Views1,204
Linked docs
Configure SAML
Rotate credentials
SCIM provisioning
1One index, three surfaces2Answer becomes a doc3Cross-surface links

FIG. 01One workspace — the docs, the forum and the blog indexed together, sharing one identity.

DocumentationCommunity forumEditorial blogUnified searchGrounded AIChange requestsTrust levelsSSO · SAML · SCIMManaged & monitoredWebhooks & APIReal-time chatExtensionsDocumentationCommunity forumEditorial blogUnified searchGrounded AIChange requestsTrust levelsSSO · SAML · SCIMManaged & monitoredWebhooks & APIReal-time chatExtensions
§ 00

Stop stitching a docs host, a forum, and a blog together.

General notes

Forumulate shares one login, one search index, one identity, and one permission model across all three surfaces. A member you invite, a role you grant, and a page you publish work everywhere.

One identityEmail, SSO, SAML & SCIM — across every surface.
One searchFull-text and semantic results span docs, forum & blog.
One graphA forum answer promotes straight into the docs.
One billSimple per-plan pricing — no three vendors.
3 surfaces · 1 platform · 0 lock-in
§ 01

Docs your team can change safely.

Documentation

A structured editor, real versioning, and change requests with review rules — so nothing reaches readers unreviewed.

  1. Change requests with reviewers, merge rules & conflict resolution
  2. Space-wide version history and one-click restore
  3. OpenAPI references with a live test console
  4. Git round-trip sync, variables & reusable content
  5. Grounded AI answers over your published docs
FIG. 02Docs — change request #248REV. B
Guides / Authentication
Rotating SAML certificates
Diffauthentication/saml.md
Replace the certificate in place.
+Add the new cert as secondary, then remove the old.
Merge change requestHistory
Reviewers
Ana K.
Jonas W.·
Revision
v4.2current
v4.121d

FIG. 02A change request under review — two approvals, then it merges and publishes.

FIG. 03Community — promote to docsREV. B
Community / Enterprise
Rotating SAML signing certificates
Priya Nair2h
Our IdP certificate expires next month and I can’t take authentication down for 400 people.
Marco DiazTL4
Add the new cert as a secondary, flip signing_key, then drop the old one.
SolvedPromote to docs →
Output
· Docs page
· Search index
· AI grounding

FIG. 03The signature operation — a solved answer becomes a documentation page in one action.

§ 02

A forum that feeds your documentation.

Community

A full Discourse-style community — trust levels, badges, flags and moderation — with the signature move: promote a solved thread straight into your docs.

  1. Trust levels, badges & reputation that unlock privileges
  2. Typed flags, a reviewable queue & an AI spam classifier
  3. Categories, tags, tag groups & saved searches
  4. Real-time chat with threads, DMs & reactions
  5. Reply — and start topics — by email
§ 03

Changelogs and stories, on the same stack.

Editorial

Author, schedule and co-byline posts; publish a clean editorial reader with RSS — next to the docs and community they're about.

  1. Scheduled publishing and multiple authors
  2. Per-space RSS and a docs updates feed
  3. Newsletter signup with one-click unsubscribe
  4. Embed docs search or forum comments on any site
FIG. 04Blog — scheduled releaseREV. B
Blog / Changelog
SCIM provisioning is now generally available
Ana K. & Jonas W.
Directory sync now runs on every enterprise plan — users and groups stay in step with your IdP automatically, with full audit history.
Schedule 09:00 UTCPreview
Distribution
RSS feed·
Newsletter·
Docs updates·
Subscribers
12,480

FIG. 04Scheduled, then released to every channel at once.

§ 04 — Sequence of operations
01

A question becomes documentation.

01

Someone asks

A question is posted in the community — indexed from the first second.

02

The community answers

03

Promote to docs

04

Everywhere, instantly

01 · Community
02 · Documentation
03 · Unified index
Question

FIG. 09Exploded assembly — one record, three layers

§ 05

Nothing is ever lost, and git stays the source of truth.

Version control

Every space keeps its full history, and the repository round-trips: a commit becomes a page, an edit becomes a commit, and conflicts surface for review instead of overwriting someone.

FIG. 10Docs — version history & restoreREV. B
v4.0v4.1v4.2v4.3v4.4authentication/saml.md — v4.4restoreevery space keeps full history — restore any revision in one action

FIG. 10Scrub the revision rail and restore any earlier state of a page.

FIG. 11Docs — git round-trip syncREV. B
github.comacme/docsforumulatedocs spacepull · commit → pagepush · edit → commita3f19c7b20dee4c881editconflicts surfaced for reviewround-trip — the repository and the space stay one source of truth

FIG. 11Round-trip sync — commits in, edits back out, conflicts flagged.

§ 06

Reference pages you can actually run.

API reference

Import an OpenAPI spec and every endpoint becomes a live console — parameters, auth, a real request and the real response, inside the docs.

  1. OpenAPI 3 import with schemas, auth & examples
  2. Executable requests against your own environment
  3. Generated SDK and CLI from the same specification
  4. Scoped API tokens with per-token audit
FIG. 12Docs — OpenAPI reference & test consoleREV. B
POST/v1/spaces/{id}/pagestitlestringrequiredparentuuidoptionalcontentmarkdownrequiredsendawaitingevery endpoint is executable from the reference — no separate client needed

FIG. 12Send a request from the reference and read the response in place.

§ 07

One query, every surface, filtered by what you may see.

Retrieval

Lexical and semantic retrieval run together and fuse into a single ranking — then the result set is cut down to exactly what the reader has permission to open.

FIG. 05Search — one indexREV. B
single sign-on⌘K
Authentication → SAML setupDocs
Solved: rotating SAML certificatesForum
Changelog: SCIM is now GABlog
3 records · 1 index · every surface

FIG. 05The reader’s view — records from docs, forum and blog in one index.

FIG. 13Search — retrieval pipelineREV. B
querytokenisebm25 · lexicalann · vectorfuserank + aclexact termsmeaningdocs · saml setupforum · solvedblog · scim gaone query — lexical and semantic, filtered by what you're allowed to see

FIG. 13The mechanism — tokenise, BM25 and vector search, fuse, then rank.

FIG. 14AI — grounded answer with citationsREV. B
docsforumblogtop-kgrounded answeranswers cite the records they came from — nothing is invented

FIG. 14Retrieved passages are cited inline — the answer is traceable to records.

§ 08

Answers that cite the record they came from.

Grounded AI

The assistant only reads what you have published and what the asker is allowed to see. Every claim carries a citation back to the page or thread it came from.

  1. Retrieval scoped to the reader’s permissions
  2. Inline citations back to docs, threads and posts
  3. Draft pages and translations from your own content
  4. Bring your own model key, or use ours
§ 09

Reputation that maps to real permissions.

Trust

Members advance through trust levels by participating, and each level unlocks concrete privileges — up to promoting an answer into the documentation.

FIG. 06Trust — member recordREV. B
Priya Nair
TL3 · 4,820 pts
Regular
Progress to TL478%
SolverRegularEditorLeader
186answers
41solutions
12docs

FIG. 06One member record — trust earned anywhere applies everywhere.

FIG. 15Community — trust level state machineREV. B
TL05 topicsTL120 likesTL2sustainedTL3staff grantTL4privileges unlockedpost links & imagesTL1flag postsTL2edit wiki pagesTL3promote to docsTL3moderate & mergeTL4reputation is earned by participation and maps to real permissions

FIG. 15The state machine — transition conditions and what each level unlocks.

§ 10

Only the uncertain middle reaches a human.

Moderation

Every post is scored on arrival. Clear spam is rejected, clean posts publish, and the ambiguous band goes to a prioritized review queue with the evidence attached.

  1. Typed flags with a reviewable, prioritized queue
  2. Automatic actions by score threshold
  3. Rate limits, silences and a full audit trail
  4. Watched words, spam checks and new-user limits
FIG. 16Community — spam classifier routingREV. B
postunknown@…classifierscore 96allow · published<40queue · human review40–89reject · silenced≥90scored on arrival — only the uncertain middle reaches a human

FIG. 16A post is scored, then routed to allow, queue, or reject.

§ 11

One permission model, wired to your directory.

Access & identity

Capabilities are granted through roles, roles can be granted to whole groups, and your identity provider keeps membership current without anyone filing a ticket.

FIG. 17Access — capability matrix & group grantsREV. B
readwritereviewmergemoderateadminReader·····Author····Editor··Moderator·Admingroup grant · engineering → editor42 membersgrant a role to a whole group — every member inherits it at once

FIG. 17Roles × capabilities — a group grant applies to every member at once.

FIG. 18Identity — SAML sign-in & SCIM provisioningREV. B
identityproviderscimconnectorforumulatedirectoryoperations appliedada@acme.comcreateengineeringgrouplegacy@acme.comdeprovisionorg-wide mfa enforcedjoiners, movers and leavers stay in step without a manual step

FIG. 18SAML sign-in with SCIM provisioning and deprovisioning.

§ 12

A platform you can build on, not just configure.

Integration

Signed webhooks with retries and replay, a documented REST API, and remote-app extensions that register their own blocks and surfaces without forking anything.

FIG. 19Platform — webhook delivery & replayREV. B
event queueendpointhttps://acme.dev/hooks/forumulatepage.publishedtopic.solvedmember.joinedsigned, retried with backoff, and replayable from the log

FIG. 19Delivery with backoff — a failed event is replayed from the log.

FIG. 20Platform — extension registrationREV. B
docscommunityblogsurface socketsappregistered by the appblock · <chart>surface · /reportswebhook · page.*runs on the app's own serverextensions add blocks and surfaces without forking the platform

FIG. 20An extension seats into a surface socket and registers its parts.

§ 13

Instrumented, and answerable after the fact.

Operations

Prometheus metrics and structured logs from day one, plus an immutable audit log that records who changed what — the things you need when something goes wrong at 3am.

FIG. 21Operations — metrics & auditREV. B
0306090120requests / sp95 latencyprometheus · /metricsrole.grantedana@acmeimmutablespace.publishedjonas@acmeimmutabletoken.revokedsystemimmutable

FIG. 21Request rate and p95 latency, with the audit trail beneath.

§ 14

One Forumulate, or three separate tools.

Specification

A docs host, a forum, and a blog platform each solve one slice — and none of them talk to each other.

Capability
Forumulate
Three tools
Documentation
A docs vendor
Community forum
A forum vendor
Editorial blog
A blog vendor
Single sign-on across all of it
Three logins
One search over everything
Three search boxes
Forum answers promote into docs
Copy-paste, if ever
One permission model
Three to reconcile
Managed, monitored and backed up
Three vendors to chase
One bill
Three invoices
§ 15

Run by us, so you never have to run it.

Reliability & trust

Monitored around the clock, backed up nightly, and patched before you hear about the CVE. Enterprise identity is built in — and your data stays exportable, so staying is a choice rather than a trap.

Uptime & monitoring

Watched around the clock, with public status and incident history.

Backups & restore

Nightly automated backups, with point-in-time restore on request.

SSO, SAML & SCIM

Enterprise login and directory sync, per organization.

Org-wide MFA

Require two-factor across every member before they’re in.

Roles & audit

Custom roles, group grants, and an immutable audit log.

Portable data

Import from GitBook & Discourse; export everything, anytime.

FIG. 07Operations — platform statusREV. B
99.98%uptime · trailing 90 daysAll systems go
Applicationoperational
Search & AIoperational
Email deliveryoperational
Webhooksoperational
nightlybackups
3regions
12msince deploy

FIG. 07Live platform status — uptime, backups and the last deploy.

§ 16

Bring your docs and community with you.

Migration

Import from where you are today — structure, history and members intact — and keep every existing URL working.

FIG. 08Migration — import in progressREV. B
GitBook spaces4 / 4
Pages imported1,284
Discourse topics9,610
Members matched3,402
Redirects preserved · original URLs keep working

FIG. 08A live import — counts and redirects tracked per source.

GB

Import from GitBook

Pull your spaces, pages and structure into Forumulate docs — then keep git-syncing.

DC

Import from Discourse

Bring categories, topics, posts and members into your Forumulate community.

§ 17

Everything included, nothing bolted on.

Parts list
17.1 — Operations

Run for you, not by you

Monitored around the clock, backed up nightly and kept patched. Import from GitBook & Discourse, and export everything whenever you want.

17.2 — Retrieval

One query, grounded answers

Full-text and semantic search across every surface, plus AI answers, page drafts and translation scoped to what you publish.

17.3 — Identity

SSO, SAML & SCIM

Enterprise login, directory sync, org-wide MFA.

17.4 — Access

Roles & group grants

A capability model, custom roles, and roles granted to whole groups.

17.5 — Operations

Observability built in

Structured logs, Prometheus metrics, scoped API tokens, webhooks & audit.

17.6 — Extension

A platform, not a silo

A remote-app extension marketplace, a documented REST API with a publishable SDK & CLI, replayable webhooks, and embeddable widgets you drop on any site.

17.7 — Localisation

i18n & translation

Localized content and a translated admin UI.

§ 18

One base, four jobs it does exceptionally.

Applications
18.1

Developer docs & API reference

Versioned guides and OpenAPI references with a live test console, git-synced and AI-answerable.

DocsAIAPI
18.2

Support & Q&A community

A place customers help each other — trust levels, solved answers, and moderation that scales.

ForumModeration
18.3

Product knowledge base

Internal or public knowledge that stays accurate, with change requests and an agent that reviews edits.

DocsReviews
18.4

Open-source project home

Docs, discussions and a changelog under one roof — hosted for you, and yours to shape.

DocsForumBlog
§ 19

Good to know.

Notes
Yes — they’re three surfaces on one platform, sharing a single account, search index, identity, and permission model. A member you invite and a role you grant work across all of them, and a solved forum answer can be promoted straight into your docs.

Issued for construction

Bring your streams together.

Spin up docs, a community and a blog in minutes — free to start, and we run it for you.

Forumulate — docs, community and blog on one platform