当前位置: 首页 > 软件库 > Web应用开发 > >

jekyll-postfiles

授权协议 MIT License
开发语言 JavaScript
所属分类 Web应用开发
软件类型 开源软件
地区 不详
投 递 者 湛联
操作系统 未知
开源组织
适用人群 未知
 软件概览

jekyll-postfiles

Easing the management of images (and other files) attached to Markdown posts

The pain of Jekyll's recommended posts assets management

Jekyll'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" in Jekyll's documentation.

You 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.

Imagine you have these files:

_posts/
  2016-06/
    2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md
…
assets/
  2016-06-09-cloudflare/
    cloudflare-architecture.png
    performance-report-sample.pdf

To use the image and PDF files in the post's Markdown, you will have to write this:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.

![Cloudflare architecture](/assets/2016-06-09-cloudflare/cloudflare-architecture.png)

Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.

Here is [an example of performance report](/assets/2016-06-09-cloudflare/performance-report-sample.pdf).

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.

Painful to write.

Imagine you want to change the post's publication date, or one of the file names?

Painful to update.

What 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.

Painful, and prone to errors.

And what about previewing the content while editing? If you use an editor like MacDown with live preview, how will it find the actual path to the images? What means /assets/… for the editor?

Painful to preview.

There must be another way

What if instead, you could have the files stored like that:

_posts/
  2016-06-09-cloudflare/
    2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md
    cloudflare-architecture.png
    performance-report-sample.pdf

And if you could write your Markdown like this:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.

![Cloudflare architecture](cloudflare-architecture.png)

Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat.

Here is [an example of performance report](performance-report-sample.pdf).

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua.

Much easier!

  • Easy to store, everything is in one single folder.
  • Easy to write, no path to add to file links
  • Easy to update
  • Easy to move from _drafts/ to _posts/, without anything to change in the Markdown content
  • Easy to edit in any editor with live preview

Not every assets need this

Some Jekyll users will try to convince you it's a bad idea, because it means the asset is tightly linked to the post.

In 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 (fixed in May 2015), Nikola (already there, but not obvious or user friendly), Octopress, etc.

But 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.

How does it work?

This plugin takes any file that is in posts folders, and copy them to the folder in which the post HTML page will be created.

Let's say you have these files:

_posts/
  2016-06-09-cloudflare/
    2016-06-09-so-long-cloudflare-and-thanks-for-all-the-fissh.md
    cloudflare-architecture.png
    performance-report-sample.pdf

And your Jekyll settings for permalinks are these:

# Permalinks
permalink: /:year/:month/:day/:title/

Jekyll with this plugin will generate the site content like this:

2016/
  06/
    09/
      so-long-cloudflare-and-thanks-for-all-the-fissh/
        index.html
        cloudflare-logo.png
        performance-report-sample.pdf

If you change your Jekyll settings for permalinks like these:

# Permalinks
permalink: /:year/:month/:day/:title.html

Jekyll with this plugin will generate the site content like this:

2016/
  06/
    09/
      so-long-cloudflare-and-thanks-for-all-the-fissh.html
      cloudflare-logo.png
      performance-report-sample.pdf

Handy, isn't it?

Installation

Add gem 'jekyll-postfiles' to the jekyll_plugin group in your Gemfile:

source 'https://rubygems.org'

gem 'jekyll'

group :jekyll_plugins do
  gem 'jekyll-postfiles'
end

Then run bundle to install the gem.

Usage

You don't have anything to do.

Just 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.

Compatibility

⚠️ This plugin is not supported by Github Pages, host your site on services like https://netlify.com which support third party plugins.

Contributing

Thanks for your interest in contributing! There are many ways to contribute to this project. Get started here.

License

The gem is available as open source under the terms of the MIT License.

Thanks

Inspired by this old Gist by @kevinoid.

  • 页面是内容最基本的构建块。它们对于独立内容(不基于日期的内容或不属于一组内容(如 staff members 或 recipes))很有用。 添加页面的最简单方法是在根目录中添加一个具有适当文件名的HTML文件。您也可以用Markdown在一个 .md 扩展名的文件中编写页面,该文件在构建时转换为HTML。对于具有主页、关于页面和联系页面的网站,以下是根目录和相关URL的样子: . ├── abo

 相关资料
  • Jekyll 是一个简单的免费的Blog生成工具,类似WordPress。但是和WordPress又有很大的不同,原因是jekyll只是一个生成静态网页的工具,不需要数据库支持。但是可以配合第三方服务,例如discuz。最关键的是jekyll可以免费部署在Github上,而且可以绑定自己的域名。 快速安装指令: gem install jekylljekyll new my-awesome-sit

  • 中文网站 jekyllcn 快速开始 ~ $ gem install jekyll bundler ~ $ jekyll new my-awesome-site ~ $ cd my-awesome-site ~/my-awesome-site $ bundle install ~/my-awesome-site $ bundle exec jekyll serve # => 打开浏览器 http

  • jekyll-admin 是一个 jekyll 插件,为用户提供了传统 CMS(内容管理系统)风格的图形化界面来创作内容和管理 jekyll 网站。 该项目分为两部分。基于 Ruby 的 HTTP API 处理 jekyll 和文件系统的操作部分,以及在这个 API 基础上的基于 JavaScript 的前端部分。 安装: 就像安装其他插件一样,请参阅 jekyll 文档的插件安装部分安装 jek

  • Jekyll的增强版,使用Markdown来写日志。 Jekyll采用静态文件方式管理,不需要数据库即可支持一个独立博客站点,在github-pages平台上被普遍采用。Jekyll-Bootstrap在Jekyll基础上,集成了twitter-bootstrap界面风格和一些实用的插件,并且易于扩展。

  • Jekyll Docker Jekyll Docker is a software image that has Jekyll and many of its dependencies ready to use for you in an encapsulated format. It includes a default set of gems, different image types wi

  • jekyll-katex This is a Jekyll plugin for performing compile-time math rendering via the KaTeX library.KaTeX is a library for rending math on the web using LaTeX, similar to MathJax. KaTeX differs from

相关阅读

相关文章

相关问答

相关文档