dragonman225/notablog

Tell stories of your work with Notion

Notablog

Generate a minimalistic blog from a Notion table, so you can tell stories of your work with Notion.

Below are some screenshots of Alexander Wang (@dragonman225)'s blog. 🙂

Mobile	Desktop

Management Interface on Notion.so

Table of Contents

• Getting Started
• Blog Management Interface
• API Reference
• Notes

Getting Started

Make sure you have Node.js v15.0.0 or higher. Check with command node -v.

For existing users who want to upgrade from v0.3.x, please go through all below steps (do a clean install), except that you can continue to use your Notion table.

1. Install Notablog.

   npm i -g notablog

2. Clone the notablog-starter repository.

   git clone https://github.com/dragonman225/notablog-starter.git

3. Duplicate this Notion table template.

4. Make the table you've duplicated public and copy its URL for the next step.

5. Go into notablog-starter/ directory, open config.json. Replace the value of url with the URL of the table you've duplicated.

6. Inside notablog-starter/ directory, run command:

   notablog generate .

7. After it finishes, go to notablog-starter/public/ directory, open index.html with a browser to preview your site.

• Optionally, you could change the previewBrowser field in config.json to the path of a browser executable you have on your computer and issue the following command anywhere to preview.

  notablog preview <path_to_the_notablog-starter>

Congratulations! Your website is ready now!

• You can copy files in notablog-starter/public/ directory to a server or upload them to any static hosting service to share your content with the world.

• Whenever you want to update your site, go into notablog-starter/ directory and issue command notablog generate ., or issue the command from outside notablog-starter/ with the pattern notablog generate <path_to_the_notablog-starter>.

• Some options for static hosting services:

  • Github Pages
  • Netlify
  • surge.sh

• Some options for self-hosting:

  • nginx
  • lighttpd
  • Apache httpd

Blog Management Interface

This is the documentation of Notion table template

Column Name	Property Type	Description
title	Title	The page title.
tags	Multi-Select	Topics related to the page.
publish	Checkbox	Determine if a page should be rendered.
inMenu	Checkbox	Determine if a page should appear in the navigation bar.
inList	Checkbox	Determine if a page should appear in the article list.
template	Select	Specify which template to use for the page. Available template names depend on the theme you use.
url	Text	A string to be used as the filename and the URL of the generated page. It should not contain / and \. If it's empty, the id of the page is used.
description	Text	Short intro of the page. Styles are working.
date	Date	User customizable date, convenient for importing posts from other platforms or adjusting the order of posts.

• Tip: Check publish but leave inMenu and inList unchecked to make a page seem like hidden because people can only view it when they know its URL.

API Reference

Introduction

Notablog is a command-line tool that works on a notablog-starter to generate sites. notablog-starter contains user config and customizable themes, and is used to store cached data and generated site. The design is inspired by hexo, a popular static site generator.

Folder Structure of notablog-starter

notablog-starter
├── config.json
├── public
├── cache
└── themes
    ├── pure
    └── pure-ejs

• config.json - User configuration.

  Field	Type	Description
  url	string	The URL of a Notion table compatible with Notablog.
  theme	string	The theme to use. It should be one of the folder names in themes/.
  previewBrowser	string	The path to the browser executable for previewing.
  autoSlug	boolean	Generate URL slugs for pages without custom ones.
  locales	string/string[]	The locales which are used to generate string of a date (passed as first argument to Date.prototype.toLocaleDateString())

• public/ - Contains generated static assets.

• cache/ - Stores cached NAST representation of Notion pages. When running notablog generate ..., if a page is not updated since last run, Notablog use the cached data to render.

• themes/ - Stores themes.

Theme

A theme contains layout templates, CSS files, fonts, and other assets that shapes the style and look of a blog.

Folder Structure

<name>
├── layouts
├── assets
└── manifest.json

• <name> - Theme folder name, also the name to be used in notablog-starter/config.json.

• layouts/ - Contains page templates. It is required to have one index layout (index.html), one post layout (post.html), and one tag layout (tag.html). You can have more templates, and a user can use them by specifying the template's filename in template column on Notion table.

• assets/ - Other assets. Anything in this folder will be copied to notablog-starter/public/ when running notablog generate ....

