# Pages

A page is a Markdown document in a wiki. Pages are organized in a tree, and every save creates a new revision. A page can also hold structured data. See [Records](https://known.info/docs/records).

## Page paths

A page's path is its position in the tree, with segments separated by dots. For example, `handbook.onboarding` is the page `onboarding` under `handbook`. Prefix the wiki name to refer to it from anywhere: `general:handbook.onboarding`.

In the browser, the same page is at `known.info/<org>/general/handbook/onboarding`.

Path segments can contain lowercase letters, digits, hyphens, and underscores, and must start with a letter or digit. Any page can have pages under it. When you write to a path whose parent pages don't exist, Known creates them.

## Create and edit pages

You create and edit pages through an agent or the CLI. The browser shows pages and updates them live, but doesn't have an editor.

To write a page with an agent, ask the Known assistant in **Chat** or a [connected agent](https://known.info/docs/connect-agent):

```
Write general:handbook.onboarding with the first week for a new engineer.
```

To write a page with the [CLI](https://known.info/docs/cli), use `wiki write` for the whole page or `wiki edit` to change one passage:

```
known acme wiki write general:handbook.onboarding --title "Onboarding" --file onboarding.md
known acme wiki edit general:handbook.onboarding --old "two weeks" --new "one week"
```

`wiki edit` fails unless the text you pass to `--old` appears exactly once on the page. Use `--all` to replace every occurrence.

## Avoid overwriting changes

If two people or agents edit the same page at once, one can overwrite the other. To prevent this, read the page with `--json`, note its `revisionId`, and pass it when you write:

```
known acme wiki write general:handbook.onboarding --file onboarding.md --if-revision <revisionId>
```

If the page changed since you read it, the write fails. Read the page again, merge the changes, and retry. Connected agents are instructed to do the same.

## Supported Markdown

Known supports headings, paragraphs, bold and italic text, lists, links, block quotes, code, and tables. A single line break is shown as a line break.

Images, task-list checkboxes, horizontal rules, strikethrough, diagrams, and math aren't supported yet.

## Embed a page

To show one page inside another, put `![[path]]` on a line by itself:

```
## This quarter
![[roadmap.q4]]
```

The embedded page shows its content and, if it holds records, its first rows. Embeds can be nested up to three levels deep.

## Move or rename a page

`wiki move` moves a page and all the pages under it, and keeps their history. You can move pages only within the same wiki.

Moving a page doesn't update links to it. Before you move a page, check what links to it:

```
known acme wiki links general:handbook.onboarding
known acme wiki move general:handbook.onboarding general:handbook.engineering-onboarding
```

## Delete a page

Deleting a page requires owner access to its wiki. On a wiki that's open to the whole organization, that means an organization admin.

```
known acme wiki rm general:drafts.old-plan
```

To delete a page that has pages under it, add `--recursive`. The page's history is kept after it's deleted.

## Page metadata

Each page has a JSON metadata object. Known uses these keys:

| Key | Description |
|---|---|
| `key` | Makes the page a table of records, keyed by this field. |
| `schema` | A JSON Schema that every record on the page must match. |
| `retain` | How long the page keeps records or record versions. |
| `description` | On a wiki's root page, the wiki's description. |

You can add other keys for your own use. To change metadata, use `wiki meta`. It merges the keys you pass with the existing ones, and a `null` value removes a key.

## FAQ

### Can I edit pages in the browser?

Not yet. Use Chat, a connected agent, or the CLI. Pages in the browser update as soon as a change is saved.

### Can I restore a deleted page?

Yes. Read the page as it was before you deleted it, then write it back to the same path:

```
known acme wiki read general:drafts.old-plan --at 2026-10-01T00:00:00Z > old-plan.md
known acme wiki write general:drafts.old-plan --file old-plan.md
```