# LearnData turns a VuePress site into your knowledge base

> LearnData is an MIT-licensed VuePress template that aggregates notes and articles into a searchable personal knowledge base, with a separate Docsify reading-notes section, its own Chinese-inspired theme, and a GitHub Actions workflow that publishes to GitHub Pages or Vercel without a local toolchain. The whole setup happens in the GitHub web interface.

**rockbenben/LearnData** — 开源笔记模板，一键部署个人知识库和博客 | 开源工具、效率方法、心理学探索的自我提升笔记

- Repository: https://github.com/rockbenben/LearnData
- Website: https://newzone.top
- Stars: 529 · Forks: 107
- Language: JavaScript
- License: not declared
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/rockbenben-learndata

## The problem the author was solving

The README opens with a confession. The author previously managed notes with Notion, Obsidian and Lark, and ended up with notes scattered everywhere and hard to share. The lesson recorded in the file is that knowledge in notes does not belong to you, and only after it is digested and applied does it become wealth. LearnData is the answer built from that: it is based on VuePress and vuepress-theme-hope, and it aggregates notes and articles into a shareable knowledge base. The interesting part is that the repository is a template rather than a tool. You fork it, you write Markdown, and the site appears. The author runs a live instance at newzone.top, which is the reference implementation you can read before committing. The licence is MIT, the version in package.json is 1.5.1, and the last push was on 2026-10-14.

## What the template actually wires up

The feature table is where the real decisions are. The engine is VuePress, a Vue-based static site generator with content written in Markdown, and the theme is a minimal eastern design built on vuepress-theme-hope, with a cinnabar and rice paper palette or a warm ink black one, and code highlighting through shiki vitesse. Long articles can be split into series manuals, which is the structure that makes a knowledge base navigable rather than a scrolling list. Search is local by default through the slimsearch plugin, with Algolia DocSearch as an alternative. The SEO and GEO tooling is unusually thorough for a template: a frontmatter SEO audit script, a separate geo audit script, and FAQ structured data emitted as FAQPage JSON-LD. Comments come from Giscus on the main site and Waline on the reading notes, both with reading statistics. There is a Live2D widget for a mascot character, and GitHub Actions publishes to GitHub Pages or Vercel.

## The setup path, all of it in the browser

The quick start is four steps and none of them need a terminal. Click the Use this template button on the repository to create your own repository. Then enable write permissions for workflows under Settings, Actions and General, choosing Read and write permissions, which the README explains prevents a failed with exit code 128 error during deployment. Then re-run the latest workflow from the Actions tab, which creates a gh-pages branch and deploys into it. Finally, in Settings and Pages, set gh-pages as the source branch, leaving the site directory at the default root. If the gh-pages branch is not listed, re-run the workflow again. The site is then reachable at your username.github.io, after a few minutes. Renaming the repository to your username.github.io is what puts it at the root of your pages domain, and if that name is taken the system shows a red error.

## Running it locally when you need to edit

Local development is a three-step path, and the version constraints are the part that trips people up. You need Node and pnpm 12, because the pnpm-workspace.yaml at the repository root already approves the build scripts of esbuild and @parcel/watcher through allowBuilds, and pnpm 12 is required or the install fails with ERR_PNPM_IGNORED_BUILDS, while the packageManager field in package.json pins the same version. Then you run pnpm i in the project directory, then pnpm docs:dev, and the site comes up at http://localhost:8080/. The package scripts show the full surface. The dev server is vuepress dev src, with docs:clean-dev adding a clean-cache flag, and the production build runs vuepress build src and then node scripts/llms-txt.js, which generates a text summary of the site for language model consumption. There are also scripts for updating the VuePress packages with pnpm dlx vp-update, for Prettier and markdownlint checks, and three single-purpose audit scripts.

## The content model: directories that become sections

The src directory is the knowledge base, and each directory means something. The .vuepress folder holds the site configuration, with config.ts for environment and site properties, sidebar.ts, navbar.ts, theme.ts for theme and plugins, and templateBuild.html for the page template, keywords and statistics. The sidebar is generated automatically from the Markdown files under the paths you name in sidebar.ts, so adding a file adds a page. Alongside that are _posts for blog articles, _temp as a scratch folder that is not synced to GitHub by default, reading for the reading notes, an encrypt folder for encrypted content that you can point elsewhere, an anyname folder for custom notes, blog.md as the blog index and intro.md for the author introduction. The order parameter in the frontmatter controls sidebar position, supports non-integer and negative values, and the author's own convention puts short posts between -0.01 and -0.99 and substantive long-form pieces at -1 and below, which lets short notes be filed without displacing the long ones.

