From c6a0e79342996915dc85bc48f55c2ac898fe16ce Mon Sep 17 00:00:00 2001
From: Shubham Padia <shubham@zulip.com>
Date: Mon, 4 Aug 2025 11:07:08 +0000
Subject: [PATCH] help-beta: Insert steps around ordered lists.

We remove the ol > li margin rule to space out ordered list items since
that was the result of us overriding an upstream margin rule in
steps.css.

We inserted Steps inside include files only if they are not entirely
composed of an ordered list. If they are, they will eventually be
wrapped inside FlattenedSteps and wrapping these macros with Steps will
not give us the results we desire.
---
 help-beta/src/styles/main.css         |  5 ---
 tools/convert-help-center-docs-to-mdx | 51 +++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 5 deletions(-)

diff --git a/help-beta/src/styles/main.css b/help-beta/src/styles/main.css
index 43eaf33176..64a2aa162a 100644
--- a/help-beta/src/styles/main.css
+++ b/help-beta/src/styles/main.css
@@ -216,11 +216,6 @@
         margin-top: 0.25rem;
     }
 
-    ol > li {
-        /* Original value was 1px which made the steps feel too tight. */
-        padding-bottom: 8px;
-    }
-
     & .sl-heading-wrapper:has(> :first-child:target) {
         /* Increase the highlighted space around the text... */
         /* We are trying to recreate `padding: 6px 0 6px 8px` below
diff --git a/tools/convert-help-center-docs-to-mdx b/tools/convert-help-center-docs-to-mdx
index 4c4293a23c..6d1643d8b3 100755
--- a/tools/convert-help-center-docs-to-mdx
+++ b/tools/convert-help-center-docs-to-mdx
@@ -379,6 +379,50 @@ def insert_flattened_steps_component(
     return "\n".join(lines)
 
 
+def insert_steps_component_for_ordered_lists(
+    markdown_string: str, import_statements: set[str]
+) -> str:
+    list_item_pattern = re.compile(r"^\s*1\.\s+")
+
+    lines = markdown_string.split("\n")
+    output_lines = []
+    inside_flattened_steps = False
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        if "<FlattenedSteps>" in line:
+            inside_flattened_steps = True
+        elif "</FlattenedSteps>" in line:
+            inside_flattened_steps = False
+
+        if not inside_flattened_steps and list_item_pattern.match(line):
+            list_block = []
+
+            while i < len(lines):
+                current = lines[i]
+                if (
+                    list_item_pattern.match(current)
+                    or current.strip() == ""
+                    or current.startswith((" ", "\t"))
+                ):
+                    list_block.append(current)
+                    i += 1
+                else:
+                    break
+
+            import_statements.add("import { Steps } from '@astrojs/starlight/components';")
+            output_lines.append("<Steps>")
+            output_lines.extend(list_block)
+            output_lines.append("</Steps>")
+        else:
+            output_lines.append(line)
+            i += 1
+
+    return "\n".join(output_lines)
+
+
 def convert_admonitions_to_asides(
     markdown_string: str, import_statement_set: set[str], components_dir_path: str
 ) -> str:
@@ -526,6 +570,7 @@ def convert_help_center_file_to_mdx(
     result = insert_flattened_steps_component(
         result, include_files_info, import_statement_set, "../../components"
     )
+    result = insert_steps_component_for_ordered_lists(result, import_statement_set)
 
     result = fix_file_imports(result, import_statement_set, "./include")
     result = convert_admonitions_to_asides(result, import_statement_set, "../../components")
@@ -571,6 +616,12 @@ def convert_include_file_to_mdx(
         result, include_files_info, import_statement_set, "../../../components"
     )
 
+    # If the file is only an ordered list, it will already have been
+    # wrapped by FlattenedSteps and does not need any changes inside
+    # the file itself.
+    if not include_files_info[os.path.basename(markdown_file_path)]["is_only_ordered_list"]:
+        result = insert_steps_component_for_ordered_lists(result, import_statement_set)
+
     result = fix_file_imports(result, import_statement_set, ".")
     result = convert_admonitions_to_asides(result, import_statement_set, "../../../components")
     result = convert_tab_syntax(result, import_statement_set)