Skip to content

docs: restructure surface docs into landing + workflow + sub-components#2102

Open
aaronlee777 wants to merge 16 commits into
mainfrom
al/docs/content-restructure
Open

docs: restructure surface docs into landing + workflow + sub-components#2102
aaronlee777 wants to merge 16 commits into
mainfrom
al/docs/content-restructure

Conversation

@aaronlee777

@aaronlee777 aaronlee777 commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Restructure docs/workflows-overview/ so each surface lives in its own subfolder with three pages: a landing (.mdx), workflow.md, and sub-components.md
  • Add four new top-level landings (companies, employees, contractors, payroll) that the Surfaces homepage and sidebar both link to
  • Add a generic LinkCardGrid component that drives every landing's card grid (configurable 1/2/3 columns)
  • Surfaces sidebar entry becomes a non-collapsible section header; active-state styling now pins highlight to the actual current page only
  • Rename sub-component section headings from developer-y Component.Name to human-readable equivalents (e.g. Company.AssignSignatory → Assign a signatory, Payroll.PayrollBlockerList → Blockers)
  • Update SurfacesGrid card targets, README.md, and inbound cross-references; fix the existing "Conractor onboarding" typo

Test plan

  • Run npm run docs:clear && npm run docs and confirm Docusaurus boots without sidebar errors
  • Walk every sidebar entry under Companies / Employees / Contractors / Payroll and verify each landing renders its Workflow and Sub-components cards
  • Click every card on every landing and confirm the destination doc or anchor resolves
  • Confirm only the actual current page shows the active state in the sidebar (no cascading highlight up the tree)
  • Run npm run docs:build and confirm no broken-link warnings are introduced

🤖 Generated with Claude Code

aaronlee777 and others added 14 commits June 11, 2026 17:35
@aaronlee777 @claude
docs: restructure surface docs into landing + workflow + sub-components
2fa27db 
Each surface in workflows-overview/ now lives in its own subfolder with
three pages — a landing that mirrors the Companies pattern, a workflow
page for the drop-in flow component, and a sub-components page with
human-readable section headings.

- New top-level landings: companies, employees, contractors, payroll
- Per-surface landings for company-onboarding, information-requests,
  employee-onboarding, employee-self-onboarding, contractor-onboarding,
  contractor-payments, run-payroll, off-cycle-payroll, dismissal-payroll,
  transition-payroll
- New LinkCardGrid component drives each landing's card grid
- Surfaces sidebar entry is a non-collapsible section header; active
  state styling pins highlight to the actual current page only
- Renamed sub-component headings from Component.Name to human-readable
  equivalents (Company.AssignSignatory -> Assign a signatory, etc.)
- Updated SurfacesGrid card targets, README.md, and inbound cross-refs

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777 @claude
style(docs): apply prettier formatting to surface landing mdx files
51c4a0a 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777
Merge remote-tracking branch 'origin/main' into al/docs/content-restr…
c880817 
…ucture

# Conflicts:
#	docs/workflows-overview/company-onboarding/sub-components.md
#	docs/workflows-overview/contractor-onboarding/sub-components.md
#	docs/workflows-overview/contractor-payments/sub-components.md
#	docs/workflows-overview/dismissal-payroll/workflow.md
#	docs/workflows-overview/employee-onboarding/sub-components.md
#	docs/workflows-overview/employee-self-onboarding/sub-components.md
#	docs/workflows-overview/information-requests.md
#	docs/workflows-overview/off-cycle-payroll.md
#	docs/workflows-overview/run-payroll/sub-components.md
#	docs/workflows-overview/transition-payroll/workflow.md
@aaronlee777 @claude
fix(docs-site): prepend /docs/ routeBasePath to SurfacesGrid card links
7cd0c34 
Card links were missing the docs plugin's routeBasePath, so each Surfaces
homepage card resolved to a non-existent URL.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777
Merge remote-tracking branch 'origin/main' into al/docs/content-restr…
fcaa667 
…ucture
@aaronlee777
Merge remote-tracking branch 'origin/main' into al/docs/content-restr…
a88cc67 
…ucture
@aaronlee777 @claude
docs: unify landing pages with LinkCardGrid
3b41b52 
Convert workflow-overview landing pages (employees, companies, contractors,
payroll) to use LinkCardGrid for consistent card UI. Switch single-item grids
to columns={2} so cards keep half-width instead of stretching. Remove empty
sub-components section from dismissal payroll landing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777 @claude
fix(docs): restore .mdx extension on cross-doc LinkCardGrid links
cb2f1de 
Docusaurus broken-link check requires the .mdx suffix for sibling
document references.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777 @claude
fix(docs): use category slugs for LinkCardGrid links
34aefa7 
The sidebar maps each *-onboarding.mdx into a category-with-link, which
relocates the doc's route to the category path (e.g. /workflows-overview/
employee-onboarding instead of .../employee-onboarding/employee-onboarding).
Target the category slug directly so the Docusaurus broken-link check
passes. Verified with a local build.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777 @claude
docs: rename "deciding-to-build-with-the-sdk" to "build-methods"
9329589 
Rename the section directory and its three pages around their new purpose:
- build-pathways-sdk-flows-api.md -> workflows.md (explains workflows)
- component-types.md -> sub-components.md (explains sub-components)
- deciding-to-build-with-the-sdk.md -> hooks.md (explains hooks)

