---
title: "Introducing Webtrotion"
slug: introducing-webtrotion
canonical_url: https://nerdymomocat-templates.github.io/posts/introducing-webtrotion/
collection: "Personal Notes"
published_at: 2023-11-28T00:00:00.000Z
updated_at: 2026-03-25T00:00:00.000Z
tags: 
  - "🪴 Potted"
  - Guide
excerpt: "Learn about and how to use this theme here!"
author: "Unknown Author"
---

## Navigation Context

- Canonical URL: https://nerdymomocat-templates.github.io/posts/introducing-webtrotion/
- You are here: Home > Posts > Personal Notes > Introducing Webtrotion

### Useful Next Links
- [Home](https://nerdymomocat-templates.github.io/)
- [Updates](https://nerdymomocat-templates.github.io/updates/)
- [Another Collection](https://nerdymomocat-templates.github.io/collections/another-collection/)
- [Personal Notes](https://nerdymomocat-templates.github.io/collections/personal-notes/)
- [Stream](https://nerdymomocat-templates.github.io/collections/stream/)

### Related Content

#### Pages That Mention This Page
- [Home](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog)
- [Updates](https://nerdymomocat-templates.github.io/updates/)
- [Supported blocks](https://nerdymomocat-templates.github.io/posts/supported-blocks/)
- [Testing Upcoming Features Page](https://nerdymomocat-templates.github.io/posts/testing-upcoming-features-page/)

#### Other Pages Mentioned On This Page
- [Supported blocks](https://nerdymomocat-templates.github.io/posts/supported-blocks/)

**Table of Contents**

[Acknowledgements](#acknowledgements)[Why Webtrotion](#why-webtrotion)[Why Notion and Astro](#why-notion-and-astro)[Key Features](#key-features)[Demo](#demo)[Quick start](#quick-start)[Notion Setup](#notion-setup)[Github Setup](#github-setup)[Preview](#preview)[Notion Properties](#notion-properties)[Local Run](#local-run)[Extra configuration options](#extra-configuration-options)[Webtrotion 1.0 extra configuration options](#webtrotion-1-0-extra-configuration-options)[License](#license)[Notes](#notes)[Interlinked Content](#autogenerated-interlinked-content)[Footnotes](#autogenerated-footnotes)

* * *

> Are you curious on Jun 25, 2024 whether to use Notion Sites v2 or Webtrotion? Check [this](https://nerdymomocat.github.io/posts/webtrotion-vs-notion-sites-v2/) out! If you are checking it out Nov 1, 2025, then Webtrotion 2.0 also supports footnotes and citations (special parsing), which Notion Sites cannot render.

> Just take me to the github link:
> 
> [
> 
> GitHub - nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog: Your own notion website with astro
> 
> Your own notion website with astro. Contribute to nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog development by creating an account on GitHub.
> 
> ![title](https://www.google.com/s2/favicons?domain=github.com)
> 
> https://github.com/nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog
> 
> ![title](https://opengraph.githubassets.com/bdec1990a5fd0a39649fea8d9dac17a992af61578bfc542626c47fe1c702dbb4/nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog)
> 
> ](https://github.com/nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog)
> 
> Bookmark for [https://github.com/nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog](https://github.com/nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog)

> Support me on product hunt!
> 
> [![Webtrotion - Notion-based configurable static website generator | Product Hunt](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=469215&theme=neutral)](https://www.producthunt.com/posts/webtrotion?embed=true&utm_source=badge-featured&utm_medium=badge&utm_souce=badge-webtrotion)

**New Features and Changelog**

Oct 28, 2025: Comprehensive Citation and Footnote System. Webtrotion now has a complete citation and footnote system. You can now add citations from BibTeX files and have them automatically formatted. Footnotes are also supported, with popovers for easy reading.

Oct 25, 2025: Enhanced OG Images. OG images for tags and collections now include descriptions. A new automated workflow has been added to clean up template-specific files when you create a new repository from the template or pull updates from it. This keeps your project clean and free of unnecessary files.

Sep 11, 2025: Search from Query Parameters and UI improvements. You can now pre-fill the search box with a query parameter in the URL. The UI for the tags page has also been updated for a cleaner look.

Sep 10, 2025: Cache Recovery Workflow. A new GitHub Actions workflow has been added to allow you to recover your cache.

Sep 4, 2025: Upgraded Notion API. The project has been updated to use a newer version of the Notion API, ensuring better stability and compatibility with future Notion features.

**Jul 6, 2024: Introducing Webtrotion. Unlike notion where your simple tables are basically just a form of displaying data, you can now search and sort your simple tables in webtrotion. Just have column headers and use <<🗂️>> in the first cell (modifiable in constants-config).**

[](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/notion/a15ce12f-d3b8-44a5-8834-71c99d53b211/table-search-sort.mp4) Your browser does not support the video tag.

  

Jul 4, 2024: Breaking change → the shortcode for HTML rendering in an iframe (if you want to use external libraries like d3.js has changed to `<!DOCTYPE html> <!-- iframe -->` and for injecting it directly into the body is now `<!DOCTYPE html> <!-- inject -->`. This helps you have code blocks that are in html and start with `<!DOCTYPE html>` without rendering them.

Jun 30, 2024: View transitions are back in and use ⌘K or ^K to search

[](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/notion/23d071d4-2bc6-43f8-b918-add38fcf5601/Screen_Recording_2024-06-30_at_12.30.55_AM.mp4) Your browser does not support the video tag.

[![Image uploaded to Notion](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.BT-1OJ_-_ZRKueu.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.BT-1OJ_-_ZRKueu.webp)

Jun 28, 2024: Floating table of contents and shiki transforms for code blocks (updated to astro 4.11), and added [view transitions](https://astro.build/blog/future-of-astro-zero-js-view-transitions/?tw=)

[![Image uploaded to Notion](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.0PHhQKUW_13RzNH.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.0PHhQKUW_13RzNH.webp)

Jun 14, 2024: Pin posts to top

[![Image uploaded to Notion](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.Cb4VOmLO_Z1hrG21.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.Cb4VOmLO_Z1hrG21.webp)

Jun 15, 2024: Add tag descriptions

[![Image uploaded to Notion](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.UQS4YSGC_Z1JsqA7.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.UQS4YSGC_Z1JsqA7.webp)

Dec 12, 2023: Add support for preview popovers

[![Image uploaded to Notion](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.BChspMoM_2n4shz.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.BChspMoM_2n4shz.webp)

Dec 4, 2023: Add support for [recent posts on homepage](https://nerdymomocat.github.io/#auto-recent-posts)

[![Image uploaded to Notion](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.LZ0hATyz_ZkMDLS.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.LZ0hATyz_ZkMDLS.webp)

Dec 2, 2023: Added interlinked content section

[![Image uploaded to Notion](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.D4hE7rjv_6LNfB.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.D4hE7rjv_6LNfB.webp)

Nov 29, 2023: Caching

* * *

Webtrotion is a extensively configurable, simple to install website builder, built with the [Astro framework](https://astro.build/) in conjunction with [Notion](http://www.notion.so/). Use it to create an easy-to-use blog **or website.**

[(Skip to features and setup)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/posts/introducing-webtrotion/#key-features)

## Acknowledgements

This theme is built based off three major contributions:

1.  [Astro Cactus](https://github.com/chrismwilliams/astro-theme-cactus)
2.  [notion-astro-blog](https://github.com/otoyo/astro-notion-blog)
3.  [And this person on fiverr who got me 80% there on how to integrate notion into cactus theme](https://www.fiverr.com/franklinshera)
4.  Claude code and gemini cli [^1]

[![Webtrotion Cat](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/pcat.geGXnw40_ZmNYme.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/pcat.geGXnw40_ZmNYme.webp)

Webtrotion Cat

* * *

## Why Webtrotion

Webtrotion was built with the simple idea - most notion based builders, require at least one of these four things:

-   A custom domain, or being willing to use a vercel like domain
-   Just have blogposts be editable in Notion while pages are edited in the repo
-   Require some third party tools, or are not free to use.
-   Are not configurable because they are either based off third parties like [super.so](http://super.so/) or the configuring requires editing multiple code files.

And I did not want that. We want something that converts well into a static site, can be hosted on github for free using the [github.io](http://github.io/) domain, and can have both pages and blog posts and be configured pretty easily.

## Why Notion _and_ Astro

-   I use Notion for all my notes, and it did not make sense for me to download them into an md file, carefully figure out the logistics and push/pull with other SSGs like Quartro, Eleventy, Hugo or Jekyll.
-   I could have used another CMS but again, I use Notion, and it is easier to keep the content in one place. Notion also comes with interesting affordances that other CMS don’t: WYSIWYG for various components, block level permissions (to add drafts to post text), easy collaboration etc.
-   There are some NextJS options that kinda fulfill this criteria but I do not know NextJS and I did not want to figure it out at the moment, for example: [Notion Next](https://github.com/tangly1024/NotionNext), [Morethan-log](https://github.com/morethanmin/morethan-log), and [Notion-Blog-NextJs](https://github.com/samuelkraft/notion-blog-nextjs)

* * *

## Key Features

-   Astro v5 and Tailwind v4
-   **Integrates with Notion to create a website and not just a blog**
-   **Single file configuration**
-   TailwindCSS Utility classes **with** **Notion** **Color** **Matching** **for** **everything****.**
-   Accessible, semantic HTML markup
-   Responsive & SEO-friendly
-   Dark / Light mode, using Tailwind and CSS variables **that can be modified using a single config file**
-   [Satori](https://github.com/vercel/satori) for creating open graph png images **that includes your featured image**
-   Pagination
-   [Automatic RSS feed](https://docs.astro.build/en/guides/rss)
-   [Webmentions](https://webmention.io/)
-   **Giscus and Bluesky comments**
-   Auto-generated sitemap
-   [Pagefind](https://pagefind.app/) static search library integration
-   [View Transitions](https://astro.build/blog/future-of-astro-zero-js-view-transitions/?tw=)
-   **Pinned Posts**
-   **Shiki Transformers for Code Blocks**
-   **API request output caching on Github Actions for fast build times**
-   **Mini blog streams (idea copied from** [**Linus’s stream**](https://stream.thesephist.com/)**)**
-   **Auto-generated related content and pages that link to this page**
-   **Pretty looking wikipedia like popups on hover that works with links to any block on any page.**

* * *

Starting Webtrotion 2.0,

-   **Footnotes and Citations** [^3]
-   **Listing view supports both list and gallery layouts**
-   **Multiple authors with dedicated author pages**
-   **Cover images as hero backgrounds**

### Demo

Check out the [Demo](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/), hosted on Github using Github actions

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/heart_pink.Cf4DkvFB_Z1EYdWV.svg)

**We’re now on Webtrotion 2.0!** When you clone the template, you'll get the latest version with JSON5 config, footnotes, citations, and all the new features. These docs reflect version 2.0.

## Quick start

### Notion Setup

1.  Duplicate [this database](https://www.notion.so/169b6e632b7448529120599281265ac5) into your Notion account. Remember to duplicate it as a standalone new page, rather than into an existing page.
    
    Your database title becomes the site title, the database icon becomes the favicon, and the description becomes the site description.
    
2.  Create a [Notion integration](https://developers.notion.com/docs/create-a-notion-integration#create-your-integration-in-notion)
3.  [Get your API secret](https://developers.notion.com/docs/create-a-notion-integration#get-your-api-secret)
4.  Give your [integration permission to the complete database](https://developers.notion.com/docs/create-a-notion-integration#give-your-integration-page-permissions) you just duplicated
5.  **Recommended:** [Get your Data Source ID](https://developers.notion.com/reference/retrieve-a-data-source#finding-a-data-source-id). This is the preferred connection method for Webtrotion 2.0 because it's more stable. You can get it from:
    
    1.  Open your database in the Notion app
    2.  Click the **•••** menu in the top right
    3.  Scroll down to **Manage data sources**
    4.  Click **Copy data source ID**
    
6.  **Alternative:** Get your database ID. Database ID is the 32 character alphanumeric string right after your workspace in the URL. It is the easiest to get this ID on a web browser rather than the Notion app. If you use the database ID, Webtrotion will automatically find the Data Source ID from it.
    
    [![Database id from notion url](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.SZN1f-2M_Z48DcJ.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.SZN1f-2M_Z48DcJ.webp)
    
    Database id from notion url
    

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/help-alternate_blue.Cn3BElbV_Z1EYdWV.svg)

**Which ID should I use?** Data Source ID is preferred because it's more stable. Database ID works as a fallback - Webtrotion will auto-find the _**first**_ Data Source ID from it. If you provide both, Data Source ID takes priority.

### Github Setup

1.  Create a new repo from [this template](https://github.com/nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog/generate) if you want to have a one and done standalone repository. If you want to be able to access and sync changes made in the template to your repository, choose to [fork it instead](https://github.com/nerdymomocat-templates/webtrotion-astro-notion-cms-website-blog).
    
    ![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/info-alternate_orange.C0q9L2LB_Z1EYdWV.svg)
    
    If you _**do not choose to add a custom domain**_, the name of your repository matters. If the name of the repository you create is **<username>.github.io**; your website will be accessible at <username>.github.io if you use github actions. If you use any other name, the website will instead be hosted at <username>.github.io/<reponame>.
    
    ![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/report_red.Bv_P4rAp_Z1EYdWV.svg)
    
    When you first fork the repository, you will see that the github action output fails. This is because we haven’t added or changed notion integration information. Don’t worry, once you add those, it will run successfully.
    
2.  In your repository settings:
    
    1.  Uncheck template repository if it is checked.
    2.  Turn on **Discussions** in features to use [**Giscus**](https://giscus.app/)
    3.  Go to **Actions → General** and set it to _Allow All_
    4.  Go to **Pages** and set **Source** as **Github Actions**
    5.  Go to **Environments** → **github-pages**; Scroll down to **Environment Secrets**, click Add New Secret. Set name as `NOTION_API_SECRET` and the value to the API secret you obtained in [Notion Setup](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/posts/introducing-webtrotion/#notion-setup)
    6.  **Very Optional** (if you are tech-savvy or want to try): Get a personal access token to delete caches and set another environment secret named `DELETE_CACHES_GH_TOKEN` to this token
        
        **Details**
        
        -   Obtain a personal access token that you can limit to this repository using the process mentioned here: [![](https://docs.github.com/assets/cb-345/images/site/favicon.png) GitHub Docs Managing your personal access tokens - GitHub Docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token). You only need the repo scope and remember to set the validity to no expiration. Remember to save this token somewhere because you will not see it again.
        -   In the environment secrets section, add another environment secret named `DELETE_CACHES_GH_TOKEN` and set it to the token you obtained in the previous step.
        -   Why do this at all? Because I like cleaner lists — and here is some information from Github’s end: [![](https://docs.github.com/assets/cb-345/images/site/favicon.png) GitHub Docs Caching dependencies to speed up workflows - GitHub Docs](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy)
        
          
        
    
3.  Go to the actions tab, and choose _**I understand and want to run actions**_. On the left sidebar click the action “Deploy Github pages”. It will show a warning saying the scheduled action is disabled in forks. Click _**Enable workflow**_.
4.  Set up giscus as mentioned on the website [giscus.app](https://giscus.app/). Keep the script it produces open as we will use it in the next step.
5.  Go back to your cloned (forked or created through a template) repository.
6.  Open file `**constants-config.json5**` [^5] in the web UI. This file is the complete setup file for your website. For now, we will make four major modifications:
    
    1.  Under `notion`, change `data-source-id` to your data source id that you obtained from Notion (or use `database-id` as fallback)
    2.  Under `site-info`, add your name to `author` (this is used for RSS feeds, OG images and metadata)
    3.  Under `socials`, add your social media profile URLs (you should also remove the value for `this-github-repo` and point it to yours)
    4.  Under `comments → giscus`, add your giscus information to `data-repo` and other fields. If you do not want to use Giscus, leave `data-repo` empty and that will disable the feature.
    
7.  Save the file and commit+merge to the main repo.
8.  The github action by default runs every 8 hours or on commits to the repo. This can be modified in `.github/astro.yml` file. You can choose any cron duration.

  

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/confetti-party-popper_blue.DSAcoEZ8_Z1EYdWV.svg)

And we are done! You can access your website on **<username>.github.io** or <username>.github.io/<reponame> depending on what you chose. Checkout all [![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/traffic-cone_blue.CwfG_Xii_Z1EYdWV.svg)Supported blocks](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/posts/supported-blocks/) but tl;dr all blocks are supported except child databases and child pages.

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/exclamation-mark-double_purple.Dl070vZp_Z1EYdWV.svg)

Remember, the cron schedule is by default set to every 8 hours. You can change it to run every 2 hours or if you want to push out a change immediately, you can also [manually run the github action](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow) if you are deploying on github. The workflow name is “Deploy Github Pages”.

## Preview

[![Light mode preview](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.Bj60_Y50_Z2lwb3.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.Bj60_Y50_Z2lwb3.webp)

Light mode preview

[![Dark mode preview](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.UJK18eb5_BDOOT.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.UJK18eb5_BDOOT.webp)

Dark mode preview

## Notion Properties

Your database title becomes the site title, the database icon becomes the favicon, and the description becomes the site description.

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/info-alternate_blue.DUh-DayC_Z1EYdWV.svg)

Pages or posts are only published if: their **Published** property is **checked** _**AND**_ if the explicit publish date is empty or is before the current date.

| Property | Usage |
| --- | --- |
| Page | Title of the page or post being rendered |
| Tags | Tags displayed for the post |
| Excerpt | Description used in OG images and RSS feeds |
| Collection | Collection in which the post/page goes. Anything tagged with **main** or your `menu-pages-collection` value (default "`stream`") is rendered as a page. |
| Published | Your post or page is only published when you tick publish |
| FeaturedImage | Image used to generate your page’s or post’s open graph image |
| Authors | Used to specify multiple authors for a post using Multi Select (tag description can be used to specify author-url, photo and description in shortcodes) |
| Specific Slug | The template generates a slug using formula, but if you want a specific slug, you can specify it here |
| Explicit Publish Date | By default, the formula considers the date notion page was created to be publish date. You can override it by setting a date for this property. |
| Explicit Last Updated Date | By default, the formula considers the date notion page was last edited to be last edited date. You can override it by setting a date for this property. |
| Rank | Want to order single pages (Updates before Papers?) Set rank in ascending order |
| Pinned | Pins post to the top of any collection page, except those tagged with `menu-pages-collection`. |
| Bluesky Post Link | Use bluesky post as a commenting mechanism, see variable: `bluesky-comments` |

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/report_yellow.BexcuVVH_Z1EYdWV.svg)

**Don’t rename the columns of DB.** They are used in the astro code. You can reorder the columns or add any other columns you want.

## Local Run

You can run the code locally by cloning the repo.

```
cd folder
export NOTION_API_SECRET=YOUR_KEY_HERE
npm install
npm run build #we need to build once because that is when all icons are downloaded
npm run dev
#use npm run build-local to reflect code changes
```

## Extra configuration options

P.S.: You can search this simple table!

| **Config Key** | **Description** |
| --- | --- |
| `notion` | Notion connection: `data-source-id` (preferred, more stable) or `database-id` (fallback, auto-finds data source if data-source-id empty) |
| `site-info` | Basic site info: `author` (name for RSS/OG/metadata), `custom-domain` (without https:// or slash, empty for Vercel/Netlify), `base-path` (subdirectory like "/blog", empty if root), `site-author-url` (URL for site author, only when author name matches site author), `site-author-photo` (avatar URL for site author) |
| `site-info → authors` | Multi-author support: `enable-author-pages` (builds /authors/ index and /authors/\[author\]/ pages), `only-when-custom-authors` (only show bylines and author pages when at least one post has a non-default author) |
| `collections-and-listings` | Post organization: `home-page-slug` (default "home"), `recent-posts-on-home-page` (show 5 recent posts), `number-of-posts-per-page` (default 10), `menu-pages-collection` (pages in nav, default "main"), `full-preview-collections` (array for stream-style display), `hide-underscore-slugs-in-lists` (hide \_ prefixed from lists/sitemap/search), `listing-view` ("list" for traditional or "gallery" for card-based grid with FeaturedImage thumbnails) |
| `theme → colors` | RGB values (with spaces, e.g. "255 255 255") for light/dark modes: `bg` (background), `text` (main text), `link` (links), `accent` (primary highlights), `accent-2` (secondary highlights), `quote` (blockquotes) |
| `theme → fontfamily-google-fonts` | Font names only (no URLs, no escaping): `sans-font-name` (body/UI font, can be sans or serif), `mono-font-name` (code blocks). Auto-loads weights \[400, 500, 600, 700\] and styles \[normal, italic\] |
| `theme → cover-as-hero-background` | Use cover image as background behind hero/post preview |
| `socials` | Social profile URLs (keys are fixed, match icons): `email`, `github`, `googlescholar`, `semanticscholar`, `dblp`, `substack`, `facebook`, `twitter`, `threads`, `instagram`, `mastodon`, `bluesky`, `calendar`, `kofi`, `buy-me-a-coffee`, `this-github-repo` |
| `tracking → google-analytics` | Google Analytics: `use-ga` (enable GA tracking), `public-ga-tracking-id` (GA4 Measurement ID like G-XXXXXXXXXX) |
| `tracking → umami` | Umami analytics: `use-umami` (enable), `data-website-id` (website ID from Umami dashboard), `self-hosted` (true for self-hosted instance), `self-hosted-umami-url` (script URL for self-hosted) |
| `tracking → google-search-console-html-tag` | Google Search Console verification: paste the 'content' attribute from verification meta tag |
| `og-setup` | OG image generation: `columns` (1 = single column with bg, 2 = side-by-side), `excerpt` (include excerpt), `title-font-name` (any Google font), `title-font-weight` (default 400), `footnote-font-name` (author/date font), `footnote-font-weight` (default 400) |
| `comments → giscus` | GitHub Discussions comments: `data-repo` (username/repo), `data-repo-id` (from [giscus.app](http://giscus.app/)), `data-category` (discussion category name), `data-category-id` (from [giscus.app](http://giscus.app/)), `data-mapping` (how to map pages, e.g. "pathname"), `data-input-position` ("top" or "bottom"), `data-reactions-enabled` (enable emoji reactions) |
| `comments → bluesky-comments` | Bluesky comments: `show-comments-from-bluesky` (enable), `auto-search-for-match` with `turn-on-auto-search` (auto-find posts), `author` (your Bluesky handle), `echo-feed-emoji` (emoji marker for blog posts) |
| `comments → webmention` | Webmentions: `webmention-api-key` (API key from [webmention.io](http://webmention.io/)), `webmention-link` (endpoint URL) |
| `block-rendering` | Content display: `enable-lightbox` (click images for fullscreen), `full-width-social-embeds` (embeds span full width on small screens), `optimize-images` (convert to WebP, slower builds but smaller files), `process-content-to-markdown` (convert all pages/posts to markdown format alongside HTML output for use with LLMs and other tools) |
| `shortcodes` | Special markers in Notion code blocks: `html-render` (render HTML in iframe, default `<!DOCTYPE html> <!-- iframe -->`), `html-inject` (inject raw HTML, default `<!DOCTYPE html> <!-- inject -->`), `expressive-code` (not implemented), `shiki-transform` (advanced highlighting, default `<<shiki-transform>>`), `mdx-inject` (MDX compilation, default `<!-- mdx inject -->`), `table` (datatable features, default `<<🗂️>>`) |
| `shortcodes → author-desc` | Author metadata shortcodes in multi-select description field: `author-url` (start/end markers `<<author-url>>`), `author-photo-url` (start/end markers `<<author-photo-url>>`). Remaining text is the bio |
| `auto-extracted-sections → footnotes` | Footnotes: `sitewide-footnotes-page-slug` (legacy manual page slug, default "_all-footnotes"),_ `_in-page-footnotes-settings_` _with_ `_enabled_` _(toggle system),_ `_source_` _(only one true:_ `_end-of-block_` _for definitions at block end,_ `_inline-latex-footnote-command_` _for \\\\footnote{content},_ `_start-of-child-blocks_` _for first n child blocks,_ `_block-comments_` _for Notion comments with Read permission,_ `_block-inline-text-comments_` _not yet implemented),_ `_marker-prefix_` _(default "ft_" for `[^ft_1]`, does not apply to inline-latex-footnote-command), `generate-footnotes-section` (collate at page bottom), `show-in-margin-on-large-screens` (margin on large, popovers on small) |
| `auto-extracted-sections → interlinked-content` | Interlinked content at page bottom (formerly `references`): `site-links-in-page` (links to other site pages), `external-links-in-page` (external website links), `media-and-file-links-in-this-page` (embedded media files), `links-to-this-page` (backlinks from other pages). Popovers enabled by default |
| `auto-extracted-sections → citations` | Citations: `add-cite-this-post-section` (add "Cite this page" section), `extract-and-process-bibtex-citations` with `enabled` (toggle BibTeX processing), `bibtex-file-url-list` (array of .bib URLs: GitHub Gist/repo, Dropbox, Google Drive; GitHub links check timestamps, Dropbox/Drive fetch on every build), `in-text-citation-format` (`[@key]` pandoc `cite\{key\}` LaTeX / `#cite(key)` Typst, renders as \[firstName et al, year\] or \[1\]\[2\]), `bibliography-format` (only one true: `simplified-ieee` for numbered ICML/NeurIPS style, `apa` for author-year ACL style), `generate-bibliography-section` (collate at page end), `show-in-margin-on-large-screens` (margin on large ≥1024px, popovers on small) |
| `external-content` | Pull external content from GitHub via Notion's "External URL" field: `enabled` (toggle feature), `sources` with `markdown` (GitHub folder URL where each subfolder is a markdown post), `mdx` (GitHub folder URL for MDX posts), `html` (GitHub folder URL for HTML posts), `custom-components` (GitHub folder for MDX imports, downloaded to src/external-content/custom-components, also usable via `mdx-inject` shortcode) |
| `redirects` | 301 redirects: object mapping old paths to new (e.g., `"/old.html": "/new/"`) for SEO when migrating content |

**Webtrotion 1.0 extra configuration options**

| Key | Value |
| --- | --- |
| public-ga-tracking-id | Your google tracking property id. Steps [here](https://support.google.com/analytics/answer/9304153?hl=en&ref_topic=14088998&sjid=1644955229874584087-NC). |
| google-search-console-html-tag | Content value of search console property verification tag. More [here](https://support.google.com/webmasters/answer/9008080?hl=en#meta_tag_verification) |
| webmention | Webmention API Key and link obtained from [https://webmention.io/](https://webmention.io/) |
| custom-domain | If you want to host the site somewhere else |
| base-path | Or subdomain inside the custom domain |
| shortocdes | There are 3 shortcodes atm, two supported, two in works. `html` shortcode is used to embed html code blocks that start with this line directly into the page. `shiki-transform` is used to transform code blocks into more expressive representations. `table` is used to set the identifier for data-tables enabling search and sort. |
| references | To show related pages, external links, and mentioned media at the end of the post. Set `popovers` to true to display a snippet when hovering over a post link in the body. |
| theme | Colors for light mode and dark mode |
| fontfamily-google-fonts | Combined URL link for all fonts you want to use from google fonts. Remember to escape spaces in font names if needed |
| number-of-posts-per-page | Number of posts in a page for pagination purposes |
| enable-lightbox | Set to true if you want people to be able to click on your image to open in a new tab |
| request-timeout-ms | Timeout for API requests |
| menu-pages-collection | Collection select value in Notion database that decides if these are pages or blogposts. Set this to value you use for pages. |
| heading-blocks | Which top-level blocks blocks should form the table of contents on right |
| full-preview-collections | Stream like view, where each post is a mini-blog in the same page as a scrollable page instead of being links to individual pages. Any Collection name added to this list will be rendered as stream view. |
| hide-underscore-slugs-in-lists | If the slug starts with `_`, hide those in post lists, rss and sitemap, but still render them, so that you can share them |
| home-page-slug | By default is set to `home` but can be anything that you want for the renderer to recognize which is your home page from the database |
| og-setup | Open graph setup refers to the images displayed when sharing links. It includes excerpts and creates two columns if a featured image is available. You can customize the title and footnote fonts for the og-image, particularly for non-English blogs. Ensure that each URL has only one font and, if it has a weight, the weight is above 400 |
| optimize-images | Converts images to next-gen formats like webp for more responsive sites |
| redirects | Intentional redirects, especially if you are moving systems that astro should redirect to |
| all-footnotes-page-slug | Defaults to `_all-footnotes`. This page is not visible in post list because it starts with a `_` but you can use this show popup blocks on any of your pages. |
| bluesky-comments | `show-comments-from-bluesky` to turn on/off a Bluesky comment section. `auto-search-for-match` searches your profile for parent posts mentioning the link, controlled by `turn-on-auto-search`, with `author` specifying your Bluesky handle; `echo-feed-emoji` filters these searches. |

## License

MIT

## Notes

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/report_yellow.BexcuVVH_Z1EYdWV.svg)

**Don’t rename the columns of DB.** They are used in the astro code. You can reorder the columns or add any other columns you want.

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/exclamation-mark-double_purple.Dl070vZp_Z1EYdWV.svg)

Remember, the cron schedule is by default set to every 8 hours. You can change it to run every 2 hours or if you want to push out a change immediately, you can also [manually run the github action](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow) if you are deploying on github. The workflow name is “Deploy Github Pages”.

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/exclamation-mark_red.DbhozgVK_Z1EYdWV.svg)

Update Jun 19, 2024: I included a [keep alive workflow](https://github.com/liskin/gh-workflow-keepalive) which will hopefully work to keep the action running without any manual intervention. Fingers crossed 🤞.

Webtrotion relies on GitHub Actions if you're deploying on GitHub Pages. If you don't commit any changes to the repository, remember to manually enable the workflow every 60 days.

**Screenshot of the email you’ll get warning you about the workflow being disabled.**

[![[GitHub] The "Deploy to GitHub Pages" workflow in nerdymomocat/nerdymomocat.github.io will be disabled soon](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.DAUOZvuN_Z1vxaEF.webp)](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/Untitled.DAUOZvuN_Z1vxaEF.webp)

\[GitHub\] The "Deploy to GitHub Pages" workflow in nerdymomocat/nerdymomocat.github.io will be disabled soon

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/info-alternate_gray.xE4Ugu2z_Z1EYdWV.svg)

**Aggressive Caching**

Remember that the setup uses aggressive caching for github actions. These caches are public. If you want to remove caches, you can go to [github action workflow](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow) and manually delete the caches

![](https://nerdymomocat-templates.github.io/webtrotion-astro-notion-cms-website-blog/_astro/info-alternate_gray.xE4Ugu2z_Z1EYdWV.svg)

**Multilingual/Non-English blogs**

Open graph setup refers to the images displayed when sharing links. It includes excerpts and creates two columns if a featured image is available. **You can customize the title and footnote fonts for the og-image, particularly for non-English blogs.** Just specify any Google font name (no URLs needed starting version 2.0), and set the font weight if desired (default is 400).

* * *

If you end up using webtrotion, please consider buying me a coffee here:

[Feed my software & bakery addiction @  ![Buy Me a Coffee at ko-fi.com](https://storage.ko-fi.com/cdn/brandasset/logo_white_stroke.png)](https://ko-fi.com/nerdymomocat)

[^1]: From September 2025 onwards, AI assistants have been used to develop complete features. Before this, GitHub Copilot and chat-based AI tools assisted with code writing but not full feature development.
[^2]: Claude code and gemini cli \[a\]
[^3]: Just like these!
[^4]: **Footnotes and Citations** \[b\]
[^5]: For Webtrotion before 2.0, open `constants-config.json` and configure four essential settings: change `DATABASE_ID` to your Notion database ID, add your name to `AUTHOR` (used for HTML semantics and OG images), add your social media links, and add your Giscus information to the `GISCUS` key (or disable it by removing the value for `data-repo` in `GISCUS`).
[^6]: Open file `**constants-config.json5**` \[c\] in the web UI. This file is the complete setup file for your website. For now, we will make four major modifications: