Fix more broken links and add stronger detection for broken links (#215)

mellson · web-flow · commit 1e63a915c9b7 · 2023-09-30T14:32:11.000+02:00
* Fix more broken links and add stronger detection for broken links

* update package json

* Try to get this to build on CI

* Testing

* Testing
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+  "editor.wordWrap": "on"
+}
diff --git a/docs/actions-and-actors/entry-and-exit-actions.mdx b/docs/actions-and-actors/entry-and-exit-actions.mdx
@@ -93,15 +93,15 @@ Use the <kbd>Backspace</kbd> key to delete the action.
 
 ## Add a built-in action
 
-You can add built-in XState actions which will be formatted in your [exported code](export-as-code.mdx). The options are:
+You can add built-in XState actions which will be formatted in your [exported code](/docs/export-as-code.mdx). The options are:
 
-- [assign](#assign-action): assigns data to the state context.
-- [raise](#raise-action): _raises_ an event that is received by the same machine.
-- [log](#log-action): an easy way to log messages to the console.
-- [sendTo](#send-to-action): sends an event to a specific actor.
-- [stop](#stop-action): stops a child actor.
+- [assign](/docs/xstate/actions/context#assign-action): assigns data to the state context.
+- [raise](/docs/xstate/actions/built-in-actions#raise-action): _raises_ an event that is received by the same machine.
+- [log](/docs/xstate/actions/built-in-actions#log-action): an easy way to log messages to the console.
+- [sendTo](/docs/xstate/actions/built-in-actions#sending-events-to-actors): sends an event to a specific actor.
+- [stop](/docs/xstate/actors/spawn#stopping-spawned-actors): stops a child actor.
 
-To add a built-in action, first add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-to-a-state), or [exit action](#add-an-exit-action-to-a-state).
+To add a built-in action, first add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
 
 ### On the canvas
 
@@ -114,15 +114,15 @@ To add a built-in action, first add a [transition action](#add-a-transition-acti
 
 1. Open the state, or event <Info size={18} /> **Details** panel from the right tool menu.
 1. Hover, focus, or select the action block to reveal the <Edit size={18} /> edit icon button.
-2. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
-3. Choose your desired action from the dropdown menu at the top of the **Action** panel.
-4. Fill out the required corresponding action input fields.
+1. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
+1. Choose your desired action from the dropdown menu at the top of the **Action** panel.
+1. Fill out the required corresponding action input fields.
 
 ## Add a custom action
 
-You can also add custom actions with a custom action type and parameters which will be formatted as [XState action objects](#action-objects) in your [exported code](export-as-code.mdx).
+You can also add custom actions with a custom action type and parameters which will be formatted as [XState action objects](/docs/xstate/actions) in your [exported code](/docs/export-as-code).
 
-First, add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-to-a-state), or [exit action](#add-an-exit-action-to-a-state).
+First, add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
 
 ### On the canvas
 
@@ -131,16 +131,16 @@ First, add a [transition action](#add-a-transition-action), [entry action](#add-
 3. Custom action is selected by default. Add your custom action type in the **Action type** text input.
 4. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
 
-[Read about action objects below for more on action types and and parameters](#action-objects).
+[Read about action objects below for more on action types and and parameters](/docs/xstate/actions).
 
 ### Using the details panel
 
 1. Open the state, or event <Info size={18} /> **Details** panel from the right tool menu.
 1. Hover, focus, or select the action block to reveal the <Edit size={18} /> edit icon button.
-2. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
-3. Custom action is selected by default. Add your custom action type in the **Action type** text input.
-4. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
-:::xstate
+1. Use the <Edit size={18} /> edit icon button to open the **Action** panel.
+1. Custom action is selected by default. Add your custom action type in the **Action type** text input.
+1. Add your custom **Action parameters** using the **Parameter key** and **Parameter value** text input pairs.
+   :::xstate
 
 ## Looking for how to use entry and exit actions in XState?
 
diff --git a/docs/studio.mdx b/docs/studio.mdx
@@ -27,7 +27,7 @@ Here you can find all the documentation for the Stately Studio and [XState](/xst
     </a>
   </li>
   <li>
-    <a className="link-box" href="/docs/xstate">
+    <a className="link-box" href="docs/xstate">
       💻 <strong>Learn XState</strong> Get started with our JavaScript and
       TypeScript library for state machines and statecharts.
     </a>
diff --git a/docs/tools/visualizer.mdx b/docs/tools/visualizer.mdx
@@ -17,7 +17,7 @@ Are you looking for the _Stately Studio_ visual _Editor_? Check out the [Stately
 
 :::tip
 
-Stately still supports the Stately Visualizer, but you will find many more advanced features, including the visual [Studio Editor](studio.mdx/#studio-editor), teams, and shared projects.
+Stately still supports the Stately Visualizer, but you will find many more advanced features, including the visual [Studio Editor](/studio.mdx#stately-studios-editor), teams, and shared projects.
 
 :::
 
diff --git a/docs/tools/xstate-vscode-extension.mdx b/docs/tools/xstate-vscode-extension.mdx
@@ -35,7 +35,7 @@ You can also [download the VS Code extension from the VS Code marketplace](https
 
 ## TypeScript typegen
 
-You can automatically generate intelligent typings for XState with our VS Code extension and [command line interface](/tools/developer-tools.mdx#xstate-cli-command-line-interface). [Read more about how to use typegen, and our recommended best practices, on the Typegen page](../xstate/typescript/typegen).
+You can automatically generate intelligent typings for XState with our VS Code extension and [command line interface](/tools/developer-tools.mdx#xstate-cli-command-line-interface). [Read more about how to use typegen, and our recommended best practices, on the Typegen page](/docs/xstate/typescript/typegen).
 
 ## `xsm` snippet
 
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -12,7 +12,7 @@ const config = {
   baseUrl: '/',
   baseUrlIssueBanner: false,
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+  onBrokenMarkdownLinks: 'throw',
   favicon: 'icon.svg',
   staticDirectories: ['static'],
 
@@ -90,7 +90,7 @@ const config = {
           blogSidebarCount: 0,
           postsPerPage: 10,
           editUrl: ({ locale, blogDirPath, blogPath, permalink }) =>
-            `https://github.com/statelyai/docs/edit/main/${blogDirPath}/${blogPath}`
+            `https://github.com/statelyai/docs/edit/main/${blogDirPath}/${blogPath}`,
         },
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
diff --git a/package.json b/package.json
@@ -1,11 +1,13 @@
 {
-  "name": "classic",
-  "version": "0.0.0",
-  "private": true,
+  "name": "stately-docs",
+  "version": "0.1.0",
+  "repository": "https://github.com/statelyai/docs",
   "scripts": {
     "docusaurus": "docusaurus",
-    "start": "docusaurus start",
-    "build": "docusaurus build",
+    "remark:once": "yarn remark --quiet --frail docs/**/* versioned_docs/**/*",
+    "remark:watch": "yarn remark --quiet --frail --watch docs/**/* versioned_docs/**/*",
+    "start": "concurrently \"yarn remark:watch\" \"yarn typecheck:watch\" \"docusaurus start\"",
+    "build": "yarn remark:once && yarn typecheck && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
@@ -14,9 +16,19 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc"
   },
+  "remarkConfig": {
+    "plugins": [
+      [
+        "remark-validate-links",
+        {
+          "repository": false
+        }
+      ]
+    ]
+  },
   "dependencies": {
-    "@docusaurus/core": "^2.4.1",
-    "@docusaurus/preset-classic": "^2.4.1",
+    "@docusaurus/core": "^2.4.3",
+    "@docusaurus/preset-classic": "^2.4.3",
     "@mdx-js/react": "^1.6.22",
     "@microsoft/api-extractor": "^7.35.1",
     "@xstate/inspect": "^0.8.0",
@@ -32,10 +44,13 @@
     "xstate": "^4.37.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.4.1",
+    "@docusaurus/module-type-aliases": "^2.4.3",
     "@fec/remark-a11y-emoji": "^3.1.0",
     "@tsconfig/docusaurus": "^1.0.7",
+    "concurrently": "^8.2.1",
     "dotenv": "^16.0.3",
+    "remark-cli": "^12.0.0",
+    "remark-validate-links": "^13.0.0",
     "typescript": "^5.0.4"
   },
   "browserslist": {
diff --git a/versioned_docs/version-5/actions.mdx b/versioned_docs/version-5/actions.mdx
@@ -129,7 +129,7 @@ You can add built-in XState actions which will be formatted in your [exported co
 - [sendTo](#send-to-action): sends an event to a specific actor.
 - [stop](#stop-action): stops a child actor.
 
-To add a built-in action, first add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-to-a-state), or [exit action](#add-an-exit-action-to-a-state).
+To add a built-in action, first add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
 
 ### On the canvas
 
@@ -150,7 +150,7 @@ To add a built-in action, first add a [transition action](#add-a-transition-acti
 
 You can also add custom actions with a custom action type and parameters which will be formatted as [XState action objects](#action-objects) in your [exported code](export-as-code.mdx).
 
-First, add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-to-a-state), or [exit action](#add-an-exit-action-to-a-state).
+First, add a [transition action](#add-a-transition-action), [entry action](#add-an-entry-action-or-exit-action-to-a-state), or [exit action](#add-an-entry-action-or-exit-action-to-a-state).
 
 ### On the canvas
 
diff --git a/versioned_docs/version-5/actors.mdx b/versioned_docs/version-5/actors.mdx
@@ -37,12 +37,12 @@ In the actor model, actors are objects that can communicate with each other. The
 
 Actor logic is the actor’s logical “model” (brain, blueprint, DNA, etc.) It describes how the actor should change behavior when receiving an event. You can create actor logic using **actor logic creators**. The types of actor logic you can create from XState are:
 
-- [State machine logic (`createMachine(...)`)](#TODO)
-- [Promise logic (`fromPromise(...)`)](#TODO)
-- [Transition logic (`fromTransition(...)`)](#TODO)
-- [Observable logic (`fromObservable(...)`)](#TODO)
-- [Event observable logic (`fromEventObservable(...)`)](#TODO)
-- [Callback logic (`fromCallback(...)`)](#TODO)
+- [State machine logic (`createMachine(...)`)](cheatsheet.mdx#creating-a-state-machine)
+- [Promise logic (`fromPromise(...)`)](cheatsheet.mdx#creating-promise-logic)
+- [Transition logic (`fromTransition(...)`)](cheatsheet.mdx#creating-promise-logic)
+- [Observable logic (`fromObservable(...)`)](cheatsheet.mdx#creating-observable-logic)
+- [Event observable logic (`fromEventObservable(...)`)](migration.mdx#use-actor-logic-creators-for-invokesrc-instead-of-functions)
+- [Callback logic (`fromCallback(...)`)](cheatsheet.mdx#creating-callback-logic)
 
 In XState, actor logic is defined by an object containing methods like `.transition(...)`, `.getInitialState()`, `.getSnapshot()`, and more. This object tells an interpreter how to update an actor’s internal state when it receives an event and which effects to execute (if any).
 
@@ -245,7 +245,7 @@ promiseActor.start();
 
 ## Transition actors
 
-Transition actor logic is described by a [transition function](#TODO), similar to a [reducer](#TODO). Transition functions take the current `state` and received `event` object as arguments, and return the next state. Actors created from transition logic (“transition actors”) can:
+Transition actor logic is described by a [transition function](migration.mdx#use-actor-logic-creators-for-invokesrc-instead-of-functions), similar to a [reducer](cheatsheet.mdx#creating-transition-logic). Transition functions take the current `state` and received `event` object as arguments, and return the next state. Actors created from transition logic (“transition actors”) can:
 
 - Receive events
 - Emit snapshots of its state
@@ -277,7 +277,7 @@ transitionActor.send({ type: 'increment' });
 
 ## Observable actors
 
-Observable actor logic is described by an [observable stream of values](#TODO). Actors created from observable logic (“observable actors”) can:
+Observable actor logic is described by an [observable stream of values](cheatsheet.mdx#creating-observable-logic). Actors created from observable logic (“observable actors”) can:
 
 - Emit snapshots of its emitted value
 
diff --git a/versioned_docs/version-5/developer-tools.mdx b/versioned_docs/version-5/developer-tools.mdx
@@ -3,7 +3,7 @@ title: 'Developer tools'
 description: 'Find out more about the Stately XState CLI (Command Line Interface) and Chrome Devtools.'
 ---
 
-Find more about our [XState CLI (Command Line Interface)](#xstate-cli-command-line-interface) and [Chrome Devtools](#chrome-devtools) below. We plan to make extensions for more IDEs (Integrated Development Environments) in the future.
+Find more about our [XState CLI (Command Line Interface)](#xstate-cli-command-line-interface) below. We plan to make extensions for more IDEs (Integrated Development Environments) in the future.
 
 :::xstate
 
diff --git a/versioned_docs/version-5/import-from-github.mdx b/versioned_docs/version-5/import-from-github.mdx
@@ -38,13 +38,13 @@ How to import all machines from a GitHub repository into a project:
   <ThemedImage
     alt="Stately Studio My Projects page showing a list of projects. Above the list is an Import from GitHub button, alongside the Create project button."
     sources={{
-      light: '/import-from-github/import.png',
-      dark: '/import-from-github/import-dm.png',
+      light: '/assets/import-from-github/import.png',
+      dark: '/assets/import-from-github/import-dm.png',
     }}
   />
 </p>
 
-You can [rename the project from the Project settings](projects#change-a-projects-name-description-and-keywords) and [change the project’s visibility from the editor’s share dialog](projects#change-a-projects-visibility).
+You can [change the project’s visibility from the editor’s share dialog](projects.mdx#change-a-projects-visibility).
 
 ### Import from a specific branch
 
diff --git a/versioned_docs/version-5/invoke.mdx b/versioned_docs/version-5/invoke.mdx
@@ -149,7 +149,7 @@ The actor snapshot is the latest emitted value from the actor. It can be read fr
 
 ## Kinds of actors
 
-- [Promises](actors.mdx#promise-actors)
+- [Promises](actors.mdx#promise-actor-logic)
 - [Machines](machines.mdx)
 - [Observables](actors.mdx#observable-actors)
 - [Transition functions](actors.mdx#transition-actors)
diff --git a/versioned_docs/version-5/lock-machines.mdx b/versioned_docs/version-5/lock-machines.mdx
@@ -18,7 +18,7 @@ Locking a machine prevents you, or anyone else on your team, from the following:
 - Deleting the machine
 - Renaming the machine
 - [Importing code](import-from-code.mdx) to replace the machine
-- [Restoring a past version](versions) of the machine
+- [Restoring a past version](versions.mdx) of the machine
 
 If somebody else is viewing or editing the machine when it is locked, their changes will not be saved, and they will be notified that the machine is now locked.
 
diff --git a/versioned_docs/version-5/quick-start.mdx b/versioned_docs/version-5/quick-start.mdx
@@ -132,7 +132,7 @@ export const toggleMachine = createMachine({
 
 ## Use your machine with a framework
 
-- [Check out all our packages](category/xstate-packages)
+- [Check out all our packages](/docs/xstate-v5/category/xstate-packages)
 - [Find out more about the `@xstate/react` package](xstate-react.mdx)
 
 ```jsx
diff --git a/versioned_docs/version-5/state-machines-and-statecharts.mdx b/versioned_docs/version-5/state-machines-and-statecharts.mdx
@@ -11,7 +11,10 @@ State machines are useful in software development because they help us capture a
 
 State machines model your application logic. Below is the logic for a video player. When the video is Played, it is opened into fullscreen mode. When the video is stopped, it closes out of fullscreen mode. When the video player is in fullscreen mode, it can be _Playing_ or _Paused_.
 
-<EmbedMachine name="Video player" embedURL="https://stately.ai/registry/editor/embed/e13bef2b-bb13-4465-96ac-0bc25340688e?machineId=dbcfca1c-075d-4cd6-a865-efcbd7be1544"/>
+<EmbedMachine
+  name="Video player"
+  embedURL="https://stately.ai/registry/editor/embed/e13bef2b-bb13-4465-96ac-0bc25340688e?machineId=dbcfca1c-075d-4cd6-a865-efcbd7be1544"
+/>
 
 ## Benefits of state machines
 
@@ -163,7 +166,7 @@ In the dog walking statechart, the final state would be **walk complete**.
 
 A parent state is a state that can contain more states, also known as child states. These child states can only happen when the parent state is happening. Inside the **on a walk** state, there could be the child states of **walking** and **running**.
 
-A parent state is symbolised by a labelled rectangle box that acts as a container for its child states. Parent states are sometimes known as *compound states*.
+A parent state is symbolised by a labelled rectangle box that acts as a container for its child states. Parent states are sometimes known as _compound states_.
 
 <!-- no alt because the image is already described in the surrounding text -->
 
@@ -238,7 +241,7 @@ In a **dog begging** process, there would be a **begging** state with a **gets t
 
 [View the dog begging machine in Stately Studio](https://stately.ai/registry/editor/1f84ff0d-fe41-4a92-ad5c-fadfa8b37ffb?machineId=1f43dcd3-255c-40bf-b6b0-eba9a2bccb23).
 
-[Read more about self transitions](transitions.mdx/#self-transitions)
+[Read more about self transitions](/transitions.mdx/#self-transitions)
 
 ## What next?
 
diff --git a/versioned_docs/version-5/studio.mdx b/versioned_docs/version-5/studio.mdx
@@ -14,7 +14,7 @@ Stately Studio is a suite of tools for building app logic, including the Editor,
   />
 </p>
 
-You can use [Stately Studio’s editor](#studio-editor) to model your logic using state machines and statecharts visually; no code required! Collaborate on your machines with coworkers and friends with [shared projects in teams](/#projects-and-teams). Use the [XState VS Code extension](xstate-vscode-extension.mdx) to use the editor with your codebase inside your code editor, or [export](/#export) your code from Stately Studio into your codebase.
+You can use [Stately Studio’s editor](/studio.mdx#stately-studios-editor) to model your logic using state machines and statecharts visually; no code required! Collaborate on your machines with coworkers and friends with [shared projects in teams](/#projects-and-teams). Use the [XState VS Code extension](xstate-vscode-extension.mdx) to use the editor with your codebase inside your code editor, or [export](/#export) your code from Stately Studio into your codebase.
 
 :::tip
 
diff --git a/versioned_docs/version-5/teams.mdx b/versioned_docs/version-5/teams.mdx
diff --git a/versioned_docs/version-5/typegen.mdx b/versioned_docs/version-5/typegen.mdx
diff --git a/versioned_docs/version-5/visualizer.mdx b/versioned_docs/version-5/visualizer.mdx
diff --git a/versioned_docs/version-5/xstate-vscode-extension.mdx b/versioned_docs/version-5/xstate-vscode-extension.mdx
diff --git a/versioned_docs/version-5/xstate.mdx b/versioned_docs/version-5/xstate.mdx
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "editor.wordWrap": "on"`
	`3`	`+}`