related: #77

blobs #

prior work: #304

We already have blob attachment working with blob+at:// schema, but I want to deprecate that. I think that's a bad idea. It's unofficial and ugly. What I dream about is upstream atproto spec supporting at://<did>/blob/<cid> uri, but that will take some time, so I want to defer this problem to future.

Instead of creating our own standard, we can just use raw https urls. It might feel less decentralized, but user can control it anyway and it works universally without the knowledge of blob+at:// schema. So we don't have to care about backwards compatibility once upstream spec starts supporting blob-uri.

Example: #

markdown content:

![image](https://blob.tangled.network/did:plc:xasnlahkri4ewmbuzly2rlc5/bafkreiesmalyav7xowkui5z7zkccjqvyni2flw46jsrmdcevao4kfsnshy)

atproto record:

{
  "$type": "org.tangled.markup.markdown",
  "text": "![image](https://blob.tangled.network/did:plc:xasnlahkri4ewmbuzly2rlc5/bafkreiesmalyav7xowkui5z7zkccjqvyni2flw46jsrmdcevao4kfsnshy)",
  "blobs": [
    {
      "$type": "org.tangled.markup.embed.image",
      "image": { "$type": "blob", "ref": {...}, "size": 1979517, "mimeType": "image/jpeg" },
      "aspectRatio": { "width": 4000, "height": 3000 }
    }
  ]
}

mentions #

Next problem is about mentions. We want to keep them immutable, but easy to use. Users should be able to use @boltless.me over @did:plc:xasnlahkri4ewmbuzly2rlc5, but @boltless.me should point only one, specific DID that resolved when the comment was written.

My solution is to do something like reference links.

Markdown (both CommonMark and GFM) supports reference links.

[label name] only

reference link with [custom text][label name]

[label name]: https://example.com

So, conceptually, we can do something like this:

[@boltless.me] hates markdown. But he opened [#issue/123].

[@boltless.me]: did:plc:xasnlahkri4ewmbuzly2rlc5
[#issue/123]: at://...

For convenience and to semantically differentiate between reference links, we can use @- and #- as link label replacement. Say @- is for user mentions and #- is for record mentions and their definitions live in atproto record and not in markdown content:

@boltless.me hates markdown. But he opened #issue/762.

{
  "$type": "org.tangled.markup.markdown",
  "text": "@boltless.me hates markdown. But he opened #issue/762.",
  "mentions": [
    { "$type": "#mentionUser", "handle": "boltless.me", "did": "did:plc:xasnlahkri4ewmbuzly2rlc5" },
    { "$type": "#mentionRecord", "label": "issue/762", "record": { "$type": "com.atproto.repo.strongRef", ... } }
  ]
}

This way, all mentioned identifiers are immutable. The shape of issue/PR mention is completely customizable and up to users. Whether it is #123, #issue/123 or even #tangled.org/core/123, all of them will work.

---

2026-11-03

#543 can be solved in this way too:

good PR

Close: #543

{
  "$type": "org.tangled.markup.markdown",
  "text": "good PR\n\nClose: #543",
  "mentions": [
    {
      "$type": "#mentionRecord",
      "label": "543",
      "reason": "will-close",
      "record": { "$type": "com.atproto.repo.strongRef", ... }
    }
  ]
}