StackBlitz

Embed StackBlitz projects into VitePress pages. Supports embedding online editors via StackBlitz ID, GitHub repository, or local project files. Can also display as a button to open in a new tab.

Installation

pnpm add vitepress-plugin-stackblitz

npm install vitepress-plugin-stackblitz

bun add vitepress-plugin-stackblitz

deno add vitepress-plugin-stackblitz

yarn add vitepress-plugin-stackblitz

Usage

vitepress-tuck Mode Recommended

.vitepress/config.ts

import { defineConfig } from 'vitepress-tuck'
import stackblitz from 'vitepress-plugin-stackblitz'

export default defineConfig({
  plugins: [stackblitz()],
})

Learn more about vitepress-tuck

Native Mode

.vitepress/config.ts

import { defineConfig } from 'vitepress'
import { stackblitzMarkdownPlugin } from 'vitepress-plugin-stackblitz'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(stackblitzMarkdownPlugin)
    },
  },
})

.vitepress/theme/index.ts

import type { Theme } from 'vitepress'
import { enhanceAppWithStackBlitz } from 'vitepress-plugin-stackblitz/client'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    enhanceAppWithStackBlitz(ctx)
  },
} satisfies Theme

Syntax

The plugin provides two syntaxes for embedding StackBlitz projects: embed syntax for referencing external projects, and container syntax for writing project files directly inline within Markdown.

Embed by StackBlitz ID

@[stackblitz](sdk-github-project)

Embed by GitHub Repository

@[stackblitz github](user/repo)

Embed Local Project

Place a stackblitz.config.json (or .yaml, .yml) configuration file in your project directory, then use the local attribute:

@[stackblitz local](path/to/your/project)

path supports the following prefixes:

Prefix	Description
`@`	Relative to VitePress `srcDir`
`/`	Relative to VitePress project root
-	Relative to the current markdown file's directory

See Local Project Configuration for more details.

Button Mode

Display as a button that opens the project in a new tab:

@[stackblitz button](stackblitz-id)

It can also be combined with GitHub:

@[stackblitz github button](user/repo)

Container Syntax

Write project files directly inline within Markdown, ideal for quickly demonstrating simple projects:

::: stackblitz title="Project" description="Project description" template="javascript"

```yml [config]
title: Project
template: javascript
description: Project description
```

```json [package.json]
{
  "name": "project",
  "version": "1.0.0"
}
```

```js [index.js]
console.log('Hello StackBlitz!');
```

```html [index.html]
<!DOCTYPE html>
<html lang="en">
<body>
  <h1>Hello StackBlitz!</h1>
  <script src="./index.js"></script>
</body>
</html>
```

:::

Attribute Reference

Embed / Open Options

Applicable to both embed syntax and button mode:

Attribute	Type	Default	Description
`theme`	`'dark' \| 'light' \| 'default'`	auto	Color theme, auto follows VitePress dark mode
`view`	`'default' \| 'preview' \| 'editor'`	`'default'`	Initial UI view
`height`	`number`	`400`	Embed height (embed mode only)
`width`	`number`	-	Embed width (embed mode only)
`clickToLoad`	`boolean`	`false`	Show "click to run" dialog
`openFile`	`string \| string[]`	-	File(s) to open on load
`hideExplorer`	`boolean`	`false`	Hide the file explorer
`hideDevTools`	`boolean`	`false`	Hide the dev tools console
`showSidebar`	`boolean`	`false`	Show sidebar as open on load
`terminalHeight`	`number` (0-100)	-	Terminal height percentage
`devToolsHeight`	`number` (0-100)	-	Dev tools height percentage
`newWindow`	`boolean`	`false`	Open project in a new tab
`forceEmbedLayout`	`boolean`	`false`	Force embed layout (deprecated)
`origin`	`string`	-	StackBlitz EE instance URL

Project Options

Only applicable to local project embed mode and container syntax:

