MVP repository for an 11ty site built from a Google Docs export
- Node JS (20.x)
This repository is made of two parts:
- a series of scripts to convert the export from Google Docs into a hierarchy of Markdown and image files inside the
contentfolder. - an 11ty setup that'll transform the Markdown files into a static site (in the
_sitefolder).
content is committed to the repository, so you can run the 11ty site straight away after cloning the repository and installing its dependencies. Guidance on how to import a newer version of the Google Doc follows right after.
Before anything, you'll need to install the project's dependencies with:
npm ciOnce the dependencies are installed, you can use the following command to run the project locally:
npm startThis will make 11ty start a server, build the files into HTML and watch for changes to rebuild after you edit.
It should be shown in the console, but you should be able to access the local site at http://localhost:8080.
A couple of pointers that may help you make sense of what's going around:
- the 11ty configuration is at
eleventy.config.js
Importing the content is a three step process:
- Download the Google Docs as Web Page and unzip it in
_import - Convert the HTML document into Markdown
- Split the Markdown file into smaller files based on the document's heading
On Google Docs, download the document as a Web Page (File > Download > Web page (.html, zipped)). As hinted by the menu in the app, you will obtain a Zip file containing:
- an HTML file
- an
imagesfolder
Delete any existing copy of these files in the _import folder before copying the ones you just obtained. Your _import folder will look like so:
_import
├── <DOC_NAME>.html
└── images
├── image1.png
├── image2.png
└── ...
The scripts/import-google-doc.mjs file contains a configuration for rehype that will clean the markup from the Google Doc export a little and turn it into Markdown.
You can run the conversion with:
npm run docs-to-markdownThis should create a new _import/index.md file in your _import folder which should now look like so:
_import
├── <DOCS_NAME>.html
├── images
│ ├── image1.png
│ ├── image2.png
│ └── ...
└── index.md // Have a peek, it should be the tidy markdown from your doc
The scripts/split-into-smaller-files.mjs script will use remark to process the Mardkown and split it into one file per H1 it discovers. It'll also move any image displayed in one of these new files into the folder holding that file, for easier association when looking at the content (also saves rewriting some links 😆).
You can run it with:
npm run split-by-headingAfter which, your content folder should reflect the content of the document you imported.