Merge pull request #8652 from braze-inc/bdocs-update-links

bdocs: improvements + script for updating old links
braze-inc · Dec 23, 2024 · 1a5d314 · 1a5d314
2 parents 0ff35f4 + 5221508
commit 1a5d314
Show file tree

Hide file tree

Showing 10 changed files with 498 additions and 74 deletions.
diff --git a/.gitignore b/.gitignore
@@ -15,3 +15,6 @@ jekyll-algolia-*
 # Jetbrains IDEs
 .idea/
 braze-docs.iml
+
+# Braze scripts
+scripts/temp/*
diff --git a/_docs/_contributing/bdocs.md b/_docs/_contributing/bdocs.md
@@ -15,13 +15,13 @@ page_order: 8.5
 
 To run a command, use the following syntax. Replace `COMMAND` with one of the [available commands](#list-of-commands).
 
-```terminal
+```bash
 ./bdocs COMMAND
 ```
 
 To see the list of commands in your terminal, use the `help` command:
 
-```terminal
+```bash
 $ ./bdocs help
 
 bdocs is a CLI tool for executing Braze Docs scripts.
@@ -38,13 +38,11 @@ OPTIONS:
   help         Display this help message and exit
 ```
 
-
-
 ## Copying to your clipboard
 
 If you're on MacOS, you can copy the output of `bdocs` directly to your clipboard by using the following command. The `|` means to "pipe" (or send) the output of the first command to the next command. `pbcopy` means to write the output to your clipboard instead of the terminal. By combining these commands, you're sending the output from `bdocs` to `pbcopy` using a pipe.
 
-```terminal
+```bash
 ./bdocs COMMAND | pbcopy
 ```
 
@@ -56,7 +54,7 @@ This command creates the pull request description for weekly deployments by comp
 
 {% tabs local %}
 {% tab usage example %}
-```terminal
+```bash
 $ ./bdocs deploy
 
 - [#6980](https://github.com/braze-inc/braze-docs/pull/6980) - Update index.md
@@ -72,7 +70,7 @@ This command creates the pull request description for monthly releases by compar
 
 {% tabs local %}
 {% tab usage example %}
-```terminal
+```bash
 $ ./bdocs release
 
 ## Deploy - September 17, 2024
@@ -96,19 +94,19 @@ $ ./bdocs release
 
 Reference-style links are not supported within Liquid `{% raw %}{% tab %}{% endraw %}` tags. `tlinks` (short for "transform links") transforms all the reference-style links on a file into [in-line links]({{site.baseurl}}/contributing/content_management/cross_referencing)&#8212;whether it be a normal URL, a `{% raw %}{{site.baseurl}}{% endraw %}`, an image, or other link. This command takes a single file or an entire directory as an argument.
 
-{% alert tip %}
-After you run `tlinks`, you'll be asked if you'd like to run [`rlinks`](#rlinks) next.
+{% alert note %}
+After you run `tlinks`, [`rlinks`](#rlinks) will be automatically run against the same file or directory.
 {% endalert %}
 
 {% tabs local %}
 {% tab usage example %}
 #### Example command
 
-```terminal
+```bash
 ./bdocs tlinks _docs/_user_guide/onboarding_faq.md
 ```
 
-#### Example page: before
+#### Example page: Before
 
 {% raw %}
 ```markdown
@@ -119,7 +117,7 @@ Before continuing, [create your SSH token][2]. When you're finished, see [Step 2
 ```
 {% endraw %}
 
-#### Example page: after
+#### Example page: After
 
 {% raw %}
 ```markdown
@@ -136,19 +134,19 @@ Before continuing, [create your SSH token]({{site.baseurl}}/developer_guide/plat
 
 `rlinks` (short for "remove links") removes any unused reference links from the bottom of a Markdown file. This command takes a single file or an entire directory as an argument.
 
-{% alert tip %}
-After you run `tlinks`, you'll be asked if you'd like to run `rlinks` next.
+{% alert note %}
+After you run `tlinks`, `rlinks` will be automatically run against the same file or directory.
 {% endalert %}
 
 {% tabs local %}
 {% tab usage example %}
 #### Example command
 
-```terminal
+```bash
 ./bdocs rlinks _docs/_user_guide/onboarding_faq.md
 ```
 
-#### Example page: before
+#### Example page: Before
 
 {% raw %}
 ```markdown
@@ -159,7 +157,7 @@ Before continuing, [create your SSH token]({{site.baseurl}}/developer_guide/plat
 ```
 {% endraw %}
 
-#### Example Page: After
+#### Example page: After
 
 {% raw %}
 ```markdown
@@ -170,9 +168,50 @@ Before continuing, [create your SSH token]({{site.baseurl}}/developer_guide/plat
 {% endtab %}
 {% endtabs %}
 
-### `redirects`
+### `ulinks`
+
+`ulinks` (short for "update links") takes a file or directory and updates any old links listed on [`broken_redirect_list.js`](https://github.com/braze-inc/braze-docs/blob/develop/assets/js/broken_redirect_list.js) with the newest possible link. For example, if link `one` redirects to link `two`, and link `two` redirects to link `three`, `ulinks` will replace both link `one` and link `two` with link `three`. This command only updates links starting with {% raw %}`{{site.baseurl}}`{% endraw %}.
+
+{% tabs local %}
+{% tab usage example %}
+#### Example command
+
+```bash
+$ ./bdocs ulinks _docs/_developer_guide/content_cards/creating_custom_content_cards.md
+In 'update_old_links.md', made 1 replacement.
+Total replacements made: 1
+```
+
+#### Example page: Before
+
+{% raw %}
+```markdown
+Learn how to [log analytics]({{site.baseurl}}/developer_guide/customization_guides/content_cards/logging_analytics) for your custom Content Cards.
+```
+{% endraw %}
+
+#### Example page: After
+
+{% raw %}
+```markdown
+Learn how to [log analytics]({{site.baseurl}}/developer_guide/content_cards/logging_analytics/) for your custom Content Cards.
+```
+{% endraw %}
+{% endtab %}
+{% endtabs %}
+
+#### Why you should update old links
+
+Ideally, redirects added to [`assets/js/broken_redirect_list.js`](https://github.com/braze-inc/braze-docs/blob/develop/assets/js/broken_redirect_list.js) should only be used to:
+
+- Redirect traffic from outside of Braze Docs to the correct content (such as those coming from Stack Overflow, [Braze Learning](https://learning.braze.com/), the [Braze Blog]({{site.baseurl}}/resources/articles), etc.).
+- Prevent existing bookmarks from breaking.
+
+It should not be used to redirect URLs on an existing Braze Docs page to another existing Braze Docs page. Instead, these URLs should be updated with the newest possible link. We want to avoid cases in which someone reading an existing Braze Docs page clicks a link and is redirected from one page, to another page, to another page, and so on. `ulinks` helps solves this issue, improving the end-user experience.
+
+### `lredirects`
 
-This command checks if any new redirects have been added to [`broken_redirect_list.js`](https://github.com/braze-inc/braze-docs/blob/develop/assets/js/broken_redirect_list.js), then lists all of the old URLs using a base URL of your choice. For more general information, see [Redirecting URLs]({{site.baseurl}}/contributing/content_management/redirecting_urls).
+`lredirects` (short for "list redirects") checks if any new redirects have been added to [`broken_redirect_list.js`](https://github.com/braze-inc/braze-docs/blob/develop/assets/js/broken_redirect_list.js), then lists all of the old URLs using a base URL of your choice. For more general information, see [Redirecting URLs]({{site.baseurl}}/contributing/content_management/redirecting_urls).
 
 {% alert tip %}
 If you're using VS Code, hold **CMD** while right-clicking a link to open it in your default browser. Because these are the old links, they should all redirect to the new URL specified in the redirect file. If it doesn't, there's an issue with the redirect.
@@ -182,7 +221,7 @@ If you're using VS Code, hold **CMD** while right-clicking a link to open it in
 {% tab usage example %}
 The following example uses the [Sage AI rebrand PR](https://github.com/braze-inc/braze-docs/pull/8040).
 
-```terminal
+```bash
 $ git checkout bd-3442
 $ ./bdocs redirects https://braze-docs-gtcavota9-braze.vercel.app/
 

diff --git a/bdocs b/bdocs
@@ -1,14 +1,26 @@
 #!/bin/bash
 
-# This is a bash script for interacting with the various files in './scripts/'.
+# This is a wrapper script for interacting with the files in './scripts/'.
 # 
 # Usage: ./bdocs [option]
 
 set -e
 
-# The project's root directory.
-export PROJECT_ROOT
-PROJECT_ROOT="$(dirname "$(realpath "$0")")"
+# The project's root directory and redirect file.
+export PROJECT_ROOT="$(dirname "$(realpath "$0")")"
+export REDIRECT_FILE="./assets/js/broken_redirect_list.js"
+export REDIRECT_MATCHES="./scripts/temp/redirect_matches.json"
+
+# All scripts exported so they can source bdocs and call each other if needed.
+export DEPLOY="$PROJECT_ROOT/scripts/create_deploy_text.sh"
+export RELEASE="$PROJECT_ROOT/scripts/create_release_text.sh"
+export TLINKS="$PROJECT_ROOT/scripts/transform_reference_links.py"
+export RLINKS="$PROJECT_ROOT/scripts/remove_unused_reference_links.rb"
+export ULINKS="$PROJECT_ROOT/scripts/update_old_links.py"
+export LREDIRECTS="$PROJECT_ROOT/scripts/list_new_redirect_urls.sh"
+# Utility scripts that are not directly used in bdocs:
+export MRD="$PROJECT_ROOT/scripts/utils/merge_redirect_descendants.py"
+export TEMP_DIR="$PROJECT_ROOT/scripts/temp"
 
 # Displays usage for bdocs
 display_help() {
@@ -19,72 +31,84 @@ USAGE:
   ./bdocs [option]
 
 OPTIONS:
-  deploy       Create the deploy body text for weekly deployments
-  release      Create the release body text for monthly releases
-  tlinks       Transform reference links to inline links on 1 or more pages
-  rlinks       Remove reference links that are not being used on 1 or more pages
-  redirects    List the old URLs for all new redirects in this branch
-  help         Display this help message and exit
+  deploy         Create the deploy body text for weekly deployments
+  release        Create the release body text for monthly releases
+  tlinks         Transform reference links to inline links on 1 or more pages
+  rlinks         Remove unused reference links on 1 or more pages
+  ulinks         Update old links using newest redirect on 1 or more pages
+  lredirects     Test new redirects by listing old URLs in this branch
+  help           Display this help message and exit
 
 EOF
 }
 
+# If no './scripts/temp' directory, create one.
+if [ ! -d "$TEMP_DIR" ]; then
+    mkdir "$TEMP_DIR"
+fi
+
+# If a file or directory is required, pass or fail.
+require_path_or_file() {
+    if [[ -z "$1" ]]; then
+        echo "Error: A file or directory path is required."
+        exit 1
+    fi    
+}
+
+# If new merges into 'develop' are required, pass or fail.
+require_new_merges() {
+    LATEST_COMMIT_HASH=$(git log --max-count=1 --format="%H" origin/master ^origin/develop)
+    COMMIT_LOGS=$(git log --first-parent "$LATEST_COMMIT_HASH"..origin/develop)
+    if [ -z "$COMMIT_LOGS" ]; then
+        echo "Error: No new merges into 'develop' since the last deployment."
+        exit 1
+    fi
+}
+
 # Check if no arguments were provided
 if [[ $# -eq 0 ]]; then
     display_help
     exit 1
 fi
 
+# Fetch the latest changes from the remote quietly.
+git fetch origin develop --quiet
+
 # Argument parsing
 case $1 in
     deploy)
+        require_new_merges
         if [[ $# -eq 3 ]]; then
-            "$PROJECT_ROOT/scripts/create_deploy_text.sh" "$2" "$3"
+            "$DEPLOY" "$2" "$3"
         else
-            "$PROJECT_ROOT/scripts/create_deploy_text.sh"
+            "$DEPLOY"
         fi
         ;;
     release)
-        "$PROJECT_ROOT/scripts/create_release_text.sh"
+        require_new_merges
+        "$RELEASE"
         ;;
     tlinks)
-        if [[ -z "$2" ]]; then
-            echo "Error: A file or directory path is required."
-            exit 1
-        fi
-        python3 "$PROJECT_ROOT/scripts/transform_reference_links.py" "$2"
-        echo "Success!"
-        while true; do
-            echo "Do you want to remove the unused reference links? [Y/n]."
-            read -r opt
-            case $opt in
-                y*|Y*) 
-                    ruby "$PROJECT_ROOT/scripts/remove_unused_reference_links.rb" "$2"
-                    echo "Success!"
-                    break 
-                    ;;
-                n*|N*)
-                    echo "The unused reference links were left untouched."
-                    break
-                    ;;
-                *) echo "Error: Invalid choice."
-                    echo ""
-                    ;;
-            esac
-        done    
+        require_path_or_file "$2"
+        "$TLINKS" "$2"
+        "$RLINKS" "$2" # Run rlinks next, to clean up unused reference links.
         ;;
     rlinks)
-        if [[ -z "$2" ]]; then
-            echo "Error: The path to file or directory is required."
-            exit 1
-        fi
-        ruby "$PROJECT_ROOT/scripts/remove_unused_reference_links.rb" "$2"
+        require_path_or_file "$2" 
+        "$RLINKS" "$2"
+        ;;
+    ulinks)
+        require_path_or_file "$2"
+        touch "$REDIRECT_MATCHES"
+        "$MRD"
+        "$ULINKS" "$2"
+        # rm "$REDIRECT_MATCHES"
         ;;
-    redirects)
+    lredirects)
         if [[ $# -eq 2 ]]; then
-            "$PROJECT_ROOT/scripts/list_redirect_urls.sh" "$2"
+            "$LREDIRECTS" "$2"
         else
-            "$PROJECT_ROOT/scripts/list_redirect_urls.sh"
+            "$LREDIRECTS"
         fi
         ;;
     help)

diff --git a/scripts/create_release_text.sh b/scripts/create_release_text.sh
@@ -44,9 +44,9 @@ main() {
         COMMIT_TITLE=$(echo "$commit" | jq -r '.title')
         COMMIT_BODY=$(echo "$commit" | jq -r '.body')
 
-        # Print the deploy text for each deployment.
+        # Print the deploy text for each deployment using the sourced DEPLOY.
         echo "## $COMMIT_BODY"
-        ./scripts/create_deploy_text.sh "$PREV_COMMIT_DATE" "$COMMIT_DATE"
+        "$DEPLOY" "$PREV_COMMIT_DATE" "$COMMIT_DATE"
         echo ""
 
         # Get the next range of commits by increasing 'PREV_COMMIT_DATE'.

diff --git a/scripts/list_redirect_urls.sh → scripts/list_new_redirect_urls.sh b/scripts/list_redirect_urls.sh → scripts/list_new_redirect_urls.sh
@@ -4,13 +4,10 @@
 # base URL to list all old URLs so the user can open old links directly from
 # the terminal to test redirects.
 # 
-# Usage: ./bdocs redirects
-
-# Fetch the latest changes from the remote.
-git fetch origin develop --quiet
+# Usage: ./bdocs lredirects
 
 # Check new redirects by comparing the current branch to develop.
-NEW_REDIRECTS=$(git diff develop -- $PROJECT_ROOT/assets/js/broken_redirect_list.js)
+NEW_REDIRECTS=$(git diff develop -- $REDIRECT_FILE)
 
 # If there's no differences, print an error message and exit.
 if [[ -z "$NEW_REDIRECTS" ]]; then
@@ -22,7 +19,6 @@ fi
 # Check if a base URL was passed as an argument from bdocs, otherwise prompt the user.
 if [[ -z "$1" ]]; then
     echo "Which base URL would you like to use? Note: You can use a local or deployment base URL."
-    echo ""
     read BASE_URL
 else
     BASE_URL=$1

diff --git a/scripts/remove_unused_reference_links.rb b/scripts/remove_unused_reference_links.rb
@@ -1,3 +1,5 @@
+#!/usr/bin/env ruby
+
 # Removes unused reference-style links from the bottom of a file, such as:
 #   [1]: {{site.baseurl}}/contributing/your_first_contribution/
 # 

diff --git a/scripts/tests/update_old_links.md b/scripts/tests/update_old_links.md
@@ -0,0 +1,14 @@
+This is a test page for testing `ulinks`. When adding "bad links", the syntax needs to match the syntax on this page:
+
+https://www.braze.com/docs/contributing/content_management/cross_referencing
+
+i.e. no `/docs` should be found in the `site.baseurl`.
+
+Here's some bad links:
+1. [Bad link 1]({{site.baseurl}}/best_practices/).
+2. [Bad link 2]({{site.baseurl}}/best_practices/#android-push-category).
+3. [Bad link 3]({{site.baseurl}}/user_guide/message_building_by_channel/email/link_templates/).
+
+Here's two good links:
+1. [Good link 1](https://www.braze.com/docs/developer_guide/platform_wide/getting_started/analytics_overview)
+2. [Good link 2]({{site.baseurl}}/developer_guide/getting_started/analytics_overview)