{"id":29492015,"url":"https://github.com/aeskildsen/mkdocs-audiotag","last_synced_at":"2026-05-16T13:06:56.799Z","repository":{"id":301023938,"uuid":"1007590860","full_name":"aeskildsen/mkdocs-audiotag","owner":"aeskildsen","description":"MkDocs plugin for simple audio file embedding","archived":false,"fork":false,"pushed_at":"2025-07-14T13:45:10.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-14T15:13:23.406Z","etag":null,"topics":["mkdocs"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mkdocs-audiotag/","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/aeskildsen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-24T08:22:56.000Z","updated_at":"2025-07-14T13:47:29.000Z","dependencies_parsed_at":"2025-06-24T19:55:42.063Z","dependency_job_id":"3deaa2f8-f25f-4312-9ce3-ed2a30af6e80","html_url":"https://github.com/aeskildsen/mkdocs-audiotag","commit_stats":null,"previous_names":["aeskildsen/mkdocs-audiotag"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aeskildsen/mkdocs-audiotag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aeskildsen%2Fmkdocs-audiotag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aeskildsen%2Fmkdocs-audiotag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aeskildsen%2Fmkdocs-audiotag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aeskildsen%2Fmkdocs-audiotag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aeskildsen","download_url":"https://codeload.github.com/aeskildsen/mkdocs-audiotag/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aeskildsen%2Fmkdocs-audiotag/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265440636,"owners_count":23765810,"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","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":["mkdocs"],"created_at":"2025-07-15T15:01:16.274Z","updated_at":"2026-05-16T13:06:56.794Z","avatar_url":"https://github.com/aeskildsen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkdocs-audiotag\n\nThis is a plugin for the wonderful [mkdocs](https://www.mkdocs.org/) static site generator that allows for easy embedding of audio files using the default HTML5 audio element.\n\nThis plugin was made as an alternative to [mkdocs-audio](https://github.com/jfcmontmorency/mkdocs-audio), in order to support embedding multiple audio file sources. This is sometimes necessary because file formats and container types are not supported equally well in different browsers or on different platforms.\n\n![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-audiotag?color=darkgreen)\n\n## Quick start\n\n### Install the plugin\n\n```shell\npip install mkdocs-audiotag\n```\n\n### Enable the plugin in mkdocs.yml\n\n```yaml\nplugins:\n  - mkdocs-audiotag\n```\n\n### Embed an audio file\n\n```markdown\n![audio/ogg](my-audio-file.ogg)\n```\n\nNote: `audio/ogg` is the MIME type for the embedded file.\n\n## Configuration\n\nYou can customize the behavior and appearance of the audio element by specifying options under the plugin in your `mkdocs.yml`. The defaults are sane, so in most cases this isn't necessary.\n\n```yaml\n# Default options\nplugins:\n  - mkdocs-audiotag:\n      autoplay: false\n      controls: true\n      loop: false\n      muted: false\n      preload: 'metadata'\n      width: 100%\n```\n\n### Options\n\n- **autoplay**:\n  If `true`, audio will start playing automatically when the page loads.\n  [MDN: autoplay](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#autoplay)\n\n- **controls**:\n  If `true`, playback controls (play, pause, etc.) are shown.\n  [MDN: controls](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#controls)\n\n- **loop**:\n  If `true`, audio will restart automatically after finishing.\n  [MDN: loop](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#loop)\n\n- **muted**:\n  If `true`, audio will be muted on page load.\n  [MDN: muted](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#muted)\n\n- **preload**:\n  Controls what gets downloaded on page load:\n  - `'none'`: Don’t preload audio\n  - `'metadata'`: Preload only metadata (default)\n  - `'auto'`: Preload the whole file\n  [MDN: preload](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#preload)\n\n- **width**:  \n  Sets the CSS width of the audio player (e.g., `'100%'`, `'300px'`).  \n  [MDN: style](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio#styling_with_css)\n\n### Config examples\n\n#### Use the default config options\n\n```yaml\nplugins:\n  - mkdocs-audiotag\n```\n\n#### Set audio playback to loop, don't preload anything\n\n```yaml\nplugins:\n  - mkdocs-audiotag:\n      loop: true\n      preload: none\n```\n\n#### Set the width of the audio player to 300 pixels\n\n```yaml\nplugins:\n  - mkdocs-audiotag:\n      width: 300px\n```\n\n## How to write the markdown content\n\nThere is no standard way to describe audio media in markdown. Inspired by [mkdocs-audio](https://github.com/jfcmontmorency/mkdocs-audio), we use the same syntax as with images. Instead of a title or a static marker, we specify the file's [MIME type](#mime-types), which **must begin with** `audio/` (otherwise, the plugin will not recognise the tag).\n\n```markdown\n![audio/ogg](my-audio-file.ogg)\n```\n\nTo specify multiple source files, just include another file **immediately below the first line, i.e. with no extra line breaks**. The browser will try to load the first audio file. If that fails, it will move on to the next one, and so forth. This means you can put the preferred format first, and then add fallback options below. See [notes on this browser behavior at MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/audio#usage_notes).\n\n```markdown\n![audio/ogg](my-audio-file.ogg)\n![audio/mpeg](my-audio-file.mp3)\n```\n\nIf you need to caption the audio element, use a separate plugin for that.\n\n### MIME types\n\nSome MIME types for common audio file formats are:\n\n- AAC/M4A: audio/mp4\n- MP3: audio/mpeg\n- OGG: audio/ogg\n- FLAC: audio/flac\n- WAVE: audio/wav\n- AIFF: audio/aiff\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faeskildsen%2Fmkdocs-audiotag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faeskildsen%2Fmkdocs-audiotag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faeskildsen%2Fmkdocs-audiotag/lists"}