feat: Create structure for guided tutorial of the language by jderochervlk · Pull Request #1283 · rescript-lang/rescript-lang.org

jderochervlk · 2026-05-04T13:40:17Z

This is not complete or being deployed anywhere yet, but the shell is there.

ReScript.Guide.and.3.more.pages.-.Work.-.Microsoft.Edge.2026-05-04.15-03-56.mp4

The results panel is the value of the last expression in the editor
"Next" button is disabled until the expected value shows up in the results
reuses playground code so hover, type hints, formatting, etc... all work as expected

This does not:

have finished styling
any real content
a way to deploy it

Review follow-up notes:

The duplicated guide/playground/docs bindings were moved into packages/shared.
The shared Babel binding intentionally exposes only the AST shapes used by the playground validator and guide runtime transform. Babel dependencies are declared on the packages whose generated JS imports them directly: guide for parser/generator/types, playground for parser, and shared for its validator/generator/traverse usage. The generator binding uses Babel's named generate export because that is the callable ESM export.
apps/docs/src/components/Search.res changed as part of that cleanup because the old ReactRouter.navigate external pointed at a missing react-router-dom.navigate export. DocSearch now uses ReactRouter.useNavigate() inside the active search component and passes that navigate function into its navigator.

…ng.org into vlk/monorepo-foundation

Move shared editor/compiler helpers into @rescript-lang/shared and the playground implementation into @rescript-lang/playground. Wire the docs app to consume both workspace packages and keep playground browser storage access safe during prerendering.

…-fix # Conflicts: # .gitignore # __tests__/SidebarLayout_.test.res # __tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-breadcrumbs-chromium-linux.png # __tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-breadcrumbs-deep-chromium-linux.png # __tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-active-item-chromium-linux.png # __tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-chromium-linux.png # __tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-many-items-chromium-linux.png # __tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-with-toc-chromium-linux.png # apps/docs/__tests__/LandingPage_.test.res # apps/docs/__tests__/SidebarLayout_.test.res # apps/docs/__tests__/SidebarNav_.test.res # apps/docs/__tests__/__screenshots__/Breadcrumbs_.test.jsx/sidebar-breadcrumbs-chromium-linux.png # apps/docs/__tests__/__screenshots__/Breadcrumbs_.test.jsx/sidebar-breadcrumbs-deep-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-breadcrumbs-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-breadcrumbs-deep-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-active-item-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-many-items-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarLayout_.test.jsx/sidebar-category-with-toc-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarNav_.test.jsx/sidebar-category-active-item-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarNav_.test.jsx/sidebar-category-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarNav_.test.jsx/sidebar-category-many-items-chromium-linux.png # apps/docs/__tests__/__screenshots__/SidebarNav_.test.jsx/sidebar-category-with-toc-chromium-linux.png # apps/docs/app/routes/LandingPage.res # apps/docs/package.json # apps/docs/plugins/reason-highlightjs.js # apps/docs/src/bindings/Env.res # apps/docs/src/common/ColorTheme.res # apps/docs/src/common/ColorTheme.resi # apps/docs/src/common/Url.res # apps/docs/src/components/DocsonLazy.res # apps/docs/src/components/Search.res # apps/docs/src/layouts/SidebarLayout.res # apps/docs/src/layouts/SidebarLayout.resi # apps/docs/src/markdown/TocUtils.res # apps/docs/styles/_theme.css # apps/docs/vite.config.mjs # apps/docs/vitest.setup.mjs

Persist guide editor code in local storage and show a desktop-only message on narrow viewports, with browser coverage for both states.

Introduce the first guide lesson model, expected-output checkpoint evaluation, and localStorage progress/code storage in the rescript-guide:v1 namespace.

Add a function-call lesson that asks learners to change greet("ReScript") to greet("Spock") and completes the checkpoint when the output is Hello, Spock!.

Route guide lessons through React Router hash navigation so browser Back returns to the previous lesson. Disable playground URL syncing in the guide compiler bridge so compiler state does not overwrite lesson hashes.

Enable the final guide Done action once the checkpoint is complete and route it to the ReScript manual introduction. Cover the completed final lesson state and docs navigation target in guide browser tests.

github-actions · 2026-05-04T18:47:38Z

Cloudflare deployment

Deployement ID: 0496d981-c295-4314-95d4-b36cdc2a6c79
Deployment Environment: preview

⛅️ wrangler 4.85.0
───────────────────
✨ Compiled Worker successfully
Uploading... (8042/8044)
Uploading... (8043/8044)
Uploading... (8044/8044)
✨ Success! Uploaded 2 files (8042 already uploaded) (3.05 sec)

✨ Uploading _redirects
✨ Uploading Functions bundle
🌎 Deploying...
✨ Deployment complete! Take a peek over at https://0496d981.rescript-lang.pages.dev
✨ Deployment alias URL: https://vlk-guide-mvp.rescript-lang.pages.dev