• manifest.json - Theme configuration.

  Field	Type	Description
  notablogVersion	string	Supported Notablog version.
  templateEngine	string	The template engine to use, depending on the template language you use. Currently only "ejs" is valid.

Template Language

• Currently only EJS, but it's possible to support more since there's an interface designed for extension. Open an issue if you would like to contribute.

• Template index.html gets the following object:

  {
    siteMeta: SiteContext
  }

• Template tag.html gets the following object:

  {
    siteMeta: SiteContext
    tagName: string
    pages: PageMetadata[]
  }

• Template post.html or others gets the following object:

  {
    siteMeta: SiteContext
    post: PageMetadata & { contentHTML: string } // All properties of PageMetadata plus contentHTML.
  }

It is highly recommended to take a look at the default theme "pure-ejs" if you want to make your own!

Notes

Code Structure

Generated by dependency-cruiser NPM package.

Project Status

See https://dragonman225.js.org/notablog-stat.html

notablog's Issues

Open new tab for external link

Hi. One quick question: is there a way to open new tab for an external hyper link? Thanks!

Support for simple table

Hi,
Notion recently released the long-awaited simple table block, but it was not rendered successfully using notablog, so I had to switch back to database xD.

Hope to support this feature.

Code highlight and page width problem

Hi, I very appreciate for your work
I have been use notablog to build my blog, but I meet two problem
code highlight
seems like notablog do not support shell and go code highlight？
the next two image is notion code block:

the next two image is notablog effect, seems like the code highlight doesn't work? :

I have been check this issue #25, but I don't know how to fix it.
Please spare a moment to support it if you can, thanks a lot.

page width
the page rendering works great, but I want to make the page wider, how to set it?

like this code block, the block is too short to show all annotation, I want to make this code block wider, it will make reader feel more comfortable.

---

Thank you for your work again

notablog + netlify

hey! firstly, thanks for making this, very cool! now, if you want i can make a PR adding the readme here to this Repository
https://github.com/mjhajharia/notion-blog

This makes it very easy to use it with Netlify!!

RSS support ?

Consider generating an rss xml file after generating site?

Social links

Could it be possible to add social links (Twitter, Linkedin, GitHub) as parameters in the config file so they can be shown as buttons when the blog is rendered?

How to change font size?

In my perspective, the font is little bit larger than I used to see in many blogs or notion itself, how can I change the font size? Many thanks!!

TypeError: Cannot read properties of undefined (reading '0') at getAllBlocksInOnePage

Hi, when I try to generate, this error appears. I don't know if I'm just doing something wrong or if it's a bug.

Images on my portfolio not showing

This is what they look like. I have been trying to fix this. Tried updating notablog but did not work. Using notablog starter

The code format in Notion cannot be displayed after generation

The code format in Notion cannot be displayed after generation. Is there any parameter to control OR is it just a bug?

Look forward to your reply or repair.

error with command "notablog generate ."

when I run command "notablog generate ." on terminal, I receive a error message, screenshot below.

Feature request: Bookshelf page

Would be awesome to have the ability to view bookshelf on the website!

Example:

npm run build error

Hi, I was trying to see if I can build notablog by running npm run build or npm run dev, but here is the error I have

(base) [costa@costa-pc notablog]$ npm run build

> [email protected] build /home/costa/Documents/work/go/src/github.com/111/notablog
> npm run build:module && npm run build:doc


> [email protected] build:module /home/costa/Documents/work/go/src/github.com/111/notablog
> rm -rf dist && rollup -c && tsc --emitDeclarationOnly


src/index.ts → dist/index.js, dist/index.esm.js...
[!] Error: 'getConfig' is not exported by src/util.ts, imported by src/generate.ts
https://rollupjs.org/guide/en/#error-name-is-not-exported-by-module
src/generate.ts (10:14)
 8: import { renderIndex } from './render-index'
 9: import { renderPost } from './render-post'
10: import { log, getConfig } from './util'
                  ^
