directory: (Required) Directory for exporting pages. A directory is created for each section, but it is basically flat.
concurrency: Defaults to 5.
authorName: You can uniformly set the author of the article.
s3ImageUrlWarningEnabled: Defaults to true. If the generated Markdown file contains an Amazon S3 URL, this tool will throw an error and terminate execution, but you can disable this behavior. It is highly recommended to enable it to avoid accidentally exposing your S3 URL. It should only be used for debugging.
s3ImageUrlReplaceEnabled (Experimental): Defaults to false. If your Notion content contains S3 URLs, replace them with local paths after downloading. This function attempts to reduce the time and effort required for image management.
s3ImageConvertToWebpEnalbed: Defaults to false. Converts downloaded images to Webp format.
utcOffset: Defaults to null as “Z”. If you don’t set the content publish time, it will be exported as 12:00 AM, but you can specify the time zone offset that will be used at that time (e.g. “+09:00”).
saveAwsImageDirectory: Defaults to null. Images uploaded to Notion’s pages are stored on Amazon S3, but the public URL has an 3600s limit. This is incompatible with generators that generate static HTML like Hugo. Therefore, you should upload it to some external storage and then embed the URL in the Notion’s page. Enabling this option will make your work a little eaiser as the software will download the images.
downloadImageCallback: Defaults to null. If you want to use the downloaded image for addition processing, you can implement a callback. For example, an example implementation for uploading an image to WordPress (using REST API) can be found in notion-hugo.config.02callback-sample.js
fetchInterval: Only available in server mode. See “Watch mode (Server mode)” for more information. Defaults to 30.
Currently, this software is not published to the NPM registry. You need local build.
Step 1. Prepare the command
Set up a link to your local environment.
git clone ...
npm install
npm link
Step 2. Set environment
Set two environment variables to access the Notion.
NOTION_BLOG_DATABASE_ID=NOTION_TOKEN=# Notion tokens can be read-only role
Step 3. Configuration
Create a config file.
cp notion-hugo.config.01sample.js notion-hugo.config.js
# Or if you need a custom process after downloading the imagecp notion-hugo.config.02callback-sample.js notion-hugo.config.js
Step 4. Prepare the proparty in Notion database
Notion database property keys must be:
Property Name
Type
Required
Default value
isPublished
Boolean
✅
Category
Select
✅
Tags
multi_select
✅
PublishedAt
date
✅
UpdatedAt
date
✅
Url
Text
✅ (Either Url or Slug)
Slug
Text
✅ (Either Url or Slug)
LegacyAlert
Boolean
(Removed mandatory constraint from v0.5)
Description
Text
✅
Image
Image (external url)
✅
ToC
Boolean
(Removed mandatory constraint from v0.5)
Section
Select
✅
Author
Text or Select
“Writer”
isDraft
Boolean
false
filepath
Text
Currently, these keys must be set manually.
filepath property: Normally, the filename is automatically generated from Section and PageID (generated by Notion), but it can be overriden by specifying the absolute path.
Cache the last modified date of a Notion’s page with Notion’s pageId as the primary key.
To minimize the number of request to the Notion API, we cache the date and time of the retrieved pages. Delete the .notion-hugo-cache/ directory if you want to initialize it.
Customize according to the property type
You can define your own custom transformer for a notion type.
CustomTransformer is a feature provided by the notion-to-md library. Seed the official document for more details.
It can be optionally implemented in the notion-hugo.config.js file as shown bellow.
Due to the specification change in notion-to-md version 2.5.1, multiple line breaks have been inserted in paragraphs. It’s a matter of taste, but we have customized it to handle the number of line breaks in paragraphs according to the conventional specifications. Future updates to the library may make this feature obsolete.
If you want to use the original library specification, you can change the behavior by setting the setting to true.
useOriginalConverter: true
See the image bellow for an example.
Page content in Notion:
Output results when the setting is enabled (right side) and disabled (left side):
Watch mode (Server mode)
Exporting Notion pages can be time consuming, so running command one by one can be tedious. You can use the --server option to enter watch mode.
In this mode, Notion updates are checked periodically and a page is generated. By using it together with Hugo’s hugo server, you can use it like a real-time preview.
It’s even more useful for process managers such as Foreman and Hivemind. The following is a example of how to configure Procfile.
notion: notion-hugo -S
hugo: hugo server --ignoreCache --buildFuture
In watch mode, the S3 image download function does not work. This is because many changes are assumed during the editing process.