jekyll-agda 0.1.0

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: c92450f9f035ee3bc748811f609cbca048b6682a4ce0db2426bab434c04e3815
4
+ data.tar.gz: e12a83966d0785d9c94546b8e90e5dd7923f94d5f722a723b4743576031bfeb2
5
+ SHA512:
6
+ metadata.gz: b2ec3f0bef311c39baeb72afd3368428e7556f8932ad7d0a23e86a62194e189c8696307d1da479eb488ac3e4798ced3fd621cbd72271704402153b3876834c5d
7
+ data.tar.gz: 395f7399ce795c69f3746efb98365cd30cb495edf9a87317b688a0501c452a6f07fb9569d03518f9e1b49ad1bbe082455ad1a1879856b1b8575648397b52fc88
data/CHANGELOG.md ADDED
@@ -0,0 +1,20 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [Unreleased]
9
+
10
+ ## [0.1.0] - 2022-01-14
11
+
12
+ ### Added
13
+
14
+ - MVP.
15
+
16
+ [unreleased]: https://github.com/paolobrasolin/jekyll-agda/compare/0.1.0...HEAD
17
+
18
+ <!-- [0.2.0]: https://github.com/paolobrasolin/jekyll-agda/compare/0.1.0...0.2.0 -->
19
+
20
+ [0.1.0]: https://github.com/paolobrasolin/jekyll-agda/releases/tag/0.1.0
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2022 Paolo Brasolin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,109 @@
1
+ # jekyll-agda
2
+
3
+ [![CI tests status badge][build-shield]][build-url]
4
+ [![Latest release badge][rubygems-shield]][rubygems-url]
5
+ [![License badge][license-shield]][license-url]
6
+ [![Maintainability badge][cc-maintainability-shield]][cc-maintainability-url]
7
+ [![Test coverage badge][cc-coverage-shield]][cc-coverage-url]
8
+
9
+ [build-shield]: https://img.shields.io/github/workflow/status/paolobrasolin/jekyll-agda/CI/main?label=tests&logo=github
10
+ [build-url]: https://github.com/paolobrasolin/jekyll-agda/actions/workflows/main.yml "CI tests status"
11
+ [rubygems-shield]: https://img.shields.io/gem/v/jekyll-agda?logo=ruby
12
+ [rubygems-url]: https://rubygems.org/gems/jekyll-agda "Latest release"
13
+ [license-shield]: https://img.shields.io/github/license/paolobrasolin/jekyll-agda
14
+ [license-url]: https://github.com/paolobrasolin/jekyll-agda/blob/main/LICENSE "License"
15
+ [cc-maintainability-shield]: https://img.shields.io/codeclimate/maintainability/paolobrasolin/jekyll-agda?logo=codeclimate
16
+ [cc-maintainability-url]: https://codeclimate.com/github/paolobrasolin/jekyll-agda "Maintainability"
17
+ [cc-coverage-shield]: https://img.shields.io/codeclimate/coverage/paolobrasolin/jekyll-agda?logo=codeclimate&label=test%20coverage
18
+ [cc-coverage-url]: https://codeclimate.com/github/paolobrasolin/jekyll-agda/coverage "Test coverage"
19
+
20
+ `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.
21
+
22
+ ## Getting started
23
+
24
+ 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.
25
+
26
+ 1. Add the `jekyll-agda` gem to your plugins in the `Gemfile` and run `bundle` to install it:
27
+
28
+ ```ruby
29
+ # Gemfile
30
+ group :jekyll_plugins do
31
+ gem "jekyll-agda"
32
+ end
33
+ ```
34
+
35
+ 2. Add Agda interface files to Jekyll's list of exclusions in `_config.yml`:
36
+
37
+ ```yaml
38
+ # _config.yml
39
+ exclude:
40
+ - "*.agdai"
41
+ ```
42
+
43
+ 3. Add Agda interface files and `jekyll-agda`'s work dir to your `.gitignore`:
44
+
45
+ ```ini
46
+ # .gitignore
47
+ *.agdai
48
+ .agda-html/
49
+ ```
50
+
51
+ 4. Add Agda's default stylesheet (which `jekyll-agda` will produce) to the `<head>` of your layout:
52
+
53
+ ```html
54
+ <link rel="stylesheet" href="{{ '/lagda/Agda.css' | relative_url }}" />
55
+ ```
56
+
57
+ That's it!
58
+ You can now write your posts and pages using [literate Agda][lagda-url].
59
+
60
+ Here is a sample post you can save as `_posts/2022-01-14-foobar.lagda.md` to get started:
61
+
62
+ ````
63
+ ---
64
+ title: My first literate Agda post
65
+ ---
66
+
67
+ Let's define Peano's natural numbers:
68
+
69
+ ```agda
70
+ data ℕ : Set where
71
+ zero : ℕ
72
+ suc : ℕ → ℕ
73
+ ```
74
+
75
+ Is `Set` clickable? Yes it is.
76
+ And the other keywords too!
77
+ ````
78
+
79
+ ## Usage
80
+
81
+ 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.
82
+
83
+ The only caveat is: **write your code in unnamed independent modules** to be totally safe.
84
+ Otherwise, Agda and Jekyll naming conventions _might_ be at odds.
85
+ You can definitely try do more complex stuff though!
86
+ I simply haven't given this enough thought yet to clearly spell out the details (see last point of the [Roadmap](#roadmap)).
87
+
88
+ ## Roadmap
89
+
90
+ Here is a roadmap of features I think would be useful.
91
+
92
+ - Custom output path/url instead of hardcoded `/lagda`
93
+ - Custom stylesheet instead of Agda's default `Agda.css`
94
+ - Custom layout for `/lagda/*` pages (leveraging `--html-highlight=code` instead of `--html-highlight=auto`)
95
+ - Find some convenient way to knit Agda and Jekyll naming conventions:
96
+ - 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
97
+ - Structuring code in multiple files/modules is doable but will require some clever dependency management to avoid redundant compilations
98
+ - 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
99
+
100
+ Of course any feedback is welcome!
101
+
102
+ ## Acknowledgements
103
+
104
+ - Thanks to [@conal](https://github.com/conal) for [prompting me with the idea](https://twitter.com/conal/status/1479884896864591874).
105
+
106
+ [jekyll-url]: https://jekyllrb.com/
107
+ [agda-url]: https://github.com/agda/agda
108
+ [lagda-url]: https://agda.readthedocs.io/en/latest/tools/literate-programming.html#literate-markdown
109
+ [mvp-url]: https://en.wikipedia.org/wiki/Minimum_viable_product
@@ -0,0 +1,19 @@
1
+ require "jekyll"
2
+
3
+ module Jekyll
4
+ module Agda
5
+ class BrowsablePage < Jekyll::Page
6
+ def url_placeholders
7
+ {
8
+ path: Jekyll::Agda::Weaver::OUTPUT_ROOT, # instead of @dir
9
+ basename: basename,
10
+ output_ext: output_ext,
11
+ }
12
+ end
13
+
14
+ def render_with_liquid?
15
+ false
16
+ end
17
+ end
18
+ end
19
+ end
@@ -0,0 +1,82 @@
1
+ require "open3"
2
+ require "digest"
3
+
4
+ require "jekyll"
5
+
6
+ module Jekyll
7
+ module Agda
8
+ class Runner
9
+ RE_LAGDA_MD_EXT = /\.lagda\.md$/i
10
+ RE_AGDA_GENERATED_HTML_PATH = /(?<=\().*?.html(?=\))/
11
+
12
+ attr_reader :target, :dependencies, :successful
13
+
14
+ def initialize(resource, work_dir)
15
+ @resource = resource
16
+ @source = Pathname.new(@resource.path)
17
+
18
+ @work_dir = Pathname.new(work_dir)
19
+ @digest = @work_dir.join(@source.basename.sub(RE_LAGDA_MD_EXT, ".md5"))
20
+ @target = @work_dir.join(@source.basename.sub(RE_LAGDA_MD_EXT, ".md"))
21
+ @extras = @work_dir.join(@source.basename.sub(RE_LAGDA_MD_EXT, ".dep"))
22
+
23
+ @dependencies = []
24
+ @successful = nil
25
+ end
26
+
27
+ def execute
28
+ new_hash = Digest::MD5.hexdigest(@resource.content)
29
+
30
+ if [@digest, @target, @extras].all?(:exist?)
31
+ if new_hash == @digest.read
32
+ @successful = true
33
+ @dependencies = Marshal.load(@extras.read)
34
+ return
35
+ end
36
+ end
37
+
38
+ log_takeoff
39
+ stdout, _stderr, status = run_agda
40
+
41
+ if (@successful = status.success?)
42
+ @digest.write(new_hash)
43
+ @dependencies = stdout.scan(RE_AGDA_GENERATED_HTML_PATH)
44
+ @extras.write(Marshal.dump(@dependencies))
45
+ log_success
46
+ else
47
+ log_failure
48
+ end
49
+ end
50
+
51
+ private
52
+
53
+ def run_agda
54
+ Open3.capture3(
55
+ [
56
+ "agda",
57
+ "--html",
58
+ "--html-highlight=auto",
59
+ "--html-dir=#{@work_dir.tap(&:mkpath).realpath}",
60
+ @source.basename,
61
+ ].join(" "),
62
+ chdir: @source.dirname,
63
+ )
64
+ end
65
+
66
+ def log_takeoff
67
+ Jekyll.logger.writer << "Running Agda: ".rjust(20)
68
+ Jekyll.logger.writer << "??".yellow + " " + @resource.relative_path
69
+ end
70
+
71
+ def log_success
72
+ Jekyll.logger.writer << "\b" * @resource.relative_path.length
73
+ Jekyll.logger.writer << "\b" * 3 + "OK".green + "\n"
74
+ end
75
+
76
+ def log_failure
77
+ Jekyll.logger.writer << "\b" * @resource.relative_path.length
78
+ Jekyll.logger.writer << "\b" * 3 + "KO".red + "\n"
79
+ end
80
+ end
81
+ end
82
+ end
@@ -0,0 +1,5 @@
1
+ module Jekyll
2
+ module Agda
3
+ VERSION = "0.1.0"
4
+ end
5
+ end
@@ -0,0 +1,82 @@
1
+ require "jekyll"
2
+
3
+ require "jekyll/agda/runner"
4
+ require "jekyll/agda/browsable_page"
5
+
6
+ module Jekyll
7
+ module Agda
8
+ class Weaver
9
+ WORK_DIR = ".agda-html"
10
+ OUTPUT_ROOT = "lagda"
11
+
12
+ RE_AGDA_GENERATED_PRE = %r{<pre class="Agda">.*?</pre>}m
13
+ RE_HREF_VALUE = /(?<=href=")(?<page>.*?.html)(?<anchor>#\d+)?(?=")/
14
+
15
+ def self.normalize_hrefs(content, internal_page, external_root)
16
+ content.gsub(RE_HREF_VALUE) do
17
+ if Regexp.last_match[:page] == internal_page
18
+ Regexp.last_match[:anchor].to_s
19
+ else
20
+ "#{external_root}/#{Regexp.last_match}"
21
+ end
22
+ end
23
+ end
24
+
25
+ def self.strip_frontmatter(input)
26
+ # stolen from https://github.com/jekyll/jekyll/blob/e3cbe584f2a78141bf7f53cfef8cf237b3f4c201/lib/jekyll/document.rb#L483-L490
27
+ input =~ Jekyll::Document::YAML_FRONT_MATTER_REGEXP
28
+ Regexp.last_match&.post_match || input
29
+ end
30
+
31
+ def initialize(site)
32
+ @site = site
33
+ @resources = [*@site.pages, *@site.documents]
34
+ @dependencies_list = []
35
+ @dependencies_root = "#{@site.baseurl}/#{OUTPUT_ROOT}"
36
+ end
37
+
38
+ def execute
39
+ elaborate_resources
40
+ @dependencies_list.uniq!
41
+ elaborate_dependencies
42
+ elaborate_extra_dependency("Agda.css")
43
+ end
44
+
45
+ private
46
+
47
+ def elaborate_resources
48
+ @resources.each do |resource|
49
+ next unless resource.path.match?(Jekyll::Agda::Runner::RE_LAGDA_MD_EXT)
50
+
51
+ runner = Runner.new(resource, WORK_DIR)
52
+ next unless runner.tap(&:execute).successful
53
+
54
+ resource.content = elaborate_target(runner.target, @dependencies_root)
55
+ @dependencies_list.concat(runner.dependencies)
56
+ end
57
+ end
58
+
59
+ def elaborate_target(pathname, dependencies_root)
60
+ content = pathname.read
61
+ content = self.class.strip_frontmatter(content)
62
+ itself = pathname.basename.sub_ext(".html").to_s
63
+ content.gsub!(RE_AGDA_GENERATED_PRE) do |pre|
64
+ self.class.normalize_hrefs(pre, itself, dependencies_root)
65
+ end
66
+ end
67
+
68
+ def elaborate_dependencies
69
+ @dependencies_list.each do |dependency|
70
+ name = Pathname.new(dependency).basename.to_s
71
+ page = BrowsablePage.new(@site, @site.source, WORK_DIR, name)
72
+ @site.pages << page
73
+ end
74
+ end
75
+
76
+ def elaborate_extra_dependency(name)
77
+ return unless Pathname.new(WORK_DIR).join(name).exist?
78
+ @site.pages << BrowsablePage.new(@site, @site.source, WORK_DIR, name)
79
+ end
80
+ end
81
+ end
82
+ end
@@ -0,0 +1,6 @@
1
+ require "jekyll/agda/version"
2
+ require "jekyll/agda/weaver"
3
+
4
+ Jekyll::Hooks.register :site, :post_read do |site|
5
+ Jekyll::Agda::Weaver.new(site).execute
6
+ end
metadata ADDED
@@ -0,0 +1,133 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: jekyll-agda
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.0
5
+ platform: ruby
6
+ authors:
7
+ - Paolo Brasolin
8
+ autorequire:
9
+ bindir: bin
10
+ cert_chain: []
11
+ date: 2022-01-14 00:00:00.000000000 Z
12
+ dependencies:
13
+ - !ruby/object:Gem::Dependency
14
+ name: jekyll
15
+ requirement: !ruby/object:Gem::Requirement
16
+ requirements:
17
+ - - ">="
18
+ - !ruby/object:Gem::Version
19
+ version: '3'
20
+ - - "<"
21
+ - !ruby/object:Gem::Version
22
+ version: '5'
23
+ type: :runtime
24
+ prerelease: false
25
+ version_requirements: !ruby/object:Gem::Requirement
26
+ requirements:
27
+ - - ">="
28
+ - !ruby/object:Gem::Version
29
+ version: '3'
30
+ - - "<"
31
+ - !ruby/object:Gem::Version
32
+ version: '5'
33
+ - !ruby/object:Gem::Dependency
34
+ name: byebug
35
+ requirement: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - "~>"
38
+ - !ruby/object:Gem::Version
39
+ version: 11.1.3
40
+ type: :development
41
+ prerelease: false
42
+ version_requirements: !ruby/object:Gem::Requirement
43
+ requirements:
44
+ - - "~>"
45
+ - !ruby/object:Gem::Version
46
+ version: 11.1.3
47
+ - !ruby/object:Gem::Dependency
48
+ name: rspec
49
+ requirement: !ruby/object:Gem::Requirement
50
+ requirements:
51
+ - - "~>"
52
+ - !ruby/object:Gem::Version
53
+ version: 3.10.0
54
+ type: :development
55
+ prerelease: false
56
+ version_requirements: !ruby/object:Gem::Requirement
57
+ requirements:
58
+ - - "~>"
59
+ - !ruby/object:Gem::Version
60
+ version: 3.10.0
61
+ - !ruby/object:Gem::Dependency
62
+ name: rufo
63
+ requirement: !ruby/object:Gem::Requirement
64
+ requirements:
65
+ - - "~>"
66
+ - !ruby/object:Gem::Version
67
+ version: 0.13.0
68
+ type: :development
69
+ prerelease: false
70
+ version_requirements: !ruby/object:Gem::Requirement
71
+ requirements:
72
+ - - "~>"
73
+ - !ruby/object:Gem::Version
74
+ version: 0.13.0
75
+ - !ruby/object:Gem::Dependency
76
+ name: simplecov
77
+ requirement: !ruby/object:Gem::Requirement
78
+ requirements:
79
+ - - "~>"
80
+ - !ruby/object:Gem::Version
81
+ version: 0.21.2
82
+ type: :development
83
+ prerelease: false
84
+ version_requirements: !ruby/object:Gem::Requirement
85
+ requirements:
86
+ - - "~>"
87
+ - !ruby/object:Gem::Version
88
+ version: 0.21.2
89
+ description: This Jekyll plugin allows to you write literate Agda. It will compile
90
+ your code using Agda itself, producing beautifully highlighted and hyperlinked pages.
91
+ email:
92
+ - paolo.brasolin@gmail.com
93
+ executables: []
94
+ extensions: []
95
+ extra_rdoc_files: []
96
+ files:
97
+ - CHANGELOG.md
98
+ - LICENSE
99
+ - README.md
100
+ - lib/jekyll/agda.rb
101
+ - lib/jekyll/agda/browsable_page.rb
102
+ - lib/jekyll/agda/runner.rb
103
+ - lib/jekyll/agda/version.rb
104
+ - lib/jekyll/agda/weaver.rb
105
+ homepage: https://github.com/paolobrasolin/jekyll-agda
106
+ licenses:
107
+ - MIT
108
+ metadata:
109
+ bug_tracker_uri: https://github.com/paolobrasolin/jekyll-agda/issues
110
+ changelog_uri: https://github.com/paolobrasolin/jekyll-agda/blob/main/CHANGELOG.md
111
+ documentation_uri: https://github.com/paolobrasolin/jekyll-agda#readme
112
+ homepage_uri: https://github.com/paolobrasolin/jekyll-agda
113
+ source_code_uri: https://github.com/paolobrasolin/jekyll-agda
114
+ post_install_message:
115
+ rdoc_options: []
116
+ require_paths:
117
+ - lib
118
+ required_ruby_version: !ruby/object:Gem::Requirement
119
+ requirements:
120
+ - - ">="
121
+ - !ruby/object:Gem::Version
122
+ version: 2.6.0
123
+ required_rubygems_version: !ruby/object:Gem::Requirement
124
+ requirements:
125
+ - - ">="
126
+ - !ruby/object:Gem::Version
127
+ version: '0'
128
+ requirements: []
129
+ rubygems_version: 3.1.4
130
+ signing_key:
131
+ specification_version: 4
132
+ summary: Use literate Agda in your Jekyll website!
133
+ test_files: []