TW-1722: Integrate offline Workflow Editor into the docs#4
Open
matenadasdi wants to merge 4 commits intomainfrom
Open
TW-1722: Integrate offline Workflow Editor into the docs#4matenadasdi wants to merge 4 commits intomainfrom
matenadasdi wants to merge 4 commits intomainfrom
Conversation
Replaces the custom Paligo CMS + Webpack pipeline with a Docusaurus 3 + MDX site
backed by an XML→Markdown migration script. Preserves every existing live URL
(444/444 coverage), the integrations layer (OneTrust, GTM, Intercom, Search
Widget), and the Bitrise visual identity.
Key components
- migration/convert.py — Paligo XML export → Markdown/MDX. Walks the structure
tree, pulls content from canonical resources via UUID origin lookup,
renders DocBook to Markdown (admonitions, tables, procedures, code blocks,
cross-references). Detects topichead nodes (non-clickable categories) and
linktype="import" subtrees (skipped — content is reused via xi:include).
- migration/build_url_map.py — extracts live page titles from the Paligo HTML
output to drive slug assignment.
- migration/apply_slugs_v2.py — section-aware slug matcher; only applies a
slug when the matched URL lives in the same top-level section, preventing
cross-section misroutes for common titles like "Getting started".
Docusaurus features wired up
- Tabs / TabItem from XML <para role="tabs"> + <procedure role="tab-content">
patterns, emitted as MDX components.
- Glossary as an HTML <dl> with anchor IDs; inline glossterms become
<GlossTerm baseform="..."> components that show a hover tooltip and click
through to the glossary anchor.
- Reusable content fragments via MDX partials. Every xi:include target gets
one file at src/partials/<readable-slug>.mdx (e.g. opening-the-workflow-
editor.mdx). Section-context references render the partial as a JSX
component; list-context references use a placeholder line that the
Docusaurus markdown.preprocessor expands inline before MDX parsing — keeps
step numbering continuous while preserving a single source of truth.
- Topichead components in the Paligo structure render as toggle-only sidebar
categories (link: null) so they expand children without navigating, matching
the live site behavior.
- Sidebar labels driven by migration/live_nav_labels.json extracted from the
Paligo HTML toc, so navigation matches the published site (e.g. "Insights
for the Build Cache" instead of just "Insights").
- Sidebar wiring: every category with an index.md gets link.type=doc; topichead
categories get link: null.
- Image references rewritten to /img/_paligo/uuid-<hex>.<ext> using the Paligo
HTML export as the canonical image store (665 files), since the XML's src/
remap attributes often pointed to legacy filenames that don't exist on disk.
- Portal landing page (src/pages/index.tsx) rebuilt as a React component with
six product cards, Bitrise brand styling, and the search input wired for the
Google Search Widget.
Build pipeline
- docusaurus.config.ts handles markdown.preprocessor for: list-context partial
expansion, JSX-tag escaping for placeholder text like <Git provider> or
<connected-app-id>, and the kebab-case {placeholder} pattern that MDX would
otherwise read as a JSX expression.
- format: 'detect' so .mdx files are parsed as MDX and .md files stay plain.
- Site builds clean (zero broken-link errors) at 444/444 URL coverage.
Removes nothing — the old paligo.js / webpack.config.js / middleware.js stay
in tree until cutover is approved.
Step-by-step instructions covering Node.js install, repo clone, npm install, dev server, production build, and troubleshooting — written for someone with no prior Docusaurus or Node.js knowledge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Single source of truth for anyone editing the docs — humans or LLMs. Ports the Bitrise Style Guide (voice, capitalization, terminology, lists, titles, punctuation) from Confluence into actionable rules with side-by-side examples. Adds the codebase-specific mechanics that arent on Confluence: frontmatter, .md vs .mdx, partial imports and the build-time list-context expansion, GlossTerm usage, image conventions, redirect rules, and the JSX-escape pitfalls the migration surfaced. Claude Code reads CLAUDE.md automatically every session, so well-written guidance here becomes both a human reference and an LLM context primer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The offline Workflow Editor was buried on a single Bitrise CLI page titled "Installing and upgrading...". Users either stumbled across it or didnt know it existed, even though it offers most of the Workflow Editor functions without needing a Bitrise login or an internet connection. Changes: - Reframe the page as "Offline Workflow Editor" (sidebar label + title) and add value-prop sections: "What you can do with it", "When to use it", "Best practices", and "Related topics". Slug stays the same so live URLs keep working. - Replace the empty "Bitrise CLI" section index with a real overview that highlights the offline Workflow Editor as one of the CLIs key uses. - Promote the existing inline mention on Workflows overview into a more visible :::tip admonition so readers see it on the landing page of the Workflows section. - Add :::tip admonitions on Creating a Workflow, Adding Steps to a Workflow, and the Steps overview, each pointing to the offline Workflow Editor with a one-liner about when itll help. - Append a :::tip to the "Editing the bitrise.yml file locally" partial, which surfaces the offline editor on the "Editing an apps bitrise.yml" page (its primary use case: editing the YAML locally). Follow-up (not in this PR): - Update the screenshot at static/img/_paligo/uuid-29b363bc-... with a fresh capture from a current build of the offline Workflow Editor. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes TW-1722.
Summary
The offline Workflow Editor was buried on a single Bitrise CLI page titled "Installing and upgrading…". Users either stumbled across it or didn't know it existed, even though it offers most of the Workflow Editor functions without needing a Bitrise login or an internet connection.
This PR integrates it into the documentation more effectively, with thorough hyperlinking from the most relevant Workflow / Steps /
bitrise.ymlpages.What changed
The offline Workflow Editor page itself
docs/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor.mdxsidebar_label: "Offline Workflow Editor" — much more discoverable in the sidebar./bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor), so live URLs keep working.Bitrise CLI section overview
docs/bitrise-ci/bitrise-cli/index.mdCross-link admonitions
Added
:::tipadmonitions on the most-trafficked Workflow / Steps pages so readers learn about the offline editor in context, where they're already looking:workflows-overview.mdx— promoted the existing inline mention to a visible tipcreating-a-workflow.mdx— tip below the existing YAML noteadding-steps-to-a-workflow.mdx— tip pointing out the same Step browser is available offlinesteps-overview.mdx— added the offline editor to the "where to find Steps" listsrc/partials/editing-the-bitriseyml-file-locally.mdx— appended a tip to the partial. Because this partial is included on the "Editing an app's bitrise.yml file" page, the new tip surfaces the offline editor exactly where users decide whether to edit YAML locally.Follow-up
The ticket also asks for an updated screenshot of the offline Workflow Editor. The current screenshot lives at
static/img/_paligo/uuid-29b363bc-ce14-f6a3-f310-62543138452e.png. Since I can't run the offline Workflow Editor to capture a current frame, that needs a follow-up commit by someone with the CLI installed. The new capture should overwrite the same UUID file so existing references continue to work.Test plan
npm install && npx docusaurus build— completes with 444/444 URL coverage/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor.html— sidebar label reads "Offline Workflow Editor"; the new sections render in order/en/bitrise-ci.html→ expand Bitrise CLI in the sidebar — the entry now reads "Offline Workflow Editor"/en/bitrise-ci/workflows-and-pipelines/workflows.htmland/en/bitrise-ci/workflows-and-pipelines/steps.html—:::tipadmonitions are present and linked/en/bitrise-ci/configure-builds/configuration-yaml/editing-an-app-s-bitrise-yml-file.htmlshows the new tip from the modified partial🤖 Generated with Claude Code