hexo-bilibili-bangumi: a tracking page for a Hexo blog, with four data sources

What the plugin does

The plugin's job is to add a watchlist page to a Hexo blog. The description in the repository is a Hexo anime page plugin with selectable data sources, and the README's summary is to add a tracking page for anime and television series to a Hexo blog.

What makes it more than a static list is the data sources. The feature list names Bilibili, Bangumi, AniList and Simkl, and the configuration reference spells out the source identifiers. bili is the Bilibili source, bgmv0 is the Bgm API at api.bgm.tv, bangumi is the Bangumi source at bangumi.tv, bgm is the Bangumi source at bgm.tv, anilist is AniList, and simkl is Simkl.

Two of those are worth pausing on, because they show how the plugin handles the difference between an account and a database. Bilibili and AniList are account-based: you log in, you get a user id, and the API returns that account's list. Bangumi and the Bgm API are database-based: they hold the catalogue of series, and the data is fetched per title. That is why the configuration has a separate bgmInfoSource setting for the Bangumi information source, with the Bangumi API and a Bangumi-Subject project as the two options, and why some settings are marked as only supported by particular sources.

The game section is a third category, and it is the most restricted. The configuration notes that the game settings support only the source bgmv0, which makes sense since a game tracker is a list of titles against a database, and there is no per-account game list on the Bilibili side.

The remaining feature list is about presentation and behaviour. Custom styling, image lazy loading, progress display, automatic data updating, responsive design, image mirror caching, and manual data entry.

The primary language is JavaScript, the licence is Apache-2.0, the default branch is master, and the homepage is a Vercel deployment hosting an effect preview. The recent releases are 2.1.9 and 2.1.8 from 2026-08-05 and 2.1.7 from 2026-06-14, and the last push was on 2026-10-20 with the project not archived. The npm package is published under the same name, hexo-bilibili-bangumi.

Installing it, and the three sections it adds

Installation is a single npm install into the blog project:

npm install hexo-bilibili-bangumi --save

After that the plugin adds three separate sections, each configured under its own key in the site's configuration file.

The bangumi key is the anime tracking section. The cinema key is the television tracking section, with the same options: enable, source, path, vmid, title, quote, theme, show, lazyload, srcValue, swup, metaColor, color, webp, progress, progressBar, extraOrder, order, extra_options and coverMirror. And the game key is the games section, restricted to the bgmv0 source.

Each of the three has a path, a title and a quote, so you can produce three separate pages, or disable two of them and keep one. The path defaults to bangumis/index.html for the anime section, and the show setting decides which of the three states is displayed initially: 0 for want to watch, 1 for watching, 2 for watched.

The instruction about where the configuration goes is worth noting, because it is a common trip-up. The settings go in the site's own _config.yml, not in the theme's configuration file. Hexo separates site configuration from theme configuration, and this plugin is a site-level generator, so its options live at the site level.

The theme setting is more restricted than it looks. The value can be light, dark or auto, and auto follows the system preference, but the documentation notes that this only works for themes that implement dark mode through a data-theme="dark" attribute. That is a specific implementation detail, and a theme that switches modes some other way will not follow the system setting, so the choice is worth testing against your own theme rather than assuming.

There is a live preview of the result, and the README shows both a light and a dark screenshot, so you can see what the generated page looks like before configuring anything.

The build step, and why you run a command before generating

This is the part of the plugin that differs most from a normal Hexo generator, and it is the part that surprises people.

Before generating or deploying the blog, you have to update the tracking data. There are three commands, one per section: hexo bangumi -u to update the anime data, hexo cinema -u for television, and hexo game -u for games. And there is a matching set for deleting: hexo bangumi -d, hexo cinema -d and hexo game -d.

The commands are added to the Hexo CLI by the plugin, so they appear alongside hexo generate and hexo deploy. The update flag fetches from the source API and writes the data into the site, and the delete flag removes it again.

The reason this cannot be automatic is the Bilibili progress feature. When you use the bili source, the plugin can display your per-episode watch progress, and getting that requires your SESSDATA cookie, the session credential Bilibili sets in your browser when you log in. The command takes it as an argument:

