{"id":13612145,"url":"https://github.com/nhoizey/jekyll-postfiles","last_synced_at":"2025-04-06T02:10:01.503Z","repository":{"id":50328515,"uuid":"64907981","full_name":"nhoizey/jekyll-postfiles","owner":"nhoizey","description":"A Jekyll plugin that copies static files from the _posts to the _site folder","archived":false,"fork":false,"pushed_at":"2021-03-22T04:06:54.000Z","size":129,"stargazers_count":128,"open_issues_count":21,"forks_count":16,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-04T05:31:10.786Z","etag":null,"topics":["jekyll","jekyll-plugin"],"latest_commit_sha":null,"homepage":"http://nhoizey.github.io/jekyll-postfiles/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nhoizey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-04T06:19:41.000Z","updated_at":"2025-02-13T13:28:40.000Z","dependencies_parsed_at":"2022-08-20T11:40:33.217Z","dependency_job_id":null,"html_url":"https://github.com/nhoizey/jekyll-postfiles","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhoizey%2Fjekyll-postfiles","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhoizey%2Fjekyll-postfiles/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhoizey%2Fjekyll-postfiles/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nhoizey%2Fjekyll-postfiles/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nhoizey","download_url":"https://codeload.github.com/nhoizey/jekyll-postfiles/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423515,"owners_count":20936626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jekyll","jekyll-plugin"],"created_at":"2024-08-01T20:00:23.349Z","updated_at":"2025-04-06T02:10:01.482Z","avatar_url":"https://github.com/nhoizey.png","language":"Ruby","funding_links":[],"categories":["Images \u0026 Pictures","Ruby"],"sub_categories":[],"readme":"# jekyll-postfiles\n\n[![Gem Version](https://badge.fury.io/rb/jekyll-postfiles.svg)](https://badge.fury.io/rb/jekyll-postfiles)\n[![Gem Downloads](https://img.shields.io/gem/dt/jekyll-postfiles.svg?style=flat)](http://rubygems.org/gems/jekyll-postfiles)\n[![Build Status](https://travis-ci.org/nhoizey/jekyll-postfiles.svg?branch=master)](https://travis-ci.org/nhoizey/jekyll-postfiles)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [Easing the management of images (and other files) attached to Markdown posts](#easing-the-management-of-images-and-other-files-attached-to-markdown-posts)\n  - [The pain of Jekyll's recommended posts assets management](#the-pain-of-jekylls-recommended-posts-assets-management)\n  - [There must be another way](#there-must-be-another-way)\n  - [Not every assets need this](#not-every-assets-need-this)\n- [How does it work?](#how-does-it-work)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Contributing](#contributing)\n- [License](#license)\n- [Thanks](#thanks)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Easing the management of images (and other files) attached to Markdown posts\n\n### The pain of Jekyll's recommended posts assets management\n\nJekyll's natural way to deal with static files attached to posts, like images or PDFs, is to put them all in a global `assets/` (or `downloads/`) folder at the site root. Read \"[Including images and resources](https://jekyllrb.com/docs/posts/#including-images-and-resources)\" in Jekyll's documentation.\n\nYou can of course put files in subfolders of `assets/`, but it will be really cumbersome to manage posts' Markdown files in `_posts/` or a subfolder, and images elsewhere, and then use the good hierarchy in all Markdown image tags.\n\nImagine you have these files:\n\n```\n_posts/\n  2016-06/\n    2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md\n…\nassets/\n  2016-06-09-cloudflare/\n    cloudflare-architecture.png\n    performance-report-sample.pdf\n```\n\nTo use the image and PDF files in the post's Markdown, you will have to write this:\n\n```markdown\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua.\n\n![Cloudflare architecture](/assets/2016-06-09-cloudflare/cloudflare-architecture.png)\n\nUt enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat.\n\nHere is [an example of performance report](/assets/2016-06-09-cloudflare/performance-report-sample.pdf).\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua.\n```\n\nPainful to write.\n\nImagine you want to change the post's publication date, or one of the file names?\n\nPainful to update.\n\nWhat if you want to put new WIP Markdown files in `_drafts/`, and the attached assets somewhere in a way they won't be copied to the destination `_site/` folder next time you build the site? You can't put the files in the `assets/` folder, so when you will publish the draft, you will have to change the assets location in the Markdown file.\n\nPainful, and prone to errors.\n\nAnd what about previewing the content while editing? If you use an editor like [MacDown](http://macdown.uranusjr.com/) with live preview, how will it find the actual path to the images? What means `/assets/…` for the editor?\n\nPainful to preview.\n\n### There must be another way\n\nWhat if instead, you could have the files stored like that:\n\n```\n_posts/\n  2016-06-09-cloudflare/\n    2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md\n    cloudflare-architecture.png\n    performance-report-sample.pdf\n```\n\nAnd if you could write your Markdown like this:\n\n```markdown\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua.\n\n![Cloudflare architecture](cloudflare-architecture.png)\n\nUt enim ad minim veniam,\nquis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo\nconsequat.\n\nHere is [an example of performance report](performance-report-sample.pdf).\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod\ntempor incididunt ut labore et dolore magna aliqua.\n```\n\nMuch easier!\n\n- Easy to store, everything is in one single folder.\n- Easy to write, no path to add to file links\n- Easy to update\n- Easy to move from `_drafts/` to `_posts/`, without anything to change in the Markdown content\n- Easy to edit in any editor with live preview\n\n### Not every assets need this\n\n[Some Jekyll users will try to convince you](http://stackoverflow.com/a/10366173/717195) it's a bad idea, because it means the asset is tightly linked to the post.\n\nIn my own experience, 95% of assets, at least, are used in one single post. And this is pretty common to find such requests from users of other static generators, like [Hugo](https://github.com/spf13/hugo/issues/147) ([fixed in May 2015](https://github.com/spf13/hugo/issues/147#issuecomment-104067783)), [Nikola](https://github.com/getnikola/nikola/issues/2266) ([already there, but not obvious or user friendly](https://github.com/getnikola/nikola/issues/2266#issuecomment-189211387)), [Octopress](http://stackoverflow.com/questions/17052468/insert-local-image-into-a-blog-post-with-octopress), etc.\n\nBut it's true this might not be ideal for all assets (the remaining 5%), so you can of course continue using full assets paths with `/assets/…` to have a few assets shared by several posts.\n\n## How does it work?\n\nThis plugin takes any file that is in posts folders, and copy them to the folder in which the post HTML page will be created.\n\nLet's say you have these files:\n\n```\n_posts/\n  2016-06-09-cloudflare/\n    2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md\n    cloudflare-architecture.png\n    performance-report-sample.pdf\n```\n\nAnd your Jekyll settings for permalinks are these:\n\n```yaml\n# Permalinks\npermalink: /:year/:month/:day/:title/\n```\n\nJekyll with this plugin will generate the site content like this:\n\n```\n2016/\n  06/\n    09/\n      so-long-cloudflare-and-thanks-for-all-the-fissh/\n        index.html\n        cloudflare-logo.png\n        performance-report-sample.pdf\n```\n\nIf you change your Jekyll settings for permalinks like these:\n\n```yaml\n# Permalinks\npermalink: /:year/:month/:day/:title.html\n```\n\nJekyll with this plugin will generate the site content like this:\n\n```\n2016/\n  06/\n    09/\n      so-long-cloudflare-and-thanks-for-all-the-fissh.html\n      cloudflare-logo.png\n      performance-report-sample.pdf\n```\n\nHandy, isn't it?\n\n## Installation\n\nAdd `gem 'jekyll-postfiles'` to the `jekyll_plugin` group in your `Gemfile`:\n\n```ruby\nsource 'https://rubygems.org'\n\ngem 'jekyll'\n\ngroup :jekyll_plugins do\n  gem 'jekyll-postfiles'\nend\n```\n\nThen run `bundle` to install the gem.\n\n## Usage\n\nYou don't have anything to do.\n\nJust put the images (and PDFs, etc.) in the same folder as your Markdown files, or even subfolders, and use the standard Markdown image syntax, with a relative path.\n\n## Compatibility\n\n:warning: This plugin is not supported by Github Pages, host your site on services like https://netlify.com which support third party plugins.\n\n## Contributing\n\nThanks for your interest in contributing! There are many ways to contribute to this project. [Get started here](https://github.com/nhoizey/jekyll-postfiles/blob/master/CONTRIBUTING.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n## Thanks\n\nInspired by [this old Gist](https://gist.github.com/kevinoid/3131752) by [@kevinoid](https://github.com/kevinoid/).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhoizey%2Fjekyll-postfiles","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhoizey%2Fjekyll-postfiles","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhoizey%2Fjekyll-postfiles/lists"}