diff --git a/docs/src/vitepress.md b/docs/src/vitepress.md index 6ecf3ad..5d6785a 100644 --- a/docs/src/vitepress.md +++ b/docs/src/vitepress.md @@ -1,21 +1,117 @@ # Usage with DocumenterVitepress PlotlyDocumenter provides an extension to work with DocumenterVitepress. As raw javascript code cannot be executed in Vue, an alternate approach is required. -For this reason, when using DocumenterVitepress, the custom plot object will be rendered as the `` component from the [vue3-plotly-ts](https://github.com/boscoh/vue3-plotly-ts) package. +For this reason, when using DocumenterVitepress, the custom plot object will be rendered as the `` component. !!! warning The keyword arguments for `to_documenter` are ignored when using DocumenterVitepress. -To make this work, first install the `vue3-plotly-ts` package in your project: +To make this work, first install the `plotly.js-dist-min` package and associated types `@types/plotly.js-dist-min` in your project: ```bash -npm install vue3-plotly-ts +npm install plotly.js-dist-min +npm install --save-dev @types/plotly.js-dist-min ``` -Then, add the `VuePlotly` component to your `.vitepress/theme/index.ts` file: +Then, in your `docs/src/components` directory create a file called `PlotlyWrapper.vue` with the following content: ```typescript -import VuePlotly from "vue3-plotly-ts" + + + +``` + +and a component called `VuePlotly.vue` with the following content: + +```typescript + + + +``` + +Finally, in your `docs/src/.vitepress/theme/index.ts` file, add the following code: +```typescript +import VuePlotly from "../../components/VuePlotly.vue" export default { ... @@ -26,5 +122,10 @@ enhanceApp({ app, router, siteData }) { } } satisfies Theme ``` + In your `make.jl`, make sure you call `using PlotlyDocumenter` before `makedocs`. - \ No newline at end of file + +## Explanation + +Due to SSR requirements of vitepress, we have to import plotly.js dynamically. This is done in the `PlotlyWrapper.vue` component. +Since this dynamic import requires a suspense boundary, this boundary is provided by the `VuePlotly.vue` component, which simply wraps the `PlotlyWrapper.vue` component.