Skip to content

Commit 7860fbe

Browse files
emir-karabegwaleedlatif1
emir-karabeg
and
waleedlatif1
authored
feat(docs): rebuild documentation with the shared Sim design system (#9459)
* feat(docs): rebuild documentation with the Paper design system * fix(docs): verify nested tabs and fresh-checkout CI setup * chore(docs): refresh preservation evidence against latest staging * fix(docs): align shared navigation and controls with Paper * fix(docs): share active heading across responsive outlines * fix(docs): track the final section at the end of the page * fix(docs): preserve sidebar scroll in a persistent layout * fix(docs): restore live screenshot backgrounds and framing * fix(docs): finish layout polish and clean implementation references * fix(docs): align shared dark theme and overlay states * fix(docs): remove dark borders from platform screenshots * test(docs): benchmark production navigation and image delivery in CI * fix(docs): preserve machine content and production reading contracts * fix(docs): retain readable tabs without JavaScript and verify current staging * fix(docs): expose root response schemas and generate clean-checkout types * fix(docs): resolve no-script tabs in the preflight cascade layer * perf(docs): import only the search schema constructors * fix(docs): preserve retrieval excerpts and reduce reading overhead * fix(docs): reuse in-flight intent prefetches during navigation * docs: record production readiness evidence and release requirements * docs: clarify optimizer measurement provenance * docs: preserve latest staging Search assets and compatibility evidence * fix(docs): polish responsive controls and keep search indexing current * test(docs): select the visible API example in browser checks * test(docs): execute native examples against streaming and binary responses * fix(docs): stream native API responses without buffering * test(docs): cover review regressions through public interfaces * fix(docs): preserve accessible examples and gate index publication * fix(docs): finish accessible controls and cached content validation * fix(docs): validate integration parents and report partial search failures * fix(docs): refine navigation and compact sample controls * fix(docs): isolate synchronous corpus validation from HTTP readers * fix(docs): restore Paper interaction styling and verify responsive controls * fix(docs): score each search page once per retrieval source * fix(docs): attribute benchmark metrics to their source document --------- Co-authored-by: Waleed Latif <walif6@gmail.com>
1 parent 91479e6 commit 7860fbe

330 files changed

Lines changed: 337244 additions & 7180 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,6 @@ Dockerfile* text eol=lf
4141
*.ttf binary
4242
*.eot binary
4343
*.pdf binary
44+
45+
apps/docs/migration/report.json linguist-generated=true
46+
apps/docs/migration/verification/** linguist-generated=true

‎.github/workflows/checks.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -684,6 +684,9 @@ jobs:
684684
tar -xzf "$archive" -C "$RUNNER_TEMP" actionlint
685685
"$RUNNER_TEMP/actionlint" -color -shellcheck= -pyflakes=
686686
687+
- name: Generate documentation modules for import audits
688+
run: bun run --cwd apps/docs content:generate
689+
687690
# Every zero-argument `check:*` script, run concurrently. The list is derived in
688691
# scripts/run-audits.ts, which also writes the per-audit timing table to the job
689692
# summary and annotates failures. Audits needing a base ref stay separate below.

‎.github/workflows/ci.yml‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1149,9 +1149,20 @@ jobs:
11491149
with:
11501150
filters: |
11511151
docs:
1152-
- 'apps/docs/content/docs/**'
1153-
- 'apps/sim/scripts/process-docs.ts'
1154-
- 'apps/sim/lib/chunkers/**'
1152+
- 'apps/docs/content/**'
1153+
- 'apps/docs/components/workflow-preview/examples.ts'
1154+
- 'apps/docs/components/workflow-preview/block-display-workflows.ts'
1155+
- 'apps/docs/scripts/compile-content.ts'
1156+
- 'apps/docs/scripts/index-search.ts'
1157+
- 'apps/docs/lib/content/**'
1158+
- 'apps/docs/lib/search/**'
1159+
- 'apps/docs/lib/openapi-specs.ts'
1160+
- 'apps/docs/lib/urls.ts'
1161+
- 'apps/docs/openapi*.json'
1162+
- 'apps/docs/package.json'
1163+
- 'bun.lock'
1164+
- '.github/workflows/docs.yml'
1165+
- '.github/workflows/ci.yml'
11551166
11561167
# Process docs embeddings (only when docs change, after images are promoted)
11571168
docs:

‎.github/workflows/docs-negotiation.yml‎

Lines changed: 203 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -17,51 +17,242 @@ on:
1717
- 'bun.lock'
1818
- '.github/workflows/docs-negotiation.yml'
1919
workflow_dispatch:
20+
inputs:
21+
benchmark:
22+
description: Run bounded production navigation, image and Lighthouse measurements
23+
type: boolean
24+
default: false
25+
build_ref:
26+
description: Commit to build for the benchmark (empty uses this workflow revision)
27+
type: string
28+
default: ''
29+
preview_artifact:
30+
description: Save the verified production build for local visual inspection
31+
type: boolean
32+
default: false
33+
benchmark_scope:
34+
description: Full measurements, navigation without Lighthouse, or only interactive controls
35+
type: choice
36+
options: [full, navigation, interactions]
37+
default: full
38+
benchmark_production:
39+
description: Also measure the public production origin (only when it permits automated access)
40+
type: boolean
41+
default: false
2042

2143
permissions:
2244
contents: read
2345

2446
concurrency:
25-
group: docs-negotiation-${{ github.ref }}
26-
cancel-in-progress: true
47+
group: docs-negotiation-${{ github.ref }}-${{ inputs.benchmark && 'benchmark' || 'verification' }}
48+
cancel-in-progress: ${{ !inputs.benchmark }}
2749

2850
jobs:
51+
benchmark:
52+
if: github.event_name == 'workflow_dispatch' && inputs.benchmark
53+
name: docs benchmark (${{ matrix.target }})
54+
runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'linux-x64-8-core' }}
55+
timeout-minutes: 150
56+
strategy:
57+
fail-fast: false
58+
max-parallel: 2
59+
matrix:
60+
target: ${{ fromJSON(inputs.benchmark_production && '["build","production"]' || '["build"]') }}
61+
env:
62+
DATABASE_URL: ''
63+
OPENAI_API_KEY: ''
64+
DOCS_BENCHMARK_BASE_URL: ${{ matrix.target == 'production' && 'https://docs.sim.ai' || 'http://127.0.0.1:3001' }}
65+
steps:
66+
- name: Checkout measured revision
67+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
68+
with:
69+
ref: ${{ inputs.build_ref || github.sha }}
70+
fetch-depth: 0
71+
filter: blob:none
72+
- name: Setup workspace
73+
uses: ./.github/actions/setup
74+
with:
75+
provider: ${{ vars.CI_PROVIDER }}
76+
- name: Checkout benchmark harness
77+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
78+
with:
79+
ref: ${{ github.sha }}
80+
path: .readiness-harness
81+
sparse-checkout: apps/docs/scripts/benchmark-readiness.ts
82+
sparse-checkout-cone-mode: false
83+
- name: Prepare measurements
84+
env:
85+
GH_TOKEN: ${{ github.token }}
86+
MEASURED_TARGET: ${{ matrix.target }}
87+
run: |
88+
mkdir -p test-results/benchmark
89+
cp .readiness-harness/apps/docs/scripts/benchmark-readiness.ts apps/docs/scripts/benchmark-readiness.ts
90+
if [ "$MEASURED_TARGET" = production ]; then
91+
gh api "repos/$GITHUB_REPOSITORY/deployments?environment=Production&per_page=1" >test-results/benchmark/deployment.json
92+
# Candidate deployments do not establish which revision owns the public alias.
93+
REVISION=unverified-public-origin
94+
else
95+
REVISION=$(git rev-parse HEAD)
96+
fi
97+
echo "DOCS_BENCHMARK_REVISION=$REVISION" >> "$GITHUB_ENV"
98+
bunx --no-install playwright install --with-deps chromium
99+
- name: Build measured production docs
100+
id: build
101+
if: matrix.target == 'build'
102+
run: bun run --cwd apps/docs build
103+
- name: Measure navigation and Lighthouse sequentially
104+
env:
105+
BENCHMARK_SCOPE: ${{ inputs.benchmark_scope || 'full' }}
106+
run: |
107+
if [ "$DOCS_BENCHMARK_BASE_URL" = http://127.0.0.1:3001 ]; then
108+
bun run --cwd apps/docs start --port 3001 >test-results/benchmark/server.log 2>&1 &
109+
DOCS_SERVER_PID=$!
110+
trap 'kill "$DOCS_SERVER_PID" 2>/dev/null || true' EXIT
111+
for attempt in $(seq 1 30); do
112+
curl -fsS "$DOCS_BENCHMARK_BASE_URL/introduction" -o /dev/null && break
113+
sleep 1
114+
done
115+
fi
116+
NAVIGATION_STATUS=0
117+
LIGHTHOUSE_STATUS=0
118+
if [ "$BENCHMARK_SCOPE" = interactions ]; then
119+
export DOCS_BENCHMARK_SCENARIOS=interactions
120+
fi
121+
DOCS_BENCHMARK_MODE=navigation DOCS_BENCHMARK_REPORT_PATH="$GITHUB_WORKSPACE/test-results/benchmark/navigation.json" bun run --cwd apps/docs scripts/benchmark-readiness.ts || NAVIGATION_STATUS=$?
122+
if [ "$BENCHMARK_SCOPE" = full ]; then
123+
DOCS_BENCHMARK_MODE=lighthouse DOCS_BENCHMARK_REPORT_PATH="$GITHUB_WORKSPACE/test-results/benchmark/lighthouse.json" bun run --cwd apps/docs scripts/benchmark-readiness.ts || LIGHTHOUSE_STATUS=$?
124+
fi
125+
test "$NAVIGATION_STATUS" -eq 0 && test "$LIGHTHOUSE_STATUS" -eq 0
126+
- name: Upload measurements
127+
if: always()
128+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
129+
with:
130+
name: docs-benchmark-${{ matrix.target }}
131+
path: test-results/benchmark/
132+
retention-days: 14
133+
- name: Package measured production preview
134+
if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
135+
run: tar -czf docs-preview-build.tar.gz --exclude='.next/cache' -C apps/docs .next .content
136+
- name: Upload measured production preview
137+
if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
138+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
139+
with:
140+
name: docs-preview-build
141+
path: docs-preview-build.tar.gz
142+
retention-days: 3
143+
29144
http:
145+
if: github.event_name != 'workflow_dispatch' || !inputs.benchmark
30146
name: docs HTTP
31147
runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'linux-x64-8-core' }}
32-
timeout-minutes: 15
148+
timeout-minutes: 45
149+
services:
150+
search-postgres:
151+
image: pgvector/pgvector:pg17
152+
env:
153+
POSTGRES_USER: docs_test
154+
POSTGRES_PASSWORD: docs_test
155+
POSTGRES_DB: docs_search_test
156+
ports:
157+
- 5432:5432
158+
options: >-
159+
--health-cmd "pg_isready -U docs_test -d docs_search_test"
160+
--health-interval 5s
161+
--health-timeout 5s
162+
--health-retries 10
33163
env:
34164
DATABASE_URL: postgresql://docs_test:docs_test@127.0.0.1:1/docs_test
35165
DOCS_E2E_BASE_URL: http://127.0.0.1:3001
36-
DOCS_NEGOTIATION_REPORT_PATH: ${{ github.workspace }}/test-results/docs-negotiation.json
37-
DOCS_HEADER_REPORT_PATH: ${{ github.workspace }}/test-results/docs-headers.json
38-
DOCS_NAVIGATION_REPORT_PATH: ${{ github.workspace }}/test-results/navigation/docs.json
166+
DOCS_NEGOTIATION_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-negotiation.json
167+
DOCS_SEARCH_E2E_DATABASE_URL: postgresql://docs_test:docs_test@127.0.0.1:5432/docs_search_test
168+
DOCS_SEARCH_E2E_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/search-postgres/report.json
169+
DOCS_INTERFACES_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-interfaces.json
170+
DOCS_CORPUS_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-corpus.json
171+
DOCS_HEADER_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/docs-headers.json
172+
DOCS_NAVIGATION_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/navigation/docs.json
173+
DOCS_GENERATORS_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/generators/report.json
174+
DOCS_MIGRATION_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/migration.json
175+
DOCS_SAMPLES_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/samples/report.json
176+
DOCS_SAMPLES_SYNTAX_LANGUAGES: javascript,python,bash,go,java,csharp
177+
DOCS_SAMPLES_HTTP_BASE_URL: http://127.0.0.1:3001
178+
DOCS_PROVIDER_E2E_DATABASE_URL: postgresql://docs_test:docs_test@127.0.0.1:5432/docs_search_test
179+
DOCS_PROVIDER_E2E_BASE_URL: http://127.0.0.1:3001
180+
DOCS_PROVIDER_E2E_REPORT_PATH: ${{ github.workspace }}/apps/docs/test-results/platform-consumer/report.json
39181
steps:
40182
- name: Checkout code
41183
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
184+
with:
185+
fetch-depth: 0
186+
filter: blob:none
42187
- name: Setup workspace
43188
uses: ./.github/actions/setup
44189
with:
45190
provider: ${{ vars.CI_PROVIDER }}
46191
- name: Build production docs
192+
id: build
47193
run: bun run --cwd apps/docs build
194+
- name: Verify generator idempotence and authored regions
195+
run: bun run --cwd apps/docs scripts/test-generators-e2e.ts
196+
- name: Verify preserved routes, anchors and examples
197+
if: always() && steps.build.outcome == 'success'
198+
run: bun run --cwd apps/docs content:verify-migration
48199
- name: Verify native header edge cases
200+
if: always() && steps.build.outcome == 'success'
49201
run: bun run --cwd apps/docs test:headers:e2e
202+
- name: Verify isolated PostgreSQL search and index lifecycle
203+
if: always() && steps.build.outcome == 'success'
204+
run: bun run --cwd apps/docs test:search:postgres:e2e
205+
- name: Set up Java for copied request examples
206+
if: always() && steps.build.outcome == 'success'
207+
uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5
208+
with:
209+
distribution: temurin
210+
java-version: '17'
211+
- name: Set up .NET for copied request examples
212+
if: always() && steps.build.outcome == 'success'
213+
uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5
214+
with:
215+
dotnet-version: '8.0.x'
216+
- name: Set up Go for copied request examples
217+
if: always() && steps.build.outcome == 'success'
218+
uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
219+
with:
220+
go-version: '1.25.x'
221+
cache: false
50222
- name: Install browser for navigation checks
51-
run: bunx --no-install playwright install --with-deps chromium
223+
if: always() && steps.build.outcome == 'success'
224+
run: bunx --no-install playwright install --with-deps chromium webkit
52225
- name: Verify HTTP content negotiation
226+
if: always() && steps.build.outcome == 'success'
53227
run: |
54-
mkdir -p test-results
55-
bun run --cwd apps/docs start --port 3001 >test-results/docs-server.log 2>&1 &
228+
mkdir -p apps/docs/test-results
229+
bun run --cwd apps/docs start --port 3001 >apps/docs/test-results/docs-server.log 2>&1 &
56230
DOCS_SERVER_PID=$!
57231
trap 'kill "$DOCS_SERVER_PID" 2>/dev/null || true' EXIT
58-
bun run --cwd apps/docs test:negotiation:e2e
59-
bun run --cwd apps/docs test:navigation:e2e
232+
STATUS=0
233+
bun run --cwd apps/docs test:negotiation:e2e || STATUS=1
234+
bun run --cwd apps/docs scripts/test-docs-interfaces-e2e.ts || STATUS=1
235+
bun run --cwd apps/docs test:corpus:e2e || STATUS=1
236+
bun run --cwd apps/docs scripts/verify-api-samples.ts || STATUS=1
237+
bun --cwd apps/sim --no-env-file scripts/test-docs-search-provider-e2e.ts || STATUS=1
238+
bun run --cwd apps/docs test:navigation:e2e || STATUS=1
239+
DOCS_NAVIGATION_BROWSER=webkit DOCS_NAVIGATION_REPORT_PATH="$GITHUB_WORKSPACE/apps/docs/test-results/navigation-webkit/docs.json" bun run --cwd apps/docs test:navigation:e2e || STATUS=1
240+
exit "$STATUS"
241+
- name: Package production preview for visual inspection
242+
if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
243+
run: tar -czf docs-preview-build.tar.gz --exclude='.next/cache' -C apps/docs .next .content
244+
- name: Upload production preview
245+
if: always() && inputs.preview_artifact && steps.build.outcome == 'success'
246+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
247+
with:
248+
name: docs-preview-build
249+
path: docs-preview-build.tar.gz
250+
retention-days: 3
60251
- name: Upload HTTP regression report
61252
if: always()
62253
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
63254
with:
64255
name: docs-negotiation-report
65-
path: test-results/
256+
path: apps/docs/test-results/
66257
if-no-files-found: warn
67258
retention-days: 14

‎.github/workflows/docs.yml‎

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,25 @@ on:
77
required: false
88
OPENAI_API_KEY:
99
required: false
10-
workflow_dispatch: # Allow manual triggering
10+
workflow_dispatch:
11+
inputs:
12+
publish:
13+
description: I verified the matching docs deployment and a restorable index backup
14+
type: boolean
15+
required: true
16+
default: false
17+
deployed_revision:
18+
description: Full source SHA of the verified serving docs deployment
19+
type: string
20+
required: true
21+
deployment_id:
22+
description: Verified serving docs deployment ID
23+
type: string
24+
required: true
25+
backup_reference:
26+
description: Restorable docs_embeddings backup identifier (no credentials)
27+
type: string
28+
required: true
1129

1230
permissions:
1331
contents: read
@@ -18,23 +36,53 @@ jobs:
1836
# Network-bound on the embeddings API: ~9% CPU and ~3% peak memory on 8 vCPU.
1937
runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
2038
timeout-minutes: 30
21-
if: github.ref == 'refs/heads/main'
39+
if: github.ref == 'refs/heads/main' && github.event_name == 'workflow_dispatch' && inputs.publish
40+
concurrency:
41+
group: docs-search-index-production
42+
cancel-in-progress: false
2243

2344
steps:
45+
- name: Record verified deployment and backup
46+
env:
47+
DEPLOYED_REVISION: ${{ inputs.deployed_revision }}
48+
DEPLOYMENT_ID: ${{ inputs.deployment_id }}
49+
BACKUP_REFERENCE: ${{ inputs.backup_reference }}
50+
run: |
51+
test "$DEPLOYED_REVISION" = "$GITHUB_SHA"
52+
test -n "$DEPLOYMENT_ID"
53+
test -n "$BACKUP_REFERENCE"
54+
jq -n --arg revision "$DEPLOYED_REVISION" --arg deployment "$DEPLOYMENT_ID" \
55+
--arg backup "$BACKUP_REFERENCE" --arg actor "$GITHUB_ACTOR" \
56+
'{revision: $revision, deploymentId: $deployment, backupReference: $backup, verifiedBy: $actor}' \
57+
> "$RUNNER_TEMP/docs-search-authorization.json"
58+
2459
- name: Checkout code
2560
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
2661
with:
62+
ref: ${{ github.sha }}
2763
persist-credentials: false
2864

2965
- name: Setup workspace
3066
uses: ./.github/actions/setup
3167
with:
3268
provider: ${{ vars.CI_PROVIDER }}
33-
node-version: '22'
69+
node-version: '24'
3470

3571
- name: Process docs embeddings
36-
working-directory: ./apps/sim
72+
working-directory: ./apps/docs
3773
env:
3874
DATABASE_URL: ${{ secrets.DATABASE_URL }}
3975
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
40-
run: bun run scripts/process-docs.ts --clear
76+
run: |
77+
bun run content:generate
78+
DOCS_SEARCH_REPORT_PATH=test-results/docs-search-publish.json bun run scripts/index-search.ts
79+
DOCS_SEARCH_REPORT_PATH=test-results/docs-search-check.json bun run scripts/index-search.ts --check
80+
81+
- name: Upload search index report
82+
if: always()
83+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
84+
with:
85+
name: docs-search-index
86+
path: |
87+
apps/docs/test-results/docs-search-*.json
88+
${{ runner.temp }}/docs-search-authorization.json

‎apps/docs/.gitignore‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,10 @@ bun-debug.log*
3535
*.tsbuildinfo
3636
next-env.d.ts
3737

38-
# Fumadocs
39-
/.source/
38+
# Build-generated content
39+
/.content/
4040
.plans/
4141

42-
# fumadocs generates .source dirs anywhere a source.config sits
43-
**/.source/
44-
4542
# Build-generated documentation asset
4643
/public/llms-full.txt
4744
/public/.llms-full-*/

0 commit comments

Comments
 (0)