gatsby-source-google-docs
is a Gatsby plugin to use Google Docs as a data source.
Why use Google Docs to write your content ?
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 Markdowngatsby-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`
⬆️ For the tree example above: ⬆️ For the tree example above:🤡 How to add metadata?
description
field in Google Drive with a YAML
objectlocale: fr
template: post
category: Category Name
tags: [tag1, tag2]
slug: /custom-slug
date: 2019-01-01
template: page
defined as default excepts if you redefine it later.page
(default), home
, post
. Checkout the example template
exclude: true
. Perfect to keep drafts documents. One you want to publish a page, juste move the document one level up.
Drafts
will be exclude because of exclude: true
.
GoogleDocs
nodes and you can use everywhere in you Gatsby
site
Add an image in your Google Document first page header🌄 How to add cover?
⬆️ For the tree example above:
The The You also can add metadata (🍞 How to add slug and breadcrumb?
slug
and breadcrumb
fields add automatically generated using the folders tree structure and transformed using kebab-case
.
GoogleDocs
node for document My year 2020
{
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 !
}
GoogleDocs
node for document Post 2
will have a custom slug{
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
}
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"],
},
},
],
}
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 To get Syntax highlighting, I recommend using Add the Import a ⚛️ How to use codes blocks ?
lang:javascript
.prismjs
but it’s not mandatory.yarn add gatsby-remark-prismjs prismjs
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"],
},
},
],
}
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.
If you prefer to create pages manualy, checkout the createPages API et adapt it to your needs.How to create pages manualy?
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.