11: 
12: type GenerateOptions = {
Error: 'getConfig' is not exported by src/util.ts, imported by src/generate.ts
    at error (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:10120:30)
    at Module.error (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:14470:16)
    at handleMissingExport (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:14371:28)
    at Module.traceVariable (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:14835:24)
    at ModuleScope.findVariable (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:13415:39)
    at FunctionScope.findVariable (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:8664:38)
    at ChildScope.findVariable (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:8664:38)
    at Identifier$1.bind (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:9123:40)
    at CallExpression$1.bind (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:8749:23)
    at CallExpression$1.bind (/home/costa/Documents/work/go/src/github.com/111/notablog/node_modules/rollup/dist/shared/rollup.js:11440:15)

npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build:module: `rm -rf dist && rollup -c && tsc --emitDeclarationOnly`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] build:module script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/costa/.npm/_logs/2020-03-27T18_13_16_407Z-debug.log
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build: `npm run build:module && npm run build:doc`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/costa/.npm/_logs/2020-03-27T18_13_16_417Z-debug.log

I was wondering If you could offer some insights. Would love to contribute.

“notablog generate .” clunky after "fetch site metadata"

Thanks for your commitment, this repo helps me a lot !

Hwoever , when I update my blog, and "notablog generate", I found this step lagging for a long time.

before

after

I'm looking forward to your reply, thank you!

errors happened when I generate blogs

When I embed a block in my blog like this:

### errors happened when I generate blogs as follows:
E/notablog-cli(20230516T165551.826): Error: Collection block df1ba7ae-c89d-4ab0-a826-458be76fa516 has no collection id
at transformCollection (C:\Users\xxx\AppData\Roaming\npm\node_modules\notablog\node_modules\nast-util-from-notionapi\dist\index.js:440:15)
at transformBlock (C:\Users\xxx\AppData\Roaming\npm\node_modules\notablog\node_modules\nast-util-from-notionapi\dist\index.js:908:24)
at C:\Users\xxx\AppData\Roaming\npm\node_modules\notablog\node_modules\nast-util-from-notionapi\dist\index.js:1120:16
at Array.map ()
at makeBlockArrayIntoTree (C:\Users\xxx\AppData\Roaming\npm\node_modules\notablog\node_modules\nast-util-from-notionapi\dist\index.js:1118:10)
at Object.getOnePageAsTree (C:\Users\xxx\AppData\Roaming\npm\node_modules\notablog\node_modules\nast-util-from-notionapi\dist\index.js:1040:12)
at processTicksAndRejections (node:internal/process/task_queues:96:5)
at async renderPost (C:\Users\xxx\AppData\Roaming\npm\node_modules\notablog\dist\index.js:818:16)

image link from 3-part webside cant showed

if i use medium article picture like below
https://user-images.githubusercontent.com/69407830/159119772-ed49e127-d3d0-4e6c-9845-a8d556ffeb29.png
it can show currect in notion ,but no in notablog html file

How to make the description appear inside the article?

I noticed that the column ‘description’ only appears in the article list on the homepage, but not inside the article. How can I do that?

Support for letting `index.html` be a post, and the links to blog entries be on a separate page.

By default, the list of blog entries is displayed on the index.html page. However, I wonder if I can change this behavior so that the list can be displayed on a different page, such as blog.html.

I would also like to be able to set the index.html page as a blog post. This would greatly allow me to use the home page for information only, and leave the links to blog posts in a separate page.

I am also curious if it's possible to extend the customization options of Notablog beyond the existing templates like index, tags, and posts. The idea is to let Notablog generate a corresponding page under the /public path based on this template that I add. This would provide a convenient way to create custom pages with personalized layouts.

Thank you very much for your attention to these requests.

TypeError: Cannot read property 'aggregate' of undefined

I followed the steps on getting started, yet got errors like this:

my config.json:

my notion page:

link

Self-hosted images

This is a feature request: I'd like to be able to have the generator request and save the images so they can be hosted with the blog. Then I believe the whole site can be served without making any requests to notion's servers. This has a few benefits:

• Images aren't broken if notion changes the image urls
• The site can be viewed locally without an internet connection
• The source Notion table can be un-shared after generation, protecting potentially sensitive info such as unpublished drafts

Show posts that are not "in list" in tag pages

separate them with those "in list", by adding a section below "in list" posts

New images aren't properly linked

All my old articles are translated to HTML pages just fine. However, when I upload a new picture, I only get a broken link, and the alt text is displayed.

