Hexo JP KLC

Hexo-Based Japanese KLC Practice Blogging

Overview

This project is designed for studying the KLC list of kanji by introducing a fixed number of kanji per blog entry and encouraging the creation of sentences that use a a selection of words gathered from all "known" kanji.

Design

Each blog entry will introduce a fixed number of kanji from the KLC list, in order introduced in the KLC book. The last known kanji number is stored in config.yaml. The daily script increments this number and fetches the daily kanji and a selection of words that use all known kanji, including the new kanji for today.

The note generated displays each kanji, along with a brief description and readings. Sample words are also included that use only known kanji and kana. It is the task of the writer to construct some sentences that use these words, ideally in some sort of story. This will help build vocabulary and reinforce grammar. There is no time limit to finishing a blog post, so each entry does not have to be daily. But in the interest of learning 2300 kanji, it is recommended to write a blog entry at least a few times a week.

Daily Kanji with Meanings and On/Kun Readings

Daily Random Selection of Words with Only Known Kanji and Kana

Tech Stack: Host

• Arch Linux or another flavor of Linux (or WSL if using Windows) is used as the base OS.
• Docker or Rancher Desktop is used locally to host Postgresql.
• Just is used as a command runner for development tasks.
• Node JS is used with Hexo to serve as a static website generator.
• Perl 5 + DBI + DBD::Pg is used for DB scripts and daily page generation.
• Just is used as a command runner.

Tech Stack: DB Container

• Postgresql is used for the DB backend (used for note creation only).

Suggested Linux/WSL Packages

openssl rsync curl glibc git vi vim nano wget ninja cmake iproute2 python python-virtualenv \
libpqxx unzip openssh man-db man-pages htop inetutils perl perl-dbi perl-dbd-pg perl-yaml-tiny nodejs just \
postgresql nodejs npm icu expat

Windows Notes

• If you are using Windows, it is recommended to use WSL to run the commands in this readme.
• If using WSL, it is recommended to use ArchWSL as a distribution, though others should work as well.

Initial one-time setup

1. Clone this (or your) repository. Change URL as needed. git clone https://github.com/darkmusic/hexojp-klc
2. Initialize submodules if needed. git submodule update --init --recursive
3. Copy db/config_template.yaml to db/config.yaml and edit accordingly.
4. Edit _config.yml as needed.
5. Copy settings_template.env to settings.env and edit accordingly.
6. Run just init to initialize the containers.
7. Wait a bit for the containers to start up, especially the DB container as this needs to initialize the database and restart.
8. Run just db restore to restore the DB.

Regular daily steps

1. just daily
2. Edit note as needed (under source/_posts).
3. hexo generate
4. hexo server (Adjust port as needed by adding --port 4010 for example; recommended to run this under PowerShell / CMD on Windows, as WSL can have issues exposing ports)
5. View the site in a browser.

As needed

• Edit _config.yml, then run just generate
• Edit themes, then run just generate
• Edit scaffolds, then run just generate
• Edit db/config.yaml, then run just generate
• Edit any post under source/_posts, then run just generate
• Run just docker up to start the docker stack.
• Run just docker stop to stop the docker stack.
• Run just docker build to manually build the containers.
• Run just docker build_nocache to build the containers without using the cache.
• Run just db connect to connect to the db container.
• Run just db logs to see the db container logs.

System Requirements

Windows, Linux, or Mac should work.

Config

The config.yaml defaults should work fine. As-is, the defaults will include kanji 1-20 in the initial blog entry.

By default, this will start from last_known_klc_num + 1 (1), and end at start + daily_study_number (20). Only sample words containing these 20 kanji (and any kana) will be included. After creating the daily note, the last_known_klc_num will be incremented to 20.

You can always manually edit the last_known_klc_num if needed.

daily_study_number: 20
database: hexojp
host: localhost
last_known_klc_num: 0
max_words: 50
password: hexojpadmin
port: 5432
userid: hexojpadmin

Using submodules for themes

It can be convenient to use submodules for themes.

For example:

cd themes
git submodule add https://github.com/xbmlz/hexo-theme-maple.git
just generate
just server

With this, you can do a git add on your repository and it will add the submodule instead of adding everything inside the theme's folder. Also if you re-clone your repository from scratch, if you follow the instructions in the Initial one-time setup above, your themes will be downloaded automatically.

Example for adding a theme and dealing with theme-related issues

Using hexo-theme-clean-dark as an example, do the following:

1. Add submodule to themes directory

cd themes
git submodule add https://github.com/howardliu-cn/hexo-theme-clean-dark

1. Read installation notes at the theme repo. Note that this particular theme repo is in Chinese, but it is usually not required to know how to read Chinese even if the readme for the repo is entirely in Chinese. In this particular repo, there are steps listed where are pretty straightforward. Note that you can skip the "clone" step as you already added the submodule. If it's still to difficult to understand the repository readme, go to Google Translate - websites and enter the URL for the repository and translate to your desired language. For this example, the translated repository (from Simplified Chinese to English) is here.

In this particular theme repository, there is the next step of adding a NPM dependency. This can be done by doing the following:

npm install --save hexo-renderer-sass
exit

1. Edit themes/_config.yml to change the theme (in this case to hexo-theme-clean-dark).
2. Edit the theme's config.yml (in this case themes/hexo-theme-clean-dark/_config.yml) as needed according to the theme's readme.
3. Generate

just generate

1. Take note of any errors during the generation process and fix as needed. If you are not familiar or comfortable with troubleshooting such errors, it may be easier to pick a different theme. Example error:

