The implementation and illustrations were checked on November 15, 2026. Interface images come from the production website and the Vercel dashboard.
1 Project background: a place of my own for articles and travel records
I first wanted a personal website to give my technical articles, projects, and travel photographs a place of their own. But maintaining it would become awkward if every new article or set of photos required editing pages and deploying the site again.
My approach was to separate content preparation from presentation: write and organize material in a suitable tool, then let the website read it and display it in a layout I could control. I chose Notion for content management, Next.js for the pages, OSS for media storage, and Vercel for hosting. I developed the site with Codex, while taking responsibility for the requirements, design choices, and review of the results.
From editing content to displaying it on the site
Content can be edited directly in Notion. I can also work with Codex on local Markdown files and use publishing tools to write them to Notion. The content and interface follow separate update paths: changes to an article update the content and its caches, while interface changes trigger a build through GitHub.
Content production and visitor access

Solid lines follow the flow of content. Dashed lines show the explicit website cache refresh after publication.
What the five main pages are for
| Page | Design focus |
|---|---|
| Home | Establish a first impression with the seascape and introduction, then provide links to recent projects, articles, and journeys |
| Blog | Help readers find articles through categories and search, then open a long-form reading page with a table of contents |
| Product | Present project summaries, technology tags, status, and visit links |
| Journey | Browse photos and videos continuously by date, opening details and larger views as needed |
| About | Introduce the author through a moonscape, personal introduction, education, and travel records |
These five pages share navigation, fonts, and a footer. Their layouts adapt to the content: photographs need space, long articles need a reading surface and contents navigation, and projects need to make their purpose clear.

The five main pages on the production site. Journey is shown with the photo filter selected so that the monthly organization and masonry layout are easier to see.
2 Content management: Notion for content, OSS for images
How the four Notion databases divide the work
In Notion, database properties support filtering and sorting. Paragraphs, code, images, and tables live in the page body. The four databases and their main fields are outlined below; some presentation fields are optional.

