This note records a round of optimizations made to the knowledge section of my blog.

The main issues fell into two categories:

1. The bundle was too heavy
2. The reading experience was not continuous enough

Both directly affect real-world usability.

1. Markdown, code highlighting, and Mermaid must be loaded on demand

The bundle problem on the knowledge page was not caused by Markdown alone. The issue was loading the entire Markdown ecosystem up front.

The heaviest parts at the beginning were:

• markdown-renderer
• code highlighting
• Mermaid
• Mermaid’s chart engine

If all of those are loaded during initial render, then even a plain document with no diagrams and no code blocks still pays the cost.

The fix was layered lazy loading.

a. Lazy-load the Markdown viewer renderer

Only load Markdown rendering logic when a document is actually opened.

b. Load code highlighting only when a normal code block is present

If there are no code blocks in the article, code highlighting should not be part of the initial cost.

c. Load Mermaid only when a mermaid fence is present

Mermaid still auto-renders, but the component and chart engine are only loaded when a real ```mermaid block is present.

After this round of changes, the build output of markdown-renderer dropped from roughly 1.1 MB to around 325 KB. mermaid.core still cost about 585 KB, but that cost became conditional and no longer applied to every document.

2. Improve navigation scrolling feel on mobile

The knowledge page is not just about bundle size. Reading details matter too.

If the mobile sidebar has too much inertia, it feels floaty, and that effect is even more obvious inside a drawer panel.

So I added an extra layer of handling to make scrolling feel tighter and more controlled.

This does not show up in the bundle report, but it has a direct impact on daily usage.

3. Preserve the user’s last reading progress

The knowledge page now records:

• which note was opened last time
• the reading progress of that note

After a refresh, if the document still exists, the page restores the same article and the same scroll position.

That way, the user does not have to find the document again or manually scroll back to where they stopped.

4. Handle invalid persisted state safely

There is an important detail in persisted reading state: you cannot blindly trust old records.

If the document that was opened last time has already been removed, the page should not keep trying to restore it.

The handling here is:

1. Validate local records against the current file tree
2. Restore the article and progress if the file still exists
3. Clear invalid records and fall back to the empty state if it no longer exists

That keeps the knowledge page from landing on broken content or behaving strangely because of stale records.

Summary

Optimization for a page like this cannot be measured by bundle size alone.

A complete optimization pass should cover:

• initial loading cost
• on-demand loading for diagrams and code blocks
• mobile interaction quality
• continuity of reading state

Only when those layers are handled together does the knowledge page move from merely usable to genuinely smooth.