Metadata-Version: 2.4
Name: mkdocs-h5p
Version: 0.1.2
Summary: MkDocs plugin for embedding H5P files in Markdown using h5p-standalone.
Author: Benoit Rospars
License: MIT
Project-URL: Homepage, https://github.com/brospars/mkdocs-h5p
Project-URL: Repository, https://github.com/brospars/mkdocs-h5p
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: MkDocs
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Documentation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: mkdocs>=1.5
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"

# mkdocs-h5p

Embed H5P packages in MkDocs Markdown using
[tunapanda/h5p-standalone](https://github.com/tunapanda/h5p-standalone).

The plugin extracts each referenced `.h5p` file during `mkdocs build` and
injects the standalone H5P player into the generated page.

## Installation

```bash
pip install -e .
```

Enable the plugin in `mkdocs.yml`:

```yaml
plugins:
  - search
  - h5p
```

## Markdown Usage

Use the image-like syntax with `h5p` as the alt text:

```markdown
![h5p](activities/example.h5p)
```

You can also use the explicit shortcode form:

```markdown
{{ h5p("activities/example.h5p") }}
```

Paths are resolved relative to the Markdown file first, then relative to
`docs_dir`.

## Configuration

```yaml
plugins:
  - h5p:
      h5p_dir: assets/h5p
      player_url: https://cdn.jsdelivr.net/npm/h5p-standalone@3.8.0/dist
      frame: true
      full_screen: true
      export: false
      embed: false
      copyright: false
      player_options:
        icon: true
```

`player_url` points to the `dist` directory for `h5p-standalone`. By default it
uses jsDelivr with version `3.8.0` pinned. For offline sites, download the
`h5p-standalone` `dist` files into your MkDocs docs folder and set `player_url`
to that local URL.

## Notes

Some H5P exports do not include every required library. The standalone player
can only run content when the `.h5p` package includes the libraries it needs.

## Publishing to PyPI

Install the packaging tools:

```bash
python -m pip install --upgrade build twine
```

Update `pyproject.toml` `version` before publishing:

Build the source distribution and wheel:

```bash
python -m build
```

Test the package on TestPyPI first:

```bash
python -m twine upload --repository testpypi dist/*
```

Then install it from TestPyPI to verify the published artifact:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ mkdocs-h5p
```

Publish to PyPI:

```bash
python -m twine upload dist/*
```

When prompted by `twine`, use `__token__` as the username and a PyPI API token
as the password.
