prt 0.3.0

data/lib/parrot/commands/new.rb

@@ -0,0 +1,25 @@
+module Parrot
+  module Commands
+    # New command is to create a new html app
+    # @usage parrot new myblog
+    class NewCommand
+      attr_reader :config, :app_root
+
+      def initialize(args = [], config)
+        @config = config
+        @app_root = args.first
+        raise ArgumentError if @app_root.nil? || @config.nil?
+      end
+
+      def run
+        raise "Directory #{@app_root} already exists" if Dir.exist? @app_root
+
+        config.logger.info "Creating new blog at #{app_root}"
+        skeleton_path = File.expand_path('../../../skel', __dir__)
+
+        config.logger.info "Copying skeleten from #{skeleton_path}"
+        FileUtils.cp_r(skeleton_path, @app_root)
+      end
+    end
+  end
+end

data/lib/parrot/commands/post.rb

@@ -0,0 +1,83 @@
+require 'date'
+require 'optparse'
+
+module Parrot
+  module Commands
+    # Post command scaffolds a new Markdown post. The index page's listing is
+    # generated at build time from every file in views/posts, so nothing here
+    # needs to link it in.
+    # @usage parrot post --title "My first post"
+    # Runs from the blog's root, like `build` and `serve`.
+    class PostCommand
+      USAGE = 'Usage: parrot post --title "My new post"'.freeze
+
+      attr_reader :config, :app_root, :title, :slug
+
+      def initialize(args = [], config)
+        @config = config
+        @title = extract_title(Array(args)).strip
+        @app_root = @config&.root_dir
+        raise ArgumentError, USAGE if @title.empty?
+        raise ArgumentError if @app_root.nil?
+
+        @slug = Helpers.slugify(@title)
+      end
+
+      def run
+        raise ArgumentError, "Title has no letters or digits to build a filename from.\n#{USAGE}" if slug.empty?
+        if slug.match?(RESERVED_POST_NAMES)
+          raise ArgumentError,
+                "\"#{slug}\" is a reserved post name (index*, 404, about, categories, now, post(s), note(s)). " \
+                "Pick a different title.\n#{USAGE}"
+        end
+
+        posts_dir = File.join(app_root, 'views', 'posts')
+
+        raise "Run this from the blog's root (no views/posts found)" unless Dir.exist?(posts_dir)
+
+        post_path = File.join(posts_dir, "#{slug}.md")
+        raise "Post #{post_path} already exists" if File.exist?(post_path)
+
+        File.write(post_path, post_template(Date.today.strftime('%d/%m/%Y')))
+        config.logger.info "Created #{post_path}"
+      end
+
+      private
+
+      # The title comes from `--title`. Any words left over after the option are
+      # treated as part of the title too, so all of these give "My new post":
+      #   parrot post --title "My new post"
+      #   parrot post --title 'My new post'
+      #   parrot post --title My new post
+      def extract_title(args)
+        from_option = []
+        rest = args.dup
+
+        OptionParser.new do |opts|
+          opts.on('--title TITLE', 'Title for the new post') { |t| from_option << t }
+        end.parse!(rest)
+
+        (from_option + rest).join(' ')
+      rescue OptionParser::ParseError
+        raise ArgumentError, USAGE
+      end
+
+      # {post_date} is filled in at build time, formatted per
+      # config.yaml's post_date_format.on_post.
+      def post_template(header_date)
+        <<~MARKDOWN
+          <!--
+          title: #{title}
+          date: #{header_date}
+          lang: en
+          category:
+          -->
+
+          # {post_title}
+
+          Write your post here.
+        MARKDOWN
+      end
+    end
+  end
+end

data/lib/parrot/commands/serve.rb

