Resolve Docs Media Variant
Use this guide to check how Antylogic chooses the media file returned for a Docs article detail request. The action is read-only: it normalises locale, platform and theme, returns the matching docs asset URL, and leaves unavailable media as planned metadata instead of failing the article.
In this article
Use this guide when a support, QA, documentation or demo capture operator needs to understand why a Docs article shows a specific image or video for the current locale, device and theme.
The resolver runs only while building an article detail response. It does not change Docs content, assets, users, permissions or demo data. Public detail requests return public asset URLs, and authenticated app requests return app asset URLs.
Before you start
- Docs content and docs assets are configured for the running environment.
- Open an article detail route, not only the Docs index.
- The requested article exists after locale normalisation; `en-GB` is handled as `en`.
- The media entry has a usable `variantPublicSrc`, `themePublicSrc` or `publicSrc` when rendered media is expected.
- For `/api/app/docs`, sign in with the Harbor Demo User in the GB demo session. `/api/public/docs` does not require sign-in.
Instructions
- 1.
Open the article detail
Request the article detail with the required locale, platform and theme. For the public surface, use `/api/public/docs/calendars/en-calendars-view-general?locale=en-GB&platform=tablet&theme=light`. For the signed-in app surface, open `antylogic://docs/calendars/en-calendars-view-general` in the Harbor Demo Group GB session.
- 2.
Check the resolved media fields
Inspect `article.media[]`. The resolver tries the requested platform and theme first, then follows the fixed fallback order. In the current English Calendars example, a tablet/light request can resolve to the available iPad dark video variant, so `src`, `resolved_platform`, `resolved_theme`, `available_platforms` and `available_themes` explain the selected file.
- 3.
Open the returned asset URL
Use the returned `src` to fetch the media through the docs asset route. The URL must keep the same prefix as the detail request, such as `/api/public/docs/assets/ipad/dark/en/calendars-view-general/calendars-view-general-overview-clip.mp4` for the public example.
- 4.
Treat planned media as pending
If a media entry has no usable source, keep the article response and treat the media as pending. A missing `src` is not an article failure; it means the media is planned or the selected source could not be converted into a safe docs asset path.
Validations and limits
- Media resolution is for `GET` article detail responses; unsupported methods return `405 metodo no permitido`.
- `locale` normalises to `en` or `es`; unsupported or empty values fall back to `es` in the backend resolver.
- `platform` or `device` normalises to `mobile`, `tablet` or `web`; tablet requests use the `ipad` content platform.
- `theme` resolves to `dark` only when `dark` is requested; every other value resolves to `light`.
- The resolver checks `variantPublicSrc` first, then `themePublicSrc`, then `publicSrc`.
- The returned `src` uses `/api/public/docs/assets/...` for public article detail and `/api/app/docs/assets/...` for authenticated app detail.
- The asset handler cleans the path again and serves files only from the configured docs assets root; a later asset `404` is an asset availability gap, not a media resolution failure.
- Do not use English `auth-native-login` as the resolved-source example for the current bundle because its English media entries are planned with empty source fields.
- The current content bundle was generated on 2026-06-18. Refresh the bundle before publishing if the 2026-06-24 documentation update changed media sources.
Expected result
The operator can confirm which media asset a Docs article selected, which fallback produced it, and whether any missing media should be handled as a pending capture or asset availability gap rather than an article loading failure.