[DEV-2984] Add step rendering #1734

MarBert · 2025-10-14T09:46:51Z

List of Changes

Adds rendering for gitbook steps

Motivation and Context

How Has This Been Tested?

on localhost

Screenshots (if appropriate):

Types of changes

Chore (nothing changes by a user perspective)
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

My change requires a change to the documentation.
I have updated the documentation accordingly.

changeset-bot · 2025-10-14T09:46:55Z

🦋 Changeset detected

Latest commit: 68db798

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
gitbook-docs	Minor
nextjs-website	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

# Conflicts: # .changeset/fuzzy-papayas-raise.md # apps/nextjs-website/src/components/molecules/MarkdownPart/MarkdownPart.tsx # apps/nextjs-website/src/components/organisms/GitBookContent/GitBookContent.tsx # apps/nextjs-website/src/components/organisms/GitBookContent/components/Heading.tsx # apps/nextjs-website/src/lib/cmsApi.ts # apps/nextjs-website/src/lib/strapi/types/part.ts

.changeset/open-guests-think.md

apps/nextjs-website/src/components/organisms/GitBookContent/components/Step.tsx

marcobottaro · 2025-10-15T12:24:43Z

packages/gitbook-docs/src/helpers/s3Bucket.helper.ts

You should revert this change

packages/gitbook-docs/src/markdoc/schema/stepper.ts

marcobottaro · 2025-10-15T12:27:30Z

packages/gitbook-docs/src/markdoc/schema/stepper.ts

