Skip to Content
OrbixDocs
Block SDK · Guides

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

ActionRequired manifest.capabilitiesIncluded 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.navigateToPagedocument: ['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.

src/PageOutlineBlock.tsx
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:

src/BatchInsert.tsx
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.

useOrbixWorkspace() queries pages, headings, backlinks, and graph edges across the workspace:

src/BacklinksList.tsx
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?):

src/IssueTable.tsx
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>').

On this page