All the old pictures started with a https://www.notion.so/signed/ URL and work quite well:
https://sold-out.io/phx/static/articles/555088-063.html

All the new ones point the <img>s point straight to Amazon servers, and they're not displayed on page. New article for reference:
https://sold-out.io/phx/static/articles/FN6882-100.html

Really wished it could get a fix. We rely on notablog for our whole blogging infrastructure.

How to Set A Default Page or Route

Hi, the default page now looks like the following

Is there any way to set the default page to something like "About"? In general, is there anywhere we can customize the "Home" page?

Thanks a lot.

TypeError: Cannot convert undefined or null to object

I am not able to run the generate command. Below is the error message I get.

Geonsoos-MacBook-Pro:notablog-starter geonsookim$ notablog generate .
I/notablog(20200929T234902.788): Copy theme assets
I/notablog(20200929T234902.815): Fetch Site Metadata
E/notablog-cli(20200929T234903.438): TypeError: Cannot convert undefined or null to object
    at Function.entries (<anonymous>)
    at parseTable (/usr/local/lib/node_modules/notablog/src/parse-table.js:26:35)
    at processTicksAndRejections (internal/process/task_queues.js:97:5)
    at async generate (/usr/local/lib/node_modules/notablog/src/generate.js:86:20)
    at async cmdGenerate (/usr/local/lib/node_modules/notablog/bin/cli.js:34:5)

Not quite sure what causes this error. I attach the code for notablog-starter/config.json.

{
  "url": "https://www.notion.so/Ian_Kim-f4525e36d64047e6b51d714f6c93a8e6",
  "theme": "pure",
  "previewBrowser": "/usr/bin/chromium"
}

Images uploaded to Notion doesn't show up

If an image uploaded to Notion is used as icon or cover, it will not show up in the generated blog. The image is prefixed with https://s3-us-west-2.amazonaws.com/secure.notion-static.com/, and server responds 403.

Pure theme

I noticed that the pure theme got removed that mimicked the default notion looks.

I would really appreciate if it could be added back.

Add comment function code of utterances

Is it possible to automatically generate the code with the comment function of utterances at the end of the HTML file

Remove .html url for website part

Remove .html url for website part

ex. https://iqlal.me/ebook.html to https://iqlal.me/ebook

Thanks

Support for Inline Math

The inline math is finally supported in notion https://www.notion.so/What-s-New-157765353f2c4705bd45474e5ba8b46c.

However, when rendering the with notablog, the inline math is not rendered properly

`public/index.html` preview issue for Node.js < v14

I did a clean install from the latest notablog repo and tried generating my blog. I got the following error when I tried to view public/index.html. Why could this have happened?

Is there a plan to support pagination of the article list?

Now all articles are on the same page, if pagination can be supported, the homepage of blog will look more concise.

Unsupported block type: transclusion_container

E/notablog-cli(20221207T233746.912): TypeError: Cannot read properties of undefined (reading '0')
at new NTable (C:\Users\Admin\AppData\Roaming\npm\node_modules\notablog\dist\index.js:336:51)
at parseTable (C:\Users\Admin\AppData\Roaming\npm\node_modules\notablog\dist\index.js:422:19)
at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
at async generate (C:\Users\Admin\AppData\Roaming\npm\node_modules\notablog\dist\index.js:900:25)
at async cmdGenerate (C:\Users\Admin\AppData\Roaming\npm\node_modules\notablog\bin\cli.js:37:5)

Notablog failed to generate the desired html file

The command notablog generate . successfully generate the desired html file of the template table you provided.
But when I changed the url in config.json and ran the command, the terminal reports "TypeError: Cannot read property '0' of undefined ... "

Thanks in advance for helping me out in this !!

Internal link issue

When I use @ to create an internal link to another page in Notion, the generated site doesn't seem to generate a link to a page in my site (xxx.github.io/xxxx) but a link to original Notion page (notion.so/xxxx). How should I solve this problem?

I've tried to put the linked page into the notablog database, but it doesn't seem to work.

Support for synced blocks

Hi,

