Getting Started

For the purposes of this page, we will assume you are using a Debian based GNU/Linux distribution.

Installing Requirements

Kata Code requires a fairly recent version of Ruby. Chances are that your distribution does not provide this yet. Here we will spell out, step by step, how to get all requirements installed on your system.

First things first, make sure required packages are installed.

sudo apt install curl git ruby-build libffi-dev libyaml-dev

Clone the Kata Code template as your upstream repository to where you want to maintain your site. Let's call it info.

git clone --origin upstream https://codeberg.org/kata/code.git info
cd info

Next, install a recent version of the rbenv utility and use that to install the Ruby version required.

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
eval "$(rbenv init -)"          # add this to your ~/.bashrc as well
rbenv install "$(cat .ruby-version)"

Finally, install the Ruby gems that Kata Code needs to render your site and make the programs they include available.

bundler install
rbenv rehash

At this point you should be able to generate your site from the upstream template. Let's confirm that.

tailwindcss -i _includes/site.css -o assets/site.css
jekyll build

If all went well, your site can be found in the _site directory and can be browsed at http://localhost:4000 after you run

jekyll serve --host localhost --port 4000

Use Ctrl-c to abort the Jekyll server process.

Configuring Languages

Supported languages are configured in _config.yaml and default to en for English and ja for Japanese. Modify the list of languages to meet your needs and update the defaults to match. Let's say you don't need Japanese but want Korean and Vietnamese in addition to English. That would mean you need the following in _config.yaml.

defaults:
  [... elided ...]
  - scope:
      path: "*/en"
    values:
      lang: en
  - scope:
      path: "*/ko"
    values:
      lang: ko
  - scope:
      path: "*/vi"
    values:
      lang: vi

languages:
  - en
  - ko
  - vi

The language codes you can use are any of the valid values for the HTML lang attribute.

With that done, you still need to create directories for all of the languages you configured. So for the example above that would be

mkdir -p {_homes,_pages,_posts}/{en,ko,vi}

if you're using bash or zsh.

Adding Content

The Kata Code template comes with zero content. That results in a very boring site. You will want to add a project home page as well as _pages and _posts for the languages your site supports. To start with the project home page and using the languages from the example above, you would need to create

_homes/en/index.md
_homes/ko/index.md
_homes/vi/index.md

Keep in mind that Kata Code requires all pages to start with a YAML snippet of front matter in order to get rendered as intended. At its simplest, this is just two lines of three dashes at the top of a file as shown below.

---
---

It's okay if one or two of the files are (initially) missing. One of the other pages will be used instead. This holds for all of your site's pages and posts. Your Korean visitors would probably not be able to make much of a Vietnamese page and vice versa but that is your problem.

Now, let's say you want to add a page documenting how to get started with your project. That means you would add

_pages/en/getting-started.md
_pages/ko/getting-started.md
_pages/vi/getting-started.md

For a post announcing the release of v1.0.0 of your software, create one or more of

_posts/en/YYYY-MM-DD-release-v1.0.0.md
_posts/ko/YYYY-MM-DD-release-v1.0.0.md
_posts/vi/YYYY-MM-DD-release-v1.0.0.md

Note that it is important to start file names for _posts with a properly formatted date. Without a properly formatted date the post will be ignored.

Generating Your Site

With all these changes taken care of, you can (re)generate your site as before.

tailwindcss -i _includes/site.css -o assets/site.css
jekyll build

Tracking Change

Since you cloned a git repository to begin with, tracking your changes is just a matter of using git.

git add .
git commit -m 'Configure languages and add first content'

You can now push this to your own repository like so

git remote add origin URL-for-your-repository
git push --set-upstream origin main

Publishing Your Site

After generating your site's content, the _site directory contains all you need and a bit more. That extra bit comes about due to the way the polyglot plugin works and the template's insistence on making C the default "language". The content that should actually be published is the index.html file, the assets directory and all of the directories that match your site's configured languages. For the example above that would be the en, ko and vi directories. The rest is not meant to be published.