{"id":13451894,"url":"https://github.com/cedricdelpoux/gatsby-source-google-docs","last_synced_at":"2025-03-23T19:33:09.465Z","repository":{"id":38173169,"uuid":"169219734","full_name":"cedricdelpoux/gatsby-source-google-docs","owner":"cedricdelpoux","description":"Gatsby plugin to use Google Docs as a data source","archived":false,"fork":false,"pushed_at":"2024-12-10T11:22:36.000Z","size":19695,"stargazers_count":212,"open_issues_count":6,"forks_count":55,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-17T22:10:37.668Z","etag":null,"topics":["gatsby","gatsby-plugin","gatsby-plugin-source","gatsby-plugins","google-docs","google-docs-api","google-drive-api"],"latest_commit_sha":null,"homepage":"https://cedricdelpoux.github.io/gatsby-source-google-docs/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cedricdelpoux.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":"https://paypal.me/cedricdelpoux"}},"created_at":"2019-02-05T09:59:24.000Z","updated_at":"2025-01-30T17:56:41.000Z","dependencies_parsed_at":"2023-07-17T04:14:27.241Z","dependency_job_id":"74ea2238-db66-4c60-bbb1-6d56c213e9bb","html_url":"https://github.com/cedricdelpoux/gatsby-source-google-docs","commit_stats":{"total_commits":432,"total_committers":26,"mean_commits":"16.615384615384617","dds":"0.30787037037037035","last_synced_commit":"11abddb4fd9fa011cbbe14253f25b5792b1b5be4"},"previous_names":["xuopled/gatsby-source-google-docs"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedricdelpoux%2Fgatsby-source-google-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedricdelpoux%2Fgatsby-source-google-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedricdelpoux%2Fgatsby-source-google-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedricdelpoux%2Fgatsby-source-google-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cedricdelpoux","download_url":"https://codeload.github.com/cedricdelpoux/gatsby-source-google-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245158748,"owners_count":20570242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gatsby","gatsby-plugin","gatsby-plugin-source","gatsby-plugins","google-docs","google-docs-api","google-drive-api"],"created_at":"2024-07-31T07:01:06.140Z","updated_at":"2025-03-23T19:33:09.031Z","avatar_url":"https://github.com/cedricdelpoux.png","language":"JavaScript","funding_links":["https://paypal.me/cedricdelpoux"],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1\u003egatsby-source-google-docs\u003c/h1\u003e\n  \u003cbr/\u003e\n  \u003cp\u003e\n    \u003cimg src=\"./logo.png\" alt=\"gatsby-source-google-docs\" height=\"100px\"\u003e\n  \u003c/p\u003e\n  \u003cbr/\u003e\n\n[![Npm][badge-npm]][npm]\n[![Build Status][badge-build]][travis]\n[![Coverage][badge-coverage]][codecov]\n[![Downloads][badge-downloads]][npm]\n[![PRs welcome][badge-prs]](#contributing)\n[![MIT license][badge-licence]](./LICENCE.md)\n[![Paypal][badge-paypal]](https://paypal.me/cedricdelpoux)\n\n\u003c/div\u003e\n\n---\n\n`gatsby-source-google-docs` is a [Gatsby](https://www.gatsbyjs.org/) plugin to use [Google Docs](https://docs.google.com/) as a data source.\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003eWhy use Google Docs to write your content ?\u003c/summary\u003e\n\n-   🖋 Best online WYSIWYG editor\n-   🖥 Desktop web app\n-   📱 Mobile app\n-   🛩 Offline redaction\n-   🔥 No need for external CMS\n-   ✅ No more content in your source code\n\n\u003c/details\u003e\u003c/p\u003e\n\n## Features\n\n-   **Google Docs** formatting options (headings, bullets, tables, images...)\n-   `MDX` support to use `\u003cReactComponents /\u003e` in your documents\n-   **Gatsby** v3 \u0026 v4 support\n-   `gatsby-plugin-image` and `gatsby-image` support\n-   Code blocs support\n-   **Gatsby Cloud** support\n-   Slug generation from **Google Drive** tree\n-   Crosslinks between pages\n-   Related content\n-   Custom metadata to enhance documents\n\n## Documentation\n\nTo preview what you can do, please checkout [the documentation website](https://cedricdelpoux.github.io/gatsby-source-google-docs/).\n\n-   👨🏻‍💻 [Source code](/examples/website)\n-   🗂 [Google Docs content](https://drive.google.com/drive/folders/1YJWX_FRoVusp-51ztedm6HSZqpbJA3ag)\n\n\u003e 💯 100% content of the website is from Google Docs. Please suggest edits to improve it.\n\n## Installation\n\nDownload `gatsby-source-google-docs` and `gatsby-transformer-remark` (or `gatsby-plugin-mdx` for [advanced usage](/examples/website))\n\n```shell\nyarn add gatsby-source-google-docs gatsby-transformer-remark\n```\n\n-   `gatsby-source-google-docs` transform **Google Docs** to **Markdown**\n-   `gatsby-transformer-remark` transform **Markdown** to **HTML**\n-   `gatsby-plugin-mdx` transform **Markdown** to **MDX**\n\n## Token generation\n\nThe package needs 3 `.env` variables.\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003ePreview variables\u003c/summary\u003e\n\n```dotenv\nGOOGLE_OAUTH_CLIENT_ID=2...m.apps.googleusercontent.com\nGOOGLE_OAUTH_CLIENT_SECRET=Q...axL\nGOOGLE_DOCS_TOKEN={\"access_token\":\"ya...J0\",\"refresh_token\":\"1..mE\",\"scope\":\"https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/documents.readonly\",\"token_type\":\"Bearer\",\"expiry_date\":1598284554759}\n```\n\n\u003c/details\u003e\u003c/p\u003e\n\n`gatsby-source-google-docs` expose a script to generate it.\n\n-   Open a terminal at the root of your project\n-   Type the following command\n\n```shell\nnpx gatsby-source-google-docs-token\n```\n\n## Usage\n\n### Organize your documents\n\nGo to your [Google Drive](https://drive.google.com/drive/), create a folder and put some documents inside it.\n\n```js\n↳ 🗂 Root folder `template: page`\n    ↳ 🗂 en `locale: en` `skip: true`\n        ↳ 📝 Home `template: home`\n        ↳ 📝 About\n        ↳ 🗂 Posts `template: post`\n            ↳ 🗂 Drafts `exclude: true`\n                ↳ 📝 Draft 1\n            ↳ 📝 My year 2020 `date: 2021-01-01`\n            ↳ 📝 Post 2 `slug: /custom/slug` `template: special-post`\n    ↳ 🗂 fr `locale: fr`\n        ↳ 📝 Accueil `template: home`\n```\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003e🤡 How to enhance documents with metadata?\u003c/summary\u003e\n\n-   Fill the document (or folder) `description` field in Google Drive with a `YAML` object\n\n```yaml\nlocale: fr\ntemplate: post\ncategory: Category Name\ntags: [tag1, tag2]\nslug: /custom-slug\ndate: 2019-01-01\n```\n\n\u003e There are special metadata\n\u003e\n\u003e -   For folders:\n\u003e     -   `exclude: true`: Exclude the folder and its documents\n\u003e     -   `skip: true`: Remove the folder from slug but keep its documents\n\u003e -   For documents:\n\u003e     -   `index:true`: Use document as the folder index\n\u003e     -   `page: false`: Prevent page creation when `createPages` option is set to `true`\n\n-   Spread metadata into the tree using folders metadata.\n\n\u003e ⬆️ For the tree example above:\n\u003e\n\u003e -   Every node will have `template: page` defined as default excepts if you redefine it later.\n\u003e -   You need to create 3 different templates: `page` (default), `home`, `post`. [Checkout the example template](./example/src/templates/page.js)\n\u003e -   \"en\" folder will be removed from slug because of `skip: true`\n\n-   Exclude folders and documents using `exclude: true`. Perfect to keep drafts documents. One you want to publish a page, juste move the document one level up.\n\n\u003e ⬆️ For the tree example above:\n\u003e\n\u003e -   Documents under `Drafts` will be exclude because of `exclude: true`.\n\n-   Every metadata will be available in `GoogleDocs` nodes and you can use everywhere in you `Gatsby` site\n\n\u003c/details\u003e\u003c/p\u003e\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003e🌄 How to add cover?\u003c/summary\u003e\n\nAdd an image in your [Google Document first page header](https://support.google.com/docs/answer/86629)\n\n\u003c/details\u003e\u003c/p\u003e\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003e🍞 How to add slug and breadcrumb?\u003c/summary\u003e\n\n`slug` and `breadcrumb` fields add automatically generated using the folders tree structure and transformed using `kebab-case`.\n\n\u003e ⬆️ For the tree example above:\n\u003e The `GoogleDocs` node for document `My year 2020`\n\u003e\n\u003e ```js\n\u003e {\n\u003e     path: \"/en/posts/my-year-2020\" // Original Google Drive path\n\u003e     slug: \"/posts/my-year-2020\" // `en` is out because of `skip: true`\n\u003e     breadcrumb: [\n\u003e         {name: \"Posts\", slug: \"/posts\"},\n\u003e         {name: \"My year 2020\", slug: \"/posts/my-year-2020\"},\n\u003e     ],\n\u003e     template: \"post\" ,// src/templates/post.js\n\u003e     locale: \"fr\",\n\u003e     date: \"2021-01-01\" // Fixed date !\n\u003e }\n\u003e ```\n\u003e\n\u003e The `GoogleDocs` node for document `Post 2` will have a custom slug\n\u003e\n\u003e ```js\n\u003e {\n\u003e     path: \"/en/posts/post-2\"\n\u003e     slug: \"/custom/slug\"\n\u003e     breadcrumb: [\n\u003e         {name: \"Posts\", slug: \"/posts\"},\n\u003e         {name: \"Post 2\", slug: \"/custom/slug\"},\n\u003e     ],\n\u003e     template: \"special-post\",  // src/templates/special-post.js\n\u003e     locale: \"en\",\n\u003e     date: \"2020-09-12\" // Google Drive document creation date\n\u003e }\n\u003e ```\n\nYou also can add metadata (`locale`, `date`, `template`, ...) to your documents.\n\n\u003c/details\u003e\u003c/p\u003e\n\n### Add the plugin to your `gatsby-config.js` file\n\n| Option           | Required | Type    | Default | Example        |\n| ---------------- | -------- | ------- | ------- | -------------- |\n| folder           | `true`   | String  | `null`  | `\"1Tn1dCbIc\"`  |\n| createPages      | `false`  | Boolean | `false` | `true`         |\n| pageContext      | `false`  | Array   | `[]`    | `[\"locale\"]`   |\n| demoteHeadings   | `false`  | Boolean | `true`  | `false`        |\n| imagesOptions    | `false`  | Object  | `null`  | `{width: 512}` |\n| keepDefaultStyle | `false`  | Boolean | `false` | `true`         |\n| skipCodes        | `false`  | Boolean | `false` | `true`         |\n| skipFootnotes    | `false`  | Boolean | `false` | `true`         |\n| skipHeadings     | `false`  | Boolean | `false` | `true`         |\n| skipImages       | `false`  | Boolean | `false` | `true`         |\n| skipLists        | `false`  | Boolean | `false` | `true`         |\n| skipQuotes       | `false`  | Boolean | `false` | `true`         |\n| skipTables       | `false`  | Boolean | `false` | `true`         |\n| debug            | `false`  | Boolean | `false` | `true`         |\n\n```js\nmodule.exports = {\n    plugins: [\n        {\n            resolve: \"gatsby-source-google-docs\",\n            options: {\n                // https://drive.google.com/drive/folders/FOLDER_ID\n                folder: \"FOLDER_ID\",\n                createPages: true,\n            },\n        },\n        \"gatsby-transformer-remark\",\n        //\n        // OR \"gatsby-plugin-mdx\" for advanced usage using MDX\n        //\n        // You need some transformations?\n        // Checkout https://www.gatsbyjs.com/plugins/?=gatsby-remark\n        // And pick-up some plugins\n    ],\n}\n```\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003e📷 How to use images ?\u003c/summary\u003e\n\n`gatsby-plugin-sharp`, `gatsby-transformer-sharp` and `gatsby-remark-images` are required if you want to take advantage of [gatsby-image blur-up technique](https://using-gatsby-image.gatsbyjs.org/blur-up/).\n\n```shell\nyarn add gatsby-plugin-sharp gatsby-transformer-sharp gatsby-remark-images\n```\n\n```js\nmodule.exports = {\n    plugins: [\n        \"gatsby-source-google-docs\",\n        \"gatsby-plugin-sharp\",\n        \"gatsby-transformer-sharp\",\n        {\n            resolve: \"gatsby-transformer-remark\",\n            options: {\n                plugins: [\"gatsby-remark-images\"],\n            },\n        },\n    ],\n}\n```\n\n\u003c/details\u003e\u003c/p\u003e\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003e⚛️ How to use codes blocks ?\u003c/summary\u003e\n\nUse [Code Blocks](https://gsuite.google.com/marketplace/app/code_blocks/100740430168) Google Docs extension to format your code blocks.\n\nTo specify the lang, you need to add a fist line in your code block following the format `lang:javascript`.\n\nTo get Syntax highlighting, I recommend using `prismjs` but it's not mandatory.\n\n```shell\nyarn add gatsby-remark-prismjs prismjs\n```\n\nAdd the `gatsby-remark-prismjs` plugin to your `gatsby-config.js`\n\n```js\nmodule.exports = {\n    plugins: [\n        \"gatsby-source-google-docs\",\n        {\n            resolve: \"gatsby-transformer-remark\",\n            options: {\n                plugins: [\"gatsby-remark-prismjs\"],\n            },\n        },\n    ],\n}\n```\n\nImport a `prismjs` theme in your `gatsby-browser.js`\n\n```js\nrequire(\"prismjs/themes/prism.css\")\n```\n\n\u003c/details\u003e\u003c/p\u003e\n\n### Create templates and pages\n\nUsing `createPages: true` option, pages will be created automatically.\nYou need to create templates and define wich template to use using `YAML` metadata.\n\n\u003e You can set `page: false` metadata for a document to prevent a page creation\n\nCheckout the [example template](./example/src/templates/page.js) and adapt it to your needs.\n\n\u003e You can use `pageContext` option if you need extra data into the context of your pages.\n\n\u003cp\u003e\u003cdetails\u003e\u003csummary\u003eHow to create pages manualy?\u003c/summary\u003e\n\nIf you prefer to create pages manualy, checkout the [createPages API](./src/utils/create-pages.js) et adapt it to your needs.\n\n\u003c/details\u003e\u003c/p\u003e\n\n### Trigger production builds\n\n-   Go to [Google Drive example folder](https://drive.google.com/drive/folders/1YJWX_FRoVusp-51ztedm6HSZqpbJA3ag)\n-   Make a copy of **Trigger Gatsby Build** file using `Right Click -\u003e Make a copy`\n-   Open your copy and update the **Build Webhook URL** in `A2`\n-   Click the **Deploy** button to trigger a new build\n\n\u003e This method works with any hosting services: Gatsby Cloud, Netlify...\n\n## Showcase\n\nYou are using `gatsby-source-google-docs` for your website? Thank you!\nPlease add the link bellow:\n\n-   [documentation](https://cedricdelpoux.github.io/gatsby-source-google-docs/)\n-   [cedricdelpoux](https://cedricdelpoux.fr/en)\n\n## Contributing\n\n-   ⇄ Pull/Merge requests and ★ Stars are always welcome.\n-   For bugs and feature requests, please [create an issue][github-issue].\n\n[badge-paypal]: https://img.shields.io/badge/sponsor-PayPal-3b7bbf.svg?style=flat-square\n[badge-npm]: https://img.shields.io/npm/v/gatsby-source-google-docs.svg?style=flat-square\n[badge-downloads]: https://img.shields.io/npm/dt/gatsby-source-google-docs.svg?style=flat-square\n[badge-build]: https://img.shields.io/travis/cedricdelpoux/gatsby-source-google-docs/master?style=flat-square\n[badge-coverage]: https://img.shields.io/codecov/c/github/cedricdelpoux/gatsby-source-google-docs/master.svg?style=flat-square\n[badge-licence]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square\n[badge-prs]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[npm]: https://www.npmjs.org/package/gatsby-source-google-docs\n[travis]: https://travis-ci.com/cedricdelpoux/gatsby-source-google-docs\n[codecov]: https://codecov.io/gh/cedricdelpoux/gatsby-source-google-docs\n[github-issue]: https://github.com/cedricdelpoux/gatsby-source-google-docs/issues/new\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedricdelpoux%2Fgatsby-source-google-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcedricdelpoux%2Fgatsby-source-google-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedricdelpoux%2Fgatsby-source-google-docs/lists"}