@@ -0,0 +1,129 @@
+require 'webrick'
+require_relative '../template_handler'
+require 'pp'
+require 'watchr'
+require_relative '../file_cache'
+require_relative 'build'
+
+module Parrot
+  module Commands
+    class ServeCommand
+      # Combined checksum of the last successful build, kept inside the build
+      # directory. It is regenerated output, so it is gitignored and must be
+      # excluded from anything that ships the build directory.
+      CHECKSUM_FILE = '.checksum'.freeze
+
+      # Serves the build directory like WEBrick's FileHandler, but answers a
+      # missing path with the built 404.html (still with a 404 status), the
+      # way static hosts do, instead of WEBrick's generic error page.
+      class FileHandler < WEBrick::HTTPServlet::FileHandler
+        def initialize(server, root, options = {}, default = WEBrick::Config::FileHandler)
+          super
+          @not_found_page = File.join(root, '404.html')
+        end
+
+        def service(req, res)
+          super
+        rescue WEBrick::HTTPStatus::NotFound
+          raise unless File.file?(@not_found_page)
+
+          res.status = 404
+          res['Content-Type'] = 'text/html; charset=utf-8'
+          res.body = File.read(@not_found_page)
+        end
+      end
+
+      attr_reader :config, :document_root, :app_root
+
+      def initialize(args = [], config)
+        @config = config
+        @args = args
+        @app_root = config.root_dir
+        @document_root = "#{app_root}/public"
+        @port = 8000
+      end
+
+      def run
+        Thread.new do
+          config.logger.info 'Running watch for changes'
+          watch_app
+        end
+
+        run_server
+      end
+
+      private
+
+      def run_server
+        server = WEBrick::HTTPServer.new Port: @port
+        server.mount('/', FileHandler, @document_root)
+
+        trap 'INT' do
+          server.shutdown
+        end
+
+        server.start
+      end
+
+      def watch_app
+        ENV['HANDLER'] = `uname`.strip
+        watcher = Watchr::Script.new
+        all_files = Dir.glob('**/*').select { |item| File.file?(item) && !item.start_with?('public/') }
+        @cache = FileCache.instance
+        builder = BuildCommand.new([], config)
+        builder.unset_build_mode!
+
+        all_files.each do |file|
+          absolute_path = File.join(app_root, file)
+          @cache.set(absolute_path)
+        end
+
+        build_if_stale(builder, @cache.checksum)
+
+        watcher.watch(all_files.join('|')) do |file|
+          config.logger.info "File changed #{file}"
+          path = "#{app_root}/#{file}"
+
+          if @cache.changed? path
+            @cache.set(path)
+            builder.build(file)
+          end
+        end
+
+        controller = Watchr::Controller.new(watcher, Watchr.handler.new)
+        controller.run
+      rescue Exception => e # rubocop:disable Lint/RescueException -- also log Ctrl-C/exit from the watcher loop
+        config.logger.error("#{e.message}\n#{e.backtrace.join("\n")}")
+        exit(-1)
+      end
+
+      # Rebuild the whole blog only when the source tree as a whole has moved
+      # since the last build. The given FileCache checksum is compared with the
+      # one stored in the build directory; a missing or mismatched file triggers
+      # a full build, after which the stored checksum is refreshed.
+      def build_if_stale(builder, checksum)
+        checksum_path = File.join(document_root, CHECKSUM_FILE)
+        stored = File.read(checksum_path).strip if File.exist?(checksum_path)
+
+        if stored == checksum
+          config.logger.info 'No source changes since last build, skipping full build'
+          return
+        end
+
+        builder.run
+        File.write(checksum_path, checksum)
+        config.logger.info "Wrote build checksum to #{checksum_path}"
+      end
+
+      def handle_path(path)
+        path.chop! while path[-1] == '/'
+
+        path = '/index.html' if path == ''
+
+        template_type = path.split('.').last.to_sym
+        handler = TemplateHandler.new(root: document_root, path: path, handle: template_type)
+        handler.compile
+      end
+    end
+  end
+end

data/lib/parrot/constants.rb

@@ -0,0 +1,45 @@
+MATHJAX_URL = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'.freeze
+
+# Rouge theme used for syntax highlighting of code blocks in posts.
+# Any theme name from Rouge::Themes works here (e.g. "monokai", "github",
+# "gruvbox", "colorful", "molokai", "thankful_eyes").
+HIGHLIGHT_THEME = 'monokai'.freeze
+
+# `{post_<key>}` expands to that key from the post's header (so
+# `{post_title}`, `{post_lang}`, or any custom header field), as plain
+# text; `{post_date}` is the same header field but run through
+# `post_date_format.on_list` below rather than shown as-authored.
+# `{post_link}` is the one field Parrot computes itself rather than
+# reading from the header: the post's href. Wrap whichever span should
+# be clickable in ordinary Markdown link syntax, [...]({post_link}).
+# `{post_category_tag}` is the post's header `category` as a link to that
+# category's listing (`<a class="category-tag">`), or nothing when the post
+# has no category. This default links the title and shows that tag:
+#   "{post_date} ~ [{post_title}]({post_link}) {post_category_tag}"
+# To make the whole line a link instead:
+#   "[{post_date} ~ {post_title}]({post_link})"
+# A bare strftime format string like {%d/%m/%Y} also still works here,
+# shown exactly as formatted rather than through post_date_format.
+DEFAULT_LIST_FORMAT = '{post_date} ~ [{post_title}]({post_link}) {post_category_tag}'.freeze
+DEFAULT_GROUP_BY = 'none'.freeze
+DEFAULT_LIST_TITLE = 'Post listing'.freeze
+DEFAULT_BACK_LINK_TEXT = '← Back to all posts'.freeze
+DEFAULT_NEWER_LINK_TEXT = '← Newer posts'.freeze
+DEFAULT_OLDER_LINK_TEXT = 'Older posts →'.freeze
+
+# `{post_date}` is the one header field with its own dedicated config,
+# config.yaml's `post_date_format` — a Ruby strftime format string (see
+# Date#strftime) per context: `on_list` when `{post_date}` appears in a
+# post_listing `list_format`, `on_post` when it appears as a literal
+# placeholder inside a post's own Markdown body.
+DEFAULT_POST_DATE_FORMAT = { 'on_list' => '%m/%Y', 'on_post' => '%d/%m/%Y' }.freeze
+
+# Post filenames (without .md) that `parrot post` refuses to create and
+# `parrot build` fails on. index*, 404 and about would build to the same
+# public/*.html as a page Parrot generates itself (the index pages,
+# 404.html, about.html, categories.html); category, now, post(s) and note(s)
+# are kept free for pages of their own. A post named like a category page
+# (category-<slug>.html) is caught by the build instead, since those names
+# depend on which categories exist. Case-insensitive, since macOS and
+# Windows filesystems are.
+RESERVED_POST_NAMES = /\A(?:index\d*|404|about|categor(?:y|ies)|now|posts?|notes?)\z/i

