Installation 🪛

Before using the editor, take the steps detailed below.

0. Install VitePress

If you don't already have a VitePress project, install VitePress and run its setup wizard.

1. Add dependency

First, add vitepress-python-editor as a dependency:

npm

npm install vitepress-python-editor

yarn

yarn add vitepress-python-editor

pnpm

pnpm add vitepress-python-editor

bun

bun add vitepress-python-editor

2. Configure Vite plugin

Then, add the Vite plugin to your VitePress config like so:

.vitepress/config.js

import { defaultConfig } from 'vitepress'
import { vitepressPythonEditor } from 'vitepress-python-editor/vite-plugin'

export defaultConfig({
  vite: {
    plugins: [
      vitepressPythonEditor(),
    ],
  },
})

If your VitePress assetsDir does not resolve to .vitepress/dist/assets (relative to the project root), pass the fully resolved path to the plugin:

.vitepress/config.js

import { defaultConfig } from 'vitepress'
import { vitepressPythonEditor } from 'vitepress-python-editor/vite-plugin'

export defaultConfig({
  vite: {
    plugins: [
      vitepressPythonEditor({ assetsDir: 'docs/.vitepress/dist/assets' }),
    ],
  },
})

3. Register global component

Next, register the editor as a VitePress global component:

.vitepress/theme/index.js

import DefaultTheme from 'vitepress/theme'
import Editor from 'vitepress-python-editor'

/** @type {import('vitepress').Theme} */
export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('Editor', Editor)
  },
}

.vitepress/theme/index.ts

import DefaultTheme from 'vitepress/theme'
import Editor from 'vitepress-python-editor'
import type { Theme } from 'vitepress'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('Editor', Editor)
  },
} satisfies Theme

This avoids the need to import the editor with a <script setup> block in each .md file.

4. Set HTTP headers

Finally, on your website host, add the following headers to fulfill the security requirements for SharedArrayBuffer:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

The exact config will vary by provider. Here are some examples:

netlify.toml

[[headers]]
  for = "/*"
  [headers.values]
    Cross-Origin-Opener-Policy = "same-origin"
    Cross-Origin-Embedder-Policy = "require-corp"

vercel.json

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Cross-Origin-Opener-Policy",
          "value": "same-origin"
        },
        {
          "key": "Cross-Origin-Embedder-Policy",
          "value": "require-corp"
        }
      ]
    } 
  ]
}

_headers

/*
  Cross-Origin-Opener-Policy = "same-origin"
  Cross-Origin-Embedder-Policy = "require-corp"

For details, see the specific documentation for each provider:

• Netlify
• Vercel
• Cloudflare Pages

TIP

As of writing, GitHub Pages does not have an easy way to add these headers. It is suggested to use one of the providers above as an alternative, all of which have serviceable free plans.