One shareable URL per project. Markdown stays local. Drive stays current.
This repo is the living spec for how we use Google Drive to kill document sprawl across all projects. Platform guides: macOS | Windows
Document sprawl is the natural entropy of any team producing knowledge:
- Files accumulate across local machines, email threads, and chat attachments
- No one knows which version is authoritative
- Links sent via email go stale the moment the file is renamed or updated
- OneDrive sharing creates friction for recipients without Microsoft accounts
- Attaching docs to emails is the worst possible distribution mechanism
Local Filesystem Google Drive
──────────────────────────── ────────────────────────────
~/dev2/clients/U-Rent/docs/ ←→ My Drive/Projects/U-Rent/
~/dev2/UpApply/docs/ ←→ My Drive/Projects/UpApply/
~/dev2/FaithVision/docs/ ←→ My Drive/Projects/FaithVision/
One Drive folder per project. Write .md files locally. Drive syncs automatically.
Recipients get one permanent URL that always reflects current state — no login required.
This is the key technical nuance: Google Drive stores .md files as native/opaque files — not Google Docs. They are not interpreted, converted, or reformatted.
| Behavior | Detail |
|---|---|
| File fidelity | 100% — byte-for-byte sync, like Dropbox |
| Browser preview | Plain-text preview (not rendered HTML) |
| Sharing | Folder URL works for any recipient, no Google account required for read-only |
| Conflict handling | Drive creates a conflict copy (filename (1).md) if two people write simultaneously |
| Offline | Drive for Desktop queues changes and syncs on reconnect |
My Drive/
└── Projects/
├── U-Rent/ ← share this URL with U-Rent stakeholders
│ ├── README.md
│ ├── api-spec.md
│ └── architecture.md
├── UpApply/
│ └── ...
└── FaithVision/
└── ...
The folder URL is the stable artifact. Files inside can be added, renamed, or updated without changing the URL you distribute. The Drive folder ID in the URL is permanent even after renames.
- Right-click the folder in Google Drive → Share
- Under "General access" → set to Anyone with the link
- Choose permission level:
- Viewer — read-only, no account required. Use for external stakeholders.
- Editor — recipients with Google accounts can upload or edit. Use for trusted collaborators.
- Copy link → paste into email
Email template:
"Here are the current project docs — this link always reflects the latest version, no login required: https://drive.google.com/drive/folders/[FOLDER-ID]"
Google's official app. Bidirectional, real-time, no CLI required. Works on macOS and Windows.
- See setup-mac.md for macOS
- See setup-windows.md for Windows
Critical setting: Choose Mirror files mode (not "Stream files"). Stream mode creates stubs that only download on open — your local editor needs real files on disk.
Open-source CLI for syncing to/from Google Drive. Use this for:
- Server-side automation (no GUI)
- CI/CD pipelines that generate docs
- Scheduled syncs on a cron/Task Scheduler interval
# Install
brew install rclone # macOS
winget install rclone.rclone # Windows
# Authorize (OAuth flow)
rclone config
# One-way push: local → Drive
rclone sync ~/dev2/clients/U-Rent/docs remote:Projects/U-Rent --include "*.md"
# Bidirectional (rclone v1.58+)
rclone bisync ~/dev2/clients/U-Rent/docs remote:Projects/U-Rent --include "*.md"Use when docs are generated by a pipeline (e.g., automated reports, AI outputs). Requires OAuth credentials and is overkill for manual workflows.
Place a .gdriveignore file in any synced folder. Syntax is identical to .gitignore.
# .gdriveignore
node_modules/
.git/
dist/
build/
.next/
__pycache__/
*.log
.env
.env.*
Drive for Desktop respects this file on both macOS and Windows.
| Dimension | Google Drive | OneDrive |
|---|---|---|
| Anonymous sharing | Yes — no account required for view | Often requires Microsoft account |
| Sharing URL stability | Permanent folder ID | Can expire; SharePoint URLs are long |
| Cross-platform sync app | macOS, Windows | macOS, Windows (Linux via rclone only) |
| Markdown handling | Native file, no conversion | Native file, no conversion |
| Free storage | 15 GB | 5 GB (Microsoft 365 for more) |
| External stakeholder friction | Low | Higher for non-Microsoft users |
Verdict: For sharing with external stakeholders, Google Drive wins on friction. If your entire team is Microsoft 365, OneDrive is fine internally — but Google Drive is the better choice for anything leaving the org.
| Approach | Use When | Skip When |
|---|---|---|
GitHub (raw .md) |
Docs live in a repo, recipients are technical | Stakeholders shouldn't touch the codebase |
| GitHub Pages / MkDocs | Want rendered HTML docs with search | Docs are working/ephemeral notes |
| Notion | Want polished, database-backed docs | Writing locally in .md is non-negotiable |
| Obsidian Publish | Already using Obsidian, want a public site | Don't want a $10/month subscription |
| Dropbox | Already have a subscription | Need free anonymous sharing (Dropbox often requires account) |
| MkDocs on Vercel | Permanent reference docs (architecture, APIs) | Ephemeral working docs (meeting notes, status) |
| Risk | Mitigation |
|---|---|
| Accidentally syncing secrets | Only sync a dedicated docs/ subfolder, never the project root. Use .gdriveignore for .env files. |
| Conflicting simultaneous edits | Drive creates conflict copies with (1) suffix. Designate one person as owner for live collaboration. |
| Storage quota hit | .md files are kilobytes. 15 GB free supports tens of thousands of docs. |
| Recipient loses the link | Re-send. Add them as an explicit collaborator in Drive for persistent access without a link. |
Fill these in after initial setup.
| Project | Drive Folder URL |
|---|---|
| U-Rent | (pending) |
| UpApply | (pending) |
| FaithVision | (pending) |
| Add more... |
Maintained by dbbuilder-org