data/lib/parrot/file_cache.rb

@@ -0,0 +1,45 @@
+require 'digest'
+require 'singleton'
+
+class FileCache
+  include Singleton
+
+  attr_accessor :cache
+
+  # Digest over the combined state of every tracked file. Recomputed on
+  # every #set, so a single value tells you whether the cache as a whole
+  # has moved.
+  attr_reader :checksum
+
+  def initialize
+    @cache = {}
+    @checksum = compute_checksum
+  end
+
+  def fetch(path)
+    cache[path]
+  end
+
+  def set(path)
+    digest = Digest::SHA256.hexdigest(File.read(path))
+    cache[path] = digest
+    @checksum = compute_checksum
+    digest
+  end
+
+  def changed?(path)
+    return true unless cache.key?(path)
+
+    data = File.read(path)
+    cache[path] != Digest::SHA256.hexdigest(data)
+  end
+
+  private
+
+  # Hash the whole cache. Entries are sorted by path so the result depends
+  # only on the contents, not on insertion order.
+  def compute_checksum
+    payload = cache.sort.map { |path, sha| "#{path}:#{sha}" }.join("\n")
+    Digest::SHA256.hexdigest(payload)
+  end
+end

data/lib/parrot/logger.rb

@@ -0,0 +1,23 @@
+require 'logger'
+
+module Parrot
+  class ParrotLoggerBuilder
+    attr_reader :logger, :device
+
+    def initialize(quiet = false)
+      @device = if Helpers.testing?
+                  File.new('parrot.test.log', 'a+')
+                else
+                  quiet ? File.new('parrot.log', 'a+') : $stdout
+                end
+
+      # shift_age = 10, keep 10 log files
+      # shift_size = 1048576, maximum 1 MB of log file size
+      @logger = Logger.new(@device, 10, 1_048_576, progname: 'ParrotLogger')
+    end
+
+    def log(message)
+      @logger.info(message)
+    end
+  end
+end

data/lib/parrot/metadata.rb

@@ -0,0 +1,4 @@
+module Parrot
+  VERSION = '0.3.0'.freeze
+  HOMEPAGE = 'https://github.com/deepakkumarnd/parrot'.freeze
+end

data/lib/parrot/runner.rb

@@ -0,0 +1,29 @@
+require 'fileutils'
+require_relative 'commands/new'
+require_relative 'commands/build'
+require_relative 'commands/serve'
+require_relative 'commands/post'
+
+module Parrot
+  class Runner
+    include Commands
+
+    attr_reader :command
+
+    def initialize(command, args = [], config)
+      @config = config
+      klass = to_command_class(command)
+      @command = klass.new(args, @config)
+    end
+
+    def run_command
+      @command.run
+    end
+
+    private
+
+    def to_command_class(command)
+      Commands.const_get("#{command.capitalize}Command")
+    end
+  end
+end

data/lib/parrot/template_handler.rb

@@ -0,0 +1,19 @@
+module Parrot
+  class TemplateHandler
+    HANDLERS = {
+      html: [:slim],
+      css: [:scss],
+      js: [:coffee]
+    }.freeze
+
+    def initialize(options = {})
+      @root = options[:root]
+      @path = options[:path]
+      @handler = HANDLERS[options[:handle]]
+    end
+
+    def handler_engines(type)
+      HANDLERS[type]
+    end
+  end
+end