Articles and projects share Content, while the profile, timeline, and interests share About. Photographs have separate JourneyPhoto records and are linked to journey records through the Journey field.
Content: articles and projects share a database, distinguished by ContentType.
| Field | Type | Purpose |
|---|---|---|
Title, Summary | Title, text | Article or project title and summary |
ContentType, Status | Select | blog/product; planned/active/completed for projects |
Slug, Language | Text, select | Stable address and zh/en language version |
Date | Date | Publication date and sorting |
Tags | Multi-select | Article categories or project technology tags |
Published, Featured | Checkbox | Public visibility and homepage selection |
CoverImage, Icon | Files | Cover and project icon; external images are supported |
ProductUrl | URL | Project visit link |
CoverAlt, SEOTitle, SEODescription | Text | Optional image descriptions and search presentation information |
Journey: the basic information for a journey, album, or video.
| Field | Type | Purpose |
|---|---|---|
Title, Slug, Language | Title, text, select | Name, address, and language |
Type | Select | album/vlog/anime-edit/travel-note |
Date, Year, Month | Date, number | Organization by time; the year and month can be derived from the date |
Place, Summary, Feeling, ShootingNote | Text | Location, summary, reflections, and photography notes |
CoverImageUrl, VideoUrl | URL | Cover image and video platform address |
CoverWidth, CoverHeight, CoverOrientation | Number, select | Optional cover dimensions and orientation |
Published | Checkbox | Public visibility |
JourneyPhoto: album membership and display information for each photograph.
| Field | Type | Purpose |
|---|---|---|
Name, ImageUrl | Title, URL | Photograph name and public display address |
Journey | Relation | Associated album/journey |
Order, Published | Number, checkbox | Order within an album and public visibility |
ImageWidth, ImageHeight | Number | Optional dimensions to help determine the layout in advance |
Alt, Caption, Location, ShootingNote | Text | Image description, location, and photography notes |
CapturedAt, CapturedDate, TimeSource | Date, date/legacy text, select | Optional capture time and its source |
About: SectionType distinguishes the profile, timeline, and interests.
| Field | Type | Purpose |
|---|---|---|
Title, SectionType, Language | Title, select | Name, profile/timeline/highlight, and language |
Headline, Subheadline, Intro | Text | Hero heading, subheading, and personal introduction |
Period | Date range | Start and end dates for education, work, and interest records |
Place, Description | Text | Location and details |
Tone, ItemType | Select | Presentation role and type of experience |
Published | Checkbox | Public visibility |
Chinese and English articles are stored as separate records, paired by Slug within the same content type. Interface text is managed by next-intl. By default, blog publishing chooses categories from “Tech Sharing,” “Personal Reflections,” and “Travel Notes.” The website sidebar is generated by deduplicating the actual Notion Tags used by published articles. Projects retain free-form technology tags.
Saving content in Notion does not determine exactly when it appears on the site: visibility and caches also matter. To see an edit immediately, Published must be checked and the caches explicitly refreshed. Section 6 describes that process.
Why most images are stored in OSS
Images uploaded directly to Notion use temporary signed URLs. According to the official documentation, these addresses are valid for one hour and must then be retrieved again. It is the address that expires; this does not mean that an image can only be cached for one hour. Notion file documentation
Most locally published images are uploaded to OSS to obtain stable addresses and control the dimensions and quality of photographs. Notion stores the references, and browsers fetch the images directly from OSS. Native Notion uploads are still supported: the server provides stable media references, and /api/notion-image locates public resources and refreshes temporary addresses when necessary, rather than embedding an old signature permanently in the page.
Article images are managed alongside Markdown and named with a content hash when uploaded. When the image bytes change, the URL changes too, avoiding stale images after an overwrite under the same name.
Journey photographs retain their originals and editing projects locally. Only a processed display master is uploaded. Notion stores album relationships, ordering, descriptions, and addresses; the website arranges the media into a monthly stream. Videos retain their Bilibili or YouTube addresses and play through the corresponding platform.
3 Website implementation: reading and displaying Notion content in Next.js
Pages and server logic share one Next.js application
The site currently uses Next.js 15.5.15, React 19.1, TypeScript 5, and Tailwind CSS v4. Pages and server logic live in the same project with separate responsibilities; they do not require two separately deployed Vercel services.
src/app/ Routes, metadata, and HTTP entry points
src/server/notion/ SDK, queries, field mapping, and body reads
src/server/content/ Shared content entry point, normalization, and gallery read models
src/server/cache/ Cache tags and invalidation rules
src/server/images/ Media references, proxying, and transport checks
packages/contracts/ Document AST, DTOs, and runtime validation
src/ui/ Pages, shared components, styles, and interactions
src/i18n/ Language routing
SKILLS/ Author-side writing, publishing, and operations toolsServer Components generate pages by calling content functions directly. Client Components handle the table of contents, menus, search, and image gestures. The browser therefore does not need to fetch article JSON before displaying the body, and Notion credentials remain on the server.
The earlier overview shows how content flows. The following diagram focuses on requests and calls: RSC calls the content layer, the content layer reads Notion, and the normalized document is passed to the UI. Function calls define the content boundary without requiring another service.

How an article gets from Notion to a page
For /zh/blog/example-post, the application first finds the record matching blog + zh + Published=true + Slug, then reads its blocks by page ID, following pagination. Table rows, nested lists, and other child blocks require recursive queries. The current read budget is 16 levels and 10,000 nodes, with at most three concurrent Notion requests. Read failures remain errors; a network failure is not turned into an empty article.
The raw blocks are then converted into the site's own AST. Headings, paragraphs, lists, images, and other nodes form a document tree, with inline formatting stored separately. The contracts provide TypeScript types and validate actual data at runtime, checking matters such as unique node IDs, table column counts, and table-of-contents consistency. The result includes document, toc, seo, and translation information, which are passed to the reading view.
Notion properties and body → Normalized AST → Contract validation
→ Body, table of contents, SEO → Shared article/project viewThe body component is still called NotionBlocks, but it now receives the site's own document nodes. Adjusting fonts, reading surfaces, or the table of contents does not require processing the Notion response again. Unsupported formats also have an explicit fallback point.
Keeping the table of contents and bilingual pages tied to the content
Each page keeps one H1, and the body is organized primarily into H2 and H3 headings. The table of contents comes from the same document tree and uses the same anchors. During scrolling, requestAnimationFrame batches updates and highlights the relevant heading. For a long table of contents, the current item's center moves toward 38.2% of the visible height, while the first and last positions remain constrained by the scroll boundaries.
Language switching, canonical URLs, hreflang, and the sitemap all reflect content that is actually published. When a translation does not exist, language switching is disabled and no fictitious English page is generated. List search currently matches only the loaded titles, summaries, and tags; it is not full-text search.

