Shift in Relative vs. Absolute Path Mentality

[emmadesilva]

Abstract

Originally posted in #1913

• Hyde was originally designed to support offline use through relative links.
• The realization: When users set a base URL (an explicit action), they're likely targeting an online deployment (99.5% of use cases).
• We should utilize the base URL when possible for online deployments.

Historical Context

• The offline browsing support mindset originated in Hyde's early days, before the realtime compiler.
• Users had to compile the site and browse locally to test it.

Proposed Improvements

1. Provide a smoother, less complex way to compile locally:

   • Add a --local option to the build command.
   • This option would internally set the base URL to null, forcing local URLs everywhere.

2. Consider moving towards more absolute URLs:

   • Need to address how the realtime compiler handles these changes.
   • Applying a --local flag locally could potentially break saved previews (which are being phased out).

Considerations

• Balance between supporting offline use and optimizing for online deployments.
• Potential impact on the realtime compiler and saved previews.
• Potential impact on portability when moving domains (sites would need to be recompiled or search+replace)

[emmadesilva]

From #1914 (comment)

I'm starting to remember why we have two methods. Media link was intended to be the main way to use get assets, as it uses the more compatible relative links. The second parameter was for things where specs required absolute urls like metadata. But I did not document this so I forgot it.

[emmadesilva]

Claude Sonnet analysis:

There are pros and cons to both approaches:

Relative links:

• More portable - the site can be moved to different domains without breaking links
• Easier local testing without needing to change link structures
• Slightly shorter URLs

Absolute links:

• Work correctly when pages are accessed out of context (e.g. from search results, RSS feeds)
• Avoid potential issues with URL resolution in edge cases
• Make it clear which domain content belongs to

In general, using relative links within a static site is often preferred for maintainability and portability reasons. However, the best choice can depend on your specific use case.

Some static site generators offer options to use relative links internally but output absolute URLs in feeds and sitemaps. This gives you the benefits of both approaches.

[emmadesilva]

I think that sitemaps, RSS feeds, and metadata (where specs require it) should use absolute URLs; otherwise, we stick with relative. It's a nice feature of Hyde that we resolve these so well. Later once the Asset API (#1904) is finalized, we can add a configurable option to override this on a global project level.