google-docs-sync
[![Build Status][badge-build]][actions] [![MIT license][badge-licence]](./LICENCE.md) [![PRs welcome][badge-prs]](#contributing) [![Paypal][badge-paypal]](https://paypal.me/cedricdelpoux)
Use Google Docs as a content source. This monorepo holds the packages that read a Google Doc, convert it to Markdown or MDX, and handle the Google authentication they need.
| Package | Version | Description |
| ------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ |
| gatsby-source-google-docs | [![npm][v-gatsby]][n-gatsby] | Gatsby plugin that uses Google Docs as a data source |
| astro-loader-google-docs | [![npm][v-astro]][n-astro] | Astro content loader that uses Google Docs as a collection |
| next-google-docs | [![npm][v-next]][n-next] | Next.js adapter that syncs Google Docs at build time |
| google-docs-sync | [![npm][v-sync]][n-sync] | Sync a Google Drive folder of Google Docs to local Markdown or MDX files |
| google-docs-to-markdown | [![npm][v-md]][n-md] | Convert a Google Docs API document to Markdown or MDX |
| google-oauth2-env-vars | [![npm][v-oauth]][n-oauth] | Generate and cache Google OAuth 2.0 tokens in .env files |
Which package do I need?
- A Gatsby site:
gatsby-source-google-docs. - An Astro site:
astro-loader-google-docs. - A Next.js site:
next-google-docs. - Another framework, a build script or the command line:
google-docs-sync.
npx google-docs-sync --folder <id>
import {syncGoogleDocs} from "google-docs-sync"
const {documents} = await syncGoogleDocs({
folder: "FOLDER_ID",
outputDir: "src/content/docs",
})
- Only the conversion of a Google Docs API document:
google-docs-to-markdown. - Only Google OAuth tokens in
.envfiles:google-oauth2-env-vars.
How it works
The framework packages are thin adapters over google-docs-sync, which owns the Google APIs and the filesystem. Each package has its own README and CHANGELOG.
gatsby-source-google-docs, astro-loader-google-docs, next-google-docs
└─ google-docs-sync
├─ google-docs-to-markdown
└─ google-oauth2-env-vars
Development
The repository uses npm workspaces and requires Node.js 22.12 or later.
npm install
npm run lint # build, then eslint and tsc in each package, then prettier
npm test # run the tests of each package
npm run build # generate the type declarations of each package
npm run format # format the repository with prettier
Use -w to run a script in one package, for example npm test -w google-docs-to-markdown.
Contributing
- Pull requests and stars are always welcome.
- For bugs and feature requests, please [create an issue][github-issue].
- A change to a package comes with a changeset: run
npm run changeset(see Releases). - Run the tests of one package with
npm test -w, for examplenpm test -w google-docs-sync.
Releases
The packages are versioned independently with changesets.
- Run
npm run changesetto choose the packages and the bump (patch, minor or major) and to describe the change. Commit the generated file with your pull request. - When the pull request is merged into
main, theReleaseworkflow opens a "Version packages" pull request. It bumps the versions, updates the changelogs and the dependency ranges between the packages. - Merging the "Version packages" pull request publishes the new versions to npm with their provenance and creates the git tags.
Support
If this project is useful to you, you can give it a star, or sponsor it with PayPal. You can also visit cedricdelpoux.fr.
License
[badge-build]: https://img.shields.io/github/actions/workflow/status/cedricdelpoux/google-docs-sync/ci.yml?branch=main&style=flat-square [badge-licence]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square [badge-prs]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square [badge-paypal]: https://img.shields.io/badge/sponsor-PayPal-3b7bbf.svg?style=flat-square [actions]: https://github.com/cedricdelpoux/google-docs-sync/actions/workflows/ci.yml [github-issue]: https://github.com/cedricdelpoux/google-docs-sync/issues/new [v-gatsby]: https://img.shields.io/npm/v/gatsby-source-google-docs.svg?style=flat-square [n-gatsby]: https://www.npmjs.com/package/gatsby-source-google-docs [v-astro]: https://img.shields.io/npm/v/astro-loader-google-docs.svg?style=flat-square [n-astro]: https://www.npmjs.com/package/astro-loader-google-docs [v-next]: https://img.shields.io/npm/v/next-google-docs.svg?style=flat-square [n-next]: https://www.npmjs.com/package/next-google-docs [v-sync]: https://img.shields.io/npm/v/google-docs-sync.svg?style=flat-square [n-sync]: https://www.npmjs.com/package/google-docs-sync [v-md]: https://img.shields.io/npm/v/google-docs-to-markdown.svg?style=flat-square [n-md]: https://www.npmjs.com/package/google-docs-to-markdown [v-oauth]: https://img.shields.io/npm/v/google-oauth2-env-vars.svg?style=flat-square [n-oauth]: https://www.npmjs.com/package/google-oauth2-env-vars