How do absolute links work?

I’ve been trying to get my website on IPFS. I tried almost two years ago, and it looks like some things have gotten better in the meantime. However, the same thing that didn’t make sense before still doesn’t make sense.

Like most websites - like, for example, this forum - my website ( uses absolute links. Hopefully it goes without saying that absolute links are very useful, and that changing them to relative links is not at all an easy workaround.

Unfortunately, given the way that the localhost:8080 gateway works, and the gateway, absolute links don’t work. If you try to rehost a website using them onto IPFS, all the absolute links will yank out the /ipfs/... or /ipns/... bit of the URL and replace it with just the linked path.

It looks like itself uses relative links, probably to work around this limitation. I can’t find anything in the documentation about IPFS for websites about this problem.

Any ideas? This is limitation breaks most most websites, so even if it isn’t fixable, it should probably be mentioned in the documentation so that similar folks don’t go through steps 1-9 just to get blocked by step 10.

I’m not sure if this is related to your concerns, but I think the long term goal for this is for there to be native support for IPFS built into browsers. In the meantime, you can link to /ipfs/... and /ipns/... paths using a trusted gateway (e.g.,, another one, or even one you run). If the user has an IPFS browser plugin installed it can redirect it to a local gateway the user is running.

There’s a bunch of discussion on this here (link is to a summary post)

Is there a reason sites like yours can’t use relative links to link to other parts of the same site? I’ll admit that absolute links are useful for linking to external resources, but using relative links within a site should be transparent to users.

If you’re talking about absolute links to within the same site, I don’t think it goes without saying why absolute links are very useful for that use case. I’d be curious to hear what absolute links offer that relative links don’t for linking within the same website.

I suppose it depends on what tools you’re using, but static site generators like Hugo make using relative links trivial.

I’d be curious to hear what absolute links offer that relative links don’t for linking within the same website.

Sure, so let’s say that you’re using Jekyll. You write a post. People read that post both on the front page (/) and some permalink (/2019/04/01/hi.html). From that post, you link to some other post.

Do you link with ../../../foo.html, because you expect it to be accessed from the permalink, or do you omit all the backtracking, because you expect it to be from the front page? This is the essence, essentially: when you’re writing your content, you don’t know where it is.

This idea extends to resources. The post has some CSS dependency. Does the <link> element reference ../../../? Or not? This is why pretty much all the websites on the internet use paths with /. Hit up boingboing, or metafilter, or kottke, or wherever: they all use absolute links that start with either the full path, or /.

Now, you’re right - Hugo has a relativeURLs option. Jekyll, the tool I use, doesn’t, and WordPress doesn’t, out of the box, and has quite a lot of discourse on the pros/cons. It looks like gatsby implemented a plugin just for ipfs to make URLs relative.

Hopefully this makes it a bit clearer why requiring relative URLs is a problem. I could write a bunch of code to rewrite all the URLs on my site to point to each other, but when I write a post about how I made my website work on IPFS and how you can too, I can’t say with a straight face that it’s reasonable if it requires that kind of hack.

So, there’s some good news: we will be moving to putting the CID/IPNS-key/HASH in a subdomain by default (so every site gets its own origin). That is, websites will be hosted from instead of The nice side effect is that absolute links will “just work”.

Unfortunately, it’ll still likely be a few months before this lands.


Great, glad that there’s a solution coming down the line. Q: that looks like it’s going to be a change to the web gateway – is there potentially a way for absolute links to work with the ‘pure IPFS’ approach – not sure about the name, but the way that you access sites via localhost:8080 when running the local gateway. While it’s great that the web gateway exists for certain usecases, using it by default seems to defeat the purpose of a decentralized system.

For anyone using the browser companion, the browser companion will proxy requests to the gateway through the local gateway. The local gateway can then intercept and handle these requests on the external gateway’s behalf.

Eventually, the plan is to (once browsers add proper support for custom protocols) support ipfs://Qm.../... and ipns://.

(note: some operating systems can also handle subdomain.localhost)

Here’s the relevant issue for the hash subdomains:

1 Like