Settings

django-wm can be customised via your project's settings module.

• Example settings.py
• Alternative formatting
• Required settings
• Optional settings
  • WEBMENTIONS_ALLOW_OUTGOING_DEFAULT
  • WEBMENTIONS_ALLOW_SELF_MENTIONS
  • WEBMENTIONS_AUTO_APPROVE
  • WEBMENTIONS_DASHBOARD_PUBLIC
  • WEBMENTIONS_DEFAULT_URL_PARAMETER_MAPPING
  • WEBMENTIONS_DOMAINS_INCOMING_ALLOW
  • WEBMENTIONS_DOMAINS_INCOMING_DENY
  • WEBMENTIONS_DOMAINS_OUTGOING_ALLOW
  • WEBMENTIONS_DOMAINS_OUTGOING_DENY
  • WEBMENTIONS_DOMAINS_OUTGOING_TAG_ALLOW
  • WEBMENTIONS_DOMAINS_OUTGOING_TAG_DENY
  • WEBMENTIONS_INCOMING_TARGET_MODEL_REQUIRED
  • WEBMENTIONS_MAX_RETRIES
  • WEBMENTIONS_RETRY_INTERVAL
  • WEBMENTIONS_TIMEOUT
  • WEBMENTIONS_URL_SCHEME
  • WEBMENTIONS_USE_CELERY
  • WEBMENTIONS_USER_AGENT
• Additional notes

Example

# settings.py

"""
Required
"""
DOMAIN_NAME = "example.org"
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.messages",
    "django.contrib.sessions",
    "mentions",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "mentions.middleware.WebmentionHeadMiddleware",
]


"""
Optional
"""
WEBMENTIONS_ALLOW_OUTGOING_DEFAULT: bool = False
WEBMENTIONS_ALLOW_SELF_MENTIONS: bool = True
WEBMENTIONS_AUTO_APPROVE: bool = False
WEBMENTIONS_DASHBOARD_PUBLIC: bool = False
WEBMENTIONS_DEFAULT_URL_PARAMETER_MAPPING: dict = {"object_id": "id"}
WEBMENTIONS_INCOMING_TARGET_MODEL_REQUIRED: bool = False
WEBMENTIONS_MAX_RETRIES: int = 5
WEBMENTIONS_RETRY_INTERVAL: int = 600
WEBMENTIONS_TIMEOUT: float = 10
WEBMENTIONS_URL_SCHEME: str = "https"
WEBMENTIONS_USE_CELERY: bool = True
WEBMENTIONS_USER_AGENT: str = "django-wm/{mentions.__version__} (+https://mysite.org)"


# Either of these options may be set, but not both.
WEBMENTIONS_DOMAINS_INCOMING_ALLOW: Iterable[str] = {
  "my-best-friend.org",
  "*.my-friends.org",  # Subdomain wildcard
}
WEBMENTIONS_DOMAINS_INCOMING_DENY: Iterable[str] = {
  "my-worst-enemy.org",
  "*.my-enemies.org",  # Subdomain wildcard
}

# Either of these options may be set, but not both.
WEBMENTIONS_DOMAINS_OUTGOING_ALLOW: Iterable[str] = {
  "my-best-friend.org",
  "*.my-friends.org",  # Subdomain wildcard
}
WEBMENTIONS_DOMAINS_OUTGOING_DENY: Iterable[str] = {
  "my-worst-enemy.org",
  "*.my-enemies.org",  # Subdomain wildcard
}

WEBMENTIONS_DOMAINS_OUTGOING_TAG_ALLOW: str = "wm-send"
WEBMENTIONS_DOMAINS_OUTGOING_TAG_DENY: str = "wm-no-send"

Alternative formatting

If you prefer, you may define a WEBMENTIONS object to contain your chosen settings.

Warning You can only use one format so pick one and stick with it. If you define a WEBMENTIONS object, individual WEBMENTIONS_... settings will be ignored.

These are equivalent:

# settings.py
WEBMENTIONS_DEFAULT_URL_PARAMETER_MAPPING: dict = {"object_id": "id"}
WEBMENTIONS_INCOMING_TARGET_MODEL_REQUIRED: bool = True
WEBMENTIONS_TIMEOUT: float = 10

# settings.py
WEBMENTIONS = {
    "DEFAULT_URL_PARAMETER_MAPPING": {"object_id": "id"},
    "INCOMING_TARGET_MODEL_REQUIRED": True,
    "TIMEOUT": 10,
}

Required settings

• DOMAIN_NAME: str: The name of your server. This is used to build absolute URLs to your content.
• INSTALLED_APPS: Add mentions to the list.
• MIDDLEWARE: Add mentions.middleware.WebmentionHeadMiddleware to the list.
  • This is not strictly 'required' but it helps other servers find your endpoint.

Optional settings

Allow outgoing default

WEBMENTIONS_ALLOW_OUTGOING_DEFAULT: bool = False