data/lib/parrot.rb

@@ -0,0 +1,120 @@
+require 'optparse'
+
+require_relative 'helpers'
+require_relative 'parrot/metadata'
+require_relative 'parrot/runner'
+require_relative 'parrot/logger'
+require_relative 'parrot/constants'
+
+module Parrot
+  Config = Struct.new(:root_dir, :logger, :build_mode)
+
+  SubcommandEntry = Struct.new(:usage, :docstr)
+
+  SUB_COMMANDS_DOC = {
+    new: SubcommandEntry.new('new <blog_name>', 'Create new blog'),
+    build: SubcommandEntry.new('build', 'Build the blog'),
+    serve: SubcommandEntry.new('serve', 'Start development server locally'),
+    post: SubcommandEntry.new('post --title <post title>', 'Add new post with a title')
+  }.freeze
+
+  USAGE_LINE = 'parrot [options] [subcommand] [args]'.freeze
+
+  HELP_TEXT =
+    <<~HELP_TEXT.freeze
+      Examples:
+        - Create new blog
+          parrot new blog
+      #{'  '}
+        - Start development server
+          cd blog
+          parrot serve
+
+        - Add a new post
+          parrot post --title "My first post"
+
+        - Build the blog
+          parrot build
+    HELP_TEXT
+
+  HELP_HEADER =
+    <<~HEADER_TEXT.freeze
+      Version:          #{Parrot::VERSION}
+      Usage:            #{USAGE_LINE}
+      Repository:       #{Parrot::HOMEPAGE}
+      Repository:       #{Parrot::HOMEPAGE}/blob/master/README.md
+    HEADER_TEXT
+
+  class Parrot
+    SUB_COMMANDS = SUB_COMMANDS_DOC.keys.map(&:to_s).freeze
+
+    attr_accessor :root_dir, :logger, :config
+
+    def initialize(args = [])
+      @options = { quiet: Helpers.testing? || false }
+      extract_options!(args)
+      @command = args.shift
+      @args = args
+      @logger = ParrotLoggerBuilder.new(@options[:quiet]).logger
+      @root_dir = Dir.pwd
+      @config = Config.new(@root_dir, @logger)
+    end
+
+    def run
+      return if @command.nil?
+
+      exit_if_invalid(@command)
+      Runner.new(@command, @args, config).run_command
+    rescue ArgumentError => e
+      # A command was called with missing or malformed arguments; show how to
+      # call it instead of dumping a backtrace.
+      warn(e.message)
+      exit(1)
+    end
+
+    def exit_if_invalid(command)
+      return if SUB_COMMANDS.include?(command)
+
+      puts('That is not a valid command. View detailed help with parrot -h')
+      puts USAGE_LINE
+      exit!
+    end
+
+    def quiet?
+      @options[:quiet]
+    end
+
+    def usage(parser = nil)
+      max_length = SUB_COMMANDS_DOC.map { |_k, v| v.usage.length }.max + 10
+      sub_command_doc = SUB_COMMANDS_DOC.map do |_command, entry|
+        entry_text = entry.usage.to_s.ljust(max_length)
+        "#{entry_text}#{entry.docstr}"
+      end.join("\n")
+
+      sub_command_doc = "Sub Commands:\n#{sub_command_doc}\n"
+      line_sep = "#{'-' * 80}\n"
+      [
+        HELP_HEADER,
+        parser,
+        sub_command_doc,
+        HELP_TEXT
+      ].join(line_sep)
+    end
+
+    private
+
+    def extract_options!(args)
+      OptionParser.new("Usage: #{USAGE_LINE}") do |parser|
+        parser.on('-q', '--quiet', 'Quiet mode') { @options[:quiet] = true }
+        parser.on_tail('-v', '--version', 'Prints version information') do
+          puts("Parrot: #{VERSION}")
+        end
+        parser.on_tail('-h', '--help', 'Prints usage instruction') do
+          puts usage(parser)
+        end
+      end.order!(args)
+      # Stop at the first non-option (the sub-command) so flags that belong to
+      # the sub-command, e.g. `parrot post --title "..."`, are left untouched.
+    end
+  end
+end

data/parrot.gemspec

