Spaces, Pages & Content Types

How to organize documentation with spaces, typed pages, templates, comments, labels, attachments, and version history.

Spaces

Spaces are the top-level organizational unit in Internal Docs. Each space contains its own page tree, labels, and permission model. Use spaces to separate documentation by team, project, or domain.

Terminal

bash

# Create a space
riven spaces create "Engineering"
 
# List all spaces
riven spaces list
 
# Get space details
riven spaces get engineering

A space has a name and an auto-generated slug (e.g., "Engineering" becomes engineering). All pages, labels, and permissions are scoped to their parent space.

Create separate spaces for distinct teams or domains. For example: "Engineering", "Platform", "Ops Runbooks", "Architecture Decisions".

Page Types

Every page in Internal Docs has a type that determines its metadata schema and how it is rendered. This goes beyond simple tagging — each type carries structured fields that enforce consistency.

page

Standard wiki page for general documentation. No additional metadata beyond title and content.

Terminal

bash

riven pages create --space engineering --title "API Design Guidelines" --type page

folder

A container page for organizing child pages into a hierarchy. Folders can have their own content but primarily serve as structural nodes in the page tree.

Terminal

bash

riven pages create --space engineering --title "Backend Services" --type folder

adr — Architecture Decision Record

Structured page for recording architecture decisions with dedicated metadata fields:

Field	Description
`status`	Proposed, Accepted, Deprecated, Superseded
`deciders`	List of people who made the decision
`date`	Date the decision was made
`supersedes`	Link to the ADR this one replaces

Terminal

bash

riven pages create --space engineering --title "Use Connect RPC for All APIs" --template adr

rfc — Request for Comments

Collaborative proposal page with review and voting workflow:

Field	Description
`status`	Draft, In Review, Accepted, Rejected, Withdrawn
`author`	RFC author
`reviewers`	Assigned reviewers
`deadline`	Review deadline
`voting`	Approval/rejection votes

Terminal

bash

riven pages create --space engineering --title "Migrate to Event Sourcing" --template rfc

runbook

Operational runbook for incident response, maintenance procedures, or on-call playbooks.

Terminal

bash

riven pages create --space ops --title "Database Failover Procedure" --template runbook

api-reference

Dedicated page type for API documentation. Useful for documenting RPC endpoints, REST APIs, or SDK methods.

Terminal

bash

riven pages create --space engineering --title "Billing Service API" --type api-reference

live-doc

Auto-updated page that syncs content from external sources. Live docs are refreshed periodically and display a last-synced timestamp.

Terminal

bash

riven pages create --space engineering --title "Cluster Status" --type live-doc

Templates

Templates provide pre-filled content and metadata for new pages. Seven built-in templates are available:

Template	Type	Description
Blank Page	page	Empty page with no content
Folder	folder	Empty folder for organizing pages
ADR	adr	Architecture Decision Record with status, context, decision, and consequences sections
RFC	rfc	Request for Comments with problem statement, proposal, alternatives, and timeline
Meeting Notes	page	Date, attendees, agenda, notes, and action items
Runbook	runbook	Title, description, prerequisites, steps, rollback, and escalation sections
Service Overview	page	Service name, owner, dependencies, architecture, endpoints, and runbook links

Terminal

bash

# List all available templates
riven templates list
 
# View a specific template
riven templates get adr
 
# Create a page from a template
riven pages create --space engineering --title "Switch to PostgreSQL 17" --template adr

Templates are organization-scoped. Custom templates are planned for a future release.

Page Tree

Pages are organized in a hierarchical tree within each space. Any page can be a parent of other pages, but folder type pages are designed specifically for this purpose.

Terminal

bash

# View the full page tree for a space
riven pages tree engineering

Example Output

text

engineering/
├── Backend Services (folder)
│   ├── API Design Guidelines (page)
│   ├── Use Connect RPC for All APIs (adr)
│   └── Billing Service API (api-reference)
├── Ops Runbooks (folder)
│   └── Database Failover Procedure (runbook)
└── Onboarding Guide (page)

Move pages within the tree to reorganize:

Terminal

bash

riven pages move <page-id> --parent <new-parent-id>

Comments

Internal Docs supports two types of comments on every page:

Footer Comments

General discussion comments at the bottom of a page. Visible to anyone with read access.

Terminal

bash

# List comments on a page
riven comments list <page-id>
 
# Add a comment
riven comments add <page-id> "Looks good, but we should add a rollback section."

Inline Comments

Comments anchored to a specific section or block within the page content. These appear as annotations in the editor.

Threading and Resolution

All comments support reply threading and a resolve/reopen workflow:

Terminal

bash

# Reply to a comment
riven comments add <page-id> "Added the rollback section." --reply-to <comment-id>
 
# Resolve a comment thread
riven comments resolve <comment-id>
 
# Reopen a resolved comment
riven comments resolve <comment-id> --reopen

Use the resolve workflow to track open questions and action items on documentation pages.

Labels

Labels are colored tags for cross-cutting categorization of pages. They are scoped to a space and auto-created on first use — no need to pre-define them.

Terminal

bash

# Add labels to a page
riven labels add <page-id> "backend" "priority:high" "team:platform"
 
# List labels on a page
riven labels list <page-id>
 
# Remove a label
riven labels remove <page-id> "priority:high"

Labels work across page types, so you can tag an ADR, an RFC, and a runbook with the same label and find them all with a single search query.

Attachments

Pages support file attachments uploaded via S3 presigned URLs through the files-gateway service. Attachments can be referenced inline within page content.

Terminal

bash

# List attachments on a page
riven attachments list <page-id>

Uploading attachments is handled through the platform UI or programmatically via the files-gateway RPC API, which returns presigned S3 URLs for direct upload.

Version History

Every edit to a page creates a new version. The full history is preserved and accessible for auditing and rollback.

Terminal

bash

# View version history for a page
riven history <page-id>

Example Output

text

Version  Author       Date                 Summary
7        gal          2026-03-21 14:30     Updated rollback steps
6        gal          2026-03-20 10:15     Added monitoring section
5        agent-bot    2026-03-19 09:00     Auto-updated from template
...

Diffing Versions

Compare any two versions side-by-side to see exactly what changed:

Terminal

bash

# Diff version 5 and version 7
riven diff <page-id> 5 7

Version history is retained indefinitely. There is no limit on the number of versions per page.

Permissions

Access control is managed at the space level with role-based permissions:

Terminal

bash

# View permissions for a space
riven permissions get engineering
 
# Grant a user editor access
riven permissions set engineering --user <user-id> --role editor
 
# Remove a user's access
riven permissions remove engineering --user <user-id>

Available roles:

Role	Capabilities
`viewer`	Read pages, view comments
`editor`	Create and edit pages, add comments, manage labels
`admin`	Full control including permissions, space settings, and deletion

Next Steps

AI Agent Integration (MCP) — Connect AI agents to your documentation.
Internal Docs Overview — High-level architecture and capabilities.
CLI Reference — Full CLI command reference for documentation management.

PreviousInternal Docs Platform NextAI Agent Integration (MCP)