From 3e60b16ac1e4106068e47630a46ed1fa2dc5845b Mon Sep 17 00:00:00 2001 From: Shubham Padia Date: Wed, 6 Aug 2025 11:05:27 +0000 Subject: [PATCH] starlight_help: Move help-beta over to starlight_help. We are starting the cutover process and starlight_help is the directory we have agreed on to place our new help center project. We do not want to use `starlight_help` as the URL for the project, but this commit changes the url from `help-beta` to `starlight_help` temporarily since we can only change URL once we get rid of the current help center project. That will be done in a future commit. --- eslint.config.js | 8 ++++---- help-beta/README.md | 12 ------------ help/include/sidebar_index.md | 2 +- pnpm-lock.yaml | 2 +- pnpm-workspace.yaml | 2 +- scripts/lib/node_cache.py | 6 +++--- {help-beta => starlight_help}/.gitignore | 0 {help-beta => starlight_help}/astro.config.mjs | 2 +- {help-beta => starlight_help}/package.json | 2 +- {help-beta => starlight_help}/src/.remarkrc.js | 0 .../src/components/EmoticonTranslations.astro | 0 .../src/components/FlattenedSteps.astro | 0 .../src/components/Footer.astro | 2 +- .../src/components/Head.astro | 0 .../src/components/KeyboardTip.astro | 0 .../src/components/NavigationSteps.astro | 0 .../src/components/ZulipNote.astro | 0 .../src/components/ZulipTip.astro | 0 .../src/content.config.ts | 0 {help-beta => starlight_help}/src/env.d.ts | 0 {help-beta => starlight_help}/src/route_data.ts | 0 .../src/scripts/client/adjust_mac_kbd_tags.ts | 0 .../src/styles/main.css | 0 {help-beta => starlight_help}/tsconfig.json | 0 templates/zerver/development/dev_tools.html | 6 +++--- tools/build-help-center | 2 +- tools/convert-help-center-docs-to-mdx | 16 ++++++++-------- tools/run-dev | 12 ++++++------ tsconfig.json | 2 +- version.py | 2 +- web/src/common.ts | 6 +++--- zerver/lib/markdown/help_settings_links.py | 4 ++-- zerver/lib/markdown/tabbed_sections.py | 2 +- 33 files changed, 39 insertions(+), 51 deletions(-) delete mode 100644 help-beta/README.md rename {help-beta => starlight_help}/.gitignore (100%) rename {help-beta => starlight_help}/astro.config.mjs (99%) rename {help-beta => starlight_help}/package.json (98%) rename {help-beta => starlight_help}/src/.remarkrc.js (100%) rename {help-beta => starlight_help}/src/components/EmoticonTranslations.astro (100%) rename {help-beta => starlight_help}/src/components/FlattenedSteps.astro (100%) rename {help-beta => starlight_help}/src/components/Footer.astro (80%) rename {help-beta => starlight_help}/src/components/Head.astro (100%) rename {help-beta => starlight_help}/src/components/KeyboardTip.astro (100%) rename {help-beta => starlight_help}/src/components/NavigationSteps.astro (100%) rename {help-beta => starlight_help}/src/components/ZulipNote.astro (100%) rename {help-beta => starlight_help}/src/components/ZulipTip.astro (100%) rename {help-beta => starlight_help}/src/content.config.ts (100%) rename {help-beta => starlight_help}/src/env.d.ts (100%) rename {help-beta => starlight_help}/src/route_data.ts (100%) rename {help-beta => starlight_help}/src/scripts/client/adjust_mac_kbd_tags.ts (100%) rename {help-beta => starlight_help}/src/styles/main.css (100%) rename {help-beta => starlight_help}/tsconfig.json (100%) diff --git a/eslint.config.js b/eslint.config.js index adf0391f9a..423e5d3d54 100644 --- a/eslint.config.js +++ b/eslint.config.js @@ -276,7 +276,7 @@ export default tseslint.config( }, }, { - files: ["help-beta/src/scripts/client/**"], + files: ["starlight_help/src/scripts/client/**"], rules: { "unicorn/prefer-module": "off", }, @@ -311,9 +311,9 @@ export default tseslint.config( ...astroConfigs.recommended, { files: [ - "help-beta/src/components/ZulipNote.astro", - "help-beta/src/components/ZulipTip.astro", - "help-beta/src/components/KeyboardTip.astro", + "starlight_help/src/components/ZulipNote.astro", + "starlight_help/src/components/ZulipTip.astro", + "starlight_help/src/components/KeyboardTip.astro", ], rules: { "import/unambiguous": "off", diff --git a/help-beta/README.md b/help-beta/README.md deleted file mode 100644 index ca40885900..0000000000 --- a/help-beta/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Help center (beta) documentation - -This directory is part of an ongoing migration project to convert our -help center documentation to use starlight and add search to the docs -at the same time. - -The status of the project can be tracked at this umbrella issue: -https://github.com/zulip/zulip/issues/30450 - -If you are a developer, you can refer to `/devtools` page on your zulip -installation to know what commands to use to run the project for -development. diff --git a/help/include/sidebar_index.md b/help/include/sidebar_index.md index 3c184b237d..a994c61e83 100644 --- a/help/include/sidebar_index.md +++ b/help/include/sidebar_index.md @@ -1,4 +1,4 @@ - + ## Guides * [Getting started with Zulip](/help/getting-started-with-zulip) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2765fcca6c..de7afc8a71 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -519,7 +519,7 @@ importers: specifier: ^2.0.8 version: 2.1.0(encoding@0.1.13) - help-beta: + starlight_help: dependencies: '@astrojs/check': specifier: ^0.9.3 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 953bab24cd..57043e994f 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,2 +1,2 @@ packages: - - help-beta + - starlight_help diff --git a/scripts/lib/node_cache.py b/scripts/lib/node_cache.py index f7ed52dcd0..0cb8f3940e 100644 --- a/scripts/lib/node_cache.py +++ b/scripts/lib/node_cache.py @@ -18,12 +18,12 @@ def setup_node_modules(production: bool = DEFAULT_PRODUCTION) -> None: except FileNotFoundError: pass - # We need this check when switching between branches without `help-beta` - # package. `node_modules` will be removed when working on a non `help-beta` + # We need this check when switching between branches without `starlight_help` + # package. `node_modules` will be removed when working on a non `starlight_help` # branch, but if `node_modules/.pnpm/lock.yaml` has not been updated by that # branch, we will end up in a situation where we might not have `node_modules` # even when we run the provision command. - if not os.path.exists("help-beta/node_modules"): + if not os.path.exists("starlight_help/node_modules"): skip = False if not skip: diff --git a/help-beta/.gitignore b/starlight_help/.gitignore similarity index 100% rename from help-beta/.gitignore rename to starlight_help/.gitignore diff --git a/help-beta/astro.config.mjs b/starlight_help/astro.config.mjs similarity index 99% rename from help-beta/astro.config.mjs rename to starlight_help/astro.config.mjs index e64dd17eb0..4aa7469e09 100644 --- a/help-beta/astro.config.mjs +++ b/starlight_help/astro.config.mjs @@ -6,7 +6,7 @@ import Icons from "unplugin-icons/vite"; // https://astro.build/config export default defineConfig({ - base: "help-beta", + base: "starlight_help", vite: { plugins: [ // eslint-disable-next-line new-cap diff --git a/help-beta/package.json b/starlight_help/package.json similarity index 98% rename from help-beta/package.json rename to starlight_help/package.json index 7cbfc8ff88..9939b51d4e 100644 --- a/help-beta/package.json +++ b/starlight_help/package.json @@ -1,5 +1,5 @@ { - "name": "help-beta", + "name": "starlight_help", "type": "module", "version": "0.0.1", "scripts": { diff --git a/help-beta/src/.remarkrc.js b/starlight_help/src/.remarkrc.js similarity index 100% rename from help-beta/src/.remarkrc.js rename to starlight_help/src/.remarkrc.js diff --git a/help-beta/src/components/EmoticonTranslations.astro b/starlight_help/src/components/EmoticonTranslations.astro similarity index 100% rename from help-beta/src/components/EmoticonTranslations.astro rename to starlight_help/src/components/EmoticonTranslations.astro diff --git a/help-beta/src/components/FlattenedSteps.astro b/starlight_help/src/components/FlattenedSteps.astro similarity index 100% rename from help-beta/src/components/FlattenedSteps.astro rename to starlight_help/src/components/FlattenedSteps.astro diff --git a/help-beta/src/components/Footer.astro b/starlight_help/src/components/Footer.astro similarity index 80% rename from help-beta/src/components/Footer.astro rename to starlight_help/src/components/Footer.astro index daf823742a..73aff79b9a 100644 --- a/help-beta/src/components/Footer.astro +++ b/starlight_help/src/components/Footer.astro @@ -3,7 +3,7 @@ import {CORPORATE_ENABLED, SUPPORT_EMAIL} from "astro:env/client"; let footer_html = `

Don't see an answer to your question? Contact this Zulip server's administrators for support.

`; if (CORPORATE_ENABLED) { - footer_html = `

Your feedback helps us make Zulip better for everyone! Please contact us with questions, suggestions, and feature requests.

`; + footer_html = `

Your feedback helps us make Zulip better for everyone! Please contact us with questions, suggestions, and feature requests.

`; } --- diff --git a/help-beta/src/components/Head.astro b/starlight_help/src/components/Head.astro similarity index 100% rename from help-beta/src/components/Head.astro rename to starlight_help/src/components/Head.astro diff --git a/help-beta/src/components/KeyboardTip.astro b/starlight_help/src/components/KeyboardTip.astro similarity index 100% rename from help-beta/src/components/KeyboardTip.astro rename to starlight_help/src/components/KeyboardTip.astro diff --git a/help-beta/src/components/NavigationSteps.astro b/starlight_help/src/components/NavigationSteps.astro similarity index 100% rename from help-beta/src/components/NavigationSteps.astro rename to starlight_help/src/components/NavigationSteps.astro diff --git a/help-beta/src/components/ZulipNote.astro b/starlight_help/src/components/ZulipNote.astro similarity index 100% rename from help-beta/src/components/ZulipNote.astro rename to starlight_help/src/components/ZulipNote.astro diff --git a/help-beta/src/components/ZulipTip.astro b/starlight_help/src/components/ZulipTip.astro similarity index 100% rename from help-beta/src/components/ZulipTip.astro rename to starlight_help/src/components/ZulipTip.astro diff --git a/help-beta/src/content.config.ts b/starlight_help/src/content.config.ts similarity index 100% rename from help-beta/src/content.config.ts rename to starlight_help/src/content.config.ts diff --git a/help-beta/src/env.d.ts b/starlight_help/src/env.d.ts similarity index 100% rename from help-beta/src/env.d.ts rename to starlight_help/src/env.d.ts diff --git a/help-beta/src/route_data.ts b/starlight_help/src/route_data.ts similarity index 100% rename from help-beta/src/route_data.ts rename to starlight_help/src/route_data.ts diff --git a/help-beta/src/scripts/client/adjust_mac_kbd_tags.ts b/starlight_help/src/scripts/client/adjust_mac_kbd_tags.ts similarity index 100% rename from help-beta/src/scripts/client/adjust_mac_kbd_tags.ts rename to starlight_help/src/scripts/client/adjust_mac_kbd_tags.ts diff --git a/help-beta/src/styles/main.css b/starlight_help/src/styles/main.css similarity index 100% rename from help-beta/src/styles/main.css rename to starlight_help/src/styles/main.css diff --git a/help-beta/tsconfig.json b/starlight_help/tsconfig.json similarity index 100% rename from help-beta/tsconfig.json rename to starlight_help/tsconfig.json diff --git a/templates/zerver/development/dev_tools.html b/templates/zerver/development/dev_tools.html index 02ba9f92ab..afc7aeb743 100644 --- a/templates/zerver/development/dev_tools.html +++ b/templates/zerver/development/dev_tools.html @@ -155,20 +155,20 @@ reload below.
  • - You can run pnpm build within the help-beta directory to run + You can run pnpm build within the starlight_help directory to run the build step separately.
  • ./tools/run-dev --help-center will host the generated build on - /help-beta. Note that search will work in the beta help center docs with + /starlight_help. Note that search will work in the beta help center docs with this flag. For testing changes related to the migration of the help center docs, using the tool to build the beta help center docs and running the dev server with this flag should be fine.
  • ./tools/run-dev --help-center-dev-server will run a dev server at - /help-beta that supports hot reload. Note that, with this flag, search will not work + /starlight_help that supports hot reload. Note that, with this flag, search will not work in the beta help center docs. This mode is useful when you are editing a help center file, and want to visualize the changes quickly in the beta help center documentation. You will need the converted MDX files to be already generated through diff --git a/tools/build-help-center b/tools/build-help-center index 73f2de0d15..699e5df9e4 100755 --- a/tools/build-help-center +++ b/tools/build-help-center @@ -37,7 +37,7 @@ def run() -> None: env["SHOW_RELATIVE_LINKS"] = str(args.show_relative_links).lower() subprocess.check_call( ["/usr/local/bin/corepack", "pnpm", "build"], - cwd="help-beta", + cwd="starlight_help", env=env, ) diff --git a/tools/convert-help-center-docs-to-mdx b/tools/convert-help-center-docs-to-mdx index eac25b5520..fe27067f61 100755 --- a/tools/convert-help-center-docs-to-mdx +++ b/tools/convert-help-center-docs-to-mdx @@ -91,15 +91,15 @@ def replace_image_path(markdown_string: str, replacement_path: str) -> str: """ We will point to the existing image folder till the cutover. After that, we will copy the images - to src folder for help-beta in order to take + to src folder for starlight_help in order to take advantage of Astro's image optimization. See https://chat.zulip.org/#narrow/stream/6-frontend/topic/Handling.20images.20in.20help.20center.20starlight.20migration.2E/near/1915130 """ # We do not replace /static/images directly since there are a few # instances in the documentation where zulip.com links are # referenced with that blurb as a part of the url. - result = markdown_string.replace("(/static/images/help-beta", f"({replacement_path}") - return result.replace('="/static/images/help-beta', f'="{replacement_path}') + result = markdown_string.replace("(/static/images/starlight_help", f"({replacement_path}") + return result.replace('="/static/images/starlight_help', f'="{replacement_path}') def fix_file_imports( @@ -138,11 +138,11 @@ def escape_curly_braces(markdown_string: str) -> str: def fix_relative_path(markdown_string: str) -> str: """ - Since the docs will live at the `help-beta/` url + Since the docs will live at the `starlight_help/` url until we migrate the project completely, we will - replace `help/` with `help-beta/` + replace `help/` with `starlight_help/` """ - return markdown_string.replace("help/", "help-beta/") + return markdown_string.replace("help/", "starlight_help/") def insert_string_at_line(text: str, destination_str: str, n: int) -> str: @@ -692,7 +692,7 @@ def get_include_files_info(include_input_dir: str) -> dict[str, IncludeFileInfo] def run() -> None: input_dir = os.path.join(BASE_DIR, "help") - output_dir = os.path.join(BASE_DIR, "help-beta/src/content/docs") + output_dir = os.path.join(BASE_DIR, "starlight_help/src/content/docs") include_input_dir = os.path.join(input_dir, "include") include_output_dir = os.path.join(output_dir, "include") print("Starting the conversion from MD to MDX...") @@ -748,7 +748,7 @@ def run() -> None: # since the first run will always give us warnings. subprocess.check_call( ["/usr/local/bin/corepack", "pnpm", "run", "format-silent"], - cwd="help-beta", + cwd="starlight_help", ) diff --git a/tools/run-dev b/tools/run-dev index 226d744913..23057a13cd 100755 --- a/tools/run-dev +++ b/tools/run-dev @@ -303,7 +303,7 @@ def run_help_center_dev_server(external_host: str) -> "subprocess.Popen[bytes]": "--host", f"--allowed-hosts={urlsplit(external_host).hostname}", ], - cwd="help-beta", + cwd="starlight_help", ) @@ -311,7 +311,7 @@ def run_help_center_dev_server(external_host: str) -> "subprocess.Popen[bytes]": async def help_center_middleware( request: web.Request, handler: Callable[[web.Request], Awaitable[web.StreamResponse]] ) -> web.StreamResponse: - if request.path.startswith("/help-beta"): + if request.path.startswith("/starlight_help"): try: filename = request.match_info["filename"] name, ext = os.path.splitext(filename) @@ -336,19 +336,19 @@ def setup_routes( ) -> None: if enable_help_center: # Order of adding the rules matters. aiohttp will stop at the first - # match, and we want `/help-beta` to be matched before Django URIs. + # match, and we want `/starlight_help` to be matched before Django URIs. try: - app.router.add_static("/help-beta", "help-beta/dist") + app.router.add_static("/starlight_help", "starlight_help/dist") except ValueError: print("""Please run the build step for the help center before enabling it. The instructions for the build step can be found in the `./devtools` -page. `/help-beta` urls will give you an error until you complete the +page. `/starlight_help` urls will give you an error until you complete the build step and rerun `run-dev`.""") elif enable_help_center_dev_server: app.add_routes( [ web.route( - hdrs.METH_ANY, r"/{path:(help-beta).*}", partial(forward, help_center_port) + hdrs.METH_ANY, r"/{path:(starlight_help).*}", partial(forward, help_center_port) ), ] ) diff --git a/tsconfig.json b/tsconfig.json index c1cd3bcf63..d6f2003568 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -37,7 +37,7 @@ }, "exclude": [ // This is a separate package with its own TypeScript configuration. - "help-beta", + "starlight_help", // Skip walking large generated directories. ".venv", diff --git a/version.py b/version.py index 78f0b72a35..b4d3dfcf12 100644 --- a/version.py +++ b/version.py @@ -49,4 +49,4 @@ API_FEATURE_LEVEL = 415 # historical commits sharing the same major version, in which case a # minor version bump suffices. -PROVISION_VERSION = (339, 1) # bumped 2025-08-04 to upgrade ShellCheck +PROVISION_VERSION = (340, 1) # bumped 2025-08-04 to move help-beta to starlight_help diff --git a/web/src/common.ts b/web/src/common.ts index e7bb812276..fa6bf86358 100644 --- a/web/src/common.ts +++ b/web/src/common.ts @@ -12,7 +12,7 @@ export function phrase_match(query: string, phrase: string): boolean { } // Any changes to this function should be followed by a check for changes needed -// to adjust_mac_kbd_tags of help-beta/src/scripts/adjust_mac_kbd_tags.ts. +// to adjust_mac_kbd_tags of starlight_help/src/scripts/adjust_mac_kbd_tags.ts. const keys_map = new Map([ ["Backspace", "Delete"], ["Enter", "Return"], @@ -21,7 +21,7 @@ const keys_map = new Map([ ]); // Any changes to this function should be followed by a check for changes needed -// to adjust_mac_kbd_tags of help-beta/src/scripts/adjust_mac_kbd_tags.ts. +// to adjust_mac_kbd_tags of starlight_help/src/scripts/adjust_mac_kbd_tags.ts. export function has_mac_keyboard(): boolean { // eslint-disable-next-line @typescript-eslint/no-deprecated return /mac/i.test(navigator.platform); @@ -30,7 +30,7 @@ export function has_mac_keyboard(): boolean { // We convert the tags used for keyboard shortcuts to mac equivalent // key combinations, when we detect that the user is using a mac-style keyboard. // Any changes to this function should be followed by a check for changes needed -// to adjust_mac_kbd_tags of help-beta/src/scripts/adjust_mac_kbd_tags.ts. +// to adjust_mac_kbd_tags of starlight_help/src/scripts/adjust_mac_kbd_tags.ts. export function adjust_mac_kbd_tags(kbd_elem_class: string): void { if (!has_mac_keyboard()) { return; diff --git a/zerver/lib/markdown/help_settings_links.py b/zerver/lib/markdown/help_settings_links.py index 8901f31df2..163417be3f 100644 --- a/zerver/lib/markdown/help_settings_links.py +++ b/zerver/lib/markdown/help_settings_links.py @@ -17,9 +17,9 @@ REGEXP = re.compile(r"\{settings_tab\|(?P.*?)\}") # If any changes to this link mapping are made, -# `help-beta/src/components/NavigationSteps.astro` should be updated accordingly. +# `starlight_help/src/components/NavigationSteps.astro` should be updated accordingly. # This manual update mechanism will cease to exist once we have switched to the -# help-beta system. +# starlight_help system. link_mapping = { # a mapping from the setting identifier that is the same as the final URL # breadcrumb to that setting to the name of its setting type, the setting diff --git a/zerver/lib/markdown/tabbed_sections.py b/zerver/lib/markdown/tabbed_sections.py index 95a24fbca6..41cad230d3 100644 --- a/zerver/lib/markdown/tabbed_sections.py +++ b/zerver/lib/markdown/tabbed_sections.py @@ -180,7 +180,7 @@ def generate_content_blocks( data_tab_key=tab["tab_key"], # This attribute is not used directly in this file here, # we need this for the current conversion script in for - # help-beta where this function is being imported. + # starlight_help where this function is being imported. tab_label=TAB_SECTION_LABELS[tab["tab_key"]], # Wrapping the content in two newlines is necessary here. # If we don't do this, the inner Markdown does not get