{"id":26049560,"url":"https://github.com/darkmusic/hexojp-klc","last_synced_at":"2026-05-17T00:33:27.952Z","repository":{"id":192729162,"uuid":"686834088","full_name":"darkmusic/hexojp-klc","owner":"darkmusic","description":"Hexo-based blogging site that gradually introduces KLC kanji, providing kanji details and sample words using known kanji only","archived":false,"fork":false,"pushed_at":"2024-06-29T20:22:44.000Z","size":7698,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-29T21:30:54.154Z","etag":null,"topics":["blogging","hexo","japanese","kanji","klc","perl","postgresql"],"latest_commit_sha":null,"homepage":"","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darkmusic.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-04T03:27:24.000Z","updated_at":"2024-06-29T21:30:58.125Z","dependencies_parsed_at":null,"dependency_job_id":"b1a2f463-a7c6-4c30-a579-3662b99a3fdb","html_url":"https://github.com/darkmusic/hexojp-klc","commit_stats":{"total_commits":13,"total_committers":1,"mean_commits":13.0,"dds":0.0,"last_synced_commit":"74092d601e938fe88e4c19c0dca9f24d00dab7b1"},"previous_names":["darkmusic/hexojp-klc"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkmusic%2Fhexojp-klc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkmusic%2Fhexojp-klc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkmusic%2Fhexojp-klc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darkmusic%2Fhexojp-klc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darkmusic","download_url":"https://codeload.github.com/darkmusic/hexojp-klc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242487757,"owners_count":20136651,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blogging","hexo","japanese","kanji","klc","perl","postgresql"],"created_at":"2025-03-08T01:44:33.094Z","updated_at":"2026-05-17T00:33:27.945Z","avatar_url":"https://github.com/darkmusic.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hexo JP KLC\n\n## Hexo-Based Japanese KLC Practice Blogging\n\n## Overview\n\nThis 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.\n\n## Design\n\nEach 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.\n\nThe note generated displays each kanji, along with a brief description and readings. Sample words are also included that use only known kanji.\nIt is the task of the writer to construct some sentences that use these words, ideally in some sort of story. The story does not have to make sense; the idea is that it will help understand how these kanji and words are used in context. This will help build vocabulary and reinforce grammar, provided some time is spent verifying that the usage of the words is correct and the readings are appropriate.\nThere 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.\n\n## Daily Kanji with Meanings and On/Kun Readings\n\n![Main page showing readings](images/Readings.png)\n\n## Daily Random Selection of Words with Only Known Kanji\n\n![Main page showing words](images/Words.png)\n\n## User Story Section\n![User Story Section](images/UserStory.png)\n\n## Tech Stack: Host\n\n- [Arch Linux](https://archlinux.org/) or another flavor of Linux (or WSL if using Windows) is used as the base OS.\n- [Docker](https://www.docker.com/products/docker-desktop/) or [Rancher Desktop](https://rancherdesktop.io/) is used locally to host Postgresql.\n- [GNU Make](https://www.gnu.org/software/make/) is used as a command runner for development tasks.\n- [Node JS](https://nodejs.org/en) is used with [Hexo](https://hexo.io/index.html) to serve as a static website generator.\n- [Perl 5](https://www.perl.org) + [DBI](https://dbi.perl.org/) + [DBD::Pg](https://metacpan.org/pod/DBD::Pg) is used for DB scripts and daily page generation.\n\n## Tech Stack: DB Container\n\n- [Postgresql](https://www.postgresql.org/) is used for the DB backend (used for note creation only).\n\n## Suggested Linux/WSL Packages\n\n```shell\nopenssl rsync curl glibc git vi vim nano wget ninja cmake iproute2 python python-virtualenv \\\nlibpqxx unzip openssh man-db man-pages htop inetutils perl perl-dbi perl-dbd-pg perl-yaml-tiny \\\npostgresql nodejs npm icu expat make\n```\n\n## Windows Notes\n\n- If you are using Windows, it is recommended to use [WSL](https://docs.microsoft.com/en-us/windows/wsl/install) to run the commands in this readme.\n- If using WSL, it is recommended to use [ArchWSL](https://github.com/yuk7/ArchWSL) as a distribution, though others should work as well.\n\n## Initial one-time setup\n\n1. Clone this (or your) repository. Change URL as needed. `git clone https://github.com/darkmusic/hexojp-klc`\n1. Initialize submodules if needed. `git submodule update --init --recursive`\n1. Copy `db/config_template.yaml` to `db/config.yaml` and edit accordingly.\n1. Copy `_config_template.yml` to `_config.yml` and edit accordingly.\n1. Copy `settings_template.env` to `settings.env` and edit accordingly.\n1. Run `make init` to initialize the containers.\n1. Wait a bit for the containers to start up, especially the DB container as this needs to initialize the database and restart (5-10 seconds).\n1. Run `make db-restore` to restore the DB.\n\n## Perl module installation\n\nFirst-time setup requires Perl modules: `sudo apt install libdbi-perl libdbd-pg-perl libyaml-tiny-perl` or `cpan DBI DBD::Pg YAML::Tiny`.\n\n## Regular daily steps\n\n1. `make daily`\n2. Edit note as needed (under **source/\\_posts**).\n3. `make generate` (or `hexo generate`)\n4. `make server` (or `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)\n5. [View the site in a browser.](http://localhost:4000)\n\n## As needed\n\n- Edit \\_config.yml, then run `make generate`\n- Edit themes, then run `make generate`\n- Edit scaffolds, then run `make generate`\n- Edit db/config.yaml, then run `make generate`\n- Edit any post under source/\\_posts, then run `make generate`\n- Run `make docker-up` to start the docker container.\n- Run `make docker-stop` to stop the docker container.\n- Run `make docker-build` to pull the latest PostgreSQL image.\n- Run `make db-connect` to connect to the db container.\n- Run `make db-logs` to see the db container logs.\n- Run `make help` to see all available commands.\n\n## System Requirements\n\nWindows, Linux, or Mac should work.\n\n## Config\n\nThe config.yaml defaults should work fine. As-is, the defaults will include kanji 1-20 in the initial blog entry.\n\nBy 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.\nAfter creating the daily note, the **last_known_klc_num** will be incremented to 20.\n\nYou can always manually edit the **last_known_klc_num** if needed.\n\n```yaml\ndaily_study_number: 20\ndatabase: hexojp\nhost: localhost\nlast_known_klc_num: 0\nmax_words: 50\npassword: hexojpadmin\nport: 5432\nuserid: hexojpadmin\n```\n\n## Using submodules for themes\n\nIt can be convenient to use submodules for themes.\n\nFor example:\n\n```shell\ncd themes\ngit submodule add https://github.com/xbmlz/hexo-theme-maple.git\nmake generate\nmake server\n```\n\nWith 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.\n\n## Responsive column display configuration\n\nWhen only using a single column to display the kanji cards, it requires a lot of vertical scrolling. To improve usability, you can configure the kanji grid to use multiple columns based on screen size.\nThe *.styl file for configuring this will depend on the theme you are using. For example, for **hexo-theme-aero-dual**, edit `themes/hexo-theme-aero-dual/source/css/_base.styl`.\nYou can use the following code to create a responsive kanji grid that adjusts the number of columns based on the screen size:\n\n```stylus\n.kanji-grid\n  display grid\n  gap 2rem\n  margin 2rem 0\n\n  // Mobile: 1 column\n  grid-template-columns 1fr\n\n  // Tablet: 2 columns\n  @media (min-width: 768px)\n    grid-template-columns repeat(2, 1fr)\n\n  // Desktop: 3 columns\n  @media (min-width: 1024px)\n    grid-template-columns repeat(3, 1fr)\n\n  // Large desktop: 4 columns\n  @media (min-width: 1440px)\n    grid-template-columns repeat(4, 1fr)\n\n.kanji-card\n  border 1px solid rgba(0, 0, 0, 0.1)\n  padding 1.5rem\n  border-radius 8px\n  background-color rgba(255, 255, 255, 0.05)\n  transition all 0.3s ease\n\n  \u0026:hover\n    box-shadow 0 4px 12px rgba(0, 0, 0, 0.15)\n    transform translateY(-2px)\n\n  h2\n    margin-top 0\n    font-size 2rem\n    color $theme-text-color\n    border-bottom 2px solid $theme-color\n    padding-bottom 0.5rem\n    margin-bottom 1rem\n\n  strong\n    color $theme-color\n\n.kanji-word\n  grid-column 1 / -1\n  padding 1.5rem\n  border-radius 8px\n  background-color rgba(255, 255, 255, 0.03)\n  margin 1rem 0\n```\n\nIf the theme instead uses standard CSS files, you can use the following CSS code:\n\n```css\n.kanji-grid {\n  display: grid;\n  gap: 2rem;\n  margin: 2rem 0;\n  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));\n}\n.kanji-card {\n  border: 1px solid rgba(0, 0, 0, 0.1);\n  padding: 1.5rem;\n  border-radius: 8px;\n  background-color: rgba(255, 255, 255, 0.05);\n  transition: all 0.3s ease;\n}\n.kanji-card:hover {\n  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);\n  transform: translateY(-2px);\n}\n.kanji-card h2 {\n  margin-top: 0;\n  font-size: 2rem;\n  color: var(--theme-text-color);\n  border-bottom: 2px solid var(--theme-color);\n  padding-bottom: 0.5rem;\n  margin-bottom: 1rem;\n}\n.kanji-card strong {\n  color: var(--theme-color);\n}\n.kanji-word {\n  grid-column: 1 / -1;\n  padding: 1.5rem;\n  border-radius: 8px;\n  background-color: rgba(255, 255, 255, 0.03);\n  margin: 1rem 0;\n}\n```\n\n## Example for adding a theme and dealing with theme-related issues\n\nUsing [hexo-theme-clean-dark](https://github.com/howardliu-cn/hexo-theme-clean-dark) as an example, do the following:\n\n1. Add submodule to themes directory\n\n```shell\ncd themes\ngit submodule add https://github.com/howardliu-cn/hexo-theme-clean-dark\n```\n\n1. Read installation notes at [the theme repo](https://github.com/howardliu-cn/hexo-theme-clean-dark). 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](https://translate.google.com/?sl=zh-CN\u0026tl=en\u0026op=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](https://github-com.translate.goog/howardliu-cn/hexo-theme-clean-dark?_x_tr_sl=zh-CN\u0026_x_tr_tl=en\u0026_x_tr_hl=en\u0026_x_tr_pto=wapp).\n\nIn this particular theme repository, there is the next step of adding a NPM dependency. This can be done by doing the following:\n\n```shell\nnpm install --save hexo-renderer-sass\nexit\n```\n\n1. Edit themes/\\_config.yml to change the theme (in this case to hexo-theme-clean-dark).\n1. Edit the theme's config.yml (in this case themes/hexo-theme-clean-dark/\\_config.yml) as needed according to the theme's readme.\n1. Generate:\n   ```shell\n   make generate\n   ```\n1. If you encounter an error about the `strip-ansi` npm package, you may need to manually update `node_modules/hexo/dist/plugins/console/list/common.js` to replace _require_ with _import_.\n1. Take note of any other 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.\n   Example error:\n\n```shell\nERROR\nReferenceError: /home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/post.ejs:17\n    15|         \u003c/div\u003e\n    16|         \u003cdiv class=\"post-content article-entry\"\u003e\n \u003e\u003e 17|             \u003c!-- \u003c%- partial('_partial/toc') %\u003e --\u003e\n    18|             \u003c%- page.content %\u003e\n    19|         \u003c/div\u003e\n    20|         \u003c% if(page.tags){ %\u003e\n\n/home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/_partial/toc.ejs:1\n \u003e\u003e 1| \u003c% if (post.toc != false) { %\u003e\n    2|     \u003cdiv id=\"toc\"\u003e\n    3|       \u003c%- toc(post.content, {list_number: false}) %\u003e\n    4|     \u003c/div\u003e\n\npost is not defined\n    at eval (\"/home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/_partial/toc.ejs\":10:8)\n    at toc (/home/hexojp/code/hexojp/node_modules/ejs/lib/ejs.js:703:17)\n    at _View._compiledSync (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:132:24)\n    at _View.renderSync (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:59:25)\n    at Object.partial (/home/hexojp/code/hexojp/node_modules/hexo/lib/plugins/helper/partial.js:34:15)\n    at eval (\"/home/hexojp/code/hexojp/themes/hexo-theme-clean-dark/layout/post.ejs\":25:17)\n    at post (/home/hexojp/code/hexojp/node_modules/ejs/lib/ejs.js:703:17)\n    at _View._compiled (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:136:50)\n    at _View.render (/home/hexojp/code/hexojp/node_modules/hexo/lib/theme/view.js:39:17)\n    at /home/hexojp/code/hexojp/node_modules/hexo/lib/hexo/index.js:64:21\n    at tryCatcher (/home/hexojp/code/hexojp/node_modules/bluebird/js/release/util.js:16:23)\n    at /home/hexojp/code/hexojp/node_modules/bluebird/js/release/method.js:15:34\n    at RouteStream._read (/home/hexojp/code/hexojp/node_modules/hexo/lib/hexo/router.js:47:5)\n    at Readable.read (node:internal/streams/readable:737:12)\n    at resume_ (node:internal/streams/readable:1255:12)\n    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)\n```\n\nThis 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.\n\nNote that you may get deprecation warnings like the following:\n\n```shell\nDeprecation Warning: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.\n\nRecommendation: math.div(30em, 14) or calc(30em / 14)\n\nMore info and automated migrator: https://sass-lang.com/d/slash-div\n\n   ╷\n12 │ $fa-li-width:         (30em / 14) !default;\n   │                        ^^^^^^^^^\n   ╵\n    themes/hexo-theme-clean-dark/source/css/font-awesome/scss/_variables.scss 12:24  @import\n    themes/hexo-theme-clean-dark/source/css/font-awesome/scss/font-awesome.scss 6:9  root stylesheet\n```\n\nThis is a sass warning, which is actually quite detailed and gives you suggestions on how to fix this.\n\nIt's optional to fix these, but if you know how to, I would recommend it as it cleans up these warnings.\n\nIn 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)**.\n\nContinue once you have reduced or eliminated all errors and warnings.\n\n1. Start server\n\n```shell\nmake server\n```\n\n1. Check the [website](http://localhost:4000) to see if any updates are needed.\n\nYou 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.\n\nFor 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.\n\nEven 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.\n\nEven 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.\n\n- In theme_scss:\n\n  - .footer:\n\n    - add:\n\n      ```css\n      height: 50px;\n      ```\n\n  - .well.post-nav.a:\n\n    - Comment out \"float: left\"\n\n      ```css\n      //float: left;\n      ```\n\n  - nav.a:\n\n    - add:\n\n      ```css\n      padding-left: 5px;\n      padding-right: 5px;\n      ```\n\n    - Change font-family to:\n\n      ```css\n      font-family: ubuntu, icomoon, \"Segoe UI\", Tahoma, Geneva, Verdana,\n        sans-serif;\n      ```\n\n  - navbar .navbar-nav:\n\n    - change display to:\n\n      ```css\n      display: flex;\n      ```\n\n    - Comment out \"float: left\"\n\n      ```css\n      //float: left;\n      ```\n\n    - add flex-direction: row\n\n      ```css\n      flex-direction: row;\n      ```\n\n  - .content:\n\n    - add:\n\n      ```css\n      padding-left: 50px;\n      padding-right: 50px;\n      ```\n\n## Other notes\n\n- To re-generate a daily note, you'll need to delete the post and then run the `make daily` task again:\n\n```shell\nrm source/_posts/05-05-2025.md\nmake daily\n```\n\n- The DB contains kanji imported from [KANJIDIC](http://www.edrdg.org/wiki/index.php/KANJIDIC_Project) using [KanjiDicParser](https://github.com/WinteryFox/KanjidicParser), and words imported from [EDICT](http://www.edrdg.org/jmdict/edict.html). A list of 2300 KLC kanji was used to number the KLC kanji in the DB.\n- 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.\n- The character 〇 (KLC 14) is ignored, as it is not a kanji.\n- The Hexo theme is configurable. See: [Hexo Themes](https://hexo.io/themes/index.html). 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.\n- The initial DB import may get a tablespace error. You may need to edit dockerfiles/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 `make 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkmusic%2Fhexojp-klc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkmusic%2Fhexojp-klc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkmusic%2Fhexojp-klc/lists"}