jekyll-lilypond 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03f518ed64fd17a4aa282f1e11c82f1ea127de1231919ad2f22f419f3a95d942
+  data.tar.gz: 8225e9fd20e2be85d2be52781a01d65de431313399d7313d754e416f78148c6c
+SHA512:
+  metadata.gz: 48f09dbd1c6101a2ff2d13500690f72efee15bfc7b33cc647ecf050de11f082de1bc195a16fa56d52958b7605c362cf7a21258498f0cce8c51015436261056c5
+  data.tar.gz: 0b51587b3ff6e62de63486833c9269bd961d025d047770431adcb8b7fb0c98207eb6798efee19ee6e175e7a705d4811216395004290f7fe223755552dac9788c

data/.gitignore

@@ -0,0 +1,12 @@
+spec/dest
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gem "jekyll"
+gem "minima"
+
+group :development, :test do
+  gem "rspec"
+  gem 'simplecov', require: false, group: :test
+end

data/Gemfile.lock

@@ -0,0 +1,99 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.7)
+    diff-lcs (1.4.4)
+    docile (1.3.5)
+    em-websocket (0.5.2)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    eventmachine (1.2.7)
+    ffi (1.14.2)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.6.0)
+    i18n (1.8.7)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.0)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-feed (0.15.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (2.1.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-seo-tag (2.7.1)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.3.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.4.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    minima (2.5.1)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-feed (~> 0.9)
+      jekyll-seo-tag (~> 2.1)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.6)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.4)
+    rouge (3.26.0)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.1)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.2)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.7.0)
+
+PLATFORMS
+  universal-darwin-19
+
+DEPENDENCIES
+  jekyll
+  minima
+  rspec
+  simplecov
+
+BUNDLED WITH
+   2.2.5

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Leah Velleman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# jekyll-lilypond
+
+<p align="center">
+<img src="files/rite.png" width="75%"/>
+</p>
+                                      
+Automatically generate sheet music images by adding Lilypond blocks to your markdown files. Customize their
+appearance using Liquid attributes. The plugin caches the images it generates, making auto-regeneration fast.
+
+For complete documentation, see [the plugin website](https://www.velleman.org/jekyll-lilypond).
+
+
+## Installation
+
+The plugin requires Lilypond and Inkscape. To use it in a Jekyll site,
+add 
+
+```ruby
+gem 'jekyll-lilypond'
+```
+
+to your Gemfile and
+
+```yaml
+plugins:
+  - jekyll-lilypond
+```
+
+to your `_config.yml`.
+
+## Quick start
+
+Inside the block, write a Lilypond music expression.
+```
+{% lilypond alt: "Five notes of the A-minor scale" %}
+  a b c d e 
+{% endlilypond %}
+```
+The expression can include multiple staves, expressive marks, time and key signature changes, and any of the other notation Lilypond supports within a music
+expression. For details, see [this brief summary](https://lilypond.org/doc/v2.20/Documentation/learning/score-is-a-_0028single_0029-compound-musical-expression) in the Lilypond teaching manual or [Wikipedia's list of common music expression details](https://en.wikipedia.org/wiki/Help:Score#Syntax).
+
+To make customizations that can't be make within a music expression — for instance, to change the width or height of the score or specify a custom font —
+use attributes on the `{% lilypond %}` tag. For more information on attributes, see [the plugin documentation](http://127.0.0.1:4000/jekyll-lilypond#attributes).
+
+## Approach
+
+### Caching
+
+Lilypond runs more slowly than Jekyll, and regenerating every score would create a noticeable lag. This would be especially painful in auto-regenerate mode,
+which is normally very responsive. To solve this, I cache images. Each Lilypond source file, and each resulting image, has a filename derived from the MD5 hash
+of the source code. The plugin only compiles a Lilypond source file when the corresponding image does not yet exist. 
+
+To force the plugin to regenerate all of the score images for a site, which is sometimes useful for debugging, empty the `lilypond_files` directory. 
+
+To keep upload size to a minimum, you can also empty the `lilypond_files` directory and regenerate the site before deploying. This removes "stale" images 
+that are no longer in use.
+
+### Templates
+
+The plugin generates two kinds of code: Lilypond source files, which it uses to generate images, and HTML includes, which appear in the finished page
+and contain the `img` element and surrounding markup. 
+
+To generate both kinds of source code, it uses Liquid templates. Liquid is the native templating language of Jekyll. Just as Jekyll users can write their own
+templates to create new page layouts, users of this plugin can write their own templates to add simple features and customizations.
+
+As well as allowing customization, using a template to generate Lilypond source avoids the need to repeat boilerplate. For instance, the default Lilypond
+template begins like this:
+```
+\version "2.20.0"
+\paper {
+  indent = 0\mm
+  short-indent = 0\mm
+  bottom-margin = 4\mm
+  oddHeaderMarkup = ##f
+  evenHeaderMarkup = ##f
+  oddFooterMarkup = ##f
+  evenFooterMarkup = ##f
+  ...
+}
+```
+These settings produce clean output without extraneous marks, headers, footers, or whitespace, but it would be a hassle to retype them in every Lilypond block.
+Later parts of the template include correct code for setting the page width, font, and so on, which saves the user from needing to remember the somewhat 
+arbitrary syntax for doing those things.
+
+### Future plans
+
+The next thing on my agenda is to generate assets other than images. For instance, Lilypond can generate MIDI files and software synthesizers can generate
+mp3 audio from MIDI. It would be nice to support those — and, beyond that, to support other workflows that users might think of. (Maybe someone will want to 
+generate video? Or do musical analysis on MIDI files?)
+
+The most flexible way to do all this would be to let users specify workflow steps in a sitewide Rakefile, alongside whatever other deployment and
+asset-processing tasks they may have specified there. Templates could then specify what sorts of generated files they require, and the plugin could call on
+Rake to generate those that don't exist. 
+
+## Testing
+
+`bundle exec rspec` runs tests. A minimal sample Jekyll site for tests to call on is in `spec/fixtures`, 
+with the interesting details being the sample templates in `spec/fixtures/layouts`.

data/jekyll-lilypond.gemspec

@@ -0,0 +1,23 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "jekyll-lilypond/version"
+
+Gem::Specification.new do |spec|
+  spec.version = "0.1.1"
+  spec.authors = "Leah Velleman"
+  spec.name = "jekyll-lilypond"
+  spec.summary = "Lilypond music snippets in Jekyll"
+  spec.homepage = "https://www.velleman.org/jekyll-lilypond.html"
+  spec.license = "MIT"
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.metadata = {
+    "documentation_uri" => "https://www.velleman.org/jekyll-lilypond.html",
+    "source_code_uri" => "https://github.com/leahvelleman/jekyll-lilypond"
+  }
+  spec.require_paths = ["lib"]
+  spec.add_dependency "jekyll", ">= 3.0", "< 5.0"
+  spec.add_development_dependency "rspec", "~> 3.5"
+end
+
+

data/lib/jekyll-lilypond/file_processor.rb

@@ -0,0 +1,67 @@
+require "digest"
+
+module Jekyll
+  module Lilypond
+    class FileProcessor
+      def initialize(working_dir, hash, source)
+        @hash = hash
+        @source = source
+        @working_dir = working_dir
+      end
+
+      def filepath
+        "#{@working_dir}/#{@hash}"
+      end
+        
+      def write
+        unless File.directory?(@working_dir)
+          FileUtils.mkdir_p(@working_dir)
+        end
+        unless File.exist?("#{filepath}.ly")
+          File.open("#{filepath}.ly", "w") do |f|
+            f.write(@source)
+          end
+        end
+      end
+
+      def compile
+        unless File.exist?("#{filepath}.svg")
+          puts "Jekyll-lilypond: making #{@hash}.svg"
+          Kernel.system("lilypond", "-lERROR", 
+                        "-dbackend=svg", 
+                        "--output=#{filepath}", 
+                        "#{filepath}.ly")
+        end
+      end
+
+      def trim_svg
+        unless File.exist?("#{filepath}-trimmed.svg")
+          if File.exist?("#{filepath}.svg")
+            puts "Jekyll-lilypond: making #{@hash}-trimmed.svg"
+            Kernel.system("inkscape", 
+                          "#{filepath}.svg", 
+                          "--export-area-drawing", 
+                          "--export-type=svg", 
+                          "--export-filename=#{filepath}-trimmed.svg")
+          else
+            raise RuntimeError.new(
+              "Cannot trim SVG: expected SVG file #{filepath}.svg does not exist")
+          end
+        end
+      end
+
+      def make_mp3
+        unless File.exist?("#{filepath}.mp3")
+          if File.exist?("#{filepath}.midi")
+            puts "Jekyll-lilypond: making #{@hash}.mp3"
+            Kernel.system("timidity #{filepath}.midi -Ow -o - | ffmpeg -i - -acodec libmp3lame -ab 64k #{filepath}.mp3", [:out, :err] => "/dev/null")
+          else
+            raise RuntimeError.new(
+              "Cannot generate mp3: expected MIDI file #{filepath}.midi does not exist.")
+          end
+        end
+      end
+    end
+  end
+end
+

data/lib/jekyll-lilypond/lilypond_tag.rb

@@ -0,0 +1,34 @@
+module Jekyll
+  module Lilypond
+    class LilypondTag < Liquid::Block
+      def initialize(_, argtext, _)
+        super
+        @attributes = parse_attributes(argtext)
+      end
+
+      def parse_attributes(text)
+        attributes = {}
+        text.scan(Liquid::TagAttributes) do |key, value|
+          value=value.delete_prefix('"').delete_prefix("'")
+          value=value.delete_suffix('"').delete_suffix("'")
+          attributes[key] = value
+        end
+        attributes["attr_text"] = text
+        attributes
+      end
+
+      def render(context)
+        content = super.strip
+        site =  context.registers[:site]
+
+        tag = Tag.new(@attributes, content)
+        tp = TagProcessor.new(site, tag)
+        tp.run!
+        tp.include
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("lilypond", Jekyll::Lilypond::LilypondTag)
+

data/lib/jekyll-lilypond/tag.rb

@@ -0,0 +1,17 @@
+module Jekyll
+  module Lilypond
+    class Tag
+      attr_accessor :attrs, :template_names, :template_code
+
+      def initialize(attrs, content)
+        @attrs = attrs
+        @attrs["content"] = content
+        @template_names = { source: @attrs.delete("source_template"),
+                            include: @attrs.delete("include_template") }
+        @template_code = { source: @attrs.delete("source_template_code"),
+                           include: @attrs.delete("include_template_code") }
+      end
+    end
+  end
+end
+

data/lib/jekyll-lilypond/tag_processor.rb

@@ -0,0 +1,56 @@
+module Jekyll
+  module Lilypond
+    class TagProcessor
+      attr_accessor :site
+
+      def initialize(site, tag)
+        @site = site
+        @tag = tag
+      end
+
+      def source
+        source_template_obj.render(@tag)
+      end
+
+      def source_template_obj
+        Template.new(@site, @tag, :source)
+      end
+
+      def hash
+        Digest::MD5.hexdigest(source)
+      end
+
+      def include
+        @tag.attrs.update("filename" => hash)
+        include_template_obj.render(@tag)
+      end
+
+      def include_template_obj
+        Template.new(@site, @tag, :include)
+      end
+
+      def file_processor
+        FileProcessor.new("#{site.source}/lilypond_files", hash, source)
+      end
+
+      def run! 
+        fp = file_processor
+        fp.write
+        fp.compile
+        fp.trim_svg
+        fp.make_mp3 if @tag.attrs["mp3"] == "true"
+
+        @site.static_files << StaticFile.new(site, 
+                                             site.source, 
+                                             "lilypond_files", 
+                                             "#{hash}-trimmed.svg") 
+
+        @site.static_files << StaticFile.new(site, 
+                                             site.source, 
+                                             "lilypond_files", 
+                                             "#{hash}.mp3") if @tag.attrs["mp3"] == "true"
+      end
+    end
+  end
+end
+

data/lib/jekyll-lilypond/templates/basic.ly

@@ -0,0 +1,45 @@
+\version "2.20.0"
+\include "articulate.ly"
+\paper {
+  indent = 0\mm
+  short-indent = 0\mm
+  {% if width %}
+    paper-width = {{ width }}\in
+    {% if height %}
+      paper-height = {{ height }}\in
+    {% else %}
+      page-breaking = #ly:one-page-breaking
+    {% endif %}
+  {% else %}
+    page-breaking = #ly:one-line-breaking
+  {% endif %}
+  left-margin = 4\mm
+  right-margin = 4\mm
+  top-margin = 4\mm
+  bottom-margin = 4\mm
+  oddHeaderMarkup = ##f
+  evenHeaderMarkup = ##f
+  oddFooterMarkup = ##f
+  evenFooterMarkup = ##f
+}
+\score {
+  \unfoldRepeats \articulate
+  <<
+  {{ content }}
+  >>
+  \layout { 
+    #(layout-set-staff-size 16)
+    \context {
+      \Lyrics
+      {% if lyricfont %}
+        \override LyricText #'font-name = #"{{ lyricfont }}"
+      {% endif %}
+      {% if lyricsize %}
+        \override LyricText #'font-size = #{{ lyricsize }}
+      {% endif %}
+    }
+  }
+  \midi { 
+    \tempo 4 = {{ tempo | default: "120" }}
+  }
+}

data/lib/jekyll-lilypond/templates/empty.ly

@@ -0,0 +1 @@
+{{ content }}

data/lib/jekyll-lilypond/templates/figure.html

@@ -0,0 +1,25 @@
+<figure>
+  <img 
+    src="lilypond_files/{{ filename }}-trimmed.svg"
+    {%- if style %}
+      style="{{ style }}"
+    {% endif -%}
+    {%- if class %}
+      class="{{ class }}"
+    {% endif -%}
+    {%- if alt %}
+      alt="{{ alt }}"
+      title="{{ alt }}"
+    {% endif -%}
+    />
+  {%- if mp3 %}
+    <audio controls>
+      <source src="lilypond_files/{{ filename }}.mp3" type="audio/mp3" />
+      Your browser does not support the <code>audio</code> element.
+    </audio>
+  {% endif -%}
+  {%- if caption %}
+    <figcaption>{{ caption }}</figcaption>
+  {% endif -%}
+</figure>
+

data/lib/jekyll-lilypond/templates/img.html

@@ -0,0 +1,4 @@
+<img src="lilypond_files/{{ filename }}-trimmed.svg"
+     alt="{{ alt }}"
+     class="{{ class }}"
+     style="{{ style }}"/>

data/lib/jekyll-lilypond/templates/raw.html

@@ -0,0 +1 @@
+{{ content }}

data/lib/jekyll-lilypond/templates/raw.ly

@@ -0,0 +1 @@
+{{ content }}

data/lib/jekyll-lilypond/templates/showsource.html

@@ -0,0 +1,36 @@
+<figure
+  {%- if style %} 
+    style="{{ style }}" 
+  {% endif -%}
+  {%- if class %}
+    class="{{ class }}"
+  {% endif -%}
+  >
+  <img src="lilypond_files/{{ filename }}-trimmed.svg" 
+    {%- if alt %}
+      alt="{{ alt }}"
+      title="{{ alt }}"
+    {% endif -%}
+    />
+  {%- if mp3 %}
+    <audio controls>
+      <source src="lilypond_files/{{ filename }}.mp3" type="audio/mp3" />
+      Your browser does not support the <code>audio</code> element.
+    </audio>
+  {% endif -%}
+  {%- if caption %}
+    <figcaption>{{ caption }}</figcaption>
+  {% endif -%}
+  <details>
+    <summary>Show source</summary>
+    <pre>
+{%- raw -%}{% {% endraw %}
+lilypond {{ attr_text -}}
+{%- raw %}%}{% endraw %}
+{{ content | escape -}}
+{%- raw -%}
+{% endlilypond %}
+{% endraw %}
+    </pre>
+  </details>
+</figure>

data/lib/jekyll-lilypond/templates.rb

@@ -0,0 +1,60 @@
+module Jekyll
+  module Lilypond
+    class Template
+      def initialize(site, tag, type)
+        @site = site
+        @type = type
+        @tag_template_names = tag.template_names
+        @tag_template_code = tag.template_code
+      end
+
+      def render(tag)
+        Liquid::Template.parse(template_code).render(tag.attrs)
+      end
+
+      def template_name
+        @tag_template_names[@type] || sitewide_template_names[@type] || plugin_template_names[@type]
+      end
+
+      def template_code
+        @tag_template_code[@type] or 
+          fetch_site_template(template_name) or
+          fetch_plugin_template(template_name) or
+          raise LoadError.new("No template named #{template_name}.#{extension}")
+      end
+
+
+      private
+      def sitewide_template_names
+        if @site.respond_to? :lilypond and @site.lilypond.respond_to? :template_names 
+          @site.lilypond.template_names
+        else
+          { source: nil, include: nil }
+        end
+      end
+
+      def plugin_template_names
+        { source: "basic", include: "img" }
+      end
+
+      def fetch_site_template(name)
+        if @site.layouts[name]
+          @site.layouts[name].content.strip
+        end
+      end
+
+      def fetch_plugin_template(name)
+        dir = File.join(File.dirname(__dir__), "/jekyll-lilypond/templates/")
+        filename = File.join(dir, "#{name}.#{extension}")
+        if File.exists?(filename)
+          File.read(filename).strip
+        end
+      end
+
+      def extension
+        if @type == :source then "ly" else "html" end
+      end
+    end
+  end
+end
+

data/lib/jekyll-lilypond/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module Lilypond
+    VERSION = "0.0.0"
+  end
+end

data/lib/jekyll-lilypond.rb

@@ -0,0 +1,11 @@
+require "jekyll"
+require "jekyll-lilypond/tag.rb"
+require "jekyll-lilypond/file_processor.rb"
+require "jekyll-lilypond/templates.rb"
+require "jekyll-lilypond/tag_processor.rb"
+require "jekyll-lilypond/lilypond_tag.rb"
+
+module Jekyll
+  module Lilypond
+  end
+end