DOCSEARCHbyAlgolia
Submit Docs

notablog

repository·master·Indexed 20 days ago

https://github.com/dragonman225/notablog

A static site generator and CLI tool that turns public Notion database tables into minimalistic blogs. It uses a starter repository with themes and EJS templates to build sites, featuring a caching mechanism for efficient generation and a programmatic API for interacting with Notion table data via the NTable class.

Tokens
7.5K
Snippets
32
Records
39
Agent score
71%

What's inside notablog

  1. Create a custom theme

    master

    A theme defines the look and feel of your blog. Themes are stored in the themes/ directory of notablog-starter.

    Theme Folder Structure:

    <name>
├── layouts/
├── assets/
└── manifest.json
    • <name>: The folder name, which must match the theme value in config.json.
    • layouts/: Contains page templates. You must include index.html, post.html, and tag.html. Additional templates can be used by specifying their names in the Notion template column.
    • assets/: Files in this folder are copied directly to public/ during generation.
    • manifest.json: Configuration for the theme.

    manifest.json Schema:

    FieldTypeDescription
    notablogVersionstringSupported Notablog version.
    templateEnginestringThe engine to use. Currently only "ejs" is supported.
    {
  "notablogVersion": "0.8.1",
  "templateEngine": "ejs"
}

  2. Install and set up Notablog

    master

    Notablog is a CLI tool that generates a minimalistic blog from a Notion table.

    Prerequisites:

    • Node.js v15.0.0 or higher.

    Setup Steps:

    1. Install the CLI globally:
      npm i -g notablog
    2. Clone the notablog-starter repository:
      git clone https://github.com/dragonman225/notablog-starter.git
    3. Duplicate the Notion table template and make it public.
    4. In notablog-starter/config.json, replace the url field with your Notion table's URL.
    5. Generate the site:
      cd notablog-starter
notablog generate .
    6. Preview the site by opening notablog-starter/public/index.html in a browser.
    npm i -g notablog
git clone https://github.com/dragonman225/notablog-starter.git
cd notablog-starter
notablog generate .

  3. Generate and preview your blog

    master

    To update your site after making changes to your Notion table, run the generate command. You can run it from inside the starter directory or by providing the path.

    Generate from inside the directory:

    notablog generate .

    Generate from outside the directory:

    notablog generate <path_to_the_notablog-starter>

    Previewing the site: You can use the preview command to automatically open the site in a browser. For this to work, ensure the previewBrowser field in config.json points to your browser's executable path.

    notablog preview <path_to_the_notablog-starter>
    notablog generate .
notablog preview <path_to_the_notablog-starter>

  4. Configure `config.json` in `notablog-starter`

    master

    The config.json file in your notablog-starter directory controls the generation process. Use the following keys:

    FieldTypeDescription
    urlstringThe URL of your public Notion table.
    themestringThe name of the theme folder in themes/ to use.
    previewBrowserstringPath to the browser executable for the preview command.
    autoSlugbooleanIf true, generates URL slugs for pages without a custom url column.
    localesstring or string[]Locales used for Date.prototype.toLocaleDateString() formatting.

  5. Configure URL slug generation in parseTable

    master

    When parsing a Notion table, the url property of a record determines the filename of the generated HTML. The parseTable function uses the Config object to decide how to handle missing or custom URLs:

    1. Custom URL: If the url property in the Notion table is provided, it is sanitized (removing / and \) and used as the filename.
    2. Auto-slugging: If the url property is empty and config.get('autoSlug') is true, the function generates a slug from the page title and appends the first 6 characters of the page ID (e.g., my-post-title-abcdef.html).
    3. Fallback: If the url property is empty and autoSlug is false, the function uses the page ID as the filename (e.g., page-id.html).

  6. Understand PageMetadata structure

    master

    The PageMetadata interface describes the properties of an individual page or post within the blog. It includes identifiers, visual assets (icon, cover), taxonomy (tags), visibility settings (publish, inMenu, inList), and temporal data (date, createdTime, lastEditedTime).

    export interface PageMetadata {
  /** No dashes. */
  id: string
  iconUrl: string | undefined
  cover: string | undefined
  title: string
  tags: Tag[]
  publish: boolean
  inMenu: boolean
  inList: boolean
  template: string
  url: string
  description: SemanticString[] | undefined
  descriptionPlain: string
  descriptionHTML: string
  date: string | undefined
  dateString: string | undefined
  createdTime: number
  lastEditedTime: number
}

  7. Understand the SiteContext structure

    master

    The SiteContext object represents the global state and metadata of the entire website. It is used during the rendering process to provide information about the site's identity and its collection of pages.

    export interface SiteContext {
  iconUrl: string | undefined
  cover: string | undefined
  title: string
  description: SemanticString[] | undefined
  descriptionPlain: string
  descriptionHTML: string
  pages: PageMetadata[]
  /** tag name -> pages */
  tagMap: Map<string, PageMetadata[]>
}

  8. Implement a custom RenderStrategy

    master

    To extend the rendering capabilities of Notablog, you can implement the RenderStrategy interface. A strategy must provide a render method that takes a templateName (string) and a data object (Record<string, unknown>) and returns the rendered template as a string. This allows you to swap between different templating engines like EJS or Squirrelly or provide your own custom engine.

    import { RenderStrategy } from './renderer';

class MyCustomStrategy implements RenderStrategy {
  render(templateName: string, data: Record<string, unknown>): string {
    // Your custom rendering logic here
    return `<html>${data.title}</html>`;
  }
}

  9. Use the notablog CLI

    master

    The notablog command-line interface allows you to generate and preview your blog using a notablog-starter directory.

    Important Note: If you update notablog, ensure you also update your notablog-starter repository to prevent layout breakage caused by mismatches between generated HTML and the CSS theme.

    Usage: notablog <command> [<option>]

Available <command>:
  help                                 Show this text.
  generate <path_to_notablog-starter>  Generate the blog.
  preview <path_to_notablog-starter>   Open a browser to preview.

Available <option>:
  -v, --verbose  Print more messages for debugging.
  --fresh        Generate without cache. Useful when you get stalled result after upgrading.

  10. Use template data in EJS layouts

    master

    Notablog currently supports EJS for templating. Different layout files receive different data objects:

    • index.html receives:

      { siteMeta: SiteContext }

    • tag.html receives:

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

    • post.html (and other custom templates) receives:

      { siteMeta: SiteContext, post: PageMetadata & { contentHTML: string } }

  11. Configure locales for date formatting

    master

    The parseTable function uses the Config object to format dates extracted from the Notion date property.

    To change the date format (e.g., from Sep 21, 2023 to a different locale), set the locales key in your Config object. If not set, it defaults to 'en-US'.

  12. Configure the Notablog starter with NotablogStarterConfig

    master

    The NotablogStarterConfig interface defines the configuration options for the notablog-starter project. Use these keys to control site URL, theme selection, preview behavior, slug generation, and localization.

    export interface NotablogStarterConfig {
  url: string
  theme: string
  previewBrowser: string
  autoSlug: boolean
  locales: string | string[] | undefined
}