+export const step: Schema = {
+  render: 'Step',
+  // Defines the content model for what's inside a stepper
+  children: ['paragraph', 'list', 'code', 'heading', 'blockquote'],


Check for other content models

Copilot

Pull Request Overview

Adds GitBook Stepper and Step Markdoc schema plus React rendering components to enable step-based content in documentation.

Introduces Markdoc schemas (stepper, step) and corresponding React components (Stepper, Step)
Extends rendering/parse pipelines to recognize new tags
(Potentially accidental) temporary change returning a hardcoded string in S3 download helper

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/gitbook-docs/src/renderContent.ts	Registers Stepper and Step in rendering components interface
packages/gitbook-docs/src/parseContent.ts	Adds stepper and step tags to Markdoc schema registry
packages/gitbook-docs/src/markdoc/schema/stepper.ts	Defines Markdoc schemas and transform logic for stepper/step
packages/gitbook-docs/src/helpers/s3Bucket.helper.ts	Alters file download to return hardcoded string (likely unintended)
apps/nextjs-website/src/components/templates/GitBookTemplate/GitBookTemplate.tsx	Minor import reordering (no functional change)
apps/nextjs-website/src/components/organisms/GitBookContent/components/Stepper.tsx	New React Stepper component injecting step numbers
apps/nextjs-website/src/components/organisms/GitBookContent/components/Step.tsx	New React Step component formatting numbered heading and body
apps/nextjs-website/src/components/organisms/GitBookContent/GitBookContent.tsx	Wires Stepper/Step into component map
apps/nextjs-website/src/components/molecules/MarkdownPart/MarkdownPart.tsx	Import order adjustment (no functional change)
.changeset/open-guests-think.md	Declares minor version bumps for new feature

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-15T12:30:45Z

packages/gitbook-docs/src/markdoc/schema/stepper.ts

+export const stepper: Schema = {
+  render: 'Stepper',
+  // This should be 'step', listing the allowed child tags.
+  children: ['Step'],


The children array lists 'Step' (capitalized) but the schema tag key you registered is 'step'; Markdoc expects the tag names (schema keys), so this should be ['step'] to allow step tags to be parsed as children. The inline comment already indicates the intended value.

Suggested change

children: ['Step'],

children: ['step'],

Copilot · 2025-10-15T12:30:45Z

packages/gitbook-docs/src/markdoc/schema/stepper.ts

+    for (const child of node.children) {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      if (child.type === 'Step') {
+        // Mutate the child node to add the index to its attributes.
+        // eslint-disable-next-line functional/immutable-data,functional/no-expression-statements
+        child.attributes.index = stepIndex;
+        // eslint-disable-next-line functional/no-expression-statements
+        stepIndex++;
+      }


Markdoc AST nodes for custom tags typically have type 'tag' with a 'tag' (or 'name') property indicating the tag name; comparing child.type === 'Step' will never match, so the index is never assigned. Replace the condition with something like if (child.tag === 'step') (aligned with the lowercase schema key).

Copilot · 2025-10-15T12:30:45Z

packages/gitbook-docs/src/markdoc/schema/stepper.ts

+      if (child.type === 'Step') {
+        // Mutate the child node to add the index to its attributes.
+        // eslint-disable-next-line functional/immutable-data,functional/no-expression-statements
+        child.attributes.index = stepIndex;


You assign an 'index' attribute, but the React Step component consumes 'stepNumber' (added later via cloning in Stepper) and never uses 'index'; this creates dead, confusing data. Either rename to 'stepNumber' and consume it to avoid double work, or remove the mutation entirely.

Suggested change

child.attributes.index = stepIndex;

// Removed dead assignment: child.attributes.index = stepIndex;

Copilot · 2025-10-15T12:30:46Z

apps/nextjs-website/src/components/organisms/GitBookContent/components/Stepper.tsx

+import { StepperProps } from 'gitbook-docs/markdoc/schema/stepper';
+
+const Stepper = ({ children }: StepperProps<ReactNode>) => (
+  <Box sx={{ gap: 0 }}>


The sx prop sets gap: 0 but Box is not given display: 'flex' or 'grid'; gap has no effect on a block div. Either remove gap or add display: 'flex' (or appropriate layout) if spacing was intended.

Suggested change

<Box sx={{ gap: 0 }}>

<Box>

packages/gitbook-docs/src/helpers/s3Bucket.helper.ts

Co-authored-by: marcobottaro <[email protected]>

…mponents/Step.tsx Co-authored-by: marcobottaro <[email protected]>

github-actions · 2025-10-16T09:35:36Z

Jira Pull Request Link

This Pull Request refers to the following Jira issue DEV-2984

github-actions · 2025-10-16T09:35:37Z

Branch is not up to date with base branch

@MarBert it seems this Pull Request is not updated with base branch.
Please proceed with a merge or rebase to solve this.

MarBert and others added 15 commits September 26, 2025 10:44

add api for markdown

6740c38

Merge branch 'main' into DEV-2911-add-markdown-part

adc3f45

add markdown part, need fixing

69d27f6

rendering is working, need file exist check

97c720d

fix rendering

2013436

add changeset

e77a219

add dictionary in tests

ab05d54

Merge branch 'main' into DEV-2911-add-markdown-part

6a94a00

Merge branch 'main' into DEV-2911-add-markdown-part

a9dba1c

add scripts to show steps

421247a

dot is showing

bfa991f

WIP rendering

0f0690f

Refactor Step and Stepper components for improved structure and clarity

58efda7

Rendering steps correctly

19e5a4e

Add changeset

f4360b6

MarBert self-assigned this Oct 14, 2025

MarBert requested review from MarcoPonchia, marcobottaro and tommaso1 as code owners October 14, 2025 09:46

MarBert added 2 commits October 14, 2025 11:52

fix issues with merge

ab8a527

github-actions bot added changeset packages website size/small labels Oct 14, 2025

MarBert temporarily deployed to uat October 14, 2025 10:23 — with GitHub Actions Inactive

MarBert temporarily deployed to dev October 14, 2025 10:23 — with GitHub Actions Inactive

MarBert temporarily deployed to prod October 14, 2025 10:23 — with GitHub Actions Inactive

marcobottaro requested changes Oct 15, 2025

View reviewed changes

marcobottaro requested a review from Copilot October 15, 2025 12:29

Copilot AI reviewed Oct 15, 2025

View reviewed changes

MarBert and others added 2 commits October 16, 2025 11:27

Update .changeset/open-guests-think.md

39e230f

Co-authored-by: marcobottaro <[email protected]>

Update apps/nextjs-website/src/components/organisms/GitBookContent/co…

0e17ef8

…mponents/Step.tsx Co-authored-by: marcobottaro <[email protected]>

MarBert temporarily deployed to dev October 16, 2025 09:30 — with GitHub Actions Inactive

MarBert temporarily deployed to uat October 16, 2025 09:30 — with GitHub Actions Inactive

MarBert temporarily deployed to prod October 16, 2025 09:30 — with GitHub Actions Inactive

fix required by reviewer

68db798

MarBert temporarily deployed to dev October 16, 2025 09:37 — with GitHub Actions Inactive

MarBert temporarily deployed to uat October 16, 2025 09:37 — with GitHub Actions Inactive

MarBert temporarily deployed to prod October 16, 2025 09:37 — with GitHub Actions Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[DEV-2984] Add step rendering #1734

[DEV-2984] Add step rendering #1734

MarBert commented Oct 14, 2025

Uh oh!

changeset-bot bot commented Oct 14, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

marcobottaro Oct 15, 2025

Uh oh!

Uh oh!

marcobottaro Oct 15, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Copilot AI Oct 15, 2025

Uh oh!

Uh oh!

github-actions bot commented Oct 16, 2025 •

edited by atlassian bot

Loading

Uh oh!

github-actions bot commented Oct 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	child.attributes.index = stepIndex;
	// Removed dead assignment: child.attributes.index = stepIndex;

[DEV-2984] Add step rendering #1734

Are you sure you want to change the base?

[DEV-2984] Add step rendering #1734

Conversation

MarBert commented Oct 14, 2025

List of Changes

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Checklist:

Uh oh!

changeset-bot bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Uh oh!

Uh oh!

marcobottaro Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marcobottaro Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Oct 16, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Jira Pull Request Link

Uh oh!

github-actions bot commented Oct 16, 2025

Branch is not up to date with base branch

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

changeset-bot bot commented Oct 14, 2025 •

edited

Loading

github-actions bot commented Oct 16, 2025 •

edited by atlassian bot

Loading