# FolioKit

A home for my projects, with bilingual writing and a conversation beside the work

Source: https://works.im0o.top/en/projects/foliokit/
Date: 2025-04-15
End date: present
Tags: Portfolio, AI Q&A, Astro, TypeScript, Full-stack development

## Project links

- [Source](https://github.com/jz0ojiang/foliokit)


My project descriptions were scattered across blog posts and repositories. Sharing them meant sending a row of links and leaving the reader to find the useful parts. Link-in-bio pages collected the URLs, but I wanted more room than that, so I built FolioKit.

The first version was sparse: a hello animation, a search box, and project cards. I preferred a dark theme and open space, and eventually replaced the card-shaped detail pages with flatter reading pages. As the collection grew, I became more interested in how a visitor could follow a question through several projects and articles.

## Read beside the conversation

The homepage supports both browsing and asking. A question about recent work can lead to several projects; a follow-up about a particular decision opens its full description. The conversation stays on the left and the document on the right. Blog articles can be read in that same space.

An answer does not always need to repeat the page. The assistant can open the relevant document, compare work when a comparison helps, or present project recommendations using their authored covers and links. It can also create a guided tour through sections of a document.

The reading pane has its own back, forward, and expand controls. Following a related project and returning should restore the place where the reader left off. Changing documents should preserve a question being typed in the conversation.

![A scripted demonstration of the split layout: conversation on the left, project reading on the right](https://image.im0o.top/2026/20261117104150188.webp "A scripted demonstration of the split layout: conversation on the left, project reading on the right")

## A small collection did not need vector retrieval

The original implementation used Nuxt 3 and Nuxt Content for Markdown, with a separate Flask API and a local LlamaIndex vector store. Model and service settings were configurable, Redis was optional, and the site supported Chinese and English, streamed answers, and automated deployment.

In use, the separate backend and retrieval setup felt heavy for this amount of content. LlamaIndex cold starts were also awkward in a serverless environment. I rebuilt the site with Astro and plain CSS, moved the question-answering API into the same project, and gave the model tools to search the catalog and read full documents and supplementary notes.

I still maintain the writing as Markdown. The homepage, detail pages, search, assistant, and text exports all read those files. Translations share stable project IDs, so updating a project means updating one maintained source per language.

![An early Nuxt version of FolioKit](https://image.im0o.top/2026/20261117104147719.webp)

The early site centered on a search box and project cards. The conversation-and-reading layout came later.

## The small interactions around an answer

Adding a conversational interface created work well beyond displaying generated text. A follow-up sent during a response needs a visible place in the queue. Stopping generation should preserve the input and the open document. Copying an answer should produce usable Markdown, without activity labels or button text mixed into it.

Blog integration has separate retrieval and reading paths. Tools find and read articles; the pane displays them. The assistant can check which article is open, while citations retain public blog links so the reader can continue outside the portfolio.

Several long articles can also fill the conversation context quickly. I manage conversation history, previously read material, and the current page separately, avoid repeatedly inserting the same article, and expand the available context when further reading calls for it. The reader can keep asking about a project without restating what they have already seen.

By November 2026, these changes had become v3.2.0. Personal writing lives on the `personal` branch, while reusable features continue on the development branch. This site is my personal instance of FolioKit.

[The original development post](https://blog.im0o.top/posts/aec1261f)

