# jimmylv.github.io treats a blog as the front end of a personal learning system

> This repository is a Chinese-language writing and knowledge base where GitHub issues act as a backlog, the markdown is linted and formatted on commit, and the site is published twice from one source. It is a personal system rather than a reusable framework, and the README documents it as such.

**JimmyLv/jimmylv.github.io** — :bowtie: Agile Learning based on GitHub issues, KEEP Retrospection and Introspection! Thanks to @GitHub https://jimmylv.github.io/issues/

- Repository: https://github.com/JimmyLv/jimmylv.github.io
- Website: https://blog.jimmylv.info
- Stars: 729 · Forks: 114
- Language: Unknown
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/jimmylv-jimmylv-github-io

## Issues as the backlog for a personal knowledge base

The repository description sets out the idea in one line: agile learning based on GitHub issues, keep retrospection and introspection. The README title and its links point at the project's issue tracker rather than at a feature list, and the badges at the top track exactly that: an imdone board badge for the TODO board, a GitHub issues badge, a badge counting closed issues, and a build badge for a jekyll-build workflow.

Counting closed issues is the detail that reveals the method. If closing an issue is how a piece of learning is retired, then the issue tracker becomes a record of what was learned, not just a place to report bugs. The issues are linked from the README as the primary artefact of the project.

The content itself is written in Chinese, organised into topic directories at the root of the repository, one for columns, one for front-end work, one for thoughts, one for talks, one for life and one for programming. Alongside them sit the pieces a static site needs: Home.md, About.md, a sidebar and a footer partial, an index.html, an images folder, and an Excalidraw folder for diagrams. There is also an .obsidian directory, which shows the notes are authored in Obsidian, and a .textlintrc.js plus a .prettierrc for the text toolchain.

The intended user is the author, and by extension anyone who wants to run the same personal system: write publicly, keep a backlog of things to learn, and treat the archive as the output. The licence is MIT, recorded in LICENSE.txt and checked by a FOSSA badge.

## One repository of posts, everything else split out

The README documents a structural change under a heading that announces a big change, moved to a distributed GitHub repo. After the move, the repository records only ideas and posts, and other features are supported by separate individual repositories named with a common prefix so they read as one namespace.

The stated benefit of the distributed layout is that the repository can be used as a git submodule of other repos, which the author says makes things more flexible and life easier. That is a real engineering argument rather than a slogan. A notes repository that can be pulled into other projects as a submodule becomes a dependency rather than an archive, and the content stays in one place while the code that consumes it lives elsewhere.

The APIs are handled the same way. A separate repository, JimmyLv/api, is used to generate a JSON result that is published under the site, so the data side is a different project with its own releases and its own lifecycle.

The slides follow the pattern too. The author still uses nodeppt to generate the final slide files, which are published on a separate subdomain, and the package.json carries that as a script alongside the lint and format commands. So the repository is the text, and the API, the slides and the blog engines are separate pieces that consume it.

## Four blog engines over one set of markdown files

The blog section of the README is a checklist of the various ways the same content has been published, and it reads as a record of decisions taken and abandoned.

The default is a Jekyll version in a separate repository, and it is the one published on the main blog domain. A Hexo version is listed as another alternative, chosen because it plays easily with Node.js, and it is marked as not yet done. A React version called Haiku invokes the raw markdown files from the GitHub repository, which lets the frontend be deployed separately from the content. An Angular 1.5x version exists but the README is blunt about it: it was created for the frontend and then given up because of AngularJS. A GitBook version, for generating an e-book by putting the markdown files together, is also still to do.

This is the most transferable idea in the repository, and also the one with the highest cost. Running the same content through several generators guarantees you can move away from any one of them, but every generator becomes a thing to keep working, and the abandoned Angular attempt shows what happens when one of them stops being worth the effort.

The README is careful about how it describes the Jekyll setup: vercel builds with jekyll, so it is easy and needs no configuration and works whatever repo you are in. That claim of configuration-free deployment is the reason a second host could be added later.

## Prettier and textlint run before anything is committed

The package.json is small but it is where the discipline is defined. The scripts are three commands:

```json
    "format": "prettier --write **/*.md",
    "lint": "textlint **/*.md",
    "lint:fix": "yarn lint --fix",
```

Formatting and linting are separated deliberately. Prettier is the formatter and rewrites the markdown, textlint is the linter and reports problems, and the fix variant applies the corrections. The lint-staged configuration then runs the linter on staged markdown files only:

```json
    "*.md": [
      "textlint --fix",
      "git add"
    ]
```

The second entry, git add, is there because linting rewrote the files and the corrected versions have to be staged again for the commit to contain them.

The husky configuration installs two git hooks:

```json
      "post-commit": "git update-index --again",
      "pre-commit": "pretty-quick --staged && lint-staged"
```

The pre-commit hook runs pretty-quick over the staged files and then lint-staged, and the post-commit hook refreshes the index, which is what makes the corrected files part of the commit that was just created. The result is that a badly formatted or badly worded file never reaches the history, without anyone remembering to run a command.

Two of the textlint rules are worth a look before copying the setup. One is a no-todo rule, which fits a system built around finishing things, and the other is a rule about spacing between half-width and full-width characters, which matters for Japanese text. Both are the kind of choice you would want to revisit for your own writing.

## Two hosts, one source, and a webhook in between

