jekyll-sidenotes 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a6bc13af6e112fda4515fd79f024754baa61ecac10f16bbde1731f2e60090d9d
+  data.tar.gz: f751232e94a896e772989ca95f07a30e28e7dfbf50b0e0aa704d17337d30fe13
+SHA512:
+  metadata.gz: e9381c9280b2f78ef71e8fb24256988cdebc7a2b0774f6b9c13199804db1df5e27c36baa073f5e31e4b36ce3ac8d31f15a5e6bfbfc8ceb2fafe7745a2a12b127
+  data.tar.gz: aaa4fe85ff92f8e9dd24ca7c7b763e21c925556674fe12f57cbb12bf3dd7f7a6a3d995f0cacf2467ad1a59c5714cccf4c198310d0ce2dec93c67d9c2050e2d87

data/.gitignore

@@ -0,0 +1,16 @@
+*.gem
+Gemfile.lock
+
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+spec/fixtures/_site
+spec/fixtures/**/.jekyll-cache
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.4
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 3.0.0
+before_install: gem install bundler -v 2.2.17

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+## [0.0.1] - 2022-12-07
+- Initial release

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in jekyll-sidenotes.gemspec
+gemspec
+
+gem "jekyll"
+gem "nanoid"
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem "rubocop", "~> 1.7"

data/README.md

