Mopidy website

This repo is the source for https://mopidy.com, hosted at GitHub Pages.

The documentation site, https://docs.mopidy.com, does not use this repo. It is based on the docs/ dir of the main Mopidy repo, and is hosted by Read The Docs.

Running locally

See the docs on Testing your GitHub Pages site locally with Jekyll.

Deploying changes

To update https://mopidy.com, make changes to the source, commit, and push to git@github.com:mopidy/website.git.

That's it.

Extension registry

This extension registry is a community effort, and will never be complete without your help.

To add or update an extension, use the existing extension definitions in the _ext/ directory for inspiration. Submit your update as a pull request on this repo.

The source files for the Mopidy extension registry can be found in the _ext/ directory. Any related images are in the media/ext/ directory.

The "front matter" part of the extension definitions is a YAML data structure with the following fields:

### Required fields:

title: Mopidy-Foo               # Name of extension
type: backend                   # One of "backend"/"frontend"/"mixer"/"web"

### Optional fields:

dev:                            # Development related fields
  # Pick one of github/gitlab/codeberg as the source repo:
  github: mopidy/mopidy-foo         # GitHub repo (github.com)
  gitlab: mopidy/mopidy-foo         # or GitLab repo on gitlab.com,
                                    # or use the object form below for a
                                    # self-hosted GitLab instance:
  gitlab:
    instance: https://gitlab.example.com  # GitLab instance URL
    repo: group/mopidy-foo                # Path within the instance
  codeberg: mopidy/mopidy-foo       # or Codeberg repo (codeberg.org)
  github_actions: true              # Whether using GitHub Actions; defaults
                                    # to a `ci.yml` workflow. GitHub-only.
                                    # For a different workflow filename, use
                                    # the object form below:
  github_actions:
    workflow: tests.yml                 # Workflow filename
  pep621: true                      # Read Python support from pyproject.toml's
                                    # `requires-python` (PEP 621) instead of
                                    # PyPI Trove classifiers. GitHub-only.
  circleci: true                    # Whether using CircleCI. GitHub-only.
  travisci: false                   # Whether using Travis CI. GitHub-only.
  codecov: true                     # Whether using Codecov code coverage.
                                    # GitHub-only.
  coveralls: false                  # Whether using Coveralls code coverage.
                                    # GitHub-only.

dist:                           # Distribution related fields:
  pypi: mopidy-foo                  # PyPI package name
  apt-debian: mopidy-foo            # Debian/Ubuntu package name
  apt-mopidy: mopidy-foo            # apt.mopidy.com package name
  arch-aur: mopidy-foo              # Arch Linux AUR package name
  fedora: mopidy-foo                # Fedora package name
  rpmfusion: mopidy-foo             # RPM Fusion package name
  homebrew:
    tap: mopidy/mopidy              # Homebrew tap name
    formula: mopidy-foo             # Homebrew formula name in above tap

logo: /media/ext/foo.png        # Logo, e.g. of the music service

images:                         # List of images of the extension in use
  - /media/ext/foo.jpg

service: FooBar                 # Name of the upstream service if any.

oauth:                          # OAuth integration for services that require tokens:
  endpoint: https://example.com     # Redirection endpoint to start OAuth flow
  origin: https://example.org       # Origin of callback page at end of OAuth flow
                                    # Defaults to endpoint's origin if not set
  button:                           # Styling for auth button
    style: background: ...              # Inline CSS to apply to button.
    logo:
      url:                              # URL to logo to use
      style:                            # Inline CSS to apply to logo.
  config:                           # One or more config sections to fill with data
    section_name:                       # Name of the config section
     - config_field                     # Config field name
  note: Extra markdown info...      # Optional text adding more info

OAuth authentication

The extension registry has support for integrating OAuth for service integration. This works by opening a pop-up targeted at the configured endpoint, during the flow we try polling with postMessage targeted at the callback origin. Once the flow is complete, and your callback page loads it should install an event listener that will reply to our polling. Once our code has the data we close the pop-up for you.

const data = {
  auth_token: ...,
  state: ...,
  error: ...,
  error_description: ...,
};
window.addEventListener('message', event => {
  if (event.origin === 'https://mopidy.com') {
    event.source.postMessage(data, event.origin);
  }
});

Note that the field names in the data should be mapped to the expected config field names. E.g. mapping access_token to auth_token. The error field is an error code, and error_description a human friendly version of the same error. state is there to pass back any initial state we might have sent to the endpoint.