Getting started: from signup to your first published page

This guide walks you from a blank browser tab to a page a stranger can read. It takes a few minutes. You will create an account, confirm your email, set up your organization, write something, and publish it — which is the step the previous version of this page left out.

1. Create your account

Go to the sign-up page. Sign-in runs on Atlas, our identity service; see Atlas, and who processes your data if you want to know what that means.

• With email and password. Enter your name, your email and a password.

• With Google. Signing up with Google is the same as signing in with it — your account is created the first time you arrive, so there is no separate registration step, and your email is already verified.

A brand-new account has no organization yet. That comes next, in the setup wizard, so that you choose your organization's name and address rather than having one generated for you.

2. Confirm your email

Open your inbox and click the link we send. You do not have to leave the wizard to do it — most people confirm in a second tab, and the setup screen notices and moves on by itself.

If it has not arrived, use Send it again, and check your spam folder.

Confirming is required before your workspace can be created, which is why it comes first.

3. Set up your workspace

You land on the setup wizard at /welcome. This is a one-time flow that creates your organization.

Name it, and pick an address

Type what your organization is called — "Acme Inc". As you type, we suggest a matching address: lowercase letters, numbers and hyphens. Edit it if you like; once you do, typing the name no longer overwrites your choice. We check availability as you type and show the resulting hostname beside the field.

Choose what to start with

Each option is a space — a documentation site, a community forum, a blog, and so on. Tick every one you want; you can start with several, and each arrives ready to use rather than as a blank screen.

There are fourteen types. The wizard offers the common ones; The fourteen space types covers all of them, including Events and Courses.

You need at least one. The button shows how many spaces it will create — "Create workspace · 3 spaces". Press it, and you land in your organization.

4. Land in the studio

You arrive at /o/<your-org-id>. Open a space and you are in the studio: your real site in the middle of the screen, and a panel beside it that changes everything about it.

The page you see is the reader view, not a form. Double-click any text to edit it in place; every change saves as you go.

The studio wants a wide window

The studio puts your live site and the panel that edits it side by side, so it needs the width to show both. Three thresholds, in CSS pixels:

So: 1024px is the minimum, 1480px is the comfortable one. There is no mobile studio and this is not a bug report — writing on a phone is not something we have made good, and showing you half a panel would be worse than saying so.

5. Write a page

In a documentation space, use the Pages fold to add a page. Give it a title — that title becomes its address, so "Installing the CLI" lands at /installing-the-cli.

Then write. Double-click into the body and type. A slash command (/) inserts a block: a code sample, a callout, a table, an image.

Everything you have written so far is a draft. Drafts are visible to people who can edit the space and to nobody else. That is the thing to understand about the next step.

6. Publish it

A page has two states — draft and published — and a space has two — private and public. A reader needs both switches thrown.

1. Publish the page. Use Publish in the studio. If the space has a review gate turned on, your change becomes a change request instead, which somebody with publish rights merges.

2. Make the space public. In the Settings fold, set the space's visibility to Public. A private space answers a logged-out reader with nothing at all — which looks exactly like a broken address, and is the single most common "my page is published but invisible" report.

To push out a lot at once, Publish all publishes every page's open draft and skips anything a review gate is holding.

7. Check it as a stranger

This is worth doing properly, because signed in you will always see your own page.

First, get the address from us — do not build it. The studio's Address panel shows every address the space is served at, with the one to use marked as primary. Copy that and open it in a private window.

The reason this matters more than it sounds: forumulate.com/p/… is our address. The moment you attach a domain of your own, your readers are on docs.yourcompany.com and a check against our path is a check of a page nobody visits. So we tell you where a piece is read, and you never work it out.

From a terminal, the same fact comes off the API. Each row of the item list carries url — the address that piece is read at, your own domain first, a site of yours next, ours only if you have neither:

export FORUMULATE_TOKEN=ak_…   # Account → Tokens
export FML='https://forumulate.com/api'
export ORG=…                   # GET $FML/orgs lists yours
export SPACE=…                 # GET $FML/orgs/$ORG/spaces lists its spaces

PAGE=$(curl -sS "$FML/orgs/$ORG/spaces/$SPACE/items" \
  -H "Authorization: Bearer $FORUMULATE_TOKEN" -A 'checking/1.0' \
  | jq -r '.items[0].url')

curl -sI -A 'checking/1.0' "$PAGE"

(Swap .items[0] for .items[] | select(.slug == "your-slug") once the space holds more than one page.)

A null back from that is an answer, not a failure: it means there is nowhere to link to — the space is not public, or the page is not published. That is the "published but invisible" diagnosis one step earlier than a header dump.

doctor takes the same URL, and for the space as a whole its primary address is on GET /orgs/{orgId}/spaces/{spaceId}/addresses:

ROOT=$(curl -sS "$FML/orgs/$ORG/spaces/$SPACE/addresses" \
  -H "Authorization: Bearer $FORUMULATE_TOKEN" -A 'checking/1.0' \
  | jq -r '.addresses[] | select(.primary) | .url')

npx --yes @forumulate/cli doctor "$ROOT"

which checks from the outside that a logged-out reader gets the page, that the canonical link is right, that robots.txt allows it and that a crawler gets the same answer you do. See The command line, and forumulate doctor.

If it is still not visible, A page is published but nobody can see it is the checklist.

What's next

• Your first space — what a space is, and how to add more.

• The fourteen space types — what each kind of space is for.

• Editing in the studio — double-click editing, the inspector rail, reordering and undo.

• Publish on your own domain — your hostname, or a path of a site you already run.

• Team and permissions — who is allowed to publish.

In the API

Every operation below is also reachable from the other surfaces without a dedicated command. forumulate api <Operation> calls it from the CLI, client.typed(method, path) from the JavaScript SDK (the Python and Go clients are generated from the same spec), and an agent reaches the organization-scoped ones through the MCP call_api tool. Where a shortcut exists, the last column names it. Operation names link to the API reference.

Address