My first Jekyll GeneratorのためにJekyllを読む

先日Jekyll と Middleman の比較をして、Jekyll の方が拡張はやりやすそうという結論を出したわけだけど、実際に書くとなったら公式のドキュメントを読んでるだけだとピンとこない部分があって、それが Generator.

Generators | Jekyll • Simple, blog-aware, static sites

いきなり Generator に site オブジェクトを突っ込んで、そこから Page を生成する例が出てくるんだけど、なんでこれでうまくいくのかがよく分からない。

この理由はそもそも全体の流れが説明されていないから。ということでコードを読んでみることにする。

対象バージョンは現行の Jekyll 3.8.5

まずはcommandから

jekyll の操作は

$ jekyll <command>

から始まる。これを担うのが commands/ 以下のコマンド群だ。

exe/jekyll

を読むと command 群は init_with_program が呼ばれるのが分かるので、例えば build.rb で追っていくと

        def init_with_program(prog)
          prog.command(:build) do |c|
            c.syntax      "build [options]"
            c.description "Build your site"
            c.alias :b

            add_build_options(c)

            c.action do |_, options|
              options["serving"] = false
              Jekyll::Commands::Build.process(options)
            end
          end
        end

中で process を呼び、process では

        def process(options)
..
          site = Jekyll::Site.new(options)
..
            build(site, options)

build を呼んでて、

        def build(site, options)
..
          process_site(site)

process_site は superclass の

      def process_site(site)
        site.process

で、Jekyll::Site オブジェクトにたどりつく。

すべてを司るJekyll::SiteオブジェクトからGenerator#generateが呼ばれる

Jekyll::Site#process はこれだけ。

    def process
      reset
      read
      generate
      render
      cleanup
      write
      print_stats if config["profile"]
    end

これを見るとピンとくるのが

Hooks | Jekyll • Simple, blog-aware, static sites

ですね。ここでようやく全体の流れが分かる。これを見ると Generator は Reader と Renderer の間で仕事をしていることが分かる。

generate の中身は

    def generate
      generators.each do |generator|
        start = Time.now
        generator.generate(self)
        Jekyll.logger.debug "Generating:",
          "#{generator.class} finished in #{Time.now - start} seconds."
      end
    end

登録された Generator それぞれの generate メソッドに Jekyll::Site そのものが渡され、site を書き換えることでコンテンツを増やし、その後 render, write が仕事をすることで実際のファイルが生成される、という流れになる。

なるほど。

Generator間の依存関係はpriorityで調整

generator の初期化は site.rb の #setup の中の

      self.generators = instantiate_subclasses(Jekyll::Generator)

からの

    def instantiate_subclasses(klass)
      klass.descendants.select { |c| !safe || c.safe }.sort.map do |c|
        c.new(config)
      end
    end

で、ここの sort で plugin.rb の

   def self.<=>(other)
     PRIORITIES[other.priority] <=> PRIORITIES[self.priority]
   end

が呼ばれて、priority の高いものから並ぶようになっている。

※ ちなみにこの setup が実行され終わる時に after_init に register した hook が走るようになっている。

したがって、例えばカテゴリやタグといった情報をもとにイマドキのリッチなスライドっぽいリンクを並べた一覧ページを作りたいということになったら、

  1. Page をなめて content から data ( Front Matter ) の中に最初の heading や paragraph, img など、リンク生成時に使いたいデータをまとめ直す処理を行う
  2. 1 のデータをもとにカテゴリやタグの Page を追加する

この際に 1, 2 の順になるように priority を調整する、という感じで利用することができる。

※ これくらいならひとまとめでもよさそうだけど、他の generator で生成したコンテンツも利用できるようになっていた方が都合がよいかもしれない。分かってくると Ganerator は応用範囲が広い感じがする。

MiddlemanのproxyのようなものもGeneratorで解決できる

考え方は以下のような感じ。

  1. site.data, site.pages などから必要なデータを取得して
  2. 取得したデータをもとに Jekyll::PageWithoutAFile を継承した Page を生成
    • この際、Page#initialize とはリスコフの置換原則を破るようにしないと page 独自の data は渡せないことに注意が必要。
   def initialize(site, base, dir, name)

適当に keyword args 足せばいいと思う :p

layout はいちいち指定してもいいけど、_config.yml の defaults で一気に指定するようにした方がたぶん他のものと整合性が確保できてよい感じになる。

Front Matter Defaults | Jekyll • Simple, blog-aware, static sites

More

Categories

Tool 日々 Web Biz Net Apple MS ことば News Unix howto Food PHP Movie Edu Community Book Security Text TV Perl Ruby Music Pdoc 生き方 RDoc ViewCVS CVS Rsync Disk Mail FreeBSD Cygwin PDF Photo Zebedee Debian OSX Comic Cron Sysadmin Font Analog iCal Sunbird DNS Linux Wiki Emacs Thunderbird Sitecopy Terminal Drawing tDiary AppleScript Life Money Omni PukiWiki Xen XREA Zsh Screen CASL Firefox Fink zsh haXe Ecmascript PATH_INFO SQLite PEAR Lighttpd FastCGI Subversion au prototype.js jsUnit Apache Trac Template Java Rhino Mochikit Feed Bloglines CSS del.icio.us SBS qwikWeb gettext Ajax JSDoc Rails HTML CHM EPWING NDTP EB IE CLI ck ThinkPad Toy WSH RFC readline rlwrap ImageMagick epeg Frenzy sysprep Ubuntu MeCab DTP ERD DBMS eclipse Eclipse Awk RD Diigo XAMPP RubyGems PHPDoc iCab DOM YAML Camino Geekmonkey w3m Scheme Gauche Lisp JSAN Google VMware DSL SLAX Safari Markdown Textile IRC Jabber Fastladder MacPorts LLSpirit CPAN Mozilla Twitter OpenFL Rswatch ITS NTP GUI Pragger Yapra XML Mobile Git Study JSON VirtualBox Samba Pear Growl Mercurial Rack Capistrano Rake Win RSS Mechanize Sitemaps Android JavaScript Python RTM OOo iPod Yahoo Unicode Github iTunes God SBM friendfeed Friendfeed HokuUn Sinatra TDD Test Project Evernote iPad Geohash Location Map Search Simplenote Image WebKit RSpec Phone CSV WiMAX USB Chrome RubyKaigi RubyKaigi2011 Space CoffeeScript Nokogiri Hpricot Rubygems jQuery Node GTD CI UX Design VCS Kanazawa.rb Kindle Amazon Agile Vagrant Chef Windows Composer Dotenv PaaS Itamae SaaS Docker Swagger Grape WebAPI Microservices OmniAuth HTTP 分析基盤 CDN Terraform IaaS HCL Webpack Vue.js BigQuery Middleman CMS AWS PNG Laravel Selenium OAuth OpenAPI GitHub UML GCP TypeScript SQL Hanami Dev Jekyll