Attribute	Type	Default	Description
`title`	`string`	-	Project title (required)
`description`	`string`	-	Project description (required)
`template`	`'angular-cli' \| 'create-react-app' \| 'html' \| 'javascript' \| 'typescript' \| 'polymer' \| 'vue' \| 'node'`	-	Project template (required)
`dependencies`	`Record<string, string>`	-	npm dependencies
`files`	`Record<string, string>`	-	Project files (auto-loaded for local mode)

Build Settings

Set via settings-prefixed attributes, only applicable to local project embed mode and container syntax:

Attribute	Type	Default	Description
`settingsTrigger`	`'auto' \| 'save' \| 'keystroke'`	`'auto'`	Compilation trigger timing
`settingsAction`	`'hmr' \| 'refresh'`	`'hmr'`	How to inject compiled changes
`settingsClearConsole`	`boolean`	`true`	Clear console after compilation

@[stackblitz local title="Demo" description="A demo" template="html" settingsTrigger="save" settingsAction="refresh"](path/to/project)

Local Project Configuration

When using @[stackblitz local](path) to embed a local project, the plugin automatically:

Loads all files from the specified directory (excluding node_modules)
Searches for stackblitz.config.json, stackblitz.config.yaml, stackblitz.config.yml in order
Merges the configuration file options with the loaded files

Example stackblitz.config.json:

json

{
  "$schema": "../../node_modules/vitepress-plugin-stackblitz/schema.json",
  "title": "Project",
  "description": "Project description",
  "template": "javascript",
  "dependencies": {
    "lodash": "^4.17.0"
  },
  "settings": {
    "trigger": "save"
  }
}

TIP

Including the $schema field provides intelligent autocompletion and validation for configuration files in your editor.

json

{
  "$schema": "https://unpkg.com/vitepress-plugin-stackblitz/schema.json"
}

Example

StackBlitz ID Embed

@[stackblitz](sdk-github-project)

Button Mode

@[stackblitz button](sdk-github-project)

Container Syntax

::: stackblitz button

```yml [config]
title: Project
template: javascript
description: Project description
```

```json [package.json]
{
  "name": "project",
  "version": "1.0.0",
  "description": "Project description",
  "main": "index.js",
  "keywords": ["project"],
  "author": "Project Author",
  "license": "MIT"
}
```

```js [index.js]
console.log('Hello StackBlitz!');
```

```html [index.html]
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Project</title>
</head>
<body>
  <h1>Hello StackBlitz!</h1>
  <script src="./index.js"></script>
</body>
</html>
```

:::

Local Project Embed

index.html

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  <h1>StackBlitz</h1>
  <script src="./index.js"></script>
</body>
</html>

index.js

// eslint-disable-next-line no-console
console.log('StackBlitz')

package.json

json

{
  "name": "stackblitz",
  "type": "module",
  "private": true
}

stackblitz.config.json

json

{
  "$schema": "https://unpkg.com/vitepress-plugin-stackblitz/schema.json",
  "title": "Project",
  "description": "Project description",
  "template": "javascript",
  "dependencies": {}
}

@[stackblitz local](@/snippets/stack)

StackBlitz ​

Installation ​

Usage ​

vitepress-tuck Mode Recommended ​

Native Mode ​

Syntax ​

Embed by StackBlitz ID ​

Embed by GitHub Repository ​

Embed Local Project ​

Button Mode ​

Container Syntax ​

Attribute Reference ​

Embed / Open Options ​

Project Options ​

Build Settings ​

Local Project Configuration ​

Example ​

StackBlitz ID Embed ​

Button Mode ​

Container Syntax ​

Local Project Embed ​

StackBlitz

Installation

Usage

vitepress-tuck Mode Recommended

Native Mode

Syntax

Embed by StackBlitz ID

Embed by GitHub Repository

Embed Local Project

Button Mode

Container Syntax

Attribute Reference

Embed / Open Options

Project Options

Build Settings

Local Project Configuration

Example

StackBlitz ID Embed

Button Mode

Container Syntax

Local Project Embed