hexo bangumi -u 'your_sessdata_here'

So the pipeline is: run the update command with your credential, then generate the site. In a CI setup this means the credential has to be a secret in the build environment, which is a real consideration for anyone automating a blog build, because a SESSDATA value in a build log is a session cookie for someone's account.

The alternative, and the one the plugin also supports, is manual data entry. You create a JSON file in the site's source/_data/ directory, named extra_bangumis.json for anime or extra_cinemas.json for television, and write the entries yourself.

The entry shape is a title, a type, an area, a cover image link, a total episode count, a link and a description, and the file holds an array whose name depends on the state: wantWatchExtra for want to watch, watchingExtra for watching, and watchedExtra for watched. The extraOrder setting then controls where manually added entries appear in the list, with 1 meaning they take priority.

So there are two ways to get data in, and the manual route needs no credential at all. For a static blog that is often the better option.

The options, grouped the way the documentation groups them

The parameter reference is organised into six groups, and the grouping is a good map of what the plugin is doing.

The basic group holds enable, source, path, vmid, title, quote and theme. Display control adds show, lazyload, srcValue, metaColor, color and swup. Image handling is webp and coverMirror. Progress display is progress, the bar shown while data is being fetched, and progressBar, the watch progress bar on the page itself, which is only supported for the bili and bgmv0 sources. Data handling is pagination, order, extraOrder, showMyComment and skipNsfw. And then proxy and extra_options.

Several of those defaults are worth explaining because they encode opinions.

The webp option defaults to true and is only supported for the Bilibili source, where it can substantially reduce image size. The lazyload option defaults to true, with the reason given plainly: it avoids a long first load. The srcValue option defaults to __image__, which is the placeholder in the src attribute, and the documented alternative is __loading__ for a loading image.

The showMyComment option displays personal comments and is only supported by the bgm and anilist sources. The skipNsfw option controls whether adult content is shown and is only supported by the bangumi source. The order option sorts by score, ascending or descending with a minus sign, and the pagination option is recommended when the number of series is large.

The swup option is for themes that use swup for page transitions, and it defaults to false because it requires theme support.

Two of the settings exist for network reasons rather than presentation ones. The proxy settings give a proxy host and port for the API calls, which matters for anyone whose network blocks or throttles these services. And the coverMirror option is a mirror service address for cover images, which the documentation says is for solving hotlink protection and cross-origin problems.

The mirror list is worth reading, because it shows the range of options. The Baidu mirror is listed with a 5MB limit, Weserv, a Xuehua mirror, and a Naver mirror. All of them work by taking the original image URL as a query parameter, so the plugin can rewrite the URL of every cover it renders.

The extra_options setting is an escape hatch. The documentation says the extended configuration is injected into the Hexo page variables, which means you can pass arbitrary data through to the template.

Getting the identifiers you need

The vmid setting is the account identifier, and how you get it depends on the source. The README documents each case.

For Bilibili, you log in to the site, visit your personal space page, and the number at the end of the URL is your UID. There is an important condition attached: the tracking list has to be set to public. That is not a detail of the plugin but of Bilibili's own privacy setting, and if your list is private the API returns nothing.

For Bangumi, the process is to log in, open the developer console with Ctrl + Shift + J, and run a snippet:

document.getElementById('header').getElementsByTagName('a')[0].getAttribute('href').split('/').at(-1)

That is a one-liner that reaches into the header of the page, takes the first link, reads its href and takes the last path segment. It is a slightly awkward approach, but it reflects how the site exposes the username in the page rather than in a settings screen.

For a Bangumi user id rather than a username, the console snippet is simpler:

CHOBITS_UID

CHOBITS_UID is a global variable the Bangumi frontend sets on the page, and reading it in the console gives the numeric id. The distinction matters because the two Bangumi sources, bangumi.tv and bgm.tv, are separate sites with separate accounts, and the plugin treats them as different sources for a reason.

So the identifier step is a small piece of friction at the start of the setup, and it is worth doing before you configure anything else, because a plugin with a wrong user id will quietly produce an empty page rather than an error.

