diff --git a/.vscode/settings.json b/.vscode/settings.json
index 060a77ad40..3d2f97c3f0 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -28,7 +28,7 @@
"editor.detectIndentation": false,
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
- "[json][[jsonc][yaml][typespec][markdown][css][astro]": {
+ "[json][[jsonc][yaml][typespec][markdown][css][astro][mdx]": {
"editor.formatOnSave": true,
"editor.formatOnPaste": true,
"editor.insertSpaces": true,
diff --git a/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md b/docs/getting-started/getting-started-rest/01-setup-basic-syntax.mdx
similarity index 97%
rename from docs/getting-started/getting-started-rest/01-setup-basic-syntax.md
rename to docs/getting-started/getting-started-rest/01-setup-basic-syntax.mdx
index a9dfdcd2e7..5776fc3434 100644
--- a/docs/getting-started/getting-started-rest/01-setup-basic-syntax.md
+++ b/docs/getting-started/getting-started-rest/01-setup-basic-syntax.mdx
@@ -4,6 +4,8 @@ title: Getting Started with TypeSpec For REST APIs
pagination_next: getting-started/getting-started-rest/02-operations-responses # Explicitly needed as its also being the category page https://github.com/facebook/docusaurus/issues/6183
---
+import { FileTree } from "@astrojs/starlight/components";
+
## Introduction
Welcome to our tutorial on using TypeSpec to define REST APIs with HTTP. In this section, we'll introduce you to TypeSpec, help you set up your environment, and cover the basic syntax and structure of TypeSpec. By the end of this section, you'll have a solid foundation to build upon in the subsequent sections.
@@ -31,14 +33,17 @@ Before we start writing TypeSpec code, we need to set up our development environ
Once you've completed these steps, you'll have a basic TypeSpec project set up. Here's an overview of the files and directories in your TypeSpec project:
-```
-Project Root
-├── main.tsp
-├── tspconfig.yaml
-├── package.json
-├── node_modules/
-└── tsp-output/
-```
+{/* prettier-ignore */}
+
+- main.tsp
+- tspconfig.yaml
+- package.json
+- node_modules/
+- tsp-output/
+ - @typespec/
+ - openapi3/
+ - openapi.yaml
+
- **main.tsp**: Entry point for TypeSpec definitions.
- **tspconfig.yaml**: TypeSpec compiler configuration.
diff --git a/docs/getting-started/getting-started-rest/06-versioning.md b/docs/getting-started/getting-started-rest/06-versioning.mdx
similarity index 97%
rename from docs/getting-started/getting-started-rest/06-versioning.md
rename to docs/getting-started/getting-started-rest/06-versioning.mdx
index e79f0ea3f2..67f50fdada 100644
--- a/docs/getting-started/getting-started-rest/06-versioning.md
+++ b/docs/getting-started/getting-started-rest/06-versioning.mdx
@@ -2,6 +2,8 @@
title: Versioning
---
+import { FileTree } from "@astrojs/starlight/components";
+
## Introduction
In this section, we'll focus on implementing versioning in your REST API. Versioning allows you to manage changes to your API over time without breaking existing clients. We'll introduce the `@versioned` decorator, show how to define versions with enums, and demonstrate how to use the `@added` decorator to specify version-specific models and operations.
@@ -88,19 +90,18 @@ In this example:
Once we start adding versions, the TypeSpec compiler will generate individual OpenAPI specifications for each version. In our case, it will generate two OpenAPI specs, one for each version of our Pet Store service API. Our file structure will now look like this:
-```tsp
-main.tsp
-tspconfig.yaml
-package.json
-node_modules/
-tsp-output/
-┗ @typespec/
- ┗ openapi3/
- // highlight-start
- ┣ openapi.1.0.yaml
- ┗ openapi.2.0.yaml
- // highlight-end
-```
+{/* prettier-ignore */}
+
+- main.tsp
+- tspconfig.yaml
+- package.json
+- node_modules/
+- tsp-output/
+ - @typespec/
+ - openapi3
+ - openapi.1.0.yaml
+ - openapi.2.0.yaml
+
Generating separate specs for each version ensures backward compatibility, provides clear documentation for developers to understand differences between versions, and simplifies maintenance by allowing independent updates to each version's specifications.
diff --git a/docs/introduction/installation.md b/docs/introduction/installation.mdx
similarity index 91%
rename from docs/introduction/installation.md
rename to docs/introduction/installation.mdx
index 0dda6d00c1..665d286967 100644
--- a/docs/introduction/installation.md
+++ b/docs/introduction/installation.mdx
@@ -4,6 +4,8 @@ title: Installation
slug: docs
---
+import { FileTree } from "@astrojs/starlight/components";
+
## Requirements
Install [Node.js 20 LTS](https://nodejs.org/en/download/) and ensure you can run the `npm` command in a command prompt:
@@ -63,16 +65,17 @@ tsp compile .
You should now have a basic TypeSpec project setup with a structure looking like this:
-```bash
-main.tsp
-tspconfig.yaml
-package.json
-node_modules/
-tsp-output/
- @typespec/
- openapi3/
- openapi.yaml
-```
+{/* prettier-ignore */}
+
+- main.tsp
+- tspconfig.yaml
+- package.json
+- node_modules/
+- tsp-output/
+ - @typespec/
+ - openapi3/
+ - openapi.yaml
+
- **main.tsp**: The entry point for your TypeSpec build. This file typically contains the main definitions for your models, services, and operations.
- **tspconfig.yaml**: Configuration file for the TypeSpec compiler, specifying options and settings for the build process.