ICU-20088 User Guide migration: Add navigation structure and TOC for …

…Jekyll, fix formatting issues, etc.

.cpyskip.txt

@@ -101,6 +101,7 @@ icu4j/perf-tests/data/conversion/*
 # docs
 #
 docs/ide4c/vscode/*.json
+docs/Gemfile.lock
 #
 # tools
 #

README.md

@@ -5,6 +5,8 @@ The ICU project is under the stewardship of [The Unicode Consortium](https://www
 
 - Source: https://github.com/unicode-org/icu
 - Bugs: https://unicode-org.atlassian.net/projects/ICU
+- API Docs: https://unicode-org.github.io/icu-docs/
+- User Guide: https://unicode-org.github.io/icu/
 
 ![ICU Logo](./tools/images/iculogo_64.png)
 

docs/404.html

@@ -1,7 +1,10 @@
 ---
-permalink: /404.html
 layout: default
 ---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
 
 <style type="text/css" media="screen">
   .container {

docs/Gemfile

@@ -1,3 +1,6 @@
+# © 2020 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
 source "https://rubygems.org"
 # Hello! This is where you manage which Jekyll version is used to run.
 # When you want to use a different version, change it below, save the
@@ -8,10 +11,13 @@ source "https://rubygems.org"
 # This will help ensure the proper Jekyll version is running.
 # Happy Jekylling!
 
+# gem "jekyll", "~> 3.8.7"
+
 # This is the default theme for new Jekyll sites. You may change this to anything you like.
 gem "minima", "~> 2.5"
-# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
-# uncomment the line below. To upgrade, run `bundle update github-pages`.
+# If you aren't using GitHub Pages, then uncomment out the line above that starts with
+# 'gem "jekyll"' and then comment out the line below that starts with 'gem "github-pages"'.
+# To upgrade, run `bundle update github-pages`.
 gem "github-pages", "~> 206", group: :jekyll_plugins
 gem "just-the-docs"
 # If you have any plugins, put them here!

docs/_config.yml

@@ -1,52 +1,95 @@
+# © 2020 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
+title: ICU Documentation
+email: [email protected]
+description: >- # this means to ignore newlines until "baseurl:"
+  ICU is a mature, widely used set of C/C++ and Java libraries providing Unicode
+  and Globalization support for software applications. The ICU User Guide provides
+  documentation on how to use ICU.
+
+baseurl: "/icu" # the subpath for the site
+url: "https://unicode-org.github.io" # the base hostname & protocol for your site
+
+twitter_username: unicode
+github_username:  unicode-org
+
 remote_theme: pmarsceill/just-the-docs
 
-# GitHub uses it's own markdown renderer.
-# We use this in order to try and have the docs pages match ones in the repo.
-markdown: CommonMarkGhPages
+# GitHub uses its own markdown renderer called CommonMarkGhPages.
+#
+# To use this we'd need to set the following options:
+#     markdown: CommonMarkGhPages
+#     Plugins:
+#       jekyll-commonmark-ghpages
+#  
+#     commonmark:
+#       options: ["SMART", "FOOTNOTES"]
+#       extensions: ["strikethrough", "autolink", "table", "tagfilter"]
+#
+# However, it doesn't work well with Jekyll and the Just-The-Docs theme,
+# and causes too many formatting problems. Additionally, it also doesn't
+# have any support for auto-generating a Table of Contents (TOC) section
+# for a page. Due to these reasons, we instead use the recommended
+# markdown renderer for Jekyll, called kramdown.
+#
+markdown: kramdown
 
-# Plugins:
-#  jekyll-commonmark-ghpages -- This is needed in order to use CommonMarkGhPages
-#  jemoji                    -- For rendering emoji like :point_right:
+# Notes on plugins:
+#  - GitHub Pages ignores all plugins included in the Gemfile.
+#    - Only the ones listed in the _config.yml file (this file) are used.
+#  - There is a very limited set of plugins that GH Pages supports (for security
+#    reasons). The listing is here: https://pages.github.com/versions
+#  - The jekyll-sitemap plugin generates a "sitemap.xml" for search engines.
+#  - We need the "jemoji" plugin for rendering emoji like ":point_right:".
 plugins:
-  - jekyll-commonmark-ghpages
   - jekyll-remote-theme
+  - jekyll-sitemap
   - jemoji
 
-commonmark:
-  options: ["SMART", "FOOTNOTES"]
-  extensions: ["strikethrough", "autolink", "table", "tagfilter"]
-
-title: ICU Documentation
-description: ICU Documentation
-
-baseurl: "/icu" # the subpath for the site
-url: "https://jefgen.github.io" # the base hostname & protocol for your site
-
 search_enabled: true
 
-# Color scheme currently only supports "dark" or nil (default)
+# Color scheme currently only supports "dark" or nil (light).
 color_scheme: nil
 
 # Aux links for the upper right navigation
 aux_links:
+  "API Docs":
+    - "https://unicode-org.github.io/icu-docs"
   "ICU on GitHub":
-    - "//github.com/jefgen/icu"
+    - "https://github.com/unicode-org/icu"
+  "ICU Home Page":
+    - "http://site.icu-project.org/"
+  "Unicode Home Page":
+    - "https://www.unicode.org"
+
+# Makes Aux links open in a new tab.
+aux_links_new_tab: true
 
-# Back to top link
+# Add a "Back to top" link at the bottom of each page.
 back_to_top: true
 back_to_top_text: "Back to top"
 
 # Enable heading anchors
 heading_anchors: true
 
-# Footer content 
-# appears at the bottom of every page's main content
-footer_content: "Copyright &copy; 2016 and later Unicode, Inc. and others. All Rights Reserved. <a href=\"http://www.unicode.org/copyright.html\">Terms of use and License</a>."
+# Footer content: appears at the bottom of every page after the main content.
+footer_content: "&copy; 2016 and later: Unicode, Inc. and others. License &amp; terms of use: <a href=\"http://www.unicode.org/copyright.html\">http://www.unicode.org/copyright.html</a>"
 
-# TODO: I think this would be better at the top of the page, but I'm not sure how to do that.
-# Footer "Edit this page on GitHub" link text
+# Footer content: Add a "Edit this page on GitHub" link.
+# Note: I think this would be better at the *top* of the page, but it isn't possible to do that by default with just-the-docs.
 gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
-gh_edit_repository: "https://github.com/jefgen/icu" # the github URL for your repo
-gh_edit_branch: "master" # the branch that your docs is served from
-gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
+gh_edit_repository: "https://github.com/unicode-org/icu"
+# NOTE: Since we serve the docs out of the "docs" folder, we need to include that here even though
+# it is technically *not* part of the branch name.
+gh_edit_branch: "master/docs"
+# Can be "tree" or "edit". Edit takes the user to jump into the editor immediately.
+gh_edit_view_mode: "tree"
+
+# Exclude from processing.
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+exclude:
+  - Gemfile
+  - Gemfile.lock

docs/_sass/color_schemes/light.scss

@@ -0,0 +1,8 @@
+// © 2020 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+
+// Increase the side bar width as some of the page titles don't fit in the default size.
+$nav-width: 284px;
+
+// Increase the main content area width as some tables assume a larger size.
+$content-width: 900px;

docs/index.md

@@ -3,7 +3,6 @@ layout: default
 title: ICU Documentation
 nav_order: 1
 description: ICU Documentation
-permalink: /
 ---
 
 <!--
@@ -17,7 +16,7 @@ License & terms of use: http://www.unicode.org/copyright.html
 
 ## ICU User Guide
 
-The [ICU User Guide](./userguideintro) provides information on i18n topics for which ICU has services, and
+The [ICU User Guide](./userguide) provides information on i18n topics for which ICU has services, and
 includes details that go beyond the C, C++, and Java API docs (and avoids some duplication between them).
 
 This is the new home of the User Guide (since 2020 August).