vwxyzjn_notablog v0.4.3

notablog

Generate a minimalistic blog from a Notion.so table.

Here are some images of my blog, using notablog-starter's default theme. 🙂

Mobile	Desktop

Management Interface on Notion.so

:construction: This is under construction, there may be breaking changes often ! :construction:

Table of Contents

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

Getting Started

Make sure you have Node.js v12.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. Or, you can change previewBrowser field in config.json to the path of a browser you use and run command:

   notablog preview .

Your site is ready now!

• You can copy files in notablog-starter/public/ directory to your 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

• Hack: 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 (Outdated)

Introduction

notablog itself is designed to be installed as a dependency, and invoked from NPM script. This way we can separate application code and user assets so that it's less confusing for a user. To make things even more simple, I have prepared notablog-starter, so a user doesn't have to setup folder structure manually. The concept is inspired by a popular project hexo.

With the design, a user only sees notablog-starter when using, therefore the following documentation will be in the context of notablog-starter.

Simplified Folder Structure

notablog-starter
├── config.json
├── public
├── source
│   └── notion_cache
└── themes
    └── pure

• config.json - Site config.

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

• public/ - Contains generated static assets of the blog.

• source/notion_cache/ - Cached JSON files of Notion pages. They are used when a user runs npm run generate, if a page contains no changes, the generator reads data from these cached files.

• themes/ - Store 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>
├── layout
└── assets

• <name> - Theme folder name, also the name to be used in notablog-starter/config.json.
• layout/ - Contains page templates. It is required to have at least one index layout (index.html) and one post layout (post.html). You can have more templates, and a user can use those bonus templates by specifying the template's filename in template field on Notion.
• assets/ - Other assets. Anything in this folder will be copied to notablog-starter/public/ when running npm run generate.

Template Language

• Currently, I use Squirrelly.js as template engine.

• Template index.html gets the following structure of data :

  {
  			siteMeta {
  				icon // Emoji or URL
  				iconHTML // Rendered HTML
  				cover // URL
  				title // String
  				description // Raw array, do not use
  				descriptionPlain // Rendered plain text, no style
  				descriptionHTML // Rendered HTML, with style
  				pages { // An array of page
  					id // Notion's page id
  					icon // Emoji or URL
  					iconHTML // Rendered HTML
  					cover // URL
  					title // String
  					tags // An array, [{ color: string, value: string }]
  					publish // Boolean, `true` if publish is checked.
  					inMenu // Boolean, `true` if inMenu is checked.
  					inList // Boolean, `true` if inList is checked.
  					template // Template name
  					url // URL of the page relative to site root
  					description // Raw array, do not use
  					descriptionPlain // Rendered plain text, no style
  					descriptionHTML // Rendered HTML, with style
  					date // Raw string, e.g. 2019-08-09
  					dateString // Formatted, e.g. Fri, Aug 9, 2019
  					createdTime // Unix timestamp
  					lastEditedTime // Unix timestamp
  				}
  			}
  }

• Template post.html or others gets the following structure of data :

  {
  			siteMeta // The same as "siteMeta" in index.html
  			post {
  				...post // All properties of a page in "siteMeta.pages"
  				contentHTML // HTML of post body
  			}
  }

It is highly recommended to take a look at notablog-theme-pure if you want to make your own !

Notes

Code Structure

Generated by dependency-cruiser NPM package.

EJS

There is an experimental version at ejs branch that uses EJS as template engine. Main advantage of EJS is its include feature, which enable us to make repetitive parts of template into components that can be reused. I also made an EJS version of notablog-theme-pure here.