Install
Brasth Document Sync requires WordPress 6.4 or higher and PHP 8.1 or higher.
Install it from the WordPress.org directory (Plugins → Add New), or upload the plugin ZIP through Plugins → Add New → Upload Plugin. The folder name is brasth-document-sync-for-google-docs; you can also drop that folder into /wp-content/plugins/.
Activate Brasth Document Sync from the Plugins screen, then open it in the admin. The setup wizard shows the authorized redirect URI and the next incomplete OAuth step. Do not skip past that screen — the redirect URI is generated for your site.
Activate Brasth Document Sync, then open it from the admin menu.
Google OAuth
This release is not a hosted Google connector. The site owner supplies a Google Cloud OAuth web client. Brasth does not issue client IDs or sit in the middle of document traffic.
You need one Google Cloud project with the Drive and Docs APIs enabled, an OAuth consent screen, and a Web application client. Copy the redirect URI from the wizard into that client, then save the client ID and secret in WordPress. You can paste them, or use Import OAuth JSON with the Web application JSON downloaded from Google Cloud. The client secret is encrypted with WordPress salts before it is stored.
The ten setup steps — project, APIs, consent screen, web client, redirect URI, save credentials, connect, link — are written out on How it works. Use that walkthrough for Google Cloud. This page picks up once the client is saved.
The wizard shows the next action, the redirect URI generated for your site, and optional OAuth JSON import.
Connect a Google account
After the site OAuth client is saved, each WordPress user connects the Google account they write with. There is no shared site-wide Google login in this release.
The plugin requests the drive.readonly scope — formally https://www.googleapis.com/auth/drive.readonly — so a connected user can browse and sync documents that account can already read. It does not ask for write access to Drive.
Per-user tokens are encrypted with WordPress salts, the same way the site client secret is. Rotating those salts makes the stored credentials unreadable. Everyone who had connected a Google account must reconnect.
After the site client is saved, each WordPress user connects their own Google account.
After Connect Google, the checklist is complete. The next action is the first synced draft.
Link a document
From the posts list, Add Sync Doc opens a Drive browser for My Drive and shared drives, with breadcrumbs, search, and folder navigation. If you already know the document, switch to paste a Google Docs URL or the raw file ID.
Link the document to a post, page, or an enabled public custom post type. Sync is one-way: Google Docs → WordPress. Later syncs overwrite the WordPress content for that source. Sync does not delete WordPress posts.
Google Docs export as HTML ZIP packages. Embedded images land in the Media Library. The HTML is sanitized and converted to Gutenberg blocks. If Google blocks a large ZIP export, the plugin falls back to the Google Docs API before it changes post content.
In the editor, the Brasth Document Sync meta box is where you Change Doc, Sync now, or Detach. Source status also appears in the posts list Sync column, including progress on large documents. Change Doc, Detach, and the layout preset lock while a sync is running.
Add Sync Doc opens the Drive picker. Select a document, then Create synced draft.
Change Doc, Sync now, Detach, and the layout preset. Source changes lock while a sync is running.
Add Sync Doc, a Sync column, and progress for large documents.
The Sync column on the posts list, then Sync now and Change Doc in the editor meta box.
Browse My Drive after Connect Google. Folder names on this shot are covered.
If you already know the document, paste a docs.google.com URL or switch to Paste file ID.
A linked Doc with status, last sync, Sync, and Logs. The file ID on this shot is covered.
Layouts
Choose how a synced document should land. Gutenberg and Elementor keep separate preset selectors, so the two paths do not overwrite each other. Site defaults live in Setup; a source can override them.
Gutenberg presets:
- Clean Article
- Documentation
- Plain Blocks
Elementor presets, used when the destination is built in Elementor:
- Elementor Hero Page
- Elementor Feature Block
The Documentation preset is aimed at technical writing already structured in Google Docs. It looks for semantic and fenced code, Google Docs styled code-like paragraphs, and explicit Note, Tip, Warning, Important, and Caution callouts.
Headings, paragraphs, lists, tables, code, callouts, and images convert to Gutenberg blocks on the way in, whichever Gutenberg preset you choose.
Site defaults for post types, scheduled sync, Gutenberg layout, and optional Elementor support.
A selected Doc can use the site default or pick a different Gutenberg preset. The document name and URL on this shot are covered.
Background sync
Manual and scheduled background syncs use WP-Cron. In Setup, scheduled sync can be Off, Hourly, Twice daily, or Daily. Linked sources stay current without opening each post. Status remains visible on the posts list and in the editor meta box.
WP-Cron runs when someone visits the site. On a low-traffic site, or a site with DISABLE_WP_CRON, scheduled syncs wait. Configure a real server cron job that calls wp-cron.php so those jobs still fire.
Drive Folders
The Drive Folders screen ships in 1.1.5. See what 1.1.5 adds.
Pick a Drive folder, then Use this folder and Start folder sync. Linked sources still need WP-Cron (or a server cron job) to stay current.
Pick a Drive folder, then Use this folder and Start folder sync.
Sync Activity logs
Sync Activity logs are searchable, with troubleshooting views, filters, and recovery hints. Open them from the Logs screen, or from a source row when you need the events for one document. The console includes All events, Needs attention, Stalled / WP-Cron, and Large doc fallback.
You can clear logs for one source or for all visible sources you can edit. Clearing removes stored diagnostic events only — the _docsync_wp_sync_events data. It does not detach documents, delete synced posts, drop imported media, or remove credentials, sync status, or progress.
Search events and switch between Needs attention and All events.
Search events and switch troubleshooting views. Clearing logs does not detach documents.
Troubleshooting
Does DocSync provide a hosted Google connector?
No. This release uses self-managed Google OAuth. The site owner supplies the Google Cloud project and OAuth web client.
Which Google APIs are required?
Enable both the Google Drive API and the Google Docs API in the same Google Cloud project used by the OAuth client. Drive lists and exports documents; Docs is used when a large HTML ZIP export is blocked.
Which Google OAuth scope is used?
https://www.googleapis.com/auth/drive.readonly, so connected users can browse and sync Google Docs their account can already read.
Does sync delete WordPress posts?
No. Sync updates the linked post content. Uninstall never deletes synced posts. Full post-meta cleanup is available only through the documented full-uninstall constant or filter.
What happens on low-traffic sites?
Manual and scheduled background syncs use WP-Cron. Low-traffic sites, or sites with DISABLE_WP_CRON, should configure a real server cron job that calls wp-cron.php.
Can I clear sync logs?
Yes. The Logs screen can clear stored diagnostic events for one source or all sources you can edit. Clearing logs does not delete linked Docs, sync status, credentials, progress, synced posts, or imported media.
Are Google OAuth secrets and user tokens stored safely?
The site OAuth client secret and per-user Google tokens are encrypted with WordPress salts before storage. Rotating WordPress salts invalidates those credentials, and users must reconnect. See Privacy for what stays on the site and what is sent to Google.
Uninstall
Uninstalling the plugin removes settings, encrypted user Google tokens, and scheduled cron events. Synced posts and imported media stay on the site.
Linked post metadata is kept unless you define DOCSYNC_WP_FULL_UNINSTALL or return true from the docsync_wp_full_uninstall filter. That full cleanup still does not delete posts or media.
Get help
If a section of this guide is wrong or incomplete, open a GitHub issue from that section’s heading tools so the report already points at the page and hash. Existing issues in the repository are internal release notes, not user documentation — do not treat issue numbers as a support index.
For the Google Cloud walkthrough, use How it works. For what the plugin stores and sends, use Privacy. The canonical plugin description is the WordPress.org listing.