The long-form reading view: the two-level table of contents and current-item highlight are on the left; the article and light reading surface are on the right.
4 Hosting migration: Vercel for the application, Alibaba Cloud for the domain
I bought a server, then chose Vercel hosting
I registered the domain with Alibaba Cloud and initially bought a server there too. Because of restrictions related to hosting in mainland China, that server was not used for production hosting. The application was ultimately deployed to Vercel.
Domain registration, application hosting, and image storage can use different providers. Today, Alibaba Cloud manages the domain, DNS points to Vercel, OSS continues to serve media, and Notion manages the content.
Deploying the GitHub repository to Vercel
The project's Vercel deployment follows these steps.
- Prepare the GitHub repository. Commit the source, lockfile, and workspace configuration, retaining the Node 24.x version requirement. Local
.env.localfiles, private article drafts, and credentials stay out of the repository. - Import the Vercel project. Authorize the corresponding repository, select Next.js, and set the project root to the repository root. The current install command is
npm ci --include=devand the build command isnpm run build; the build compiles contracts before building the site. - Configure environment variables. Following
.env.example, provideNOTION_API_KEY, the four data source IDs for Content/Journey/JourneyPhoto/About,REVALIDATE_SECRET, andNEXT_PUBLIC_SITE_URL, and grant the Notion integration access to the relevant pages. The four ID variables retain their*_DATABASE_IDnames, although queries actually use data source IDs. Credentials do not use theNEXT_PUBLIC_prefix. OSS write credentials and GitHub automation credentials remain only on the local publishing side. - Complete the first build. Use the assigned domain to check pages, Notion content, and media access. Distinguish between the Production and Preview scopes of environment variables; changing a variable requires redeployment. Environment variable documentation
- Connect the purchased domain. Add it under the project's Domains settings, then configure Alibaba Cloud DNS with the records Vercel provides for this deployment, and wait for domain and certificate verification. Do not copy another project's IP/CNAME. The site URL must also match the canonical configuration in the source. Domain configuration documentation
Subsequent updates to the production branch trigger production deployments; other branches can be used for previews. A successful build still needs to be checked at the production address, and code deployment and content publication must be verified separately. Git deployment documentation

Production deployment snapshot: Ready, built from commit 42f26aa on the main branch.

Snapshot of the domain settings: www is assigned to Production, and the apex domain redirects to www with a 308 response. Both custom domains show a DNS Change Recommended notice; the Vercel default domain shows Valid Configuration.
HTTP endpoints the site still uses
Page reads mainly use server-side function calls. Dynamic requests following user actions and maintenance operations use these HTTP endpoints:
| Endpoint | Purpose |
|---|---|
/api/posts, /api/products | Compatibility endpoints for article/project lists |
/api/content/journey-media | Gallery queries and cursor pagination |
/api/content/journey-media/[mediaId] | Locate the current media item and its browsing sequence |
/api/content/journey-media/[mediaId]/metadata | Fill in missing image dimensions; does not return full photography details |
/api/content/site-warmup | A bounded resource manifest for the main pages in the current language |
/api/notion-image | Stable proxy endpoint for public Notion media |
/api/revalidate | Authenticated POST requests to invalidate the relevant caches |
5 Visual direction: a design inspired by Sonny Boy
From discussing the scene to a design specification
I really like Sonny Boy. When planning the site, I first discussed the scenes, colors, and sense of space with ChatGPT, then had Codex turn those discussions into a design specification, prototypes, and a frontend refactoring plan. The sea and sky, the Moon and Earth, and the texture of animation drawing paper gradually found their way into the pages.
The homepage opens with a seascape, while the About page's moonscape continues the quiet sense of space. A dandelion seed appears in the logo and branded entrance. Articles use a light reading surface, and education and interests are organized as complete modules. The photo details view uses a dark gray background to frame the image, while the contents navigation and search remain lightweight. Colors, typography, and surface roles are centralized as tokens; buttons, entries, reading views, and the footer are shared.
How the illustrations and paper texture are implemented
Hero illustrations use WebP assets. The desktop version separates foreground and background, scales them to the scene height, and mainly crops the sides. The mobile version uses a complete portrait composition so that adapting a desktop scene does not cut off the figure and sky. An SVG mask blends the bottom into the paper background, while the text remains independent HTML for responsive layout and search access.
The paper texture reuses an open-source Paper Design shader. Its source and license are retained locally, and parameters control folds, creases, and fibers. Its current speed is 0, producing a fixed, static texture. It mounts during idle time with a canvas budget of at most 2 million pixels; a WebGL failure does not block the article. The paper surface and Hero illustrations are implemented separately, rather than covering the entire site with one paper-texture image.
Fonts are self-hosted through Fontsource, with different roles for Chinese text, English display text, and code. The geometry of the mobile top bar remains stable and its glass gradient is configured separately. On desktop, scrolling mainly leaves the central navigation visible. The mobile language button is inside the menu, which stays open after switching languages.
How the gallery is arranged and navigated
| Reused component | Role in this project |
|---|---|
| Paper Design shader | Paper texture, with parameters and fallback behavior controlled by this project |
| React Photo Album | Responsive masonry layout foundations |
| Yet Another React Lightbox | Carousel, zoom, video, and gestures |
| next-intl, Fontsource | Bilingual routing/interface text and local font assets |
Journey unfolds by month. Month and album entries in the contents navigation scroll to the relevant location, while search and type filters determine which media are shown. The gallery responds to the available container width: the current screenshot has three columns, switching to four from 1360px. Photographs with an aspect ratio of at least 2.5 span the full width. The layout looks among up to six nearby ordinary photographs for a more level insertion point, without crossing month boundaries, and allows a little natural whitespace.
On desktop, the details view places the photo and information side by side. On mobile, it stacks the title, photo, and details; another click opens fullscreen viewing. Legacy album URLs redirect to anchors in the unified gallery, avoiding two separate entry paths to maintain.

