Editing the ICU User Guide

Contents

  1. Overview
  2. How to Contribute
  3. Jekyll Theme Configuration
  4. Document Structure
  5. Syntax
  6. Common Styles
  7. Code
  8. Notes
  9. TODOs
  10. Emoji
  11. Bookmarks & Links
  12. Previewing Changes Locally
    1. Setup
    2. Running
  13. Previous version

Overview

This version of the ICU User Guide is generated directly from the Markdown files in the /docs directory of the main repository. In particular, the Markdown files are customized to work with the Jekyll static site generator, which benefits from GitHub’s built-in support for Jekyll sites.

How to Contribute

Because ICU User Guide source files are now contained within the main repository, changes can now be made through the same process for contributing code patches. See Contributions to the ICU Library for the current process of filing an issue and submitting a pull request.

In the case of a single file edit (ex: typo correction), a convenient way to create the pull request is to follow the “Edit this page on Github” link at the bottom of the page and use GitHub to edit the file and create the new pull request.

After the source branch for a potential pull request is made, the changes can be previewed using the fork repository that contains the source branch. The fork repository must be configured to serve GitHub Pages from the branch and the Markdown pages root directory (/docs).

:point_right: Note: there is a latency of several minutes before GitHub Pages renders new changes, and errors prevent the changes from being rendered.

Jekyll Theme Configuration

Jekyll site-wide configurations are stored in the _config.yml file. The current theme being used is Just the Docs.

Due to incompatibilities between this theme and GitHub’s built-in implementation of the CommonMark Markdown parser, the default Jekyll Markdown parser, Kramdown, is used.

Document Structure

Major chapters have Introduction pages, and further sections in a chapter are subpages of that main chapter page. The navigation bar is generated from the information provided in the header section of the Markdown file according to the theme’s navigation annotations.

Syntax

Markdown should be preferred over custom HTML to create content wherever possible.

Common Styles

Styles are provided by the theme’s settings, which can be modified in _config.yml.

Code

Use the markdown notation of single backtick code spans (inline) and tilde line-demarcated fenced code blocks (multi-line).

Unlike Github-flavored Markdown, in multi-line fenced code blocks, the programming language in the info string should be lowercased.

Notes

:point_right: Note: Notes should be made by starting the line with the following Markdown:

> :point_right: **Note**:

TODOs

“TODO” items should be marked by starting the line with the following Markdown:

> :construction: **TODO**:

This will result in a “TODO” item like this:

:construction: TODO: Adjust this page for use of GitHub Markdown (since 2020)

Emoji

GitHub-flavored emoji are enabled using the Jemoji Ruby gem.

Bookmarks & Links

For internal links, please used relative paths to the corresponding Markdown file as the Markdown link path rather than specifying the full URL.

Anchors are generated by Jekyll for sections using the section header text in lowercase with hyphens instead of spaces.

:construction: TODO: search our pages for “(§)” and fix the links.

Previewing Changes Locally

Because of the latency in GitHub Pages rendering changes, it can be useful to run a Jekyll instance locally to preview changes.

Setup

GitHub Pages provides a list of dependency versions used in order to allow local environments to match exactly. Since Jekyll is a Ruby project, setup details depend on gems (code packages), Bundler (dependency management for execution), and the version of Ruby.

rbenv is one of the few different ways to install and control the version of Ruby. To install it and the required ruby-build plugin:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src # Optional but greatly speeds up certain operations
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc

mkdir -p "$(rbenv root)"/plugins
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

To install specific Ruby version that GitHub Pages uses:

rbenv versions  # list all Ruby versions available
rbenv install <version-num>  # install GH Pages Ruby version
rbenv versions  # list all Ruby versions after installing

To activate the version of Ruby:

rbenv init  # OR:  eval "$(rbenv init -)"
rbenv shell <version-num>
rbenv versions  # verify the specified version is in use

To install Bundler:

gem install bundler

The simplest way to ensure that transitive dependency versions are included correctly is to just specify the github-pages gem. This is already configured in Gemfile in the root directory. Thus, to ensure that the Ruby shell has the correct versions of dependencies downloaded and cached, in the root directory (/docs), run:

cd <ICU>/docs  # change to User Guide docs root directory
bundle update

Running

Ensure that the specific version of Ruby has been activated. Then use Bundler to ensure that the dependencies are downloaded in the current Ruby “shell” instance. Then use Bundler to execute the Jekyll server.

rbenv init  # OR:  eval "$(rbenv init -)"
rbenv shell <version-num>
cd <ICU>/docs  # change to User Guide docs root directory
bundle update
bundle exec jekyll server

Jekyll will take several seconds to generate HTML from the Markdown, so the Jekyll server will wait for that before being ready. Then, the rendered pages will be available at http://localhost:4000/icu/.

Previous version

The previous version of the ICU User Guide has been maintained via Google Sites. The Site address is http://sites.google.com/site/icuprojectuserguide/