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/>