eleventy-plugin-relat11ve

🌎 English | 🇯🇵 日本語

🌎 English

An Eleventy (11ty) plugin to safely and automatically transform absolute paths to relative paths in HTML and CSS.

Write your code comfortably using root-relative paths (/assets/...) during development, and output perfectly linked relative paths (../assets/...) for your build. Ideal for local viewing or decentralized hosting like IPFS.

✨ Features

• Zero Dependencies: Just 11ty and this plugin. No bloated parsers.
• CSS Support: Transforms src, href, data-* in HTML, as well as url(/...) inside <style> tags and style="" attributes.
• Safe for Tech Blogs: Automatically ignores contents inside <pre> and <code> blocks to prevent accidental path replacement in your code snippets.
• Manual Ignore: Explicitly protect specific blocks from transformation using HTML comments.

📦 Installation

npm install eleventy-plugin-relat11ve

🚀 Usage

Add the plugin to your .eleventy.js config.

const relat11ve = require("eleventy-plugin-relat11ve");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(relat11ve);
};

Input / Output Example

Input (Development):

<img src="/img/hero.jpg">
<style>.bg { background: url(/img/bg.png); }</style>

Output (Built as /news/detail/index.html):

<img src="../../img/hero.jpg">
<style>.bg { background: url(../../img/bg.png); }</style>

⚙️ Configuration

By default, safety protections are enabled. You can disable them if you are building a simple LP or corporate site.

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(relat11ve, {
    ignoreCodeBlocks: false, // Disable auto-ignore for <pre> and <code> (Default: true)
    ignoreComments: false    // Disable manual comment ignore (Default: true)
  });
};

Manual Ignore

When ignoreComments is true, wrap content in these comments to protect it from transformation. Useful for rendering raw JSON from an API.

<!-- RELATIVE_IGNORE_START -->
<pre>
{
  "user_profile": "/assets/img/avatar.png"
}
</pre>
<!-- RELATIVE_IGNORE_END -->

Working with <script> tags

For JavaScript, it is best practice to pass paths via HTML data-* attributes:

<section id="hero" data-bg-pc="/assets_2026/img/hero.png"></section>
<script>
  const paths = {
      bgPc: document.getElementById('hero').dataset.bgPc
  };
  const bgTexturePC = loader.load(paths.bgPc); // Path is safely resolved!
</script>

🇯🇵 日本語

Eleventy (11ty) でビルドされたHTMLやCSS内の絶対パス（/assets/...）を、ディレクトリ階層に応じた正しい相対パス（../assets/...）へ自動的かつ安全に変換するプラグインです。

開発時はルート相対パスで快適にコーディングしつつ、ビルド結果は「ローカルのPCで直接開いても」「IPFSなどの分散型ホスティングに上げても」絶対にリンク切れしない、最強のポータビリティを実現します。

✨ 特徴

• 依存関係ゼロ: 11ty + このプラグインのみ。他に必須なプラグインは無いです。
• CSSにも対応: HTMLタグの src href data-* だけでなく、<style> タグや style="" 属性内の url(/...) も正確に変換します。
• 技術ブログ向けの安全設計: <pre> や <code> ブロック内のテキストは自動で変換対象から除外（退避）されるため、ソースコードが勝手に書き換わる誤爆バグが起きません。
• 手動での保護機能: 特定のブロックを変換させたくない場合は、HTMLコメントで明示的に保護することができます。

📦 インストール

npm install eleventy-plugin-relat11ve

🚀 使い方

あなたの .eleventy.js にプラグインを追加するだけです。

const relat11ve = require("eleventy-plugin-relat11ve");

module.exports = function(eleventyConfig) {
  // 基本的な使い方（デフォルト設定）
  eleventyConfig.addPlugin(relat11ve);
};

変換の挙動

開発時のコード（Input）:

<img src="/img/hero.jpg">
<style>.bg { background: url(/img/bg.png); }</style>

/news/detail/index.html としてビルドされた結果（Output）:

<img src="../../img/hero.jpg">
<style>.bg { background: url(../../img/bg.png); }</style>

⚙️ オプション設定

デフォルトでは、ソースコードの誤変換を防ぐための保護機能がすべてONになっています。コーポレートサイトやLP制作など、保護機能が不要な場合はオプションでオフにすることができます。

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(relat11ve, {
    // <pre> と <code> ブロック内の自動保護を無効にする（デフォルト: true）
    ignoreCodeBlocks: false, 
    
    // 手動コメントによる保護機能を無効にする（デフォルト: true）
    ignoreComments: false
  });
};

手動でのパス保護（Manual Ignore）

ignoreComments: true の場合、以下のHTMLコメントで囲まれた範囲はパス変換の対象外となります。REST APIの生のJSONを画面に出力したい場合などに便利です。

<!-- RELATIVE_IGNORE_START -->
<pre>
{
  "user_profile": "/assets/img/avatar.png"
}
</pre>
<!-- RELATIVE_IGNORE_END -->

Scriptタグ内でも使う場合

下記のようにScriptタグ内で使う時は、HTMLの dataset プロパティを経由して受け取ることで安全に回避できます。

<section id="hero" data-bg-pc="/assets_2026/img/hero.png"></section>
<script>
  const paths = {
      bgPc: document.getElementById('hero').dataset.bgPc
  };
  const bgTexturePC = loader.load(paths.bgPc);
</script>

📄 License

MIT