jekyll-agda 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c92450f9f035ee3bc748811f609cbca048b6682a4ce0db2426bab434c04e3815
+  data.tar.gz: e12a83966d0785d9c94546b8e90e5dd7923f94d5f722a723b4743576031bfeb2
+SHA512:
+  metadata.gz: b2ec3f0bef311c39baeb72afd3368428e7556f8932ad7d0a23e86a62194e189c8696307d1da479eb488ac3e4798ced3fd621cbd72271704402153b3876834c5d
+  data.tar.gz: 395f7399ce795c69f3746efb98365cd30cb495edf9a87317b688a0501c452a6f07fb9569d03518f9e1b49ad1bbe082455ad1a1879856b1b8575648397b52fc88

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2022-01-14
+
+### Added
+
+- MVP.
+
+[unreleased]: https://github.com/paolobrasolin/jekyll-agda/compare/0.1.0...HEAD
+
+<!-- [0.2.0]: https://github.com/paolobrasolin/jekyll-agda/compare/0.1.0...0.2.0 -->
+
+[0.1.0]: https://github.com/paolobrasolin/jekyll-agda/releases/tag/0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Paolo Brasolin
+
+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,109 @@
+# jekyll-agda
+
+[![CI tests status badge][build-shield]][build-url]
+[![Latest release badge][rubygems-shield]][rubygems-url]
+[![License badge][license-shield]][license-url]
+[![Maintainability badge][cc-maintainability-shield]][cc-maintainability-url]
+[![Test coverage badge][cc-coverage-shield]][cc-coverage-url]
+
+[build-shield]: https://img.shields.io/github/workflow/status/paolobrasolin/jekyll-agda/CI/main?label=tests&logo=github
+[build-url]: https://github.com/paolobrasolin/jekyll-agda/actions/workflows/main.yml "CI tests status"
+[rubygems-shield]: https://img.shields.io/gem/v/jekyll-agda?logo=ruby
+[rubygems-url]: https://rubygems.org/gems/jekyll-agda "Latest release"
+[license-shield]: https://img.shields.io/github/license/paolobrasolin/jekyll-agda
+[license-url]: https://github.com/paolobrasolin/jekyll-agda/blob/main/LICENSE "License"
+[cc-maintainability-shield]: https://img.shields.io/codeclimate/maintainability/paolobrasolin/jekyll-agda?logo=codeclimate
+[cc-maintainability-url]: https://codeclimate.com/github/paolobrasolin/jekyll-agda "Maintainability"
+[cc-coverage-shield]: https://img.shields.io/codeclimate/coverage/paolobrasolin/jekyll-agda?logo=codeclimate&label=test%20coverage
+[cc-coverage-url]: https://codeclimate.com/github/paolobrasolin/jekyll-agda/coverage "Test coverage"
+
+`jekyll-agda` is a [Jekyll][jekyll-url] plugin which allows you to use [literate Agda][lagda-url] for your website and take full advantage of its highlighting and hyperlinking features.
+
+## Getting started
+
+Assuming you have a working [Agda][agda-url] installation and a [Jekyll][jekyll-url] website already set up, you need to do just four things.
+
+1.  Add the `jekyll-agda` gem to your plugins in the `Gemfile` and run `bundle` to install it:
+
+    ```ruby
+    # Gemfile
+    group :jekyll_plugins do
+        gem "jekyll-agda"
+    end
+    ```
+
+2.  Add Agda interface files to Jekyll's list of exclusions in `_config.yml`:
+
+    ```yaml
+    # _config.yml
+    exclude:
+      - "*.agdai"
+    ```
+
+3.  Add Agda interface files and `jekyll-agda`'s work dir to your `.gitignore`:
+
+    ```ini
+    # .gitignore
+    *.agdai
+    .agda-html/
+    ```
+
+4.  Add Agda's default stylesheet (which `jekyll-agda` will produce) to the `<head>` of your layout:
+
+    ```html
+    <link rel="stylesheet" href="{{ '/lagda/Agda.css' | relative_url }}" />
+    ```
+
+That's it!
+You can now write your posts and pages using [literate Agda][lagda-url].
+
+Here is a sample post you can save as `_posts/2022-01-14-foobar.lagda.md` to get started:
+
+````
+---
+title: My first literate Agda post
+---
+
+Let's define Peano's natural numbers:
+
+```agda
+data ℕ : Set where
+  zero : ℕ
+  suc : ℕ → ℕ
+```
+
+Is `Set` clickable? Yes it is.
+And the other keywords too!
+````
+
+## Usage
+
+Right now this plugin is an [MVP][mvp-url] and accepts no configuration, so [Getting started](#getting-started) covers pretty much everything about its usage.
+
+The only caveat is: **write your code in unnamed independent modules** to be totally safe.
+Otherwise, Agda and Jekyll naming conventions _might_ be at odds.
+You can definitely try do more complex stuff though!
+I simply haven't given this enough thought yet to clearly spell out the details (see last point of the [Roadmap](#roadmap)).
+
+## Roadmap
+
+Here is a roadmap of features I think would be useful.
+
+- Custom output path/url instead of hardcoded `/lagda`
+- Custom stylesheet instead of Agda's default `Agda.css`
+- Custom layout for `/lagda/*` pages (leveraging `--html-highlight=code` instead of `--html-highlight=auto`)
+- Find some convenient way to knit Agda and Jekyll naming conventions:
+  - Currently all pages are compiled as independent "root" files, so Agda is not affected by Jekyll's conventions as long as you don't define a `module` in your files
+  - Structuring code in multiple files/modules is doable but will require some clever dependency management to avoid redundant compilations
+  - Ideally, we'd like complete freedom in structuring code to do stuff like multiple pages corresponding to modules, or a series of posts in which later ones import the previous ones
+
+Of course any feedback is welcome!
+
+## Acknowledgements
+
+- Thanks to [@conal](https://github.com/conal) for [prompting me with the idea](https://twitter.com/conal/status/1479884896864591874).
+
+[jekyll-url]: https://jekyllrb.com/
+[agda-url]: https://github.com/agda/agda
+[lagda-url]: https://agda.readthedocs.io/en/latest/tools/literate-programming.html#literate-markdown
+[mvp-url]: https://en.wikipedia.org/wiki/Minimum_viable_product

data/lib/jekyll/agda/browsable_page.rb

@@ -0,0 +1,19 @@
+require "jekyll"
+
+module Jekyll
+  module Agda
+    class BrowsablePage < Jekyll::Page
+      def url_placeholders
+        {
+          path: Jekyll::Agda::Weaver::OUTPUT_ROOT, # instead of @dir
+          basename: basename,
+          output_ext: output_ext,
+        }
+      end
+
+      def render_with_liquid?
+        false
+      end
+    end
+  end
+end

data/lib/jekyll/agda/runner.rb

@@ -0,0 +1,82 @@
+require "open3"
+require "digest"
+
+require "jekyll"
+
+module Jekyll
+  module Agda
+    class Runner
+      RE_LAGDA_MD_EXT = /\.lagda\.md$/i
+      RE_AGDA_GENERATED_HTML_PATH = /(?<=\().*?.html(?=\))/
+
+      attr_reader :target, :dependencies, :successful
+
+      def initialize(resource, work_dir)
+        @resource = resource
+        @source = Pathname.new(@resource.path)
+
+        @work_dir = Pathname.new(work_dir)
+        @digest = @work_dir.join(@source.basename.sub(RE_LAGDA_MD_EXT, ".md5"))
+        @target = @work_dir.join(@source.basename.sub(RE_LAGDA_MD_EXT, ".md"))
+        @extras = @work_dir.join(@source.basename.sub(RE_LAGDA_MD_EXT, ".dep"))
+
+        @dependencies = []
+        @successful = nil
+      end
+
+      def execute
+        new_hash = Digest::MD5.hexdigest(@resource.content)
+
+        if [@digest, @target, @extras].all?(:exist?)
+          if new_hash == @digest.read
+            @successful = true
+            @dependencies = Marshal.load(@extras.read)
+            return
+          end
+        end
+
+        log_takeoff
+        stdout, _stderr, status = run_agda
+
+        if (@successful = status.success?)
+          @digest.write(new_hash)
+          @dependencies = stdout.scan(RE_AGDA_GENERATED_HTML_PATH)
+          @extras.write(Marshal.dump(@dependencies))
+          log_success
+        else
+          log_failure
+        end
+      end
+
+      private
+
+      def run_agda
+        Open3.capture3(
+          [
+            "agda",
+            "--html",
+            "--html-highlight=auto",
+            "--html-dir=#{@work_dir.tap(&:mkpath).realpath}",
+            @source.basename,
+          ].join(" "),
+          chdir: @source.dirname,
+        )
+      end
+
+      def log_takeoff
+        Jekyll.logger.writer << "Running Agda: ".rjust(20)
+        Jekyll.logger.writer << "??".yellow + " " + @resource.relative_path
+      end
+
+      def log_success
+        Jekyll.logger.writer << "\b" * @resource.relative_path.length
+        Jekyll.logger.writer << "\b" * 3 + "OK".green + "\n"
+      end
+
+      def log_failure
+        Jekyll.logger.writer << "\b" * @resource.relative_path.length
+        Jekyll.logger.writer << "\b" * 3 + "KO".red + "\n"
+      end
+    end
+  end
+end

data/lib/jekyll/agda/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module Agda
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll/agda/weaver.rb

@@ -0,0 +1,82 @@
+require "jekyll"
+
+require "jekyll/agda/runner"
+require "jekyll/agda/browsable_page"
+
+module Jekyll
+  module Agda
+    class Weaver
+      WORK_DIR = ".agda-html"
+      OUTPUT_ROOT = "lagda"
+
+      RE_AGDA_GENERATED_PRE = %r{<pre class="Agda">.*?</pre>}m
+      RE_HREF_VALUE = /(?<=href=")(?<page>.*?.html)(?<anchor>#\d+)?(?=")/
+
+      def self.normalize_hrefs(content, internal_page, external_root)
+        content.gsub(RE_HREF_VALUE) do
+          if Regexp.last_match[:page] == internal_page
+            Regexp.last_match[:anchor].to_s
+          else
+            "#{external_root}/#{Regexp.last_match}"
+          end
+        end
+      end
+
+      def self.strip_frontmatter(input)
+        # stolen from https://github.com/jekyll/jekyll/blob/e3cbe584f2a78141bf7f53cfef8cf237b3f4c201/lib/jekyll/document.rb#L483-L490
+        input =~ Jekyll::Document::YAML_FRONT_MATTER_REGEXP
+        Regexp.last_match&.post_match || input
+      end
+
+      def initialize(site)
+        @site = site
+        @resources = [*@site.pages, *@site.documents]
+        @dependencies_list = []
+        @dependencies_root = "#{@site.baseurl}/#{OUTPUT_ROOT}"
+      end
+
+      def execute
+        elaborate_resources
+        @dependencies_list.uniq!
+        elaborate_dependencies
+        elaborate_extra_dependency("Agda.css")
+      end
+
+      private
+
+      def elaborate_resources
+        @resources.each do |resource|
+          next unless resource.path.match?(Jekyll::Agda::Runner::RE_LAGDA_MD_EXT)
+
+          runner = Runner.new(resource, WORK_DIR)
+          next unless runner.tap(&:execute).successful
+
+          resource.content = elaborate_target(runner.target, @dependencies_root)
+          @dependencies_list.concat(runner.dependencies)
+        end
+      end
+
+      def elaborate_target(pathname, dependencies_root)
+        content = pathname.read
+        content = self.class.strip_frontmatter(content)
+        itself = pathname.basename.sub_ext(".html").to_s
+        content.gsub!(RE_AGDA_GENERATED_PRE) do |pre|
+          self.class.normalize_hrefs(pre, itself, dependencies_root)
+        end
+      end
+
+      def elaborate_dependencies
+        @dependencies_list.each do |dependency|
+          name = Pathname.new(dependency).basename.to_s
+          page = BrowsablePage.new(@site, @site.source, WORK_DIR, name)
+          @site.pages << page
+        end
+      end
+
+      def elaborate_extra_dependency(name)
+        return unless Pathname.new(WORK_DIR).join(name).exist?
+        @site.pages << BrowsablePage.new(@site, @site.source, WORK_DIR, name)
+      end
+    end
+  end
+end

data/lib/jekyll/agda.rb

@@ -0,0 +1,6 @@
+require "jekyll/agda/version"
+require "jekyll/agda/weaver"
+
+Jekyll::Hooks.register :site, :post_read do |site|
+  Jekyll::Agda::Weaver.new(site).execute
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-agda
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paolo Brasolin
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-01-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.1.3
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.10.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.10.0
+- !ruby/object:Gem::Dependency
+  name: rufo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.2
+description: This Jekyll plugin allows to you write literate Agda. It will compile
+  your code using Agda itself, producing beautifully highlighted and hyperlinked pages.
+email:
+- paolo.brasolin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/jekyll/agda.rb
+- lib/jekyll/agda/browsable_page.rb
+- lib/jekyll/agda/runner.rb
+- lib/jekyll/agda/version.rb
+- lib/jekyll/agda/weaver.rb
+homepage: https://github.com/paolobrasolin/jekyll-agda
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/paolobrasolin/jekyll-agda/issues
+  changelog_uri: https://github.com/paolobrasolin/jekyll-agda/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/paolobrasolin/jekyll-agda#readme
+  homepage_uri: https://github.com/paolobrasolin/jekyll-agda
+  source_code_uri: https://github.com/paolobrasolin/jekyll-agda
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Use literate Agda in your Jekyll website!
+test_files: []