Jul 6, 2024: Simple tables with search and sort. 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).
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
Jun 28, 2024: Floating table of contents and shiki transforms for code blocks (updated to astro 4.11), and added view transitions
Webtrotion is a extensively configurable, simple to install website builder, built with the Astro framework in conjunction with Notion. Use it to create an easy-to-use blogor website.
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 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 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, Morethan-log, and Notion-Blog-NextJs
Key Features
Astro v4.11
Integrates with Notion to create a website and not just a blog
Get your database id of the database you duplicated. 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.
Database id from notion url
Github Setup
Create a new repo from this template 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.
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>.
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.
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
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.
Set up giscus as mentioned on the website giscus.app. Keep the script it produces open as we will use it in the next step.
Go back to your cloned (forked or created through a template) repository.
Open file constants-config.json in the web UI. This file is the complete setup file for your website. For now, we will make four major modifications:
Change DATABASE_ID to your database id that you obtained from Notion.
Add your name to AUTHOR (this is used for HTML semantics and OG image generation)
Add your socials (you can also remove the value for this-github-repo)
Add your giscus information to the GISCUS key. If you do not want you use Giscus, remove value for data-repo in GISCUS and that will disable the feature.
Save the file and commit+merge to the main repo.
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.
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 Supported blocks in Webtrotion but tl;dr all blocks are supported except child databases and child pages.
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 if you are deploying on github. The workflow name is “Deploy Github Pages”.
Preview
Light mode preview
Dark mode preview
Notion Properties
Pages or posts are only published if: their Published property is checked ANDif 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 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
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 Publish 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.
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 folderexport NOTION_API_SECRET=YOUR_KEY_HEREnpm installnpm run build #we need to build once because that is when all icons are downloadednpm run dev
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
License
MIT
Notes
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.
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 if you are deploying on github. The workflow name is “Deploy Github Pages”.
Update Jun 19, 2024: I included a keep alive workflow 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
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 and manually delete the caches
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. Ensure that each URL has only one font and, if it has a weight, the weight is above 400
If you end up using webtrotion, please consider buying me a coffee here:
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>.
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.
Supported blocks in Webtrotion but tl;dr all blocks are supported except child databases and child pages. 
![[GitHub] The "Deploy to GitHub Pages" workflow in nerdymomocat/nerdymomocat.github.io will be disabled soon](/notion/6c6e8f96-a269-4eab-8cdc-b123194509d7/Untitled.webp)