The repository, and how the project is put together

The top-level listing is a Hexo plugin with a build step of its own, and the structure explains why.

There is index.js at the root, which is the plugin entry point and the package main. There is lib/ and src/, the source directories, and scripts/ holding the build scripts. Then a demo/ directory, which contains a complete Hexo site: a _config.yml, a package.json with its own lock file, a source/ directory, a vercel.json and a README. A working demo site in the repository is worth a lot for a plugin like this, because the configuration is fiddly and seeing a real _config.yml answers questions faster than the reference does.

The package manifest shows the build pipeline, and it is the interesting part. The build script runs three Node scripts in sequence: scripts/babel.js, scripts/cleancss.js and scripts/copy-pug.js. The lint script runs eslint --fix and then the puglint script, which uses glob-exec to find every pug template under src/lib/templates and run a pug lint over them.

So the templates are Pug rather than HTML, and there is a dedicated linter for them. The three build steps make sense together: Babel transpiles the source, clean-css processes the stylesheet, and copy-pug moves the templates into the published package. The published files list in the manifest includes lib, which is why there is a copy step rather than a compile step for the templates.

The puglint setup is a detail worth noting because it is the kind of thing that only shows up in a mature project. Template syntax errors are easy to make and hard to spot, and running a linter over every template as part of the test script means a broken template fails the build rather than producing a page with a missing block.

The dependencies are also revealing. axios for HTTP, cheerio for parsing HTML, which is how the plugin scrapes source pages rather than using only the JSON APIs, hexo-fs for file operations, hexo-log for logging, hexo-i18n for translations, and bangumi-data, which is a bundled dataset of series information.

The eslint config is a flat config at eslint.config.mjs, and there is a .github/ directory for workflows, an .npmignore alongside the .gitignore, and the two example images referenced from the README.

How to evaluate it, and the questions to ask first

There are four things to decide.

First, which data source. This is the decision with the most downstream consequences, because the sources are not interchangeable. The Bilibili source is the only one with watch progress, the only one with webp conversion, and the only one that needs a SESSDATA credential. The Bangumi and Bgm API sources are database-based and need no credential. AniList and Simkl are account-based with their own id schemes. And the documentation marks specific options as supported only by particular sources, so picking a source determines which features you can use.

Second, whether you want the build step in your pipeline. The plugin requires a command before hexo generate, and for a continuous deployment setup that means the SESSDATA value has to be available as a secret. If you would rather not have a session cookie anywhere near your build, use the manual data entry route with the extra_bangumis.json file in source/_data/, which needs no network access and no credential at all.

Third, how much of the configuration you actually want. There are around thirty options across three sections, and the full set is documented twice, once as a summary and once as a detailed reference inside a collapsed section. The most consequential are theme, because the auto setting only works with themes that use a data-theme attribute, and coverMirror, because without it a cover image may fail to load at all behind hotlink protection.

Fourth, the maintainership. The last push was on 2026-10-20 and there were releases in June and August, so the project is active. The version is 2.1.9, which is well past the point where a plugin's configuration tends to change shape, and the npm package, the GitHub repository and the demo site are all maintained by the same person.

What you get is a static site with a live tracking page that updates from an account you already have, which is a nice thing for an anime blog and a surprisingly common request. The cost is a build step and a configuration surface large enough that you should skim the reference before you start, and the plugin's own demo site is the fastest way to see the shape of a working setup.

Editorial conclusion

Adopt hexo-bilibili-bangumi if you run a static Hexo blog and want a live anime, television or game tracking page sourced from an account you already have, with theming, lazy loading and image mirroring rather than a hand-maintained list. Do not adopt it if you cannot add a build step before hexo generate, since the data is fetched by an explicit command rather than during the build, and be careful with the Bilibili source because it needs a SESSDATA session cookie, which then has to be handled as a secret in any automated pipeline. Before you commit, pick your data source first, because it decides which features are available, and if you would rather avoid the credential entirely, use the manual JSON entry route in source/_data/ instead, which needs no network access at all.

Frequently asked questions

Official sources

1. HCLonely/hexo-bilibili-bangumi on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases