How the Japanese ML/AI Vocabulary Site Works

This project is a bilingual glossary built as a static Jekyll site. It combines hand-authored topic articles with a small SQLite vocabulary cache and a set of local authoring tools. The resulting website consists only of HTML, CSS, images, and links: it does not need an application server or a database connection after it has been built.

Architecture at a glance

JSON term seeds ──> SQLite vocabulary cache
                            │
                  ┌─────────┴──────────┐
                  ▼                    ▼
          Topic-page tools       Index generator
                  │                    │
                  ▼                    ▼
          Markdown topics       Markdown indices
                  └─────────┬──────────┘
                            ▼
Navigation data + Liquid layouts + SCSS ──> Jekyll ──> Static website

There are therefore two related pipelines:

The content pipeline maintains consistent bilingual terminology and produces Markdown.
The Jekyll pipeline converts that Markdown and the shared layouts into the published static site.

The published site is static

Jekyll is the site’s rendering engine. Its configuration in _config.yml declares _topics/ as a collection and assigns every member of that collection the topic layout. A source file such as _topics/supervised-learning.md consequently becomes a page such as /topics/supervised-learning/.

Jekyll combines four kinds of source material:

Markdown supplies the articles and index content.
YAML front matter supplies titles, categories, ordering, and permanent URLs.
Liquid templates assemble repeated page structure and internal URLs.
SCSS and image assets provide the Hanamaru visual design.

Running bundle exec jekyll build writes the final website to _site/. That generated folder is deliberately not committed, so it has no repository link: it is a build product rather than an authoring source. A host such as GitHub Pages can serve its equivalent output without running Python or SQLite for visitors.

Topic pages

Each file in _topics/ represents one subject. Its front matter contains the information Jekyll needs to organize it:

---
title: Supervised Learning
japanese: <ruby>教師<rt>きょうし</rt></ruby>あり<ruby>学習<rt>がくしゅう</rt></ruby>
category: core
category_title: Core Machine Learning Topics
order: 1
---

The body contains an introductory explanation, a numbered bilingual glossary, and related topics. Links to other subjects use Jekyll’s relative_url filter, so they remain valid if the site is later hosted below a URL prefix.

The shared _layouts/topic.html template wraps every article with:

a link back to its homepage category;
the English and Japanese titles;
a GitHub repository link;
an optional contribution notice for pages marked as stubs; and
the article content itself.

That layout then inherits _layouts/default.html, which supplies the document shell, metadata, header navigation, Hanamaru logo, stylesheet, and footer. This two-level layout structure keeps topic files focused on vocabulary rather than repeated presentation markup.

Homepage organization

The homepage is generated from both index.md and _data/navigation.yml. The YAML file defines the three high-level sections—core topics, advanced topics, and ethics and applications. For each section, Liquid selects topic documents with the matching category, sorts them by order, and renders a linked card.

This means adding a correctly configured file to _topics/ is enough to make it appear in the appropriate homepage section. There is no separate list of individual topic URLs to maintain.

The vocabulary cache

data/vocabulary.sqlite3 is the reusable source of truth for individual glossary terms during authoring. It exists to prevent the English name, Japanese rendering, reading, explanation, and Wikipedia link from drifting when the same term appears in more than one article.

The terms table stores:

a stable slug and English term;
Japanese display HTML containing <ruby> readings;
a plain-kana reading used for sorting;
a concise English explanation;
the most appropriate English Wikipedia URL; and
a usage count.

The topic_terms table is the many-to-many relationship between topics and terms. Each association records whether a term is the main subject, part of the explanation, or a related concept, as well as its display position. SQLite triggers update usage_count when an association is inserted or deleted.

The database is deliberately excluded from the generated website by _config.yml. Jekyll does not query it, and a browser never downloads it. Instead, it supports consistent content before the static build begins.

Seed data and maintenance tools

The JSON files in data/ are reviewable input bundles used to add or update groups of terms and topic associations. data/wikipedia-links.json is a bulk mapping for external reference links.

The local ml-vocabulary-page skill describes the editorial workflow. Its vocab_cache.py tool can:

initialize or update the cache;
look up an existing term;
load reviewed JSON term bundles;
associate terms with a topic;
render a numbered glossary;
render batches of topic pages; and
validate a topic page against its cached records.

The workflow queries the cache before a definition is written. Existing definitions are reused when appropriate, while corrections are made centrally and then propagated to the relevant generated content.

English and Japanese indices

The two index pages are generated by generate_indices.py from the same SQLite cache.

The English index groups terms alphabetically by their English names. The Japanese index normalizes readings to hiragana, groups them by the Japanese syllabary, and sorts entries by reading. Both indices include the translation, explanation, Wikipedia reference, usage count, and links to every associated topic page.

The generated files, english-index.md and japanese-index.md, are normal Jekyll pages. They are committed as readable Markdown/HTML and rebuilt along with the rest of the site.

Japanese readings

Japanese kanji are annotated with semantic HTML ruby markup:

<ruby>機械学習<rt>きかいがくしゅう</rt></ruby>

Browsers display the <rt> text as a reading above the base Japanese text. The japanese-ruby-readings local skill defines the project’s markup rules, and its convert_ruby.py utility can convert explicit reading notation or audit files for kanji that remain outside <ruby> elements.

This validation is part of content quality rather than runtime behavior. Once Jekyll has built the page, ruby rendering is handled natively by the browser.

Links and references

The site distinguishes between two kinds of links:

A mention of a documented subject links to its local topic page, keeping readers inside the learning path.
The first reference for a definition links to the most appropriate English Wikipedia article for broader background.

Wikipedia links use a dotted underline and a small external-link arrow rather than bold type. This keeps Japanese character shapes easy to read while still making the destination clear. Topic pages also inherit a GitHub symbol from their layout so readers can reach the source repository.

Presentation layer

assets/css/style.scss contains the complete presentation layer. Jekyll compiles it to CSS during the build. The design tokens at the top of the file define the Hanamaru palette, including leaf and forest greens, moss, charcoal, pale green, and warm white.

The stylesheet provides responsive treatments for the header, hero, topic cards, article containers, notices, indices, ruby text, links, and mobile layouts. assets/images/hanamaru-logo.png is used in the site header, homepage hero, and browser icon metadata.

No JavaScript is currently required. Navigation, responsive layout, ruby annotations, and the glossary itself all work with HTML and CSS alone.

End-to-end authoring flow

A typical content change follows this sequence:

Research or select the topic and the technical terms its introduction uses.
Look up each term in the SQLite cache and reuse or update its bilingual record.
Associate the terms with the topic, including genuinely useful related concepts.
Render or edit the topic Markdown page.
Regenerate the English and Japanese indices if cached terms or associations changed.
Validate the topic against SQLite and audit Japanese text for ruby readings.
Run the Jekyll build.
Publish the resulting static site through GitHub Pages or another static host.

This separation gives the project the consistency of a small content database while retaining the simplicity, portability, and low operating cost of a static website.