{
  "version": "https://jsonfeed.org/version/1",
  "title": "Marmite 0.4.0",
  "home_page_url": "https://marmite.blog",
  "feed_url": "https://marmite.blog/tag-media.json",
  "description": "Static Site Generator <br> <small>for blogs</small> <br> <small>made with ❤️ and 🦀</small>",
  "items": [
    {
      "id": "https://marmite.blog/media-organization-with-slug-based-subfolders.html",
      "url": "https://marmite.blog/media-organization-with-slug-based-subfolders.html",
      "title": "Media Organization with Slug-Based Subfolders",
      "content_html": "<p>Marmite supports organizing media files in subfolders named after your content's slug. This keeps media tidy for sites with many images per post and provides a convenient <code>@/</code> shorthand for referencing those files.</p>\n<h2><a href=\"#media-subfolder-discovery\" aria-hidden=\"true\" class=\"anchor\" id=\"media-subfolder-discovery\"></a>Media Subfolder Discovery</h2>\n<p>Banner and card images can live as flat files in <code>media/</code> with the slug as a filename prefix (e.g., <code>media/my-post.banner.jpg</code>), in a subfolder named after the slug inside <code>media/</code>, or in a <code>media/</code> directory inside a content subfolder:</p>\n<pre class=\"marmite-code\"><code class=\"marmite-code-inner\">content/\n  media/\n    my-post/\n      banner.jpg\n      card.png\n      diagram.svg\n      photo.png\n  2024-01-15-my-post.md\n</code></pre>\n<p>Or, when using content subfolders (e.g., for translations), media can live alongside the content:</p>\n<pre class=\"marmite-code\"><code class=\"marmite-code-inner\">content/\n  my-post/\n    my-post.md\n    pt-meu-post.md\n    media/\n      banner.jpg          # Shared by all files in the subfolder\n      card.png\n</code></pre>\n<p>Marmite checks for <code>banner.{ext}</code> and <code>card.{ext}</code> files automatically. The lookup order is:</p>\n<ol>\n<li><code>media/{slug}.banner.{ext}</code> (flat file in global media)</li>\n<li><code>content/{slug}/media/banner.{ext}</code> (content subfolder media - takes precedence over global)</li>\n<li><code>content/media/{slug}/banner.{ext}</code> (global media subfolder)</li>\n<li><code>content/{subfolder}/media/banner.{ext}</code> (generic fallback - shared by all files in the subfolder)</li>\n</ol>\n<p>Content subfolder media takes precedence over global media. A generic <code>banner.jpg</code> in a content subfolder's media directory is shared by all <code>.md</code> files in that subfolder, so translations automatically inherit the base content's banner without needing their own copy.</p>\n<p>Existing sites using flat files are unaffected.</p>\n<h2><a href=\"#the--shorthand\" aria-hidden=\"true\" class=\"anchor\" id=\"the--shorthand\"></a>The <code>@/</code> Shorthand</h2>\n<p>Inside markdown content, use <code>@/</code> to reference files in your content's media subfolder. Marmite replaces <code>@/</code> in image and link attributes with <code>media/{slug}/</code> in the rendered HTML.</p>\n<pre class=\"marmite-code\"><code class=\"marmite-code-inner language-markdown\"><a-p>---</a-p>\n<a-pr>title</a-pr><a-p>:</a-p> <a-s>My Post</a-s>\n<a-pr>slug</a-pr><a-p>:</a-p> <a-s>my-post</a-s>\n<a-p>---</a-p>\n\nHere is a photo from the trip:\n\n![Sunset](@/sunset.jpg)\n\nDownload the [full resolution version](@/sunset-full.jpg).</code></pre>\n<p>The rendered HTML will contain <code>src=&quot;media/my-post/sunset.jpg&quot;</code> and <code>href=&quot;media/my-post/sunset-full.jpg&quot;</code>.</p>\n<h3><a href=\"#what-gets-replaced\" aria-hidden=\"true\" class=\"anchor\" id=\"what-gets-replaced\"></a>What gets replaced</h3>\n<p>The <code>@/</code> replacement only applies to <code>src</code> and <code>href</code> attributes in the final HTML. It does <strong>not</strong> affect:</p>\n<ul>\n<li><strong>Plain text</strong> - Writing <code>@/</code> in a paragraph leaves it as-is</li>\n<li><strong>Code blocks</strong> - Documenting the feature with <code>`@/example.png`</code> or fenced code blocks works correctly</li>\n<li><strong>Fragment files</strong> - Files prefixed with <code>_</code> (like <code>_hero.md</code>) do not get <code>@/</code> replacement since they are shared across content and have no slug context</li>\n</ul>\n<h3><a href=\"#custom-media-path\" aria-hidden=\"true\" class=\"anchor\" id=\"custom-media-path\"></a>Custom media path</h3>\n<p>If you configure a custom <code>media_path</code> in <code>marmite.yaml</code>, the <code>@/</code> shorthand uses it:</p>\n<pre class=\"marmite-code\"><code class=\"marmite-code-inner language-yaml\"><a-pr>media_path</a-pr><a-p>:</a-p> <a-s>assets</a-s></code></pre>\n<p>With this config, <code>@/photo.png</code> in a post with slug <code>my-post</code> becomes <code>assets/my-post/photo.png</code>.</p>\n<h2><a href=\"#putting-it-together\" aria-hidden=\"true\" class=\"anchor\" id=\"putting-it-together\"></a>Putting It Together</h2>\n<p>A typical workflow for a media-heavy post:</p>\n<ol>\n<li>Create your post: <code>content/2024-06-15-travel-photos.md</code></li>\n<li>Create the media subfolder: <code>content/media/travel-photos/</code></li>\n<li>Place your images there: <code>banner.jpg</code>, <code>card.png</code>, <code>photo1.jpg</code>, <code>photo2.jpg</code></li>\n<li>Reference images in markdown with <code>@/</code>:</li>\n</ol>\n<pre class=\"marmite-code\"><code class=\"marmite-code-inner language-markdown\"><a-p>---</a-p>\n<a-pr>title</a-pr><a-p>:</a-p> <a-s>Travel Photos</a-s>\n<a-pr>slug</a-pr><a-p>:</a-p> <a-s>travel-photos</a-s>\n<a-pr>date</a-pr><a-p>:</a-p> <a-s>2024-06-15</a-s>\n<a-p>---</a-p>\n\n![Beach at sunset](@/photo1.jpg)\n\n![Mountain view](@/photo2.jpg)</code></pre>\n<p>Marmite will:</p>\n<ul>\n<li>Automatically discover <code>media/travel-photos/banner.jpg</code> as the banner image</li>\n<li>Automatically discover <code>media/travel-photos/card.png</code> as the card image</li>\n<li>Replace <code>@/photo1.jpg</code> with <code>media/travel-photos/photo1.jpg</code> in the rendered HTML</li>\n<li>Copy the entire <code>media/travel-photos/</code> folder to the output directory</li>\n</ul>\n<h2><a href=\"#media-with-content-subfolders\" aria-hidden=\"true\" class=\"anchor\" id=\"media-with-content-subfolders\"></a>Media with Content Subfolders</h2>\n<p>When using content subfolders (for example, for multilingual content), you can place a <code>media/</code> directory inside the content subfolder instead of using the global <code>content/media/</code> folder:</p>\n<pre class=\"marmite-code\"><code class=\"marmite-code-inner\">content/\n  travel-photos/\n    travel-photos.md\n    pt-fotos-de-viagem.md\n    es-fotos-de-viaje.md\n    media/\n      banner.jpg\n      card.png\n      photo1.jpg\n</code></pre>\n<p>This keeps media files close to the content that uses them. The <code>media/</code> directory inside a content subfolder is automatically copied to <code>output/media/{subfolder_name}/</code> during the build.</p>\n<p>A generic <code>banner.jpg</code> or <code>card.png</code> (without a slug prefix) in the subfolder's media directory is shared by all <code>.md</code> files in that subfolder. This is useful for translations - all language versions of a post inherit the same banner image without needing separate copies or frontmatter overrides.</p>\n<p>Any individual file can still override the shared media by setting <code>banner_image</code> or <code>card_image</code> in its own frontmatter, or by having a slug-specific file like <code>media/{slug}.banner.jpg</code>.</p>\n<blockquote>\n<p>Please consider giving a ☆ on Marmite <a href=\"https://github.com/rochacbruno/marmite\">Github</a> repository, that helps a lot!</p>\n</blockquote>\n<!-- Contents from _markdown_footer.md are appended to every content -->\n<!-- _references.md is a file to gather all references together \nthis file is appended to every raw markdown.\n-->\n",
      "summary": "\"Organize media files in per-content subfolders and reference them with the @/ shorthand in markdown\"",
      "date_published": "2026-06-25T00:00:00-00:00",
      "image": "media/media-organization-with-slug-based-subfolders.banner.jpg",
      "authors": [
        {
          "name": "Bruno Rocha",
          "url": "https://go.rocha.social/@bruno",
          "avatar": "https://github.com/rochacbruno.png"
        }
      ],
      "tags": [
        "docs",
        "features",
        "media",
        "images"
      ],
      "language": "en"
    }
  ]
}