Skip to main content

Side Editor

This theme adds a collapsible code editor pane which can be populated with the code snippets from the page.

The button is hidden in mobile.

Usage​

Add the edit meta to a code snippet to inject a Edit button that loads the source in the side editor.

```msagl edit
graph G {
    kspacey -- swilliams;
    swilliams -- kbacon;
    bpitt -- kbacon;
    hford -- lwilson;
    lwilson -- kbacon;
}
```
http://localhost:3000
graph G {
    kspacey -- swilliams;
    swilliams -- kbacon;
    bpitt -- kbacon;
    hford -- lwilson;
    lwilson -- kbacon;
}
Generated graph

Tools that do not need an integrated editor can also be loaded.

```devicescript edit
console.log('hello')
```
http://localhost:3000
console.log('hello')

Configuration​

IFrame runner​

You can configure the theme to load an external iframe. This is the recommended way to integrate your tool

The plugin communicates with the IFrame using messages and you will also need to configure their format.

./docusaurus.config.js
const config = configure({ ... }, {
    ...
    sideEditor: {
        editors: [
            {
                type: "iframe",
                id: "devicescript",
                // specify different urls for color modes
                lightUrl: "https://...",
                darkUrl: "https://...",
                // docs -> editor message template
                message: {
                    channel: "devicescript",
                    type: "source",
                    force: true,
                    startMissingSimulators: true,
                },
                messageTextFieldName: "source",
                // editor -> docs ready message
                readyMessage: {
                    channel: "jacdac",
                },
            },
        ],
    },
})

Static IFrame​

It's also possible to deploy your tool HTML along with Docusaurus by placing the sources in the ./static/editors folder. For example, the msagljs tool is wrapped as ./static/editors/msagl.html.

./static/editors/msagl.html
<html>
  <script src="https://unpkg.com/msagl-js@latest/dist.min.js"></script>
  <script src="https://unpkg.com/@msagl/parser@latest/dist.min.js"></script>
  <script src="https://unpkg.com/@msagl/renderer@latest/dist.min.js"></script>
  <body>
    <script type="module">
      const renderer = new msagl.Renderer();
      // handle rendering of dot sources
      window.addEventListener('message', (ev) => {
        const { type, dot } = ev.data;
        if (type === 'msagl') {
          const graph = msagl.parseDot(dot);
          renderer.setGraph(graph);
        }
      });
      // tell parent, we're ready
      if (window.parent && window.parent !== window)
        window.parent.postMessage({
          type: 'msagl',
          state: 'ready',
        });
    </script>
  </body>
</html>

See how it is done in docusaurus-plugins

./docusaurus.config.js
const config = configure({ ... }, {
    ...
    sideEditor: {
        editors: [
            {
                id: "msagl",
                lightUrl: "./editors/msagl.html?theme=light",
                darkUrl: "./editors/msagl.html?theme=dark",
                ...
            },
            ...
        ]
    }
})

Monaco editor​

You can specify the monaco editor language to enable the Monaco editor.

./docusaurus.config.js
const config = configure({ ... }, {
    ...
    sideEditor: {
        editors: [
            {
                id: "devicescript",
                language: "typescript"
            }
        ]
    }
})

Lang to editor mapping​

You can provide a mapping from code language code to editor id.

./docusaurus.config.js
const config = configure({ ... }, {
    ...
    sideEditor: {
        languages: {
            "ds": "devicescript"
        },
        editors: [
            {
                id: "devicescript",
                ...
            }
        ]
    }
})

Panels position persitence​

Provide the persistenceId field to serialize the tabs positions accross page reloads.

./docusaurus.config.js
const config = configure({ ... }, {
    ...
    sideEditor: {
        editors: [
            {
                id: "devicescript",
                persistenceId: "devicescript"
            }
        ]
    }
})