ERROR
ReferenceError: /home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/post.ejs:17
    15|         </div>
    16|         <div class="post-content article-entry">
 >> 17|             <!-- <%- partial('_partial/toc') %> -->
    18|             <%- page.content %>
    19|         </div>
    20|         <% if(page.tags){ %>

/home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/_partial/toc.ejs:1
 >> 1| <% if (post.toc != false) { %>
    2|     <div id="toc">
    3|       <%- toc(post.content, {list_number: false}) %>
    4|     </div>

post is not defined
    at eval ("/home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/_partial/toc.ejs":10:8)
    at toc (/home/hexojp/code/hexojp/node_modules/ejs/lib/ejs.js:703:17)
    at _View._compiledSync (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:132:24)
    at _View.renderSync (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:59:25)
    at Object.partial (/home/hexojp/code/hexojp/node_modules/hexo/lib/plugins/helper/partial.js:34:15)
    at eval ("/home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/post.ejs":25:17)
    at post (/home/hexojp/code/hexojp/node_modules/ejs/lib/ejs.js:703:17)
    at _View._compiled (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:136:50)
    at _View.render (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:39:17)
    at /home/hexojp/code/hexojp/node_modules/hexo/lib/hexo/index.js:64:21
    at tryCatcher (/home/hexojp/code/hexojp/node_modules/bluebird/js/release/util.js:16:23)
    at /home/hexojp/code/hexojp/node_modules/bluebird/js/release/method.js:15:34
    at RouteStream._read (/home/hexojp/code/hexojp/node_modules/hexo/lib/hexo/router.js:47:5)
    at Readable.read (node:internal/streams/readable:737:12)
    at resume_ (node:internal/streams/readable:1255:12)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)

This one looks daunting, but is actually easy to fix. In themes/hexo-theme/clean/dark/layout/post.ejs, the commented-out block in line 17 is causing the issue, so just delete that line and do a sync, fix permissions, and generate to try again.

Note that you may get deprecation warnings like the following:

Deprecation Warning: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.

Recommendation: math.div(30em, 14) or calc(30em / 14)

More info and automated migrator: https://sass-lang.com/d/slash-div

   ╷
12 │ $fa-li-width:         (30em / 14) !default;
   │                        ^^^^^^^^^
   ╵
    themes/hexo-theme-clean-dark/source/css/font-awesome/scss/_variables.scss 12:24  @import
    themes/hexo-theme-clean-dark/source/css/font-awesome/scss/font-awesome.scss 6:9  root stylesheet

This is a sass warning, which is actually quite detailed and gives you suggestions on how to fix this.

It's optional to fix these, but if you know how to, I would recommend it as it cleans up these warnings.

In this case, these calculations need to happen inside a calc() block, so just add calc in front of the math operations that are mentioned. For example, (30em / 14) becomes calc(30em / 14).

Continue once you have reduced or eliminated all errors and warnings.

1. Start server

just server

1. Check the website to see if any updates are needed.

You may notice that the website does not look correct; perhaps the fonts don't look right, or things aren't aligned as expected. If you're not comfortable with adjusting CSS, then you may wish to find another theme.

For this example theme, below are some updates that I made to get things to look a bit more normal on my system. This is just an example of the types of updates you may need to make.

Even with this updates to the hexo-theme-clean-dark, it still doesn't look exactly like the theme repo's screenshot, and the fonts don't look the best, so your mileage may vary based on what updates you make (and the time you want to spend messing with CSS). This is the case with many Hexo themes - they don't work right or look right. This is not the direct fault of the repo owner because libraries (including NPM libraries such as hexo, sass etc.) and browser technologies (such as CSS) go through evolutions and sometimes significant changes that may break or cause issues with legacy websites. Many Hexo themes can be considered "legacy websites" in this case, because many have not been updated in several years and are unmaintained. So while these issues are not the direct fault of the repo owner, any issues with the theme should be reported to the repo owner so they are aware of the issue and can make fixes. But with many github repos, issues opened may sit eternally without being resolved, so oftentimes reporting github issues isn't helpful. It all depends on how responsive and active the repo owner is.

Even these example updates will become obsolete at some point once the CSS spec or SASS changes again, so just use this as a general guide for the types of updates you may need to make.

• In theme_scss:

  • .footer:

    • add:

      height: 50px;

  • .well.post-nav.a:

    • Comment out "float: left"

      //float: left;

  • nav.a:

    • add:

      padding-left: 5px;
      padding-right: 5px;

    • Change font-family to:

      font-family: ubuntu, icomoon, 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;

  • navbar .navbar-nav:

    • change display to:

      display: flex;

    • Comment out "float: left"

      //float: left;

    • add flex-direction: row

      flex-direction: row;

  • .content:

    • add:

          padding-left: 50px;
          padding-right: 50px;

Other notes

• To re-generate a daily note, you'll need to connect to the dev container and delete the post like doing the following:

rm source/_posts/05-05-2025.md
exit

and then run the just daily task again.

• The DB contains kanji imported from KANJIDIC using KanjiDicParser, and words imported from EDICT. A list of 2300 KLC kanji was used to number the KLC kanji in the DB.
• The db/daily.pl script has all of the logic for generating the daily note. This makes use of a procedure called add_matching_words to perform a regex match (using all known kanji) against the word table and populating a known_words table with results. It also queries other tables to retrieve kanji-specific information.
• The character 〇 (KLC 14) is ignored, as it is not a kanji.
• The Hexo theme is configurable. See: Hexo Themes. It should be noted that not all Hexo themes work properly, so you may have to adjust things or find another theme if you run into issues.
• The initial DB import may get a tablespace error. You may need to edit db/init-user-db.sh (where it says Tablespace for initial db import) to adjust the path. If you don't know what path to use, run just db connect and look around in the container (under /var/lib/postgresql/data/pg_tblspc/) and see what the folder is named, and adjust the script as needed. But currently there is a wildcard, so this may not be required.