{"id":30179716,"url":"https://github.com/nickcrews/mkdocs-jupyterlite","last_synced_at":"2026-05-07T01:04:55.299Z","repository":{"id":309136656,"uuid":"1035242961","full_name":"NickCrews/mkdocs-jupyterlite","owner":"NickCrews","description":"A MkDocs plugin for embedding interactive jupyter notebooks in your docs via jupyterlite.","archived":false,"fork":false,"pushed_at":"2025-08-10T05:13:33.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T05:16:46.347Z","etag":null,"topics":["jupyter-notebook","jupyterlite","mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"https://nickcrews.github.io/mkdocs-jupyterlite/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NickCrews.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-10T00:53:31.000Z","updated_at":"2025-08-10T05:13:50.000Z","dependencies_parsed_at":"2025-08-10T05:16:51.383Z","dependency_job_id":"9e3b4b9e-1353-4700-b7e0-3c03b4f57575","html_url":"https://github.com/NickCrews/mkdocs-jupyterlite","commit_stats":null,"previous_names":["nickcrews/mkdocs-jupyterlite"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/NickCrews/mkdocs-jupyterlite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickCrews%2Fmkdocs-jupyterlite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickCrews%2Fmkdocs-jupyterlite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickCrews%2Fmkdocs-jupyterlite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickCrews%2Fmkdocs-jupyterlite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NickCrews","download_url":"https://codeload.github.com/NickCrews/mkdocs-jupyterlite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NickCrews%2Fmkdocs-jupyterlite/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270011198,"owners_count":24511903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jupyter-notebook","jupyterlite","mkdocs","mkdocs-plugin"],"created_at":"2025-08-12T06:15:29.519Z","updated_at":"2026-05-07T01:04:55.294Z","avatar_url":"https://github.com/NickCrews.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# mkdocs-jupyterlite\n\nA MkDocs plugin for embedding interactive notebooks in your docs via jupyterlite.\n\n![Recording of a JupyterLite notebook embedded in MkDocs](https://raw.githubusercontent.com/NickCrews/mkdocs-jupyterlite/main/docs/assets/recording.gif)\n\nSay you have a notebook `example.ipynb` in your awesome project, and you want\nusers to be able to play around with it.\nBy using [JupyterLite](https://jupyterlite.readthedocs.io/),\nyou can run Jupyter notebooks directly in the browser without any server-side dependencies.\n\n## Examples\n\n- [This project's documentation site](https://nickcrews.github.io/mkdocs-jupyterlite)\n- [Mismo's documentation site](https://nickcrews.github.io/mismo/examples/patent_deduplication/)\n  (Mismo was the initial motivation for this plugin.)\n\n## Installation\n\n### Step 1: Install the plugin from [PyPI](https://pypi.org/project/mkdocs-jupyterlite/):\n\n```bash\npython -m pip install mkdocs-jupyterlite\n```\n\n### Step 2: Configure your `mkdocs.yml` file\n\nSee the [mkdocs.yml](https://github.com/NickCrews/mkdocs-jupyterlite/blob/main/mkdocs.yml)\nthat configures [this project's site](https://nickcrews.github.io/mkdocs-jupyterlite).\n\n```yaml\nsite_name: mkdocs-jupyterlite\nsite_url: https://nickcrews.github.io/mkdocs-jupyterlite/\nrepo_url: https://github.com/nickcrews/mkdocs-jupyterlite/\n\nnav:\n  - Home: index.md\n  - Notebook 1: notebook.ipynb\n\nplugins:\n  - jupyterlite:\n      # An easy way to turn off the entire plugin.\n      enabled: true\n      # Uses the same syntax as .gitignore:\n      # Include and exclude files using glob patterns, the last matching pattern\n      # determines if a file is included or excluded.\n      notebook_patterns:\n        # Include all. This is the default.\n        - \"**/*.ipynb\"\n        # Exclude drafts.\n        - \"!**/draft_*.ipynb\"\n        # Re-include a specific draft.\n        - \"project/drafts/draft_keep.ipynb\"\n        # Exclude a notebook at the root. Doesn't match /a/b/c/top_secret.ipynb\n        - \"!/top_secret.ipynb\"\n      # Add custom wheels so that when you\n      # `%pip install my-package` in the notebook,\n      # the micropip library has a backup after PyPI to fall back on.\n      wheels:\n        # Specify a url directly.\n        - url: \"https://files.pythonhosted.org/packages/2d/2c/7f32ba15302847f0cd0d01101470b2f427ec5b3a07756f41c823c01c0242/ibis_framework-10.5.0-py3-none-any.whl\"\n        # Run a shell command that dynamically\n        # builds/fetches/creates 0 to N .whl files in the given {wheels_dir}\n        # (which will be replaced by this plugin with a real, temporary directory).\n        - command: \"curl -L -o {wheels_dir}/cowsay-6.1-py3-none-any.whl https://files.pythonhosted.org/packages/f1/13/63c0a02c44024ee16f664e0b36eefeb22d54e93531630bd99e237986f534/cowsay-6.1-py3-none-any.whl\"\n        - command: \"cd src/package_not_on_pypi/ \u0026\u0026 uv build --out-dir {wheels_dir}\"\n```\n\nHere are the details on the configuration options:\n\n### `enabled`\n\nbool, whether or not the plugin is enabled. Defaults to `true`.\n\n### `notebook_patterns`\n\nA list of patterns that uses [gitignore](https://git-scm.com/docs/gitignore)\nsemantics to include and exclude files.\nThe last matching pattern will be used to determine if a file is a notebook.\n\nThese are resolved relative to your MkDocs `docs_dir` directory,\nwhich by default for most projects is `docs/`.\nSo if you have a notebook at `docs/notebook.ipynb`,\nthat corresponds to the pattern `/notebook.ipynb`.\n\nFor all files that match, the content of the page will be an\niframe that embeds the JupyterLite Notebook html.\n\n### `wheels`\n\nA list of wheels to include in the JupyterLite environment.\nThe simplest form is to specify a file path or URL directly underneath the `url` key.\n\nOr, if you use the `command` key, this is interpreted as a shell command.\nThis plugin will replace the `{wheels_dir}` placeholder with a temporary directory,\nand then run the command in the directory that the `mkdocs` command was run from.\nThis command must place/create 0 to N `.whl` files in the given `{wheels_dir}` directory.\n\n## Related Work and Alternatives\n\n- [Binder](https://mybinder.org/):\n  A popular tool for creating sharable, interactive environments for Jupyter notebooks.\n  Requires a full docker environment and a remote server.\n  The notebook is hosted separately from your docs, so a user has to click\n  away in order to run the notebook.\n  Takes 30-60 seconds to boot up a new environment.\n- [mkdocs-jupyter](https://github.com/danielfrg/mkdocs-jupyter):\n  A MkDocs plugin that embeds *static* Jupyter notebooks into your MkDocs site.\n  That project is very similar to this one, except that one executes and\n  renders the notebooks as static HTML at build time, so they\n  aren't interactive on the site.\n  It is much more mature than this project though.\n- [jupyterlite-sphinx](https://github.com/jupyterlite/jupyterlite-sphinx):\n  A Sphinx extension that integrates JupyterLite within your Sphinx documentation.\n  That project is very similar to this one, except that it is for Sphinx\n  instead of MkDocs.\n  It also has more features than this project.\n  I will probably use that as inspiration for future development of this project,\n  for example how it uses `environment.yml` to specify python packages that will\n  be included in the JupyterLite environment.\n- [jupyterlite](https://github.com/jupyterlite/jupyterlite):\n  The core project that powers this plugin.\n  You *can* use jupyterlite directly in your docs, it just is more work.\n  You would need to a build step to package your notebooks, other files, and python\n  dependencies into a single static .html file.\n  Then you would need to inject this .html file into the proper pages of your MkDocs site.\n  This plugin automates that process for you.\n\n## Style Compatibility with `mkdocs-material`\n\n[mkdocs-material](https://squidfunk.github.io/mkdocs-material/)\nis a popular theme for MkDocs that is compatible with this plugin.\nBut, in its css, it limits the `max-width` of the content area to be 61rem.\nThis is just small enough that the JupyterLite notebook, when embedded,\nthinks it is on a mobile device, and so many of the important UI elements of JupyterLite,\nsuch as the \"add cell below\" hover menu, are hidden.\nTo get around this, see https://github.com/NickCrews/mkdocs-jupyterlite/blob/main/docs/extra.css\n\n## Contributing\n\nI want this to be usable for other people, so file an issue if you want\nto use this in your site, but run into any problems.\n\nPossible improvements:\n\n- [x] Include custom python wheels into the JupyterLite environment.\n- [x] Fix the TOC so clicking headers actually scrolls in the iframe.\n- [ ] Passing an entire jupyter-lite.json config file.\n- [ ] Instead of using an iframe, actually inline the contents of the generated HTML?","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickcrews%2Fmkdocs-jupyterlite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickcrews%2Fmkdocs-jupyterlite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickcrews%2Fmkdocs-jupyterlite/lists"}