Improving the Permalink Structure for `?attachment_id=123`

[kimjiwoon]

Since I’m not very fluent in English, I prepared two AI-generated versions of this proposal. To keep things simple, let me start with the conclusion.

Currently, the permalink of an Attachment Post Type is placed under the *uploaded-to* parent post.
I propose changing the structure so that the permalink is placed under the author instead.

For taxonomy, I suggest using categories. Multiple categories should not be allowed; instead, a hierarchical directory-style structure should be supported.

Summary

This ticket proposes a follow-up idea to the concepts discussed in #47839 (Extended file management in Media Library). While that ticket focused on general media management, this proposal takes a different direction. It prioritizes the scalability of WordPress in multisite and multi-user environments and aims to improve compatibility with external systems like ActivityPub (Fediverse) and Openverse. I believe that adopting these broader goals will lead to fundamental improvements that benefit all users.

The design is inspired by the user experience of platforms like Pinterest, Misskey Drive, and FileBird Pro. Users familiar with these systems will find the core concept of this proposal easy to grasp.

The Problem: The Current Media File Structure

A WordPress media file currently has two distinct levels, which are not cleanly connected:

1. The Physical File: This is the file's URL on the server, e.g., /wp-content/uploads/2025/08/myimage.jpg.
2. The Attachment Post Type (post_type = 'attachment'): This is a separate entry in the wp_posts table that provides the media item with its own dedicated post page, e.g., ?attachment_id=123.

In the current Media Library, the "Uploaded to" field only displays the first Post/Page a media item is attached to, even if it is used in multiple locations. This contrasts with platforms like Misskey Drive, which allow viewing *all notes* where a media file has been attached, providing a much clearer and more organized user experience.

Proposal: A Canonical and Semantic Permalink Structure

I propose a unified and semantic permalink structure for federated media. This would resolve the current inconsistencies and make the system more robust for both human and machine readability.

A proposed structure could be:

• /%author%/%media%/%_boards%/%filename%?w=300/ for a "drive feed" or media gallery view.
• /%author%/%media%/%_pins%/%filename%?w=1024/ for an individual media object page.

Design Principles & Inspiration

This design is informed by key principles from existing WordPress features and external systems.

From Core Trac Ticket #47839: I have adopted the key principle of implementing a virtual folder structure using hierarchical taxonomies rather than actually moving files. This is crucial for avoiding backwards compatibility issues.

• Folders vs. Categories: A virtual Folders approach is preferred, where an image can be placed into a single folder. This simplifies the user experience and reduces the complexity that can come with a multiple-category approach.
• Virtual vs. On-Disk: The virtual folder structure must be implemented without altering the physical location of files on the server's hard drive.

Furthermore, this virtual structure should be seamlessly integrated into the "Add Image" interface and allow for the creation of galleries based on these virtual folders.

From FileBird Pro: My concept is also inspired by a FileBird Pro-like design, incorporating the following features:

• Folders are unique to each user.
• The API allows for searching by folder names.
• Breadcrumbs are displayed for navigation.
• The design supports folders for various post types.
• It provides a function to track attachment size for storage limits.

From the Jetpack Carousel: Drawing from this concept, I identify three distinct ways to link to a piece of media:

• Image gallery view (block): A federated view of a media collection.
• Upload target (page): A dedicated page for a single media object.
• Direct file link: The canonical URL to the raw file.

My proposal is to position the Upload target (page) as the federated Object that resides under the user's actor profile. The attachments field in the federated post should link to this Object URL, not the direct file link. This distinction is crucial for optimization and for maintaining a clean, scalable Fediverse profile.

Centralized Media Storage

For WordPress multisite networks, which typically have separate media libraries for each subsite, a centralized media storage solution should be considered.

This could involve a system like the Network Media Library plugin to consolidate all media files into a single location on the main site. This would allow each media file to have a single, canonical URL (e.g., https://example.com/uploads/2025/08/image.jpg), preventing URL conflicts and redundant data in the Fediverse. This is also essential for implementing user-specific storage limits.

I had initially dismissed the Network Media Library plugin because of its age and lack of recent updates on WordPress.org. However, based on recent reports, it appears to function well with modern WordPress versions.

• ​Network Media Library plugin
• ​워드프레스 멀티사이트 공유 라이브러리를 만드는 방법 (How to create a WordPress multisite sharing library, in Korean)
• ​What is a CID (content identifier)?

[kimjiwoon]

my proposal takes a different direction, placing more weight on:

• Multisite network & multi-user scalability
• ActivityPub (Fediverse) and Openverse compatibility

The motivation is that once we assume these future directions, subtle improvements—otherwise invisible in simple use cases—become evident.

Inspiration comes from platforms like Pinterest, Misskey Drive, and FileBird Pro. Anyone familiar with these will understand the concept more intuitively.

### The Two Levels of a WordPress Media File

1. The Physical File

/wp-content/uploads/2025/08/myimage.jpg
This is just the file's URL on the server.

2. The Attachment Post Type (post_type = 'attachment')

This is a separate entry in the wp_posts database table. This entry is what gives the media a dedicated attachment post page (e.g., ?attachment_id=123).

### Proposal: A Canonical Permalink Structure

I propose a unified and semantic permalink structure for federated media. This would clean up the current chaos and make the system more robust for both human and machine readability.

A proposed structure could be:

• /%author%/%media%/%_boards%/%filename%?w=300/ for a "drive feed" or media gallery view.
• /%author%/%media%/%_pins%/%filename%?w=1024/ for an individual media object page.

Why
In the current Media Library, the Uploaded to field only displays the first Post/Page a media item is attached to, even if the media is used in multiple places.
​https://wordpress.org/documentation/article/media-library-screen/(​https://wordpress.org/documentation/article/media-library-screen/)

By contrast, platforms like Misskey Drive allow viewing *all notes* where a media file has been attached.

If the upload target is stored as metadata and connected through backlinks, a single media page could be linked to multiple upload targets.