Introduction

About half a year ago, in early February, while browsing illustrations I like on X and Pixiv, it suddenly occurred to me: why not decorate my BLOG with these gorgeous illustrations and have them change automatically every day?

So I spent a few evenings tinkering, quickly got the feature working, and then went ahead and added the same decorative image area to two other Notion sites. At the moment I have three Notion pages with a “daily rotating decorative image” feature, with the image sources managed by myself.

2. Anime-Girls-Holding-Programming-Books-710px-width.json | | 实教角色名录 | ‣ |

Researching the Approach

After looking at the image block object structure in the Notion API, my first thought was to replace images by updating the url property of an image block.

But that would require hosting the images myself. Using X/Pixiv’s own image URLs could break at any time due to CDN cache purges or anti-hotlinking measures.

Self-hosting also brings some headaches:

1. Extra effort to maintain the image host
2. Possible bandwidth charges or even DDoS attacks
3. The risk of your image host being scraped, which can escalate into copyright issues

So I set that approach aside and kept looking for a better way. After some trial and error, I found an alternative: using Synced Blocks.

Implementation Diagram

The diagram below illustrates the workflow of the “daily rotating decorative image” feature on my Notion pages.

graph TD
  A[Find the “marker block” in the Notion page by ID] --> B[Delete the image block after the marker]
  B --Append a Duplicate synced block object--> C[Randomly select an image from the image database and return the ID of the Original synced image block]
  C --> D[Append a newly constructed Duplicate synced block after the marker, with its “synced from” property set to the ID selected in the previous step]
  B --Append a Image block object--> E[Randomly select an unused image URL from the JSON file]
  E --> F[Append a newly constructed image block after the marker, with its “url” property set to the selected image URL]

A few key points:

• Marker block

  This is an empty line block placed right before the image block you want to replace. Since I use the blocks.children.append() API to update image blocks, I need a block to anchor the insertion point. I call this the “marker block.”

• Original/Duplicate Synced Block

  See the Notion API Reference. Chronologically, an Original synced block is the first synced block you create; a Duplicate synced block is a copy derived from it.

  In my case, the Original lives in the image database, and the Duplicate is what gets displayed on a Notion page.

• Using the Image object

  Earlier I mentioned the hassles of self-hosting images. But if the images are already in a public GitHub repo, there’s no need to worry. For example, one of the decorative image sources for my Tech Blog is Anime-Girls-Holding-Programming-Books-710px-width, which I simply host on GitHub.

  One limitation of updating images via the Image object is that the API currently can’t attach a hyperlink to the image itself, so visitors can’t click through to the original source. The Image block’s data structure just doesn’t have such a field yet — hopefully Notion will add this to the API in the future.

Conclusion