Interactive Examples

[DanielHabenicht]

Context

I learned about webcontainers and wanted to integrate them into my existing mkdocs documentation to provide users with interactive examples, which can be changed by them. Unfortunately, there are no extensions for it yet. But I also saw PyScript which does the same for Python.

Description

Make the Documentation more interactive, e.g.:

• CLI commands, executable right away (e.g. by adding a switch)

  ```bash interactive=environment1
  custom-cli init

• Configuration Samples could include a live updating instance on the same page right next to it:

  ```typescript interactive=environment1 filepath=/workspace/config.ts
  export const config = {
   option1: "test",
  }

• Or one could embed or link to an extra component (or page) where interactive examples (or tutorials) could be added.

  ```python interactive=environment1 example=https://github.com/repository/example/path/to/mounted/folder
  def coolFunction():
    pass

For now this would probably be limited to node and python examples, but I am sure more web assembly versions of languages will follow.

Related links

• Webcontainers
• Interactive Guide
• Example: Angular Documentation Playground
• Interactive CLI
• Also saw SQLime for interactive SQLite queries

Use Cases

As the Documentation Author, I can more easily create hands-on examples of how to work with what I am documenting.

As a user I don't need to install something locally to give it a try, there are fewer barriers.

Visuals

Extra Button for opening the example interactively (but not in the 3rd party service but on your own docs site): Or even better if the output would be side-by-side with the example.

Before submitting

• [X] I have read and followed the change request guidelines.
• [X] I have verified that my idea is a change request and not a bug report.
• [X] I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• [X] I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[squidfunk]

Thanks for the suggestion! There are already some similar solutions like Markdown Exec, albeit they might (?) not be interactive (tagging @pawamoy for visibility) – maybe it's worth exploring them ☺️ This, currently, goes beyond the scope of Material for MkDocs, as we're focusing on the rendered output, and interactivity is left to third-party integrations, but we may reconsider in the future.

Moving this into discussions for further input by other users.

[pawamoy]

We do support interactive Python code blocks, thanks to Pyodide. Definitely open to adding support for more languages 🙂