The seascape and moonscape establish the spatial composition; the article returns to paper texture and a light reading surface.

The desktop details view places the image and its description side by side.

The same gallery uses three-column browsing, vertically stacked details, and a separate fullscreen view on mobile. Image gestures are interactive behavior; static screenshots show only the layout of each view.
6 Content publishing: working with Codex to publish local content to Notion
Putting writing and publishing rules into Skills
Content can still be edited directly in Notion. For local collaboration, I keep Markdown, images, and a manifest in the same content directory, work with Codex on the Chinese text and facts, then prepare the English version. Each Skill starts with SKILL.md, which describes its use cases, inputs, workflow, and constraints. Associated scripts handle complex operations, while shared modules handle Notion, OSS, and body conversion.
These tools run on the author's machine and are not part of visitor requests. The main ones I use are:
| Skill | Function and constraints |
|---|---|
yeagerzhao-writing | Organize the main argument, facts, and language; does not invent experiences or performance figures, or publish automatically |
publish-blog-product | Convert bilingual Markdown/manifests to Notion and upload local images to OSS; the standard entry point requires both Chinese and English |
publish-journey-album | Process photographs, add watermarks, upload images, and create album relationships; private by default, with idempotency issues still to address when overwriting |
publish-journey-video | Register Bilibili/YouTube information without uploading video; public by default, with --draft for drafts |
publish-about | Rebuild the profile and timeline from structured data, public by default; small edits can also be made directly in Notion |
operations | Set up databases, back up data, refresh caches, and retry; a JSON backup is not a complete offline article package |
Read back the published body and attempt recovery on failure
An article directory normally contains draft.zh.md, draft.en.md, manifest.json, and images. The manifest specifies the type, Slug, date, categories, and public visibility. First check the files and conversion with a dry run, then publish:
npm run publish:content -- --dir "<article-directory>" --dry-run
npm run publish:content -- --dir "<article-directory>"--overwrite changes properties only; --replace-content replaces the body. A new page starts private, and its state is committed from the manifest after the body is read back: private is the default, and only an explicit published=true makes it public.
When replacing an existing body, the script saves the old properties and a recursive snapshot, appends the new blocks, checks them, then archives the old content. If publication fails, it attempts recovery and leaves snapshots for diagnosis.
After writing, the publishing script prompts for a refresh. Cache invalidation is a separate command in operations. Once the content is confirmed public, the following example refreshes example-post:
npm run revalidate:site -- --site https://www.yeagerzhao.com --paths "/zh/blog,/en/blog,/zh/blog/example-post,/en/blog/example-post"The author-side publishing workflow