I noticed that synced blocks are not copied into the blog. Does the notionblog-api package handle these blocks? I noticed that notion-utils.ts handles the rendering part, but couldn't pinpoint which part of the code handles the blocks.

If you could give me some pointers to which part of the code I should look into, that'd be great. Thanks!

Toggle lists on mobile devices

Toggle lists do not look normal on mobile devices for example like below in the figure.

Quick Question On Update

Hello, quick question, is there any way that it can update the site automatically once you update notion? Is that already an existing feature?

APIError: Server says "ValidationError: Invalid input."

Issue

Hi, I meet some issue recently. I am not familiar to nodejs. I dont know if I do something wrong.

Terminal Output

PS D:\a_Git_Project\test\notablog-starter> notablog generate .

I/notablog(20211006T114938.547): Copy theme assets
I/notablog(20211006T114938.556): Fetch site metadata
E/notablog-cli(20211006T114940.131): APIError: Server says "ValidationError: Invalid input."
    at Object.queryCollection (C:\Users\a3918\AppData\Roaming\npm\node_modules\notablog\node_modules\notionapi-agent\dist\index.js:136:19)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at async transformCollection (C:\Users\a3918\AppData\Roaming\npm\node_modules\notablog\node_modules\nast-util-from-notionapi\dist\index.js:443:25)
    at async Promise.all (index 0)
    at async makeBlockArrayIntoTree (C:\Users\a3918\AppData\Roaming\npm\node_modules\notablog\node_modules\nast-util-from-notionapi\dist\index.js:1114:24)
    at async parseTable (C:\Users\a3918\AppData\Roaming\npm\node_modules\notablog\dist\index.js:445:29)
    at async generate (C:\Users\a3918\AppData\Roaming\npm\node_modules\notablog\dist\index.js:903:25)
    at async cmdGenerate (C:\Users\a3918\AppData\Roaming\npm\node_modules\notablog\bin\cli.js:37:5)

PS D:\a_Git_Project\test\notablog-starter>

Column Layout Broken and Gallery Incomlete

Hi, thanks for the amazing work. The generated site looks really amazing. I have two issues to report.

1. The column layout seems to be broken. Please see the first screenshot as what is in https://dragonman225.js.org/block-test.html, and the second screenshot as what I generated today.

2. The gallery is missing things like tags and properties.

What is actually there:

What is being rendered:

Looking forward to hearing from you. Thanks for the great work again.

Automatic URL based on slug of title instead of page id

It would be nice if we could have the option to automatically generate the page URL using its title's slug instead of its Notion page id. For example, with a title of How to setup Notablog, we could get mydomain.com/how-to-setup-notablog.html

Allow different culture for date column

I can see that parseTable.ts has en-US culture hardcoded for date column.
https://github.com/dragonman225/notablog/blob/030981cdbeac9bc0b6aaf1dd24aac5ee4d6a596f/src/parseTable.ts

I'd like to be able to use different culture for date.
How to best achieve that?
The only idea I have is to add a new column with culture info, and in code a check if it's present then use it.

Search function

Would it be possible to add a search function for posts?

How to use utterances in generated blog?

First of all, thanks for your project. Your code is precise and well written. I really like your code and learned a lot from it.

I saw your personal blog and find utterances component in your page. That is the mainly reason I use notablog instead of other Notion blog CMS tools like notion-blog to build my new version of GitHub Page.

When I try to put it to prod, however, I find no utterances relative items in folder. I also read source code in your GitHub Page repo and find utterances config file, css files and relevant setting.

So, how do you implement it? Is there any way to generate utterances using notablog cli?

Links within siteMeta.description to internal pages are not transformed

I'm trying out (and loving) notablog. Thanks for this project!

I tried putting a link in the table description that becomes siteMeta.description, and found that the link isn't being transformed or transformed correctly. Instead the link just contains the full-length page id, whether or not the linked page as a url slug provided.

Note: adding a link this way is an attempting at working around not being able to designate a page as the home page, which I can see was requested and closed in #6.

notablog generate . command not found

After successfully installed notablog from npm and cloned the git repository, the command "notablog generate ." doesn't work and the terminal filed a command not found.

Error “Unsupported formatting: ["_",null]”

when I generate, error happens below：

then extra commas and characters are added like:

Expected format is：

thanks！