Move the initial guide lessons into positioned MDX files and load them through the guide route loader. Parse frontmatter and markdown content in ReScript, keeping GuideLesson as the typed UI contract.

fhammerschmidt · 2026-05-05T09:17:53Z

This is already awesome!

github-actions · 2026-05-05T19:14:49Z

Cloudflare deployment

Deployement ID: 60dc1f0e-7511-4f05-a043-bb8ec6db689d
Deployment Environment: preview

⛅️ wrangler 4.85.0
───────────────────
✨ Compiled Worker successfully
Uploading... (8041/8044)
Uploading... (8042/8044)
Uploading... (8043/8044)
Uploading... (8044/8044)
✨ Success! Uploaded 3 files (8041 already uploaded) (2.01 sec)

✨ Uploading _redirects
✨ Uploading Functions bundle
🌎 Deploying...
✨ Deployment complete! Take a peek over at https://60dc1f0e.rescript-lang.pages.dev
✨ Deployment alias URL: https://vlk-guide-mvp.rescript-lang.pages.dev

Move duplicated guide and playground bindings into shared modules, update guide tests to use MemoryRouter and unsafe test accessors, and replace guide-only helpers with shared ReScript APIs. Also routes DocSearch navigation through useNavigate so the shared React Router binding no longer points at a missing react-router-dom export.

Move guide navigation, layout resizing, editor lifecycle, output rendering, and compiler bridge effects into focused modules. Add brief comments around the storage, hash, editor, and runtime import edge cases.

Break the guide browser tests into focused suites for compiler feedback, compiler settings, lessons, layout persistence, output rendering, and runtime transforms. Add runtime import helper coverage and keep GuideHome tests focused on integrated browser behavior.

Move guide runtime transformation onto the shared Babel bindings already used by playground code. Keep Babel package ownership in the shared workspace so guide code imports the shared API instead of declaring its own bindings.

Add short comments describing why the shared Babel surface stays narrow, why externals are wrapped, and why the generator binding uses Babel's named export.

Return the shared Babel module to direct externals and declare Babel dependencies on workspaces whose generated JavaScript imports them directly.

jderochervlk added 18 commits April 25, 2026 19:12

chore: add yarn workspaces

5026728

fix: honor workspace resolutions at root

9c7eb50

chore: move docs app into workspace

3bc1c9a

chore: update workspace root tooling

b136bda

fix: generate docs scripts before index updates

26d2f1e

fix: make root build work from clean checkout

c95c842

fix: resolve docs workspace paths

5237c1a

fix: update repository links for docs workspace

b962da6

fix: update deployment workflows for docs workspace

b991130

fix: update formatter ignores for docs workspace

ec10200

fix: run docs formatter from repo root

9814ff6

fix: correct users source link

a444f75

Merge branch 'master' of https://github.com/rescript-lang/rescript-la…

12a98e0

…ng.org into vlk/monorepo-foundation

fix: load docs env from workspace root

0d8e8f8

fix: handle nested public hrefs in docs checks

4222f00

fix: add root rescript monorepo config

d5b8df0

github-actions Bot deployed to preview May 4, 2026 13:54 View deployment

feat: add guide MVP

a7fee72

github-actions Bot deployed to preview May 4, 2026 14:54 View deployment

feat: persist guide editor state

83a0f00

Persist guide editor code in local storage and show a desktop-only message on narrow viewports, with browser coverage for both states.

github-actions Bot deployed to preview May 4, 2026 14:59 View deployment

feat: add guide checkpoint progress

2b6fb61

Introduce the first guide lesson model, expected-output checkpoint evaluation, and localStorage progress/code storage in the rescript-guide:v1 namespace.

github-actions Bot deployed to preview May 4, 2026 15:07 View deployment

feat: add second guide lesson

42d6c6d

Add a function-call lesson that asks learners to change greet("ReScript") to greet("Spock") and completes the checkpoint when the output is Hello, Spock!.

github-actions Bot deployed to preview May 4, 2026 15:38 View deployment

fix: support guide lesson back navigation

7101509

Route guide lessons through React Router hash navigation so browser Back returns to the previous lesson. Disable playground URL syncing in the guide compiler bridge so compiler state does not overwrite lesson hashes.

github-actions Bot requested a deployment to preview May 4, 2026 16:01 Abandoned

github-actions Bot deployed to preview May 4, 2026 16:06 View deployment

github-actions Bot deployed to preview May 4, 2026 17:58 View deployment

fix: enable completed guide done action

9636370

Enable the final guide Done action once the checkpoint is complete and route it to the ReScript manual introduction. Cover the completed final lesson state and docs navigation target in guide browser tests.

github-actions Bot deployed to preview May 4, 2026 18:47 View deployment

jderochervlk changed the title ~~Vlk/guide mvp~~ feat: Create structure for guided tutorial of the language May 4, 2026

feat: load guide lessons from mdx

e56e0f0

Move the initial guide lessons into positioned MDX files and load them through the guide route loader. Parse frontmatter and markdown content in ReScript, keeping GuideLesson as the typed UI contract.