Publishing the Chinese and English pages is not a transaction across both pages. An already-public page may also briefly contain both old and new blocks during replacement. Even after a command succeeds, both language versions and their public visibility still need to be checked.
7 Ongoing maintenance: cache refreshes and photograph processing
What each cache stores and what a refresh affects
When a refresh appears to have changed nothing, the first question is which cache was refreshed. The layers store different things and have different boundaries.
| Layer | Cached content and boundaries |
|---|---|
React cache | Deduplication within a server render, such as sharing a read between the body and metadata |
| Next Data Cache | Notion queries, body trees, and gallery snapshots; most default to 3,600 seconds and are invalidated by tags |
| Page/ISR | HTML and RSC for cacheable routes; updates follow access and revalidation rules after expiration |
| Client Router Cache | RSC data for navigation within the site; does not mean images have been downloaded |
| Browser HTTP cache | JS, fonts, and image response bytes, reused according to their actual URLs and response headers |
| Gallery details cache | Keeps media and neighboring positions, isolated by language, query, browsing scope, and revision |
| Image decode cache | At most 32 entries and 24 million pixels within the current document; older entries are evicted and decoded masters are not kept long-term |
Raw Notion SDK HTTP requests use no-store; the query layer manages caching. Gallery JSON also uses no-store, although the server can still use cached snapshots. Probes for missing photograph dimensions are cached separately for 24 hours and can be invalidated by refreshing the corresponding content domain. The media proxy also keeps a disposable in-process byte cache, but does not treat it as the authority on public visibility.
For explicit updates, authenticated /api/revalidate requests invalidate tags and related paths by content domain. The local tool saves receipts, retries within a limit, and supports resuming execution. Success means that cache invalidation has completed. The receipt explicitly says prewarmed:false; it does not guarantee that every page has been rebuilt, or clear the visitor's browser image cache.
Display the first screen, then prepare resources for browsing
The dandelion entrance is controlled by sessionStorage and plays once per tab session, remaining visible for at least one second. It waits up to four seconds for the current first-screen images, background, styles, and fonts, but proceeds on failure or timeout. After a further delay of about one second, it prepares a bounded set of first-screen resources for the other main pages in the current language.
These preparation tasks run with a concurrency of two and have timeouts. They pause while the page is hidden, are canceled on navigation, and are skipped on constrained connections. An initial visit to a detail page can prepare all five main entry pages.
OSS photographs in the gallery use different resolutions for different viewing levels. Each tier is derived independently from the public display master. Dimensions are calculated from the source size, display box, and a DPR capped at 2:
| Display context | Tier | Long-edge limit/pixel budget | WebP quality |
|---|---|---|---|
| Ordinary masonry view | S | 1,280px/1.5 million | 72 |
| Full-width panorama | S panorama policy | 2,560px/1.5 million | 72 |
| Current image in the details view | M | 2,560px/4 million | 82 |
| Current fullscreen image | L | 3,840px/8 million | 88 |
| Further zoom in fullscreen | Public display master | Actual master dimensions | No re-encoding |
Non-OSS and signed URLs do not use these transformations; their original addresses are retained.
Hovering prewarms only the current image's M tier. Opening the details view prepares neighboring images at M and the current image at L. Opening fullscreen prepares neighboring images at L and downloads the current image's master bytes. Fetching a master early does not display it early: the view switches only after an actual wheel or pinch zoom. When preparing display resources for neighboring items, S is the baseline, and an already available higher-resolution source can continue to be reused.
To avoid flashing back to a blurred image when switching between details and fullscreen, the application requests the image and waits for decode() before replacing the current view. It also gives priority to an already available sharp source. Stable browsing slots, known details-cache entries, and already painted frames help reduce repeated loading caused by component remounts.
Creating display masters and understanding watermark limits
When publishing Journey photographs, Sharp first corrects orientation, removes EXIF/GPS, resizes to a budget of about 8 million pixels, and encodes JPEG at q88. The dwtDctSvd method from invisible-watermark then embeds an author identifier and outputs a public display master at q80. Small source images are not enlarged to meet the pixel budget. Local RAW files and editing projects are not uploaded through this process.
An invisible watermark can provide a clue for checking attribution, but cannot guarantee resistance to arbitrary cropping, screenshots, or compression, and is not an unforgeable authentication mechanism. Hiding download buttons or disabling right-click on decorative layers likewise cannot prevent people from obtaining pixels that are already public. Clearing Published in Notion mainly controls entry points on the website; it does not automatically make the public OSS objects private.
Dimensions and tiny previews have separate synchronization manifests and are not automatically rebuilt by a content refresh. Fixed-URL caching and duplicate records during album overwrites still need improvement. Writing and the interface can now be maintained separately. The next priority is more reliable publishing retries, while keeping the boundaries between originals, public display masters, and caches clear.