## Why the reading notes are a separate site

The reading notes are the most interesting structural decision in the template. Reading notes contain large amounts of quoted source text, which does not fit the minimal style of the main site, so the author builds them with Docsify instead and keeps the two apart, forming two independent search systems. The mechanics are worth understanding. The reading notes live in src/reading, and that path is not converted to HTML but copied as-is to the static site, where it becomes a Docsify page with its own search index. Because Docsify does not support relative links, the sidebar entry in src/.vuepress/sidebar.ts has to point at the absolute URL of the reading section rather than a path. There is a dedicated script, reading:sidebar, that regenerates that sidebar. The upshot is that a reader searching the knowledge base will not find the reading notes, and vice versa, which is a trade the author has made deliberately.

## Where LearnData is the wrong choice

Three cases. The first is a team that needs to own its content pipeline, because a template that arrives through Use this template gives you a fork with the author's structure, and the SEO and geo audit scripts, the sidebar generator and the theme configuration are the author's code that you then have to read before you can change safely. The second is anyone who wants a plugin-rich site, since the dev dependency list is a fixed set: the MathJax source package, the Vite bundler, the Docsearch, feed and Google Analytics plugins, slimsearch, the Waline client, artplayer, cpx2, dashjs, gray-matter, hls.js, markdownlint-cli, Prettier, sass-embedded, Vue and the theme. That covers a text knowledge base well and a media-heavy site less so. The third is a project that does not want a Chinese-inspired theme at all, since the design is a deliberate aesthetic choice rather than a neutral default. Against building a plain VuePress site by hand, the difference in approach is that LearnData hands you a working site with the awkward parts already solved, the sidebar generated from files, the reading notes split out, the search wired, the comments installed and the deployment pipeline running, at the price of inheriting a configuration set you did not write and have to learn before you can change it.

## Conclusion

LearnData is a good fit for a writer who keeps notes in Markdown and wants a public knowledge base with a blog attached, and for anyone who wants a working site without installing Node, because the documented setup path is entirely inside the GitHub web interface. It is a poor fit for a team that needs content ownership outside the template author, and a poor fit if you want a plugin ecosystem beyond what the theme already wires up. Check three things before you start: that you are happy with pnpm 12, which the package.json pins as the package manager and which the README says is required to avoid an ERR_PNPM_IGNORED_BUILDS error, that you will set the repository name to your username.github.io if you want the site at the root of your pages domain, and that you decide early whether the reading notes belong inside the main site, because the Docsify section is a separate site with its own search index and the README explains the reading notes are moved out specifically because they contain long quotations that do not fit the template's minimal style.

## FAQ

### What is LearnData?

It is an open source note template built on VuePress and vuepress-theme-hope that aggregates notes and articles into a shareable personal knowledge base, with a separate Docsify-based reading-notes site, local full-text search, and one-click deployment to GitHub Pages or Vercel through GitHub Actions.

### How do I deploy a LearnData site?

Create your repository with the Use this template button, enable Read and write permissions under Settings, Actions and General, re-run the latest workflow from the Actions tab to create the gh-pages branch, then set gh-pages as the source branch in Settings and Pages. The whole process happens in the GitHub web interface with no local environment needed.

### What does LearnData need to run locally?

Node and pnpm 12, because the root pnpm-workspace.yaml approves the esbuild and @parcel/watcher build scripts and the packageManager field in package.json pins pnpm 12. Then run pnpm i and pnpm docs:dev, which serves the site at http://localhost:8080/.

### Why are the reading notes hosted separately from the main site?

Reading notes contain large amounts of quoted source text, which does not fit the template's minimal style, so they are built with Docsify and kept apart from the main VuePress site, forming two independent search systems. The notes live in src/reading, are copied rather than converted, and their sidebar link must be an absolute URL because Docsify does not support relative links.

### What search and comment options does LearnData include?

Search is local by default through the slimsearch plugin, and Algolia DocSearch can be used instead by uncommenting the docsearch block in the theme configuration, the two being alternatives. Comments use Giscus on the main site and Waline on the reading notes, both with reading statistics.

## Sources

- [Issues](https://github.com/rockbenben/LearnData/issues)
- [Project website](https://newzone.top)
- [README](https://github.com/rockbenben/LearnData/blob/main/README.md)
- [Releases](https://github.com/rockbenben/LearnData/releases)
- [rockbenben/LearnData on GitHub](https://github.com/rockbenben/LearnData)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rockbenben-learndata