How I Learned to Stop Worrying and Love VitePress
Personal Web Culture of the 1990s
I first started using the internet in the 1990s, during the era when Yahoo! and Netscape Navigator were in widespread use. Personal sites of that time were primarily built by hand-coding HTML, and it was common to feature a visitor counter and a bulletin board. Discoverability depended heavily on human-curated directory listings and the "link collections" that individual sites maintained. For example, "Banner Club" — a 200×40-pixel banner-link collection by Woody-Rinn — established what was effectively the standard format of the time. "Surfers Paradise" and "TINAMI" functioned as registration-based search engines centered on illustration sites.
Cross-linking culture was widely shared during this era, and users would navigate to new information and creative works by following links between sites. Personal sites fell into recognizable types according to their content — text sites centered on written pieces, illustration sites centered on drawings and artwork — but all were fundamentally published for the purpose of presenting "works." In this sense, the personal site of those days was the primary expressive medium on the Web, and can be characterized as the central presence in Web space.
The Transformation of Web Culture Brought by Advanced Search Engines and the Blog Boom
In the 2000s, the structure of information distribution on the Web changed dramatically. First, search engines shifted rapidly from the directory model to crawler-based automatic indexing, and services such as AltaVista, Excite, Infoseek, Lycos, and goo came into widespread use. Google, launched in 1998, far surpassed other search engines in accuracy through its PageRank algorithm and had become the de facto standard by the early 2000s. With this shift, SEO emerged as a concept, and the condition for being found on the Web moved from participating in link collections and mutual linking to adapting to search algorithms. With mutual linking between personal sites, the circle of connections was essentially limited to an individual's sphere of activity — even a few hundred sites was considered a large-scale link collection — but in a search environment premised on automatic indexing and algorithmic presentation, the number of sites a user might encounter expanded to hundreds of thousands.
During this period, personal site operations also migrated to blogs using Movable Type and WordPress. As RSS subscription culture developed, the importance of update frequency and search optimization grew, and posts became increasingly time-oriented. The clear publication timestamps made it easy for readers to track updates, and since RSS presented items in reverse chronological order, increasing posting frequency became necessary to reach more readers. Furthermore, new articles were no longer placed as part of category pages but were positioned at the very top of the homepage — the site structure itself was reorganized around chronology. As a result, the personal site as a place to exhibit works came to be understood as a media outlet for continuous information output, and the relative value of quickly-produced content rose. In this sense, quantity began to outweigh craft.
As an attempt at cross-blog connectivity, Movable Type implemented Trackback in 2002. Trackback was a feature that automatically notified another blog when you wrote an article that referenced it, and it was anticipated as a new means of forming links between personal sites. In practice, however, spam trackbacks from unrelated promotional sources proliferated, forcing operators to manually delete them, and the mechanism declined rapidly. I remember reading enthusiastic introductions to Trackback, but the technology declined before I actually got to experience it — that is my personal impression of how it was received.
These changes brought a considerable sense of rupture with the existing personal site culture. Personally, it felt as though the connections that had been built between personal sites were suddenly replaced by Weblogs. The awkwardness of abbreviating "Weblog" to "blog," resistance to the mass influx of users who couldn't write HTML directly, and disgust at the small, low-contrast fonts used in unreadable designs all led to a strong sense of rejection at the time. These feelings were subjective and emotional, not evaluations that can be generalized in any way, but they do illustrate that the shift in Web culture of that era was experienced as a loss by at least some existing users.
The Transformation of Information Flow in the SNS Era and the Reevaluation of Personal Sites
In the 2010s, SNS platforms represented by mixi, Facebook, and Twitter became widespread, and the center of people's sharing and browsing activity shifted from personal sites and RSS to SNS. On mixi, accumulating "footprints" (ashiato) was strongly emphasized, and by the time management identified this as a problem, users had already become difficult to separate from their engagement-seeking behavior. When mixi weakened the visibility of engagement by revising the footprint feature, users' interest turned outward, and the service ultimately became a gaming platform, declining as an SNS. The SNS platforms that followed saw information that had previously been read through dedicated RSS readers consumed instead through timelines. RSS at least contained a minimum volume of content that the author themselves recognized as an article, but on SNS, short texts that could not always be called articles became the mainstream. Twitter and similar platforms were initially called "microblogging," but most posters did not seem to think of themselves as writing articles. This format was explosively adopted, but simultaneously, since you could easily post and receive responses without writing full articles, motivation to write carefully crafted pieces weakened. Furthermore, it became clear that even if you invested effort in writing an article, you could not gain sufficient traction against the sheer volume of content produced by advanced SEO practitioners and professional content mills. People stopped writing articles, RSS feeds stopped being updated, and RSS as a culture declined. This transition can be summarized as a shift from the pull-type, stock-information-centered era of the 2000s to the push-type, flow-information-centered era of the 2010s and beyond.
As the volume of information grew and users who preferred not to curate for themselves became the mainstream, algorithmic timelines took hold. Following someone on SNS was originally an act of receiving a specific person's perspective and thoughts through the flow of time; chronological display preserved the context of "who said what, in what continuity." When platform-driven algorithmic timelines were introduced, however, standardized expressive forms that generate engagement came to be prioritized over the personality and thought of the creators. As a result, "authenticity" lost its rarity: visual vocabulary became fixed — symbolized by the phenomenon of "Instagrammability" — and successful formats were transformed into performative styles that could be imitated and mass-produced. This is better understood as a phenomenon accelerated by platform design rather than a naturally occurring cultural shift.
At the same time, the arena for expression was enclosed within platforms such as YouTube, Medium, Substack, Qiita, Zenn, and note. With audience acquisition, distribution, and monetization integrated, visibility came to be determined by algorithms, and content was effectively treated as platform assets. SEO competition intensified greatly, personal site traffic declined sharply, and the reason to write on one's own domain eroded. On the other hand, the significance of personal sites as archives for primary information increased rather than diminished. Algorithms that favor recent posts like "this week's popular articles" or "trending articles" treat content as flow information, but technology and thought are inherently static information that should accumulate over the long term. In this sense, one's own domain remains an important place for stably maintaining stock information. The author posted hundreds of thousands of times on SNS throughout the 2010s, only to be dismayed to find that nothing remained. This experience illustrates the fragility of expression that depends on flow-type media.
In recent years, with the disappearance of Twitter as one turning point, a certain number of people have appeared who are reconsidering their relationship with SNS. The distributed nature of the Fediverse seems to be generating a tendency by functioning as a place to present "works" that fosters creative motivation, avoids excessive dependence on specific platforms, and returns the stage for publication to individuals. Furthermore, with the spread of AI, information exploration is changing from keyword search to dialog-based primary information retrieval. Summarization and generation are absorbing the intermediate-layer information that search engines and other intermediaries provided between primary sources and readers; meanwhile, SEO for AI does not yet appear to have been established. Personal sites are once again gaining importance as a source of primary information and originality, equipped with uniqueness, permanence, and technical freedom.
Consideration of Documentation Systems and the Decision to Adopt VitePress
In light of these circumstances, I concluded that I needed to distance myself from the attitude of getting the feeling of accomplishment by posting emotionally on SNS, and to build an environment where I could continuously accumulate and publish technical writing. While building the overall site with Blocs 6 for Mac, I decided to use a documentation system separate from it for composing and publishing technical documents. For self-hosted tools, I generally spun each one up in Docker and tried it out individually.
Among the candidates, Markdown-centered compositions were the most realistic starting point. Markdown is the de facto standard: lightweight, with a low learning cost and a very rich ecosystem. It also has strong affinity with GitHub Pages and combines well with static site generators. Static site generators bind content and templates at build time to produce static HTML, offering advantages in response speed, scalability, and a reduced attack surface. Some also support embedding React or Vue components, providing high extensibility. Representative tools include Docusaurus, MkDocs, Hugo, Jekyll, MDX, and VitePress. AsciiDoc, on the other hand, supports cross-references and allows publication-quality output suitable for book-level documents. In terms of publication quality, Vivliostyle is also significant, offering CSS-based high-quality typesetting, particularly strong for vertical text documents. I have personally relied for many years on the text formatting tool XTR, created by Shinyu Murakami, as my primary documentation tool, and I extend the same trust to Vivliostyle along those lines. reStructuredText is the central notation in the Python ecosystem, widely adopted through Sphinx in Python's official documentation and in science and engineering projects. However, with Markdown support also progressing via the MyST parser, I have a somewhat divided impression as to whether the Python community as a whole still strongly champions reStructuredText.
Beyond these, dynamic documentation tools such as Outline and BookStack were also candidates. Regarding Outline: at the time of consideration, authentication was limited to Google or Microsoft with no other options, which made it unsuitable given my preference to avoid dependence on large platform companies. It now supports magic link email authentication, so reconsideration is possible. BookStack looked very attractive overall, but the fact that BookStack's own documentation was built with Hugo, not BookStack itself, left a lasting impression as a factor in my evaluation. As non-self-hosted means, the Publish features of note-taking tools such as Craft, Notion, and Obsidian are an option. These offer excellent writing experiences and can be published as-is. I am in fact a Craft Plus user and an Obsidian Catalyst and Sync Plus user, and integration with Blocs-based static site generation is possible. As a separate publication avenue from a personal site, distribution platforms such as Medium, Substack, Qiita, Zenn, and note are also options; their built-in audience acquisition, distribution, and monetization features make them strong publishing platforms. The first article I posted on Qiita received over 26,000 views, and the decision to commit to writing and publish it was well worthwhile; another article continues to be read to this day. At the same time, it became clear to me that being read by others is not itself my most important value.
Taking all of this into account, I judged that what suited me was a static site generator-based setup with high extensibility and a smooth writing experience. In particular, I wanted to write articles about running Rust-written code as WebAssembly in the browser. In addition to wanting to learn Rust itself, I had a strong interest in being able to build web applications that operate efficiently in the browser. Evaluating options against this goal, while I was not yet sufficiently familiar with TypeScript, Vue, or Vite, VitePress appeared to stand a step ahead. VitePress is a static site generator designed primarily for creating and publishing technical documentation, made by the Vue.js development team. It occupies a successor-like position to VuePress, redesigned toward simpler configuration and faster builds. Vue components can be used directly for theme customization, allowing flexible extension for anyone with frontend knowledge. In fact, when I checked the documentation of software I use regularly, VitePress-built sites appeared frequently; VitePress's own documentation is itself created with VitePress, a point that stood in contrast to the impression left by BookStack. Automatic sidebar generation and organization around coherent document units also looked practically useful. Additionally, per-page and per-folder PDF generation appeared achievable through @media print definitions combined with tools like Puppeteer, which at that point did not seem to be a significant constraint.
For these reasons, I decided to adopt VitePress as my documentation system.
Impressions on Adopting VitePress
Having actually adopted VitePress, my overall evaluation is that it was an appropriate choice. That said, because the tool is very actively developed, its documentation has often not fully kept pace with the progress of implementation. As a result, necessary information was sometimes impossible to find in the official documentation alone, and I frequently had to dig through GitHub Issues to find solutions — a process that required considerable effort. Moreover, since I was not sufficiently familiar with frontend technologies myself, the problem-solving process felt like pushing through vegetation in a tropical peat swamp forest. Even seemingly trivial tasks sometimes required several days before any progress could be made.
Nevertheless, no truly insurmountable problems were encountered, and the overall experience has been satisfactory. In particular, I give high marks to the ease of preview in development mode, the quality of the generated output, the concise but sufficient feature set, and the extensibility available when needed. Based on all this, the decision to adopt VitePress was sound, and it has turned out to be a satisfying choice.