Google Docs Export (publish Markdown to Google Docs)
Take a Markdown string from anywhere in Omniscio and publish it as a fully-formatted new Google Doc: real headings, tables, lists and code, with the URL handed back as a toast and old copies of the same title tidied away.
On this page
What it is
Omniscio's Google Docs Export takes a Markdown string from anywhere in the app and publishes it as a fully-formatted new Google Doc — headings, bold/italic, fenced code, lists, blockquotes, links, and native Google Docs tables are all preserved. The destination Doc lives in your Drive (a default folder, or one you configure), the URL comes back as a toast with Open Doc, and older versions of the same title in the same folder are auto-trashed so the destination folder stays clean.
When you trigger a publish from the UI, a persistent "Publishing to Google Docs…" toast with a spinner appears the instant you click, and its text advances through the real publish stages as they happen — Preparing → Creating the document → Adding your content → Formatting → Finishing up — before being replaced by the Open Doc success toast (or a humanized error). It's honest live progress streamed from the main process, not a faked timer, so for the ~3–5 seconds a publish takes you always see that it started and roughly where it is.
The feature is off by default and gated by googleDocsExportEnabled in Settings → Connections → Google Workspace → Docs Export. Turning it on does NOT add an OAuth consent step — Google Docs Export piggybacks on the same single "Connect Google" sign-in that Calendar, Drive, Sheets, and Gmail share, because the publisher uses the documents + drive scopes you already approved at connect time.
Both entry points feed the same publisher pipeline, so a published doc looks the same regardless of where you triggered it from.
Where to find it
How to use it
There are two convergent entry points. Each lands in the same publishMarkdownToGoogleDocs() orchestrator, so the resulting Doc is byte-identical regardless of which surface you used:
Right-click in the UI on six surfaces:
- A project doc card in the Project Docs section of a project dashboard (ProjectDocsSection.tsx).
- A scratchpad row in the Scratchpads view (ScratchpadsView.tsx).
- An agent message bubble in a session (MessageBubble.tsx).
- A whole session transcript — the Export to Google Docs item in the session
⋯→ Exports submenu (SessionOverflowMenu.tsx; handlerhandlePublishToGoogleDocsin SessionPanel.tsx). Publishes the same visible-only transcript the other session exports use. Shown only when this feature is enabled. - A markdown file link inside chat — right-clicking a
.mdor.markdownlink in any agent or user message (agent-markdown-helpers.tsx →CopyableLink). The menu item appears next to the existing Copy path + Share as public artifact entries, but only when the link's extension is.mdor.markdown. The file is read off disk in the main process; the document title defaults to the file's basename (minus the extension). - The File Peek Viewer — when you click a file link to open the side-panel previewer (FilePeekOverlay.tsx), markdown files get a Export to Google Docs button in the action bar next to Copy contents / Share / Edit. Hidden for non-markdown files.
Every surface shows Export to Google Docs in its right-click menu / overflow / action bar. Title defaults to the doc/scratchpad name, the message's first heading, or — for path-mode surfaces — the file's basename. A success toast surfaces the URL with Open Doc for one-click navigation. All five routes share usePublishMarkdownToGoogleDoc.ts, which centralises the feature-flag gate, empty-content guard, error→toast mapping, and the
amc://settings/integrations/google-accountre-auth deeplink. The hook accepts XOR input — eithermarkdown(content surfaces) orpath(file-link surfaces) — and the IPC handler delegates path-mode reads to the main-process read-markdown-from-path.ts helper so the file-read limits stay consistent with the CLI route.External AI / CLI via
POST /gdoc/publishon Omniscio's local control server (127.0.0.1:19519by default). Body shape is{ markdown, title? }OR{ path, title? }(a local.md/.markdownfile). Bearer-token auth, 1 MB body cap, 2 MB markdown cap, 10/min mutation bucket. Returns the same{ docId, url, title, trashedOlderCount }shape as the IPC handler. Useful when you want claude.ai, the phone web UI, or a third-party CLI to publish straight into your Omniscio Drive without re-implementing the conversion pipeline. The CLI route shares thereadMarkdownFromPath()helper with the IPC handler, so a Drive document built from a local file is byte-identical whether the file was opened from the chat right-click menu or from an external curl call.
How it behaves
How it works
The end-to-end pipeline is the same three-batch apply for every entry point — porting it once into publisher.ts means a markdown blob renders identically whether the originator was a right-click menu or an external HTTP POST.
Auth. google-auth-service.ts owns the shared Google OAuth2Client and the refresh token. The publisher calls getAuthClient() to mint a googleapis docs.v1 + drive.v3 pair. If the user isn't signed in OR the documents scope wasn't granted, PublisherError throws with GDOC_NOT_AUTHENTICATED / GDOC_SCOPE_INSUFFICIENT and needsReauth: true — every consumer surfaces this as a toast with a Re-authorize action that deep-links to Settings → Connections → Google Workspace.
Markdown → request batches. markdown-to-doc.ts parses Markdown via marked and emits four arrays:
insertRequests— the raw text insertions (headings flattened to plain text, bullets prefixed with tabs).listRequests—createParagraphBulletsranges that promote the tab-prefixed lines into native lists (the tab characters are removed by this batch).styleRequests—updateTextStyle(bold/italic/code/links) +updateParagraphStyle(heading levels, blockquotes) requests, whose offsets are then re-adjusted byadjustStyleIndicesForTabRemoval()to compensate for the tabs the list batch consumed.tableDescriptors— placeholder regions that tables.ts replaces with native Docs tables in a follow-up pass.
The three-batch apply order is LOCKED — text → lists → styles + tables — because Google Docs' batchUpdate index math depends on each step having already happened. Re-ordering produces visibly broken output (style runs misaligned by one character per bullet, lists with stray tabs, tables inserted into the wrong paragraphs). The orchestrator owns the order; the parser only provides the batches.
Typography belongs to the document, not to the publisher. A published doc's font comes from the document's own paragraph styles: on a template copy those are the template's Title / Heading / Normal styles, and on a blank doc they are Google's built-in defaults. Text inserted where a cleared template body left its final paragraph inherits that paragraph's explicit run-level font family and size, and an explicit run style outranks every paragraph style — so before this rule, every run of a published Doc carried Arial at a fixed size and the user's own styles could never apply. The style batch therefore opens with one range-wide updateTextStyle that resets weightedFontFamily and fontSize (field mask set, values left unset), handing typography back to the document; the table pass resets the same two on every cell it formats, because a table is placed after that batch and would otherwise inherit the same leftover style. The publisher never sets a font family or size on a run, with one deliberate exception: an inline code span gets a monospace family and a grey background. Bold, italic, links, blockquotes, lists and tables apply after the reset, so they are unaffected. Note that the Google Docs API cannot apply an account's saved "default styles" to an API-created document — that is a Google limitation, not an Omniscio setting; a doc only inherits those styles when it is created from a template that carries them.
Orchestrator. publishMarkdownToGoogleDocs() runs:
- Copy the template doc → new file in the destination folder, renamed to the resolved title (the template's footer with page numbering is preserved on the copy).
documents.getto find the firsttabId(templates use tabs to keep the page number footer; if the copy has zero tabs the template is misconfigured →GDOC_NO_TAB).- Clear the template body via a
deleteContentRangeon the tab (footer survives because it lives outside the body segment). - Three sequential
batchUpdatecalls — insert, lists, styles — each scoped to the resolvedtabId. applyTables()— replaces table placeholders with native Docs tables.- Trash older versions of the same title in the destination folder (
drive.files.listwith aname = ... and ... in parents and mimeType = 'application/vnd.google-apps.document' and trashed = falsequery, thenfiles.update {trashed: true}for each match older than the just-published doc). Non-fatal on failure — publish has already succeeded; trash failures only log.
Live progress. The publisher takes an optional onProgress(phase) and calls it between the steps above (preparing → create → insert → format → finalize) — purely additive, it never reorders the locked three-batch apply. When a UI publish supplies a renderer-minted progressId, the IPC handler bridges onProgress to an emitPush(GDOC_PUBLISH_PROGRESS, { progressId, phase }) push; the shared hook (usePublishMarkdownToGoogleDoc.ts) shows the persistent "Publishing…" toast (a loading spinner), advances its text per phase for its own progressId only (a unique coalesceKey keeps concurrent publishes independent), and removes it on resolve. The CLI route sends no progressId, so it streams nothing. Progress is an enhancement layer — the start + success/error toasts work even if no event arrives. Full invariant: I7 in google-docs-export-contract.md.
Defaults + overrides. Template doc ID and destination folder ID resolve in priority order: explicit input → user setting (googleDocsTemplateId / googleDocsDestFolderId) → none, in which case the publisher creates a blank Doc in the Drive root instead of copying a template. A template is only reachable when Omniscio created that file itself, or Google granted the app access to it: the connection holds drive.file (per-file access), not full auth/drive, so a Doc the user made in Drive is invisible to a copy and the publish fails GDOC_TEMPLATE_NOT_FOUND. Reusing an existing SOP Doc as the template therefore needs that Doc to have been created by Omniscio (publish once, style the result, then point the setting at it).
Stable error codes. Every entry point returns the same PublisherErrorCode discriminator (or wraps it in an IPC envelope / HTTP status code, but the underlying code is the same string).
On the CLI route the HTTP
codeis a sharedERROR_CODESmember instead —FORBIDDEN,UNPROCESSABLE,NOT_FOUND,SERVICE_UNAVAILABLE,INTERNAL. The strings below stay the publisher's and the IPC envelope's discriminator, and the CLI route keeps them on its server-side log line and telemetry; a CLI client must branch on the shared code.
GDOC_FEATURE_DISABLED—googleDocsExportEnabledis off (IPC + CLI gate; the publisher itself does not check the flag).GDOC_NOT_AUTHENTICATED— no refresh token in config OR the token was revoked.GDOC_SCOPE_INSUFFICIENT— the documents scope was never granted at connect time (user must re-auth).GDOC_PARSE_FAILED—markdown-to-doc.tsthrew on the input (malformed markdown that the parser can't recover from).GDOC_API_FAILED—docs.batchUpdate/drive.files.copy/ etc. returned a non-401 error (network, quota, throttle).GDOC_NO_TAB— the copied template has zero tabs (template misconfigured — user needs to fix the template doc).
IPC handler. google-doc-handlers.ts wraps the publisher in a wrapHandler('publish markdown to google doc', ...) that always returns { success: true, data: GdocPublishMarkdownResult } — the discriminated-union result carries the same error code on failure, so the renderer never sees a raw thrown string. The handler is the gate that enforces googleDocsExportEnabled (the publisher itself is flag-agnostic so the same code path can be reused by the CLI route without re-checking).
Renderer recovery. The right-click surfaces publish through usePublishMarkdownToGoogleDoc.ts, which humanizes every failure before it reaches a toast — no raw invalid_grant / token expired / HTTP-status text is ever shown, via the shared friendlyGoogleProductError translator (the same one Drive / Sheets / Calendar use). An expired or revoked Google session (GDOC_NOT_AUTHENTICATED / GDOC_SCOPE_INSUFFICIENT) shows a Re-authorize toast action that opens Settings → Google Workspace to reconnect; an unenabled Docs API shows an Enable Docs API link. (Navigation goes through useWizardNavigationStore.setPendingSection, not window.location.hash — Omniscio has no hash router.)
CLI route. cli-server.ts § registerGdocRoutes wires POST /gdoc/publish as an apply-immediately mutation behind the standard bearer-token gate + 10/min mutation bucket. Accepts either an inline markdown blob or a path to a local .md / .markdown file (read off disk inside the route). HTTP status mapping: 200 published, 400 bad body, 401 auth missing, 403 feature disabled, 413 body too large, 422 parse failed, 502 Google API failed. Safe to retry: an identical repeat — same X-Client-Request-Id header, or the same publish inputs when no header is sent — returns the doc the first call already created (idempotent: true) instead of making a duplicate, so a dropped response or network retry can't double-publish.
gog CLI fallback (resilience). If a publish is refused because the Docs API isn't enabled on Omniscio's Google Cloud project — or a Docs scope is missing — Omniscio automatically retries the publish through the local gog CLI, on your connected Google account, so the export still succeeds. Both entry points (the IPC handler and the CLI route) publish through publishMarkdownToGoogleDocsWithFallback, so every surface is covered. It's best-effort and safe-by-default: it only activates when gog is installed and signed into the same account Omniscio is connected to (guarded so a doc can never land in the wrong account), it's gated by the googleCliFallbackEnabled setting (on by default), and if gog can't help it falls back closed to the normal humanized error. Wiring this also made the publisher atomic — a failed publish no longer leaves an empty template copy in your Drive. Engineering detail + invariants: google-cli-fallback-contract.md.
Settings UI. GoogleDocsExportSettings.tsx is the collapsible card inside GoogleWorkspaceSettings.tsx — three settings, all reachable via Settings search: google-docs-export-enabled (the toggle), google-docs-template-id (template Doc ID override, optional), google-docs-dest-folder-id (destination folder ID override, optional). The card sits alongside Calendar / Drive / Sheets because all four piggyback on the same Google sign-in.
Integration registry. Entry google-docs-export in integration-registry.ts — kind: 'channel-adapter', featureFlag: 'googleDocsExportEnabled', settingsSearchId: 'google-docs-export-enabled', llmDocPath: 'docs/llm-library/google-docs-export.md'. The CI completeness lint enforces that every claim on the row has real backing wiring.
Telemetry. Every publish attempt fires gdoc_published via trackEvent() — attempted on failure (with errorCode), published on success (with markdownChars and trashedOlderCount). The free-form surface label distinguishes the originator: renderer:project-doc, renderer:scratchpad, renderer:message-bubble, renderer:chat-file-link, renderer:file-peek from the five right-click surfaces, cli from the HTTP route, and ipc / unknown as fallbacks when no label is supplied.
Related
- INDEX.md — full library index
- google-integrations.md — umbrella doc for Calendar + Drive + Sheets + Gmail, shared OAuth; documents the reverse route
POST /gdoc/import(Google Doc → markdown), a separate feature gated bygoogleDocImportEnabled - drive-integration.md — sibling Google integration using the same OAuth client
- sheets-integration.md — sibling Google integration with similar agent-driven UX
Last verified 2026-10-02