Sets the default value of allow_outgoing_webmentions on your MentionableMixin implementations.

---

Allow self-mentions

WEBMENTIONS_ALLOW_SELF_MENTIONS: bool = True

Whether to send webmentions to content on your own server.

---

Auto-approve

WEBMENTIONS_AUTO_APPROVE: bool = False

Whether received webmentions are automatically approved for public display. If False, received webmentions will be hidden from view until manually approved.

---

Public Dashboard View

WEBMENTIONS_DASHBOARD_PUBLIC: bool = False

Whether the webmentions dashboard can be accessed by anonymous users. If False, only users with permission can access it.

---

Default URL parameter mapping

WEBMENTIONS_DEFAULT_URL_PARAMETER_MAPPING: dict = {"object_id": "id"}

This is used for the default implementation of MentionableMixin.resolve_from_url_kwargs

This works the same as model_filter_map argument in URL path helper functions.

---

Domain filtering: incoming allow list

Warning

Mutually exclusive with WEBMENTIONS_DOMAINS_INCOMING_DENY.

WEBMENTIONS_DOMAINS_INCOMING_ALLOW: Iterable[str] = None

Only accept incoming webmentions from domains included in the given list. See accepted formats.

---

Domain filtering: incoming deny list

Warning

Mutually exclusive with WEBMENTIONS_DOMAINS_INCOMING_ALLOW.

WEBMENTIONS_DOMAINS_INCOMING_DENY: Iterable[str] = None

Ignore any webmentions received from domains in the given list. See accepted formats.

---

Domain filtering: outgoing allow list

Warning

Mutually exclusive with WEBMENTIONS_DOMAINS_OUTGOING_DENY.

WEBMENTIONS_DOMAINS_OUTGOING_ALLOW: Iterable[str] = None

Only attempt to submit webmentions to domains in the given list. See accepted formats.

---

Domain filtering: outgoing deny list

Warning

Mutually exclusive with WEBMENTIONS_DOMAINS_OUTGOING_ALLOW.

WEBMENTIONS_DOMAINS_OUTGOING_DENY: Iterable[str] = None

Never attempt to submit webmentions to domains in the given list. See accepted formats.

---

Domain filtering: allow tag

WEBMENTIONS_DOMAINS_OUTGOING_TAG_ALLOW: str = None

A tag which can be applied to an HTML <a> element to override WEBMENTIONS_DOMAINS_OUTGOING_DENY for that individual link.

May be applied as:

• a class <a class="my-override-string" ….
• a data attribute <a data-my-override-string ….
• a custom attribute <a my-override-string ….

---

Domain filtering: deny tag

WEBMENTIONS_DOMAINS_OUTGOING_TAG_DENY: str = None

A tag which can be applied to an HTML <a> element to override WEBMENTIONS_DOMAINS_OUTGOING_ALLOW for that individual link.

May be applied as:

• a class <a class="my-override-string" ….
• a data attribute <a data-my-override-string ….
• a custom attribute <a my-override-string ….

---

Model required

WEBMENTIONS_INCOMING_TARGET_MODEL_REQUIRED: bool = False

Whether an incoming webmention needs to resolve to a model to be accepted. If False, received webmentions may target any accessible page on your server.

---

Retry attempts

WEBMENTIONS_MAX_RETRIES: int = 5

Maximmum number of times to retry processing of a webmention.

---

Retry interval

WEBMENTIONS_RETRY_INTERVAL: int = 600

Minimum time in seconds to wait before trying to reprocess a webmention after a failed attempt.

---

Network timeout

WEBMENTIONS_TIMEOUT: float = 10

Maximum time in seconds to wait for network calls to complete.

---

URL scheme

WEBMENTIONS_URL_SCHEME: str = "https"

May be either https or http. It should be https. This is used along with DOMAIN_NAME to build absolute URLs to your content.

---

Use Celery

WEBMENTIONS_USE_CELERY: bool = True

Whether to use Celery for processing webmentions. If False, you will need to run python manage.py mentions_pending to process webmentions.

---

User agent

WEBMENTIONS_USER_AGENT: str = f"django-wm/{mentions.__version__} (+{mentions.__url__})"

Value used in HTTP User-Agent header when making network requests.

---

Notes

Domain allow/deny formats

The settings WEBMENTIONS_DOMAINS_INCOMING_ALLOW, WEBMENTIONS_DOMAINS_INCOMING_DENY, WEBMENTIONS_DOMAINS_OUTGOING_ALLOW, WEBMENTIONS_DOMAINS_OUTGOING_DENY each accept a list of domains.

Domains with *. prefix will also match subdomains.

Domain	Matches
example.org	example.org
*.example.org	example.org sub.example.org sub.sub.example.org …
*.org	example.org anything.org sub.anything.org …
* *.*.org www.*.org anything.*	Invalid - matches nothing!