• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1---
2layout: default
3title: User Guide Editing
4nav_order: 5
5parent: Misc
6---
7<!--
8© 2020 and later: Unicode, Inc. and others.
9License & terms of use: http://www.unicode.org/copyright.html
10-->
11
12# Editing the ICU User Guide
13{: .no_toc }
14
15## Contents
16{: .no_toc .text-delta }
17
181. TOC
19{:toc}
20
21---
22
23## Overview
24
25This version of the ICU User Guide is generated directly from the Markdown
26files in the `/docs` directory of the main repository. In particular, the
27Markdown files are customized to work with the Jekyll static site generator,
28which benefits from [GitHub's built-in support](https://docs.github.com/en/github/working-with-github-pages/setting-up-a-github-pages-site-with-jekyll)
29for Jekyll sites.
30
31## How to Contribute
32
33Because ICU User Guide source files are now contained within the main
34repository, changes can now be made through the same process for contributing
35code patches. See [Contributions to the ICU Library](constributions.md) for the
36current process of filing an issue and submitting a pull request.
37
38In the case of a single file edit (ex: typo correction), a convenient way to
39create the pull request is to follow the "Edit this page on Github" link at
40the bottom of the page and [use GitHub to edit the file](https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-your-repository)
41and create the new pull request.
42
43After the source branch for a potential pull request is made, the changes can
44be previewed using the fork repository that contains the source branch.  The
45fork repository must be [configured to serve GitHub Pages](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source)
46from the branch and the Markdown pages root directory (`/docs`).
47> :point_right: **Note**:  there is a
48latency of several minutes before GitHub Pages renders new changes, and
49[errors](https://docs.github.com/en/github/working-with-github-pages/about-jekyll-build-errors-for-github-pages-sites)
50prevent the changes from being rendered.
51
52## Jekyll Theme Configuration
53
54Jekyll site-wide configurations are stored
55in the `_config.yml` file. The current theme being used is
56[Just the Docs](https://pmarsceill.github.io/just-the-docs/).
57
58Due to incompatibilities between this theme and GitHub’s built-in implementation of the
59CommonMark Markdown parser, the default Jekyll Markdown parser, Kramdown, is
60used.
61
62## Document Structure
63
64Major chapters have Introduction pages, and further sections in a chapter are
65subpages of that main chapter page. The navigation bar is generated from the
66information provided in the header section of the Markdown file according to
67the theme's [navigation annotations](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/).
68
69## Syntax
70
71[Markdown](https://kramdown.gettalong.org/syntax.html) should be preferred over custom
72HTML to create content wherever possible.
73
74## Common Styles
75
76Styles are provided by the theme's settings, which can be modified in `_config.yml`.
77
78## Code
79
80Use the markdown notation of [single backtick](https://kramdown.gettalong.org/quickref.html#inline-code)
81code spans (inline) and [tilde line-demarcated](https://kramdown.gettalong.org/quickref.html#code-blocks)
82fenced code blocks (multi-line).
83
84Unlike Github-flavored Markdown, in multi-line fenced code
85blocks, the programming language in the [info string](https://spec.commonmark.org/0.29/#info-string)
86should be lowercased.
87
88## Notes
89
90> :point_right: **Note**: Notes should be made by starting the line with the
91following Markdown:
92
93~~~
94> :point_right: **Note**:
95~~~
96
97## TODOs
98
99"TODO" items should be marked by starting the line with the
100following Markdown:
101
102~~~
103> :construction: **TODO**:
104~~~
105
106This will result in a "TODO" item like this:
107
108> :construction: **TODO**: Adjust this page for use of GitHub Markdown (since 2020)
109
110## Emoji
111
112GitHub-flavored emoji are enabled using the
113[Jemoji](https://github.com/jekyll/jemoji) Ruby gem.
114
115## Bookmarks & Links
116
117For internal links, please used relative paths to the corresponding Markdown
118file as the Markdown link path rather than specifying the full URL.
119
120Anchors are generated by Jekyll for sections using the section header text in
121lowercase with hyphens instead of spaces.
122
123> :construction: **TODO**: search our pages for "(§)" and fix the links.
124
125## Previewing Changes Locally
126
127Because of the latency in GitHub Pages rendering changes, it can be useful to
128run a Jekyll instance locally to preview changes.
129
130### Setup
131
132GitHub Pages provides a list of
133[dependency versions](https://pages.github.com/versions/) used in order
134to allow local environments to match exactly. Since Jekyll is a Ruby project,
135setup details depend on gems (code packages), Bundler (dependency management for
136execution), and the version of Ruby.
137
138[rbenv](https://www.ruby-lang.org/en/documentation/installation/#rbenv) is one
139of the few different ways to install and control the version of Ruby.  To
140install it and the required `ruby-build` plugin:
141```bash
142git clone https://github.com/rbenv/rbenv.git ~/.rbenv
143cd ~/.rbenv && src/configure && make -C src # Optional but greatly speeds up certain operations
144echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
145```
146```bash
147mkdir -p "$(rbenv root)"/plugins
148git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
149```
150
151To install specific Ruby version that GitHub Pages uses:
152```bash
153rbenv versions  # list all Ruby versions available
154rbenv install <version-num>  # install GH Pages Ruby version
155rbenv versions  # list all Ruby versions after installing
156```
157
158To activate the version of Ruby:
159```bash
160rbenv init  # OR:  eval "$(rbenv init -)"
161rbenv shell <version-num>
162```
163
164To install [Bundler](https://bundler.io/):
165```bash
166gem install bundler
167```
168
169The simplest way to ensure that
170transitive dependency versions are included correctly is to just specify the
171`github-pages` gem. This is already configured in `Gemfile` in the root
172directory. Thus, to ensure that the Ruby shell has the correct versions of
173dependencies downloaded and cached, in the root directory, run:
174```bash
175bundle update
176```
177
178### Running
179
180Ensure that the specific version of Ruby has been activated. Then use Bundler
181to ensure that the dependencies are downloaded in the current Ruby "shell"
182instance.  Then use Bundler to execute the Jekyll server.
183```bash
184rbenv init  # OR:  eval "$(rbenv init -)"
185rbenv shell <version-num>
186bundle update
187bundle exec jekyll server
188```
189
190Jekyll will take several seconds to generate HTML from the Markdown, so the
191Jekyll server will wait for that before being ready. Then, the rendered pages
192will be available at <http://localhost:4000/icu/>.
193
194## Previous version
195
196The previous version of the ICU User Guide has been maintained via Google Sites. The Site
197address is <http://sites.google.com/site/icuprojectuserguide/>