Table of Contents

1. Acknowledgements
2. Why Webtrotion
3. Why Notion and Astro
4. Key Features
   • Demo
5. Quick start
   • Notion Setup
   • Github Setup
6. Preview
7. Notion Properties
8. Local Run
9. Extra Configuration Options
10. License
11. Notes

Webtrotion is a simple to install, configurable to $n^{th}$ limit starter built with the Astro framework in conjunction with Notion. Use it to create an easy-to-use blog or website.

(Skip to features and setup)

This theme is built based off three major contributions:

1. Astro Cactus
2. notion-astro-blog
3. And this person on fiverr who got me 80% there on how to integrate notion into cactus theme

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.

• 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

• Astro v4.11
• 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 for creating open graph png images that includes your featured image
• Pagination
• Automatic RSS feed
• Webmentions
• Giscus comments
• Auto-generated sitemap
• Pagefind static search library integration
• 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)
• 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.

Check out the Demo, hosted on Github using Github actions

1. Duplicate this database into your Notion account. Remember to duplicate it as a standalone new page, rather than into an existing page.
2. Create a Notion integration
3. Get your API secret
4. Give your integration permission to the complete database you just duplicated
5. 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.

1. 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 .github.io; your website will be accessible at .github.io if you use github actions. If you use any other name, the website will instead be hosted at .github.io/.

⚠️ 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
   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.
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. 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.json in the web UI. This file is the complete setup file for your website. For now, we will make four major modifications:
   1. Change database-id to your database id that you obtained from Notion.
   2. Add your name to author (this is used for HTML semantics and OG image generation)
   3. Add your socials (you can also remove the value for this-github-repo)
   4. 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.
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.

🥳 And we are done! You can access your website on .github.io or .github.io/ depending on what you chose. Checkout all Supported blocks but tl;dr all blocks are supported except child databases and child pages. This specific page will show up as insecure because it has a direct HTML injection.

📝 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”.

Light mode preview

Dark mode preview

ℹ️ 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.

⚠️ 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.

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

MIT

• 📝 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 .github.io; your website will be accessible at .github.io if you use github actions. If you use any other name, the website will instead be hosted at .github.io/.
• ⚠️ 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”.
• ℹ️ 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:

Support Nerdy Momo Cat on Ko-fi! ❤️. ko-fi.com/nerdymomocat