@@ -0,0 +1,36 @@
+require_relative 'lib/parrot/metadata'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'prt'
+  spec.version       = Parrot::VERSION
+  spec.authors       = ['Deepak Kumar']
+  spec.email         = ['deepakkumarnd@gmail.com']
+  spec.summary       = 'A static markdown blog builder written in ruby for minimalist bloggers'
+  spec.description   = 'A static blogging tool written in ruby, posts are in markdown format'
+  spec.homepage      = Parrot::HOMEPAGE
+  spec.license       = 'MIT'
+
+  # Runtime Dependencies
+  spec.add_dependency 'kramdown'
+  spec.add_dependency 'kramdown-parser-gfm'
+  spec.add_dependency 'logger'
+  spec.add_dependency 'nokogiri'
+  spec.add_dependency 'observer'
+  spec.add_dependency 'rouge'
+  spec.add_dependency 'sassc'
+  spec.add_dependency 'tilt'
+  spec.add_dependency 'watchr'
+  spec.add_dependency 'webrick'
+
+  # File Management
+  spec.bindir = 'exe'
+  spec.executables   = 'parrot'
+  spec.files         = `git ls-files`.split("\n")
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.post_install_message = <<~MESSAGE
+    Refer to readme at README.md to know how to get started with Parrot
+  MESSAGE
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/skel/.gitignore

@@ -0,0 +1,3 @@
+# Incremental-build checksum. Regenerated on every `parrot serve`; never
+# commit it and never ship it with the built site.
+public/.checksum

data/skel/config.yaml

@@ -0,0 +1,68 @@
+# Settings for the post listing Parrot generates on the index page from
+# everything in views/posts/*.md. There is no views/index.md to hand-edit —
+# the listing is always built from the posts themselves, newest first.
+#
+# Posts with a `category: Name` header also get a listing page per category
+# (category-name.html, then category-name_2.html, … once it outgrows
+# per_page), all linked from categories.html. Those pages use the same
+# group_by, per_page, pager text and list_format as the index.
+post_listing:
+  # The index page's <h1>. Set to "" to omit the heading entirely.
+  list_title: "Post listing"
+
+  # How to group posts in the listing.
+  #   none  - a single flat list
+  #   year  - a "## <year>" heading per year
+  #   month - a "## <Month Year>" heading per month
+  group_by: none
+
+  # Text for the link back to the index shown at the top of every post. It
+  # always points at whichever index page that post actually appears on.
+  # Set to "" to omit the link entirely.
+  back_link_text: "← Back to all posts"
+
+  # Maximum number of posts on one index page. Once there are more posts
+  # than this, Parrot splits the listing across index.html (newest posts),
+  # index2.html, index3.html, etc., each with a pager linking to the next
+  # and previous page. Leave unset (or 0) to keep every post on index.html.
+  # per_page: 10
+
+  # Text for the pager links at the bottom of a paginated index page. Set
+  # either to "" to omit that link (e.g. on the first/last page, where it
+  # wouldn't point anywhere anyway).
+  newer_link_text: "← Newer posts"
+  older_link_text: "Older posts →"
+
+  # Markdown format string for each post's list entry.
+  #   {post_<key>} - that key from the post's header, as plain text:
+  #                  {post_title}, {post_lang}, or any custom field you add
+  #                  to a post's <!-- key: value --> header
+  #   {post_date}  - the header's `date`, formatted per post_date_format.on_list
+  #                  below rather than shown as-authored
+  #   {post_category_tag} - the post's `category` as a link to its category
+  #                  page (class "category-tag"); empty for posts without one
+  #   {post_link}  - the post's href, the one field Parrot computes itself
+  #                  rather than reading from the header — wrap whichever
+  #                  part should be clickable in Markdown link syntax
+  #                  yourself: [...]({post_link})
+  #   {...}        - anything else is a Ruby strftime format string (see
+  #                  Ruby's Date#strftime) applied to the post's header
+  #                  `date`, shown as-is rather than through
+  #                  post_date_format.on_list, e.g. {%A, %B %d %Y}
+  #
+  # Link just the title and show the category (default):
+  #   list_format: "{post_date} ~ [{post_title}]({post_link}) {post_category_tag}"
+  # Link the whole line instead:
+  #   list_format: "[{post_date} ~ {post_title}]({post_link})"
+  list_format: "{post_date} ~ [{post_title}]({post_link}) {post_category_tag}"
+
+# How to format a post's header `date` wherever it's shown via the
+# {post_date} token — as opposed to a bare strftime pattern like {%d/%m/%Y},
+# which is already a fixed format. A Ruby strftime format string (see
+# Ruby's Date#strftime), same as list_format's bare {...} patterns.
+post_date_format:
+  # Used for {post_date} inside post_listing's list_format above.
+  on_list: "%m/%Y"
+  # Used for a literal {post_date} placeholder inside a post's own Markdown
+  # body — `parrot post` writes new posts with one under the title.
+  on_post: "%d/%m/%Y"