From 38c7900e2a801005ee17ffdc8b269eec14a27685 Mon Sep 17 00:00:00 2001
From: rzuckerm <rzuckerm@users.noreply.github.com>
Date: Fri, 22 Dec 2023 20:07:05 -0600
Subject: [PATCH] Add alphabet and 'Return to Top' links to Languages page
 (#631)

* Add alphabet and 'Return to Top' links to Languages page

* Revert changes to generate.sh

* Modify generate.sh to use same docker image as GitHub action
---
 docs/assets/css/style.scss | 28 ++++++++++++++++++++++++++++
 generate.sh                | 17 ++++++++++++-----
 scripts/automate.py        | 37 ++++++++++++++++++++++++++++++++-----
 3 files changed, 72 insertions(+), 10 deletions(-)

diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
index 0219eb9872..c20778b805 100644
--- a/docs/assets/css/style.scss
+++ b/docs/assets/css/style.scss
@@ -135,6 +135,34 @@ img {
   padding-bottom: 0px;
 }
 
+.letter-link {
+  list-style: none;
+  border-radius: 4px;
+  border: 0px;
+  display: block;
+  font-size: 22px;
+  font-family: serif;
+  font-weight: bold;
+}
+
+.letter-link>li {
+  display: inline-block;
+}
+
+.letter-link a {
+  color: $brand-color;
+}
+
+.letter-link a:hover {
+  color: darken($brand-color, 20%);
+}
+
+.letter-link>li+li:before {
+  color: #232323;
+  content: "|\00a0";
+  font-weight: normal;
+}
+
 @media print, screen and (max-width: 1200px) {
 
   div.wrapper {
diff --git a/generate.sh b/generate.sh
index b8dafaf8c1..c11861490b 100755
--- a/generate.sh
+++ b/generate.sh
@@ -6,14 +6,21 @@ python scripts/automate.py
 
 echo ""
 echo "*** Build With Jekyll ***"
-export JEKYLL_VERSION=4.2.2
+# Use image that is a close to what is used for GitHub actions
+export GITHUB_PAGES_IMAGE=ghcr.io/actions/jekyll-build-pages
+export GITHUB_PAGES_VERSION=v1.0.9
 docker run --rm \
-    -e "JEKYLL_UID=$(id -u)" \
-    -e "JEKYLL_GID=$(id -g)" \
     -v "$PWD/docs:/srv/jekyll:Z" \
     -w "/srv/jekyll" \
-    -it jekyll/jekyll:$JEKYLL_VERSION \
-    bash -c "bundle install && jekyll build -V --config _config.yml"
+    -e JEKYLL_ENV=development \
+    --entrypoint="" \
+    -it $GITHUB_PAGES_IMAGE:$GITHUB_PAGES_VERSION \
+    bash -c "rm -f Gemfile.lock && \
+        bundle install && \
+        chown $(id -u):$(id -g) Gemfile.lock && \
+        jekyll clean --config _config.yml && \
+        jekyll build -V --config _config.yml && \
+        chown -R  $(id -u):$(id -g) _site"
 
 echo ""
 echo "*** Change Base URL For Generated Files ***"
diff --git a/scripts/automate.py b/scripts/automate.py
index 097d080942..80db944cee 100644
--- a/scripts/automate.py
+++ b/scripts/automate.py
@@ -638,12 +638,23 @@ def generate_languages_index(repo: subete.Repo):
     language_index.add_paragraph(welcome_text)
     language_index.add_heading("Language Collections by Letter", level=2)
     language_index.add_paragraph(
-        "To help you navigate the collection, the following languages are organized alphabetically and grouped by first letter."
+        "To help you navigate the collection, the following languages are organized alphabetically and grouped by first letter. "
+        "To go to a particular letter, just click one of the links below."
     )
+    language_index.add_raw(_get_language_letter_links(repo))
+
+    return_to_top = [
+        "&laquo; ",
+        snakemd.Inline("Return to Top", link="#language-collections-by-letter"),
+        " &raquo;"
+    ]
+    language_index.add_block(
+        snakemd.Paragraph(["To return here, just click the "] + return_to_top + [" link."])
+    )
+
     for letter in repo.sorted_language_letters():
         language_index.add_heading(letter.upper(), level=3)
-        languages: list[subete.LanguageCollection] = repo.languages_by_letter(
-            letter)
+        languages: list[subete.LanguageCollection] = repo.languages_by_letter(letter)
         snippets = sum(language.total_programs() for language in languages)
         tests = sum(1 if language.has_testinfo()
                     else 0 for language in languages)
@@ -666,9 +677,25 @@ def generate_languages_index(repo: subete.Repo):
             for x in languages
         ]
         language_index.add_block(snakemd.MDList(languages))
+        language_index.add_block(snakemd.Paragraph(return_to_top))
+
     language_index.dump("index", dir=str(language_index_path))
 
 
+def _get_language_letter_links(repo: subete.Repo) -> str:
+    # Have to use raw HTML for this since there is no way to add a class attribute
+    # in Markdown
+    language_letter_links = [
+        '<ul class="letter-link">'
+    ] + [
+        f'    <li><a href="#{letter.lower()}">{letter.upper()}</a></li>'
+        for letter in repo.sorted_language_letters()
+    ] + [
+        "</ul>"
+    ]
+    return "\n".join(language_letter_links)
+
+
 def _get_language_link_and_testability(
     language: subete.LanguageCollection
 ) -> Union[snakemd.Inline, snakemd.Paragraph]:
@@ -678,9 +705,9 @@ def _get_language_link_and_testability(
 
     if language.has_untestable_info():
         testability = [
-            snakemd.Inline(" ("),
+            " (",
             snakemd.Inline("untestabled", link=language.untestable_info_url()),
-            snakemd.Inline(")")
+            ")"
         ]
     else:
         testability = [snakemd.Inline(" (untested)")]