search

cedricdelpoux / gatsby-source-google-docs

Gatsby plugin to use Google Docs as a data source
https://cedricdelpoux.github.io/gatsby-source-google-docs/
MIT License
212 stars 58 forks source link
gatsby gatsby-plugin gatsby-plugin-source gatsby-plugins google-docs google-docs-api google-drive-api

readme

gatsby-source-google-docs


gatsby-source-google-docs


[![Npm][badge-npm]][npm] [![Build Status][badge-build]][travis] [![Coverage][badge-coverage]][codecov] [![Downloads][badge-downloads]][npm] [![PRs welcome][badge-prs]](#contributing) [![MIT license][badge-licence]](./LICENCE.md) [![Paypal][badge-paypal]](https://paypal.me/cedricdelpoux)

gatsby-source-google-docs is a Gatsby plugin to use Google Docs as a data source.

Why use Google Docs to write your content ? - 🖋 Best online WYSIWYG editor - 🖥 Desktop web app - 📱 Mobile app - 🛩 Offline redaction - 🔥 No need for external CMS - ✅ No more content in your source code

Features

Documentation

To preview what you can do, please checkout the documentation website.

💯 100% content of the website is from Google Docs. Please suggest edits to improve it.

Installation

Download gatsby-source-google-docs and gatsby-transformer-remark (or gatsby-plugin-mdx for advanced usage)

yarn add gatsby-source-google-docs gatsby-transformer-remark

Token generation

The package needs 3 .env variables.

Preview variables ```dotenv GOOGLE_OAUTH_CLIENT_ID=2...m.apps.googleusercontent.com GOOGLE_OAUTH_CLIENT_SECRET=Q...axL GOOGLE_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} ```

gatsby-source-google-docs expose a script to generate it.

npx gatsby-source-google-docs-token

Usage

Organize your documents

Go to your Google Drive, create a folder and put some documents inside it.

↳ 🗂 Root folder `template: page`
    ↳ 🗂 en `locale: en` `skip: true`
        ↳ 📝 Home `template: home`
        ↳ 📝 About
        ↳ 🗂 Posts `template: post`
            ↳ 🗂 Drafts `exclude: true`
                ↳ 📝 Draft 1
            ↳ 📝 My year 2020 `date: 2021-01-01`
            ↳ 📝 Post 2 `slug: /custom/slug` `template: special-post`
    ↳ 🗂 fr `locale: fr`
        ↳ 📝 Accueil `template: home`

🤡 How to enhance documents with metadata? - Fill the document (or folder) `description` field in Google Drive with a `YAML` object ```yaml locale: fr template: post category: Category Name tags: [tag1, tag2] slug: /custom-slug date: 2019-01-01 ``` > There are special metadata > > - For folders: > - `exclude: true`: Exclude the folder and its documents > - `skip: true`: Remove the folder from slug but keep its documents > - For documents: > - `index:true`: Use document as the folder index > - `page: false`: Prevent page creation when `createPages` option is set to `true` - Spread metadata into the tree using folders metadata. > ⬆️ For the tree example above: > > - Every node will have `template: page` defined as default excepts if you redefine it later. > - You need to create 3 different templates: `page` (default), `home`, `post`. [Checkout the example template](./example/src/templates/page.js) > - "en" folder will be removed from slug because of `skip: true` - 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. > ⬆️ For the tree example above: > > - Documents under `Drafts` will be exclude because of `exclude: true`. - Every metadata will be available in `GoogleDocs` nodes and you can use everywhere in you `Gatsby` site

🌄 How to add cover? Add an image in your [Google Document first page header](https://support.google.com/docs/answer/86629)

🍞 How to add slug and breadcrumb? `slug` and `breadcrumb` fields add automatically generated using the folders tree structure and transformed using `kebab-case`. > ⬆️ For the tree example above: > The `GoogleDocs` node for document `My year 2020` > > ```js > { > path: "/en/posts/my-year-2020" // Original Google Drive path > slug: "/posts/my-year-2020" // `en` is out because of `skip: true` > breadcrumb: [ > {name: "Posts", slug: "/posts"}, > {name: "My year 2020", slug: "/posts/my-year-2020"}, > ], > template: "post" ,// src/templates/post.js > locale: "fr", > date: "2021-01-01" // Fixed date ! > } > ``` > > The `GoogleDocs` node for document `Post 2` will have a custom slug > > ```js > { > path: "/en/posts/post-2" > slug: "/custom/slug" > breadcrumb: [ > {name: "Posts", slug: "/posts"}, > {name: "Post 2", slug: "/custom/slug"}, > ], > template: "special-post", // src/templates/special-post.js > locale: "en", > date: "2020-09-12" // Google Drive document creation date > } > ``` You also can add metadata (`locale`, `date`, `template`, ...) to your documents.

Add the plugin to your gatsby-config.js file

Option Required Type Default Example
folder true String null "1Tn1dCbIc"
createPages false Boolean false true
pageContext false Array [] ["locale"]
demoteHeadings false Boolean true false
imagesOptions false Object null {width: 512}
keepDefaultStyle false Boolean false true
skipCodes false Boolean false true
skipFootnotes false Boolean false true
skipHeadings false Boolean false true
skipImages false Boolean false true
skipLists false Boolean false true
skipQuotes false Boolean false true
skipTables false Boolean false true
debug false Boolean false true 
module.exports = {
    plugins: [
        {
            resolve: "gatsby-source-google-docs",
            options: {
                // https://drive.google.com/drive/folders/FOLDER_ID
                folder: "FOLDER_ID",
                createPages: true,
            },
        },
        "gatsby-transformer-remark",
        //
        // OR "gatsby-plugin-mdx" for advanced usage using MDX
        //
        // You need some transformations?
        // Checkout https://www.gatsbyjs.com/plugins/?=gatsby-remark
        // And pick-up some plugins
    ],
}

📷 How to use images ? `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/). ```shell yarn add gatsby-plugin-sharp gatsby-transformer-sharp gatsby-remark-images ``` ```js module.exports = { plugins: [ "gatsby-source-google-docs", "gatsby-plugin-sharp", "gatsby-transformer-sharp", { resolve: "gatsby-transformer-remark", options: { plugins: ["gatsby-remark-images"], }, }, ], } ```

⚛️ How to use codes blocks ? Use [Code Blocks](https://gsuite.google.com/marketplace/app/code_blocks/100740430168) Google Docs extension to format your code blocks. To specify the lang, you need to add a fist line in your code block following the format `lang:javascript`. To get Syntax highlighting, I recommend using `prismjs` but it's not mandatory. ```shell yarn add gatsby-remark-prismjs prismjs ``` Add the `gatsby-remark-prismjs` plugin to your `gatsby-config.js` ```js module.exports = { plugins: [ "gatsby-source-google-docs", { resolve: "gatsby-transformer-remark", options: { plugins: ["gatsby-remark-prismjs"], }, }, ], } ``` Import a `prismjs` theme in your `gatsby-browser.js` ```js require("prismjs/themes/prism.css") ```

Create templates and pages

Using createPages: true option, pages will be created automatically. You need to create templates and define wich template to use using YAML metadata.

You can set page: false metadata for a document to prevent a page creation

Checkout the example template and adapt it to your needs.

You can use pageContext option if you need extra data into the context of your pages.

How to create pages manualy? If you prefer to create pages manualy, checkout the [createPages API](./src/utils/create-pages.js) et adapt it to your needs.

Trigger production builds

This method works with any hosting services: Gatsby Cloud, Netlify...

Showcase

You are using gatsby-source-google-docs for your website? Thank you! Please add the link bellow:

Contributing