Rewrite each page to cover its new topic and add a build-methods.md
landing page with a side-by-side comparison and "when to pick which"
decision guide. Wire the new landing page into the sidebar.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777
Merge remote-tracking branch 'origin/main' into al/docs/content-restr…
35527ca 
…ucture
@aaronlee777 @claude
fix(docs): add trailing slashes to LinkCardGrid category links
43df4f1 
Each category landing (company-onboarding, etc.) is emitted at
.../company-onboarding/index.html, so its canonical URL ends with a
slash. The absolute hrefs from the surface landing pages omitted the
slash, which left the in-app pathname without one. The relative
./workflow and ./sub-components links on the destination then resolved
up a directory and 404'd. Direct navigation worked only because the
browser canonicalized the URL on load.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777 @claude
docs: rename workflows-overview route/directory to surfaces
1daa86c 
The directory was already labeled "Surfaces" in the sidebar; rename
docs/workflows-overview to docs/surfaces and the index file to
surfaces.mdx so the URL matches: /docs/workflows-overview/* ->
/docs/surfaces/*. Update sidebar IDs, SurfacesGrid links, footer link,
NotFound page link, landing-page LinkCardGrid hrefs, and cross-doc
references in build-methods and composition guides.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777 @claude
docs: add Customize section, group hooks sidebar, tidy hooks landing
7115fb5 
- New Customize landing page (docs/customize/customize.mdx) grouping
  Theming and Component Adapter behind a single "Customize" sidebar
  category, with a 2-up LinkCardGrid on the landing.
- Hooks sidebar: replace the flat 3-hook list with two visually
  separated label groups (Company / Employee) using type: 'html'
  items styled by a new .sidebar-group-label rule (spacing, no
  divider), and expand the listing to every documented hook.
- Hooks landing: collapse the redundant Reference column — the Hook
  column itself is now the link to the reference page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronlee777 aaronlee777 marked this pull request as ready for review June 15, 2026 20:27
@aaronlee777 aaronlee777 requested a review from a team as a code owner June 15, 2026 20:27
@jeffredodd jeffredodd mentioned this pull request Jun 15, 2026
Closed
5 tasks
@aaronlee777
Merge remote-tracking branch 'origin/main' into al/docs/content-restr…
d3d9919 
…ucture

# Conflicts:
#	docs-site/sidebars.ts
#	docs/deciding-to-build-with-the-sdk/component-types.md
#	docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md
#	docs/surfaces/company-onboarding/sub-components.md
#	docs/surfaces/contractor-onboarding/sub-components.md
#	docs/surfaces/contractor-payments/sub-components.md
#	docs/surfaces/employee-onboarding/sub-components.md
#	docs/surfaces/employee-self-onboarding/sub-components.md
@aaronlee777
Merge remote-tracking branch 'origin/main' into al/docs/content-restr…
18a0cce 
…ucture
mariechatfield
mariechatfield requested changes Jun 15, 2026
View reviewed changes

@mariechatfield mariechatfield left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aaron can we sync on this one? Most of the content inside the workflows and hooks directories is going to be deleted as soon as I finish the backfill -- you can already see some of the content live at https://sdk.gusto.com/docs/api/Employee/EmployeeManagement/flows for example. I've been using these guides as fodder for the tsdoc content but the plan is to delete all these files as soon as we have stable paths we can point people towards instead

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mariechatfield mariechatfield mariechatfield requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@aaronlee777 @mariechatfield