Need help with gatsby-source-google-docs?
Click the β€œchat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

cedricdelpoux
145 Stars 36 Forks MIT License 302 Commits 0 Opened issues

Description

Gatsby plugin to use Google Docs as a data source

Services available

!
?

Need anything else?

Contributors list

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] ![MIT license][badge-licence] ![Paypal][badge-paypal]


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
  • πŸ—‚ Automatic breadcrumb generation
  • 🀑 Custom metadata fields

Install

Download

gatsby-source-google-docs
and
gatsby-transformer-remark
yarn add gatsby-source-google-docs gatsby-transformer-remark
  • gatsby-source-google-docs
    transform Google Docs to Markdown
  • gatsby-transformer-remark
    transform Markdown to HTML

Generate a token

The package needs 3

.env
variables.

Preview variables
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 them.
  • Open a terminal at the root of your project
  • Type the following command
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 add metadata?
  • Fill the document (or folder) description field in Google Drive with a YAML object
locale: fr
template: post
category: Category Name
tags: [tag1, tag2]
slug: /custom-slug
date: 2019-01-01
  • 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

  • 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

🍞 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

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",
        // 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.

yarn add gatsby-plugin-sharp gatsby-transformer-sharp gatsby-remark-images
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 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.

yarn add gatsby-remark-prismjs prismjs

Add the gatsby-remark-prismjs plugin to your gatsby-config.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

require("prismjs/themes/prism.css")

| Option | Required | Type | Default | Example | | -------------- | -------- | ------- | ------- | ------------ | | folder | true | String | - | "1Tn1dCbIc" | | createPages | false | Boolean | false | true | | pageContext | false | Array | [] | ["locale"] | | demoteHeadings | false | Boolean | true | false | | imagesOptions | false | Object | - | {width: 512} | | 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 |

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.

Checkout the example template et 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 et adapt it to your needs.

Showcase

You are using

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

Contributing

  • ⇄ Pull/Merge requests and β˜… Stars are always welcome.
  • For bugs and feature requests, please create an issue.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.