The CI/CD section is short and describes a deliberate choice. A GitHub Action, the deploy workflow, uses a webhook to trigger a Vercel build and deploy automatically, and the README explains that vercel builds with jekyll so it is easy and needs no configuration whatever repository you are in.

The site is then hosted in two places, on Vercel at the blog address and on GitHub Pages at the pages address. The netlify badge in the header suggests Netlify was used at some point as well, though the README now points at Vercel.

Publishing to two hosts is a redundancy decision rather than a performance one, and it is common for personal sites where a single provider outage would otherwise take down an archive that people link to. The cost is that two deployment paths have to keep working, and the GitHub Pages build is the one you have to maintain yourself.

Dependency upkeep is automated separately. A renovate.json file at the root means version bumps for the development dependencies are proposed rather than done by hand, which suits a repository where the toolchain is small and the dependencies are all in the devDependencies section.

The last push was on 2026-09-17 and the repository is not archived. There are no GitHub releases, which is what you would expect for a site that is deployed from a branch rather than packaged as software.

## The tooling around the writing

A few supporting pieces sit outside the core idea but explain how the work actually gets done.

The slides are generated with nodeppt from the talks directory into a slides directory, with the -a flag, and are published on their own subdomain. nodeppt is in the devDependencies at version 1.4.5, and the same command appears as a script in package.json, so the slide build is a single command like any other.

The related tools list at the end of the README is the author's working environment: a full IDE, a text editor, a terminal emulator and a documentation lookup tool. That is a short, honest list rather than a curated set of recommendations.

The repository also carries the usual governance files in .github, and the presence of a code of conduct is not implied but the directory exists in the root listing along with the workflows.

None of this is complicated, and that is the point of describing it. Each tool has one job: an issue tracker for the backlog, a formatter and a linter for the prose, a hook to run them, a generator for the site, a script for the slides, and two hosts to serve the result. The value of the system is in that the steps are wired together rather than in any single component.

## Where this repository is the wrong tool

The first wrong case is expecting a general purpose site generator. The repository is a personal knowledge base with topic directories named after the author's interests, a home page and about page, a sidebar and footer, and an index.html. There is no configuration for your own navigation, no theme of its own, and no documented way to add a section beyond editing the sidebar and creating a directory. Forking it gives you the author's archive, not a starter.

The second wrong case is the toolchain assumptions. The lint rules are tuned for the author's writing, including a rule about Japanese spacing and a rule that forbids TODO markers, which would fight anyone writing in English or keeping tasks in the document. The husky setup pins pretty-quick and lint-staged at versions from the era when the repository was written, and the pre-commit and post-commit hook pair depends on git behaving in a particular way.

The third is the language and the domain. The content is in Chinese and the topics are personal: personal knowledge management, writing environments, productivity on macOS, reading trackers. Someone who wants the same mechanics in a different language or a different field will spend most of their effort translating the rules and the structure rather than reusing them.

The realistic alternative is a plain static site generator plus a linter, configured in an afternoon: the same idea of a repository as the source of truth, a pre-commit hook that formats and lints, and a deployment on whichever host you already use. What this repository adds is a decade of accumulated decisions, and those are worth reading for the reasoning rather than copying for the code.

## Conclusion

Adopt the pattern rather than the repository if you want a writing system in which issues are the backlog, linting is automatic on commit, and the same markdown is published from two hosts. Do not fork this repository expecting a general purpose static site generator, because it is a personal knowledge base with topic directories, a slide deck tool and a plugin specific to the author's own workflow. Before copying anything, read the package.json scripts and the husky hooks, note that the lint rules include a no-todo rule and a Japanese spacing rule that you will probably want to change, and remember that the repository is MIT licensed with no releases, so there is no version to pin.

## FAQ

### What is jimmylv.github.io?

It is a personal knowledge base and blog repository, MIT licensed, where the writing lives in topic directories at the root of the repository and the project's GitHub issues are used as the learning backlog. The site is published from the same markdown through several generators.

### How does jimmylv.github.io lint and format its markdown?

Prettier formats the markdown and textlint lints it, with separate format, lint and lint:fix scripts in package.json. Husky hooks run pretty-quick and lint-staged before a commit and refresh the index afterwards, so corrections are committed with the change.

### Where is the jimmylv.github.io site hosted?

The README lists hosting on Vercel at the blog address and on GitHub Pages at the pages address. A GitHub Action uses a webhook to trigger the Vercel build and deploy automatically, and Vercel builds with jekyll.

### Why was jimmylv.github.io split into separate repositories?

The README explains that after the move the repository records only ideas and posts, with other features supported by separate repositories sharing a common name prefix. The stated benefit is that this repository can then be used as a git submodule of other projects.

### Which blog engines does jimmylv.github.io support?

The README lists a Jekyll version as the default and published site, a Hexo version and a GitBook version that are still to do, a React version that reads raw markdown from the repository, and an Angular 1.5x version that was given up because of AngularJS.

## Sources

- [Issues](https://github.com/JimmyLv/jimmylv.github.io/issues)
- [JimmyLv/jimmylv.github.io on GitHub](https://github.com/JimmyLv/jimmylv.github.io)
- [License: MIT](https://github.com/JimmyLv/jimmylv.github.io/blob/master/LICENSE)
- [Project website](https://blog.jimmylv.info)
- [README](https://github.com/JimmyLv/jimmylv.github.io/blob/master/README.md)

---

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