Read and edit the document
Inspect headings and blocks on the current page, insert or batch-edit blocks, query workspace pages, and use live collections.
Blocks can read and modify the surrounding Orbix document with useOrbixDocument, search or navigate across pages with useOrbixWorkspace, and store structured rows with useLiveQuery or useOrbixDatabase.
Capabilities required
| Action | Required manifest.capabilities | Included in community default? |
|---|---|---|
Read current page (useOrbixDocument fields & doc.read.*) | document: ['read'] | Yes |
Edit current page (appendBlock, doc.write.*) | document: ['read', 'write'] | No — must declare 'write' |
Navigate pages via doc.navigation.navigateToPage | document: ['read', 'navigate'] | No — must declare 'navigate' |
Search/list workspace pages (useOrbixWorkspace) | workspace: ['read:all_pages'] | Yes |
Create workspace pages (ws.createPage) | workspace: ['read:all_pages', 'write:pages'] | No — must declare 'write:pages' |
Local block table (useLiveQuery(table)) | storage: ['local'] | Yes |
Workspace database (useOrbixDatabase) | database: { read: ['<dbId>'], write: ['<dbId>'] } | No — must declare database IDs |
Reading page or workspace data disables outbound network calls
To prevent untrusted blocks from silently sending private notes to third-party servers, reading document, workspace, or database data marks a non-trusted block instance as tainted in orbixEgressFirewall. Subsequent useOrbixFetch or orbixFetch calls from that block instance are denied, and Marketplace install grants strip network when workspace or cross_block_data permissions are enabled. Split document-mutating blocks and external API blocks into separate blocks if you need both workflows.
Reading and editing the current page (useOrbixDocument)
All methods on useOrbixDocument() are synchronous — they do not return Promises.
import {
defineBlock,
useOrbixDocument,
type BlockRenderProps,
} from '@orbixdocs/sdk';
export default defineBlock({
manifest: {
id: 'acme.page-outline',
name: 'Page Outline',
version: '1.0.0',
sdk: '^3.0.0',
capabilities: {
document: ['read', 'write'],
},
},
component(props: BlockRenderProps) {
const doc = useOrbixDocument();
const insertSummaryFooter = () => {
if (props.isReadOnly) return;
doc.appendBlock(
'callout',
`Summary for "${doc.pageTitle}": ${doc.wordCount} words across ${doc.blockCount} blocks.`
);
};
return (
<div
style={{
padding: 14,
borderRadius: 12,
background: 'var(--orbix-card-bg, #16171b)',
border: '1px solid var(--orbix-surface-border, #2a2b32)',
color: 'var(--orbix-text-primary, #f4f4f5)',
}}
>
<div style={{ fontSize: 13, marginBottom: 8 }}>
<strong>{doc.pageTitle || 'Untitled'}</strong> — {doc.headings.length} headings
</div>
<ul style={{ margin: 0, paddingLeft: 18 }}>
{doc.headings.map((h) => (
<li key={h.id}>
<button
type="button"
onClick={() => doc.scrollToHeading(h.id)}
style={{
background: 'none',
border: 'none',
color: 'var(--orbix-text-primary, #f4f4f5)',
textDecoration: 'underline',
cursor: 'pointer',
padding: 0,
}}
>
{h.text}
</button>
</li>
))}
</ul>
{!props.isReadOnly && (
<button
type="button"
onClick={insertSummaryFooter}
style={{ marginTop: 10 }}
>
Append word-count callout
</button>
)}
</div>
);
},
});Structured reads and batch writes
Use doc.read to inspect specific blocks or editor selection, and doc.write to insert, update, move, delete, or batch operations:
import { useOrbixDocument } from '@orbixdocs/sdk';
export function TemplateInserter({ isReadOnly }: { isReadOnly?: boolean }) {
const doc = useOrbixDocument();
const addMeetingSection = () => {
if (isReadOnly) return;
const rootIds = doc.read.getRootBlockIds();
const anchorId = rootIds[rootIds.length - 1];
if (!anchorId) {
doc.appendBlock('heading2', 'Meeting Notes');
return;
}
doc.write.batch([
{
type: 'insert',
payload: {
targetId: anchorId,
position: 'bottom',
block: { type: 'heading2', content: 'Action Items' },
},
},
{
type: 'insert',
payload: {
targetId: anchorId,
position: 'bottom',
block: { type: 'todo', content: 'Follow up with notes' },
},
},
]);
};
return (
<button type="button" disabled={isReadOnly} onClick={addMeetingSection}>
Insert Action Items section
</button>
);
}doc.write.createSubPage(title, blocks?) creates a child page under the current document and returns the new page's string ID synchronously.
Workspace pages and backlinks (useOrbixWorkspace)
useOrbixWorkspace() queries pages, headings, backlinks, and graph edges across the workspace:
import { useOrbixWorkspace } from '@orbixdocs/sdk';
export function RelatedPages() {
const ws = useOrbixWorkspace();
const backlinks = ws.activePageId ? ws.findBacklinks(ws.activePageId) : [];
return (
<div>
<div>Total workspace pages: {ws.pages.length}</div>
<div>Backlinks to current page: {backlinks.length}</div>
</div>
);
}To create a new top-level or nested page from useOrbixWorkspace(), declare workspace: ['read:all_pages', 'write:pages'] and call ws.createPage('Sprint Retro', { parentId: ws.activePageId ?? undefined }).
Structured rows (useLiveQuery and useOrbixDatabase)
For lightweight tabular data scoped to your block (backed by local storage with reactive updates across renders), use useLiveQuery<T>(tableName, options?):
import { useLiveQuery } from '@orbixdocs/sdk';
interface IssueRow {
id?: string;
title: string;
open: boolean;
}
export function IssueList() {
const { data, loading, insert, update, remove } = useLiveQuery<IssueRow>('issues', {
initialData: [{ id: 'seed-1', title: 'Document API limits', open: true }],
filter: (row) => row.open,
});
if (loading) return <div>Loading issues...</div>;
return (
<div>
<ul>
{data.map((issue) => (
<li key={issue.id}>
{issue.title}{' '}
<button
type="button"
onClick={() => issue.id && void update(issue.id, { open: false })}
>
Close
</button>
<button
type="button"
onClick={() => issue.id && void remove(issue.id)}
>
Delete
</button>
</li>
))}
</ul>
<button
type="button"
onClick={() => void insert({ title: 'New issue', open: true })}
>
Add issue
</button>
</div>
);
}Notice that useLiveQuery returns { data, loading, error, insert, update, remove, refetch } (data is always an array once loaded, even if you delete the last seeded item so it becomes []).
To read or mutate an existing Orbix workspace database table by ID, declare database: { read: ['<dbId>'], write: ['<dbId>'] } in manifest.capabilities and call useOrbixDatabase().connected('<dbId>').