@@ -0,0 +1,46 @@
+# Jekyll::SideNotes
+
+`jekyll-sidenotes` is similar to markdown footnotes, but adds notes that render to either the left or right of the main content. The style is inspired by [tufte-css](https://edwardtufte.github.io/tufte-css/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jekyll-sidenotes'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install jekyll-sidenotes
+
+## Syntax
+
+```markdown
+This is what a left-sidenote[<left] and a right-sidenote[>right] look like.
+
+[<left]: the syntax looks similar to...
+[>right]: ...regular markdown footnotes.
+```
+
+On medium to small sized screens, you can click on sidenote superscripts to show or hide their content.
+
+Note:
+
+- Sidenotes increment together, but separately from footnotes2. So, for example, it’s possible for there to be a ‘1’ for both a standard markdown footnote and a sidenote.
+- Sidenotes require an “\n” after each definition to parse properly. A warning will display if there are missing newlines (regardless of sidenotes).
+
+## Influences
+
+For clean’n’simple sidenote css implementation:
+[tufte css](https://github.com/edwardtufte/tufte-css)
+
+How to implement tufte css in jekyll.
+[simply jekyll](https://github.com/raghudotcc/simply-jekyll)
+
+For sidenote implementation comparisons.
+[gwern.net](https://github.com/gwern/gwern.net)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "jekyll/sidenotes"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/jekyll-sidenotes.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/jekyll-sidenotes/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "jekyll-sidenotes"
+  spec.version       = Jekyll::SideNotes::VERSION
+  spec.authors       = ["manunamz"]
+  spec.email         = ["manunamz@pm.me"]
+
+  spec.summary       = "Extended markdown syntax for sidenotes."
+  spec.description   = "Create sidenotes, like footnotes, in your jekyll blog by using [<left] and [>right] syntax."
+  spec.homepage      = "https://github.com/manunamz/jekyll-sidenotes"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+  spec.licenses      = ["GPL3"]
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/manunamz/jekyll-sidenotes"
+  spec.metadata["changelog_uri"] = "https://github.com/manunamz/jekyll-sidenotes/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_runtime_dependency "nanoid"
+
+  # For more information and examples about making a new gem, checkout our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/jekyll-sidenotes/_sidenotes.scss

@@ -0,0 +1,137 @@
+// Sidenotes
+$content-sidenote-width: .375 * $content-width;
+
+@mixin sidenote-container {
+  padding-right: $gutter-spacing-sm;
+  padding-left: $gutter-spacing-sm;
+  
+  // @include mq(md) {
+  //   // padding-right: $gutter-spacing;
+  //   // margin-right: $content-width / 3;
+  //   margin-right: -$content-width / 2;
+  //   width: $content-width / 4;
+  // }
+  @include mq(lg) {
+    padding-left: $gutter-spacing;
+    padding-right: $gutter-spacing;
+  }
+}
+
+  // more on sidenote implementation: https://www.gwern.net/Sidenotes
+  .main-content {
+    counter-reset: sidenote-counter;  
+
+    // right-sidenote
+    .rsn {
+      @include sidenote-container;
+      display: none;
+      word-wrap: break-word;
+
+      @include mq(lg) {
+        display: block;
+        float: right;
+        clear: right;
+
+        margin-right: -$content-sidenote-width;
+        width: $content-sidenote-width;
+        margin-top: $sp-1;
+        margin-bottom: 0;
+        font-size: $font-size-2;
+        // line-height: 1.3;
+        vertical-align: baseline;
+        position: relative;
+      }
+    }
+
+    // left-sidenote
+    .lsn {
+      @include sidenote-container;
+      display: none;
+      word-wrap: break-word;
+
+      @include mq(lg) {
+        display: block;
+        float: left;
+        clear: left;
+
+        margin-left: -$content-sidenote-width;
+        width: $content-sidenote-width;
+        margin-top: $sp-1;
+        margin-bottom: 0;
+        font-size: $font-size-2;
+        // line-height: 1.3;
+        vertical-align: baseline;
+        position: relative;
+      }
+    }
+
+    // all sidenotes
+    .sidenote-toggle:checked + .rsn,
+    .sidenote-toggle:checked + .lsn {
+      display: block;
+      float: left;
+      left: 1rem;
+      clear: both;
+      width: 95%;
+      margin: 1rem 2.5%;
+      vertical-align: baseline;
+      position: relative;
+    }
+
+    label.sidenote-toggle:not(.sidenote-number) {
+      display: inline;
+    }
+
+    .sidenote-number {
+      counter-increment: sidenote-counter;
+    }
+
+    input.sidenote-toggle {
+      display: none;
+    }
+
+    label.sidenote-number {
+      display: inline;
+    }
+
+    label.sidenote-toggle:not(.sidenote-number) {
+      display: none;
+    }
+
+    .sidenote-number:after,
+    .rsn:before,
+    .lsn:before {
+      position: relative;
+      vertical-align: baseline;
+    }
+
+    .sidenote-number:after {
+      content: counter(sidenote-counter);
+      color: var(--wiki-link-color);
+      cursor: pointer;
+      font-size: $font-size-2;
+      top: -$sp-1-75;
+      left: $sp-0-75;
+      padding-right: $sp-0-75;
+    }
+
+    .rsn:before,
+    .lsn:before {
+      content: counter(sidenote-counter) " ";
+      font-size: $font-size-2;
+      top: -$sp-2;
+    }
+
+    // blockquote .rsn,
+    // blockquote .lsn {
+    //   margin-right: -82%;
+    //   min-width: 59%;
+    //   text-align: left;
+    // }
+
+    .rsn > code,
+    .lsn > code {
+      font-size: $font-size-2;
+    }
+  }
+}

data/lib/jekyll-sidenotes/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module SideNotes
+  	VERSION = "0.0.1"
+  end
+end

data/lib/jekyll-sidenotes.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+require 'jekyll'
+require 'nanoid'
+require 'time'
+
+require_relative "jekyll-sidenotes/version"
+
+
+module Jekyll
+  module SideNotes
+  
+    # verify all entries end with a "\n" so sidenotes works 
+    #   (sidenotes don't detect the last definition if there is no ending "\n").
+    class SideNoteGenerator < Jekyll::Generator
+      safe true
+      attr_accessor :md_docs
+
+      ##
+      # parser constants
+      ##
+      # constants are taken from kramdown and baseparser.
+      # (for easier kramdown integration)
+      
+      # from baseparser: https://github.com/ruby/rexml/blob/master/lib/rexml/parsers/baseparser.rb#L36    
+      LETTER = '[:alpha:]'
+      COMBININGCHAR = '' # TODO
+      EXTENDER = ''      # TODO
+      NCNAME_STR= "[#{LETTER}_][-[:alnum:]._#{COMBININGCHAR}#{EXTENDER}]*"
+      UNAME_STR= "(?:#{NCNAME_STR}:)?#{NCNAME_STR}"
+      
+      # from kramdown: https://github.com/gettalong/kramdown
+      # from blank_line.rb
+      BLANK_LINE = /(?>^\s*\n)+/
+      # from eob.rb
+      EOB_MARKER = /^\^\s*?\n/
+      # from kramdown.rb
+      OPT_SPACE = / {0,3}/
+      # Regexp for matching indentation (one tab or four spaces)
+      INDENT = /^(?:\t| {4})/
+      # from extensions.rb
+      ALD_ID_CHARS = /[\w-]/
+      ALD_ANY_CHARS = /\\\}|[^\}]/
+      ALD_ID_NAME = /\w#{ALD_ID_CHARS}*/
+      IAL_BLOCK = /\{:(?!:|\/)(#{ALD_ANY_CHARS}+)\}\s*?\n/
+      IAL_BLOCK_START = /^#{OPT_SPACE}#{IAL_BLOCK}/
+      # from html.rb
+      # Some HTML elements like script belong to both categories (i.e. are valid in block and
+      # span HTML) and don't appear therefore!
+      # script, textarea
+      HTML_SPAN_ELEMENTS = %w[a abbr acronym b big bdo br button cite code del dfn em i img input
+                              ins kbd label mark option q rb rbc rp rt rtc ruby samp select small
+                              span strong sub sup tt u var]
+      # from paragraph.rb
+      LAZY_END_HTML_SPAN_ELEMENTS = HTML_SPAN_ELEMENTS + %w[script]
+      LAZY_END_HTML_START = /<(?>(?!(?:#{LAZY_END_HTML_SPAN_ELEMENTS.join('|')})\b)#{REXML::Parsers::BaseParser::UNAME_STR})/
+      LAZY_END_HTML_STOP = /<\/(?!(?:#{LAZY_END_HTML_SPAN_ELEMENTS.join('|')})\b)#{REXML::Parsers::BaseParser::UNAME_STR}\s*>/m
+      # from markdown.rb
+      # CODEBLOCK_MATCH = /(?:#{BLANK_LINE}?(?:#{INDENT}[ \t]*\S.*\n)+)*/
+      # because `.gsub(INDENT, '')` in footnote.rb
+      # CODEBLOCK_MATCH = /(?:#{BLANK_LINE}?(?:s[ \t]*\S.*\n)+)*/
+      # from codeblock.rb
+      CODEBLOCK_MATCH = /(?:#{BLANK_LINE}?(?:#{INDENT}[ \t]*\S.*\n)+(?:(?!#{IAL_BLOCK_START}|#{EOB_MARKER}|^#{OPT_SPACE}#{LAZY_END_HTML_STOP}|^#{OPT_SPACE}#{LAZY_END_HTML_START})^[ \t]*\S.*\n)*)*/
+
+      # footnotes (for reference)
+      # FOOTNOTE_DEFINITION_START = /^#{OPT_SPACE}\[\^(#{ALD_ID_NAME})\]:\s*?(.*?\n#{CODEBLOCK_MATCH})/
+      # FOOTNOTE_MARKER_START = /\[\^(#{ALD_ID_NAME})\]/
+      ##
+      # constants for local use
+      ##
+      # right
+      RIGHT_SIDENOTE_DEFINITION_START = /^#{OPT_SPACE}\[\>(#{ALD_ID_NAME})\]:\s*?(.*?\n#{CODEBLOCK_MATCH})/
+      RIGHT_SIDENOTE_MARKER_START = /\[\>(#{ALD_ID_NAME})\]/
+      # left
+      LEFT_SIDENOTE_DEFINITION_START = /^#{OPT_SPACE}\[\<(#{ALD_ID_NAME})\]:\s*?(.*?\n#{CODEBLOCK_MATCH})/
+      LEFT_SIDENOTE_MARKER_START = /\[\<(#{ALD_ID_NAME})\]/
+
+      def generate(site)
+
+        # setup markdown docs
+            docs = site.pages + site.docs_to_write
+            @md_docs = docs.filter {|doc| site.find_converter_instance(Jekyll::Converters::Markdown).matches(doc.extname) }
+        
+        link_extension = !!site.config["use_html_extension"] ? '.html' : ''
+     
+        @md_docs.each do |cur_doc|
+          # check for newlines @ eof.
+          #   (kramdown can handle footnotes with no newline, but the regex i'm getting requires a newline after the last footnote to find it.)
+          if cur_doc.content[-1] != "\n"
+            Jekyll.logger.debug "Missing newline at end of file -- this could break sidenotes: ", cur_doc.data['title']
+          end    
+          parse_sidenote(cur_doc, "left")
+          parse_sidenote(cur_doc, "right")
+        end
+      end
+
+      # just get tufte-style sidenotes working for now...
+      # if there's time, emulate gwern's method: https://github.com/gwern/gwern.net/blob/9e6893033ec63248b1f0b29df119c40d39a7dcef/css/default.css#L1223
+
+      # mark -> [<left-sidenote], [>right-sidenote]
+      # def -> [<left-sidenote]:, [>right-sidenote]:
+      # `side` should be 'right' or 'left'
+      def parse_sidenote(doc, side)
+        # left v right setup
+        if side == "right"
+          sidenote_def_regex = RIGHT_SIDENOTE_DEFINITION_START
+          # sidenote_mark_regex = RIGHT_SIDENOTE_MARKER_START
+          css_class = "rsn"
+          sn_regex = /\>/
+        elsif side == "left"
+          sidenote_def_regex = LEFT_SIDENOTE_DEFINITION_START
+          # sidenote_mark_regex = LEFT_SIDENOTE_MARKER_START
+          css_class = "lsn"
+          sn_regex = /\</
+        else
+            Jekyll.logger.warn "Can't process sidenote that is not either 'right' or 'left'."
+            return
+        end
+        # process sidenotes
+        sidenotes = doc.content.scan(sidenote_def_regex)
+        doc.content.gsub!(sidenote_def_regex, '') # rm sidenote defs from original note.
+        i = 0
+        sidenotes.each do |sidenote|
+          i += 1
+          mark = sidenote[0]
+          definition = sidenote[1]
+          doc.content = doc.content.gsub(
+            /\[#{sn_regex}(#{mark})\]/i,
+            "<label for=\"#{css_class}-#{i}\" class=\"sidenote-toggle sidenote-number\"></label><input type=\"checkbox\" id=\"#{css_class}-#{i}\" class=\"sidenote-toggle\"><span class=\"#{css_class}\">#{definition}</span>"
+          )
+        end
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-sidenotes
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- manunamz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nanoid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Create sidenotes, like footnotes, in your jekyll blog by using [<left]
+  and [>right] syntax.
+email:
+- manunamz@pm.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- jekyll-sidenotes.gemspec
+- lib/jekyll-sidenotes.rb
+- lib/jekyll-sidenotes/_sidenotes.scss
+- lib/jekyll-sidenotes/version.rb
+homepage: https://github.com/manunamz/jekyll-sidenotes
+licenses:
+- GPL3
+metadata:
+  homepage_uri: https://github.com/manunamz/jekyll-sidenotes
+  source_code_uri: https://github.com/manunamz/jekyll-sidenotes
+  changelog_uri: https://github.com/manunamz/jekyll-sidenotes/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.11
+signing_key:
+specification_version: 4
+summary: Extended markdown syntax for sidenotes.
+test_files: []