mint 0.7.4 → 0.8.1

data/lib/mint/mint.rb

@@ -1,94 +1,75 @@
+
 require "pathname"
 require "fileutils"
 require "yaml"
 require "tilt"
-
+require "tilt/mapping"
 require "active_support/core_ext/hash/slice"
+require "active_support/core_ext/string/output_safety"
+require "mint/css_template"
+require "mint/markdown_template"
 
 module Mint
-  ROOT = (Pathname.new(__FILE__).realpath.dirname + "../..").to_s 
-
-  SCOPES = {
-    local:  Pathname.new(".mint"),
-    user:   Pathname.new("~/.mint").expand_path,
-    global: Pathname.new("#{ROOT}/config").expand_path
-  }
-
-  SCOPE_NAMES = SCOPES.keys
+  ROOT                = (Pathname.new(__FILE__).realpath.dirname + "../..").to_s
+  MARKDOWN_EXTENSIONS = %w[md markdown mkd].freeze
+  LOCAL_SCOPE         = Pathname.new(".mint")
+  USER_SCOPE          = Pathname.new("~/.config/mint").expand_path
+  GLOBAL_SCOPE        = Pathname.new("#{ROOT}/config").expand_path
+  SCOPES              = { local: LOCAL_SCOPE, user: USER_SCOPE, global: GLOBAL_SCOPE }
+  SCOPE_NAMES         = SCOPES.keys
+  CONFIG_FILE         = "config.yaml"
+  TEMPLATES_DIRECTORY = "templates"
 
-  # Assume that someone using an Html template has formatted it
-  # in Erb and that a Css stylesheet will pass untouched through
-  # a Scss parser.
-  Tilt.register Tilt::ERBTemplate, :html
-  Tilt.register Tilt::ScssTemplate, :css
-
-  # @return [String] the Mint root path name
-  def self.root
-    ROOT
+  def self.default_options
+    {
+      root: Dir.getwd,
+      destination: nil,
+      style_mode: :inline,
+      style_destination: nil,
+      output_file: '#{basename}.#{new_extension}',
+      layout_or_style_or_template: [:template, 'default'],
+      scope: :local,
+      recursive: false,
+      verbose: false
+    }
+  end
+  
+  def self.mapping
+    if @mapping
+      @mapping
+    else
+      @mapping = Tilt::Mapping.new.tap do |m|
+        m.register Mint::CSSTemplate,       'css'                # Inline Css @imports, creating a single file
+        m.register Mint::MarkdownTemplate, 'txt'                # Process Txt as Markdown
+        m.register Mint::MarkdownTemplate, *MARKDOWN_EXTENSIONS
+        m.register Tilt::ScssTemplate,      'scss'
+        m.register Tilt::SassTemplate,      'sass'
+        m.register Tilt::ERBTemplate,       'erb', 'html'        # Allow for Erb inside HTML
+        m.register Tilt::HamlTemplate,      'haml'
+      end
+    end
   end
 
   # Returns an array with the Mint template path for the named scope
   # or scopes. This path is used to lookup templates and configuration options.
   #
-  # @param [Hash] opts a list of options, including :scopes
+  # @param [Array] scopes a list of scopes to include
   # @return [Array] the Mint path as an Array of Pathnames
-  def self.path(opts={})
-    opts = { scopes: SCOPE_NAMES }.merge(opts)
-    SCOPES.slice(*opts[:scopes]).values
+  def self.path(scopes = SCOPE_NAMES)
+    SCOPES.slice(*scopes).values
   end
 
-  # Returns the part of Mint.path relevant to scope.
-  # I want to refactor this so that Mint.path is always a Hash...
-  # should take care of this in the Mint.path=() method.
-  # Right now, this is a hack. It assumes a sane MINT_PATH, where the
-  # first entry is most local, the second is user-level,
-  # and the last entry is most global.
+  # Returns the base directory for Mint configuration at the specified scope.
   #
   # @param [Symbol] scope the scope we want to find the path for
-  # @param [Boolean] as_path if as_path is true, will return Pathname object
-  # @return [String] the Mint path for +scope+ as a String or Pathname
-  def self.path_for_scope(scope=:local, as_path=false)
-    case Mint.path
-    when Array
-      index = { local: 0, user: 1, global: 2 }[scope]
-      Mint.path[index]
-    when Hash
-      Mint.path[scope]
-    else
-      nil
-    end
-  end
-
-  # @return [Hash] key Mint directories
-  def self.directories
-    { 
-      templates: "templates"
-    }
-  end
-
-  # @return [Hash] key Mint files
-  def self.files
-    { 
-      syntax: "syntax.yaml",
-      defaults: "defaults.yaml"
-    }
-  end
-
-  # @return [Hash] last-resort options for creating Mint documents.
-  def self.default_options
-    {
-      # Do not set default `template`--will override style and
-      # layout when already specified -- causes tricky bugs
-      layout: "default",     # default layout
-      style: "default",      # default style
-      destination: nil,      # do not create a subdirectory
-      style_destination: nil # do not copy style to root
-    }
+  # @return [Pathname] the Mint path for +scope+ as a Pathname
+  def self.path_for_scope(scope = :local)
+    SCOPES[scope]
   end
 
   # @return [Array] all file extensions that Tilt will render
   def self.formats
-    Tilt.mappings.keys
+    mapping.template_map.keys
   end
 
   # @return [Array] CSS formats, for source -> destination
@@ -97,6 +78,7 @@ module Mint
     ["css", "sass", "scss", "less"]
   end
 
+  
   # Returns a hash of all active options specified by file (for all scopes).
   # That is, if you specify file as "defaults.yaml", this will return the aggregate
   # of all defaults.yaml-specified options in the Mint path, where more local
@@ -110,10 +92,16 @@ module Mint
     # Merge config options from all config files on the Mint path,
     # where more local options take precedence over more global
     # options
-    configuration = Mint.path(:scopes => opts[:scopes]).
-      map {|p| p + Mint.files[:defaults] }.
+    configuration = Mint.path(opts[:scopes]).
+      map {|p| p + Mint::CONFIG_FILE }.
       select(&:exist?).
-      map {|p| YAML.load_file p }.
+      map do |p| 
+        begin
+          YAML.load_file p
+        rescue Psych::SyntaxError, StandardError => e
+          {}
+        end
+      end.
       reverse.
       reduce(Mint.default_options) {|r,p| r.merge p }
 
@@ -127,42 +115,79 @@ module Mint
   # @return [Hash] a structured set of configuration options with opts
   #   overriding any options from config files
   def self.configuration_with(opts)
-    configuration.merge opts
+    scopes = if opts[:local] || opts[:user] || opts[:global]
+      if opts[:local]
+        [:local]
+      elsif opts[:user]  
+        [:user]
+      elsif opts[:global]
+        [:global]
+      end
+    else
+      SCOPE_NAMES
+    end
+    
+    processed_opts = opts.dup
+    if processed_opts[:layout_or_style_or_template]
+      option_type, option_value = processed_opts.delete(:layout_or_style_or_template)
+      case option_type
+      when :template
+        processed_opts[:template] = option_value
+      when :layout
+        processed_opts[:layout] = option_value
+      when :style
+        processed_opts[:style] = option_value
+      end
+    end
+    
+    configuration(scopes: scopes).merge processed_opts
   end
 
   # @return [Array] the full path for each known template in the Mint path
-  def self.templates(opts={})
-    opts = { scopes: SCOPE_NAMES }.merge(opts)
-    Mint.path(:scopes => opts[:scopes]).
-      map {|p| p + directories[:templates] }.
+  def self.templates(scope = :local)
+    Mint.path([scope]).
+      map {|p| p + TEMPLATES_DIRECTORY }.
       select(&:exist?).
       map {|p| p.children.select(&:directory?).map(&:to_s) }.
       flatten.
       sort
   end
 
-  # Decides whether the template specified by `name_or_file` is a real
-  # file or the name of a template. If it is a real file, Mint will
-  # return a that file. Otherwise, Mint will look for a file with that
-  # name in the Mint path. The `type` argument indicates whether the
-  # template we are looking for is a layout or a style and will affect
-  # which type of template is returned for a given template name. For
-  # example, `lookup_template :normal` might return a layout template
-  # referring to the file ~/.mint/templates/normal/layout.erb.
-  # Adding :style as a second argument returns
-  # ~/.mint/templates/normal/style.css.
+  # Returns the template directory for the given template name
   #
-  # @param [String, File, #to_s] name_or_file a name or template file 
+  # @param [String, File, #to_s] name_or_file a name or template file
   #   to look up
   # @param [Symbol] type the resource type to look up
   # @return [File] the named, typed template file
   def self.lookup_template(name_or_file, type=:layout)
     name = name_or_file.to_s
-    File.exist?(name) ? name : find_template(name, type)
+    
+    # Only treat as a direct file if it's an actual file (not directory) 
+    if File.file?(name) && formats.include?(File.extname(name)[1..-1])
+      Pathname.new(name).dirname
+    else
+      Pathname.new(find_template_directory(name))
+    end
+  end
+
+  # Returns the layout file for the given template name
+  #
+  # @param [String] name the template name to look up
+  # @return [String] path to the layout file
+  def self.lookup_layout(name)
+    find_template(name, :layout)
+  end
+
+  # Returns the style file for the given template name
+  #
+  # @param [String] name the template name to look up
+  # @return [String] path to the style file  
+  def self.lookup_style(name)
+    find_template(name, :style)
   end
 
   # Finds a template named `name` in the Mint path. If `type` is :layout,
-  # will look for `MINT_PATH/templates/layout.*`. If it is :style, will
+  # will look for `MINT_PATH/templates/template_name/layout.*`. If it is :style, will
   # look for `MINT_PATH/templates/template_name/style.*`. Mint assumes
   # that a named template will hold only one layout and one style template.
   # It does not know how to decide between style.css and style.less, for
@@ -175,32 +200,74 @@ module Mint
   #
   # @return [File] the named, typed template file
   def self.find_template(name, type)
-    templates_dir = Mint.directories[:templates]
-
-    file_name  = lambda {|x| x + templates_dir + name + type.to_s }
+    file_name  = lambda {|x| x + Mint::TEMPLATES_DIRECTORY + name + type.to_s }
     find_files = lambda {|x| Pathname.glob "#{x.to_s}.*" }
-    acceptable = lambda {|x| x.to_s =~ /#{Mint.formats.join "|"}/ }
+    acceptable = lambda {|x| 
+      ext = File.extname(x.to_s)[1..-1]
+      return false unless ext
+      case type
+      when :layout
+        formats.include?(ext)
+      when :style  
+        css_formats.include?(ext)
+      else
+        false
+      end
+    }
 
-    Mint.path.map(&file_name).map(&find_files).flatten.
-      select(&acceptable).select(&:exist?).first.tap do |template|
-      raise TemplateNotFoundException unless template
-    end.to_s
+    template_file = Mint.path.
+      map(&file_name).
+      map(&find_files).
+      flatten.
+      select(&acceptable).
+      select(&:exist?).
+      first
+      
+    unless template_file
+      template_dirs = Mint.path.map {|p| p + Mint::TEMPLATES_DIRECTORY + name }.select(&:exist?)
+      if template_dirs.any?
+        expected_exts = case type
+                        when :layout then formats.join(', ')
+                        when :style then css_formats.join(', ')
+                        end
+        raise TemplateNotFoundException, "Template '#{name}' exists but has no valid #{type} file. Expected #{type}.{#{expected_exts}}"
+      else
+        raise TemplateNotFoundException, "Template '#{name}' does not exist."
+      end
+    end
+    
+    template_file.to_s
   end
 
-  def self.template_path(name, type, opts={})
-    defaults = { 
-      scope: :local,
-      ext: { layout: "haml", style: "sass" }[type]
-    }
-    opts = defaults.merge(opts)
-    path = Mint.path_for_scope(opts[:scope])
-
-    case type
-    when :layout, :style
-      "#{path}/templates/#{name}/#{type}.#{opts[:ext]}"
-    when :all
-      "#{path}/templates/#{name}"
+  # Finds a template directory by name
+  #
+  # @param [String] name the template name to find
+  # @return [String] path to the template directory
+  def self.find_template_directory(name)
+    template_dir = Mint.path.
+      map {|p| p + Mint::TEMPLATES_DIRECTORY + name }.
+      select(&:exist?).
+      first
+      
+    unless template_dir
+      raise TemplateNotFoundException, "Template '#{name}' does not exist."
     end
+    
+    template_dir.to_s
+  end
+
+  # Finds a specific template file by name and type
+  #
+  # @param [String] name the template name to find
+  # @param [Symbol] type :layout or :style
+  # @return [String] path to the template file
+  def self.find_template_file(name, type)
+    find_template(name, type)
+  end
+
+  # Returns the template directory for the given scope, if found
+  def self.template_path(name, scope)
+    Mint.path_for_scope(scope) + "templates/#{name}"
   end
 
   # Checks (non-rigorously) to see if the file is somewhere on the
@@ -211,7 +278,7 @@ module Mint
   def self.template?(file)
     paths = Mint.path.map {|f| File.expand_path f }
     file_path = Pathname.new(file)
-    file_path.exist? and 
+    file_path.exist? and
       file_path.dirname.expand_path.to_s =~ /#{paths.map(&:to_s).join("|")}/
   end
 
@@ -225,7 +292,7 @@ module Mint
     css = Mint.css_formats.join "|"
     name.to_s.
       gsub(/\.(#{css})$/, ".css").
-      gsub(/(\.[^css]+)$/, ".html")
+      gsub(/(\.(?!css).*)$/, ".html")
   end
 
   # Transforms a path into a template that will render the file specified
@@ -233,7 +300,7 @@ module Mint
   #
   # @param [Path, File, String, #to_s] path the file to render
   def self.renderer(path)
-    Tilt.new path.to_s, :smart => true, :ugly => true
+    mapping.new path.to_s
   end
 
   # Publishes a Document object according to its internal specifications.

data/lib/mint/plugin.rb

@@ -1,5 +1,5 @@
-require "mint/document"
 require "set"
+require "mint/document"
 
 module Mint
   def self.plugins
@@ -28,11 +28,11 @@ module Mint
   end
 
   def self.template_directory(plugin)
-    Mint.root + "/plugins/templates/" + plugin.underscore
+    Mint::ROOT + "/plugins/templates/" + plugin.underscore
   end
 
   def self.config_directory(plugin)
-    Mint.root + "/plugins/config/" + plugin.underscore
+    Mint::ROOT + "/plugins/config/" + plugin.underscore
   end
 
   def self.commandline_options_file(plugin)

data/lib/mint/plugins/epub.rb

@@ -1,7 +1,6 @@
 require "nokogiri"
 require "hashie"
-require "zip/zip"
-require "zip/zipfilesystem"
+require "zip"
 require "active_support/core_ext/hash/deep_merge"
 require "active_support/core_ext/hash/keys"
 

data/lib/mint/resource.rb

@@ -4,6 +4,8 @@ module Mint
   class Resource
     attr_accessor :type
 
+    attr_accessor :context
+
     attr_reader :name
     def name=(name)
       @name = name
@@ -26,7 +28,7 @@ module Mint
 
     def source_file_path
       path = Pathname.new(source)
-      path.absolute? ? 
+      path.absolute? ?
         path.expand_path : root_directory_path + path
     end
 
@@ -59,22 +61,23 @@ module Mint
     def destination_directory
       destination_directory_path.to_s
     end
-    
+
     def renderer=(renderer)
       @renderer = renderer
     end
 
-    def initialize(source, options={})
+    def initialize(source, root: nil, destination: nil, context: nil, name: nil, &block)
       return nil unless source
 
       self.type = :resource
       self.source = source
-      self.root = options[:root] || source_directory
-      self.destination = options[:destination]
+      self.root = root || source_directory
+      self.destination = destination
+      self.context = context
 
-      yield self if block_given?
+      yield self if block
 
-      self.name = Mint.guess_name_from source
+      self.name = name || Mint.guess_name_from(source)
       self.renderer = Mint.renderer source
     end
 
@@ -83,9 +86,16 @@ module Mint
     end
     alias_method :==, :equal?
 
-    def render(context=Object.new, args={})
+    def render(context=self, args={})
       # see Tilt TEMPLATES.md for more info
-      @renderer.render context, args 
+      @renderer.render context, args
+    end
+
+    def publish!(opts={})
+      FileUtils.mkdir_p self.destination_directory
+      File.open(self.destination_file, "w+") do |f|
+        f << self.render
+      end
     end
   end
 end

data/lib/mint/style.rb

@@ -2,13 +2,12 @@ require "mint/resource"
 
 module Mint
   class Style < Resource
-    # Creates a new Layout object using a mandatory source file
+    # Creates a new Style object using a mandatory source file
     # and optional configuration options.
     #
     # @param [String] source the absolute or relative file path
-    # @param [Hash, #[]] opts style options
-    def initialize(source, opts=Mint.default_options)
-      super(source, opts)
+    def initialize(source, root: nil, destination: nil, context: nil, name: nil, &block)
+      super(source, root: root, destination: destination, context: context, name: name, &block)
       self.type = :style
 
       # We want to render final stylesheet to the /css subdirectory if
@@ -19,7 +18,9 @@ module Mint
       # However, if a destination directory is already specified, we
       # leave it alone.
       if Mint.template?(self.source_directory) and rendered?
-        self.destination ||= "css" 
+        tmp_dir = Mint.path_for_scope(:user) + "tmp"
+        self.destination ||= tmp_dir.to_s
+        self.root = "/"
       end
     end
 
@@ -27,19 +28,14 @@ module Mint
     #
     # @return [Boolean] whether or not style should be rendered
     def rendered?
-      source_file_path.extname !~ /\.css$/
+      true  # All styles need rendering now (CSS for imports, Sass for compilation)
     end
 
-    # Renders a Style object if necessary. Otherwise, returns the contents
-    # of its source file.
+    # Renders a Style object through Tilt template system
     #
-    # @return [String] a rendered stylesheet
+    # @return [String] a rendered stylesheet  
     def render
-      if rendered?
-        super
-      else
-        File.read source
-      end
+      super
     end
   end
 end

data/lib/mint/version.rb

@@ -1,3 +1,3 @@
 module Mint
-  VERSION = "0.7.4"
+  VERSION = "0.8.1"
 end

data/lib/mint.rb

@@ -9,3 +9,4 @@ require "mint/css"
 require "mint/command_line"
 require "mint/exceptions"
 require "mint/plugin"
+require "mint/css_template"

data/man/mint.1

@@ -0,0 +1,135 @@
+.TH MINT 1 "December 2024" "mint" "User Commands"
+.SH NAME
+mint \- transform plain text documents into beautiful styled HTML
+.SH SYNOPSIS
+.B mint
+.I COMMAND
+[\fIOPTIONS\fR] [\fIFILE\fR...]
+.SH DESCRIPTION
+Mint transforms your plain text documents into beautiful documents. It makes that process as simple (but customizable) as possible.
+
+Mint processes Markdown, Textile, and other templating languages into styled HTML documents ready to print, email, and present.
+.SH COMMANDS
+.TP
+.B publish
+Transform one or more source files into HTML documents
+.SH OPTIONS
+.TP
+.BR \-d ", " \-\-destination " " \fIDIRECTORY\fR
+Specify a destination directory, relative to the root
+.TP
+.BR \-\-style\-mode " " \fIMODE\fR
+Specify how styles are included (inline, external, original). Default is inline.
+.TP
+.BR \-\-style\-destination " " \fIDESTINATION\fR
+Create stylesheet at specified directory or file path and link it. This sets style mode to external.
+.TP
+.BR \-\-template " " \fITEMPLATE\fR
+Specify a template to use for both layout and styling
+.TP
+.BR \-l ", " \-\-layout " " \fILAYOUT\fR
+Specify a specific layout template
+.TP
+.BR \-\-style " " \fISTYLE\fR
+Specify a specific style template
+.TP
+.BR \-g ", " \-\-global
+Specify config changes on a global level
+.TP
+.BR \-u ", " \-\-user
+Specify config changes on a user-wide level
+.TP
+.BR \-\-local
+Specify config changes on a local level (default)
+.TP
+.BR \-r ", " \-\-recursive
+Recursively find all Markdown files in subdirectories
+.TP
+.BR \-v ", " \-\-verbose
+Enable verbose output
+.TP
+.BR \-h ", " \-\-help
+Display help information
+.SH STYLE OPTIONS
+Mint offers flexible control over how stylesheets are incorporated into your documents:
+
+.SS Inline Styles (Default)
+By default, Mint inlines CSS directly into your HTML documents, creating self-contained files:
+.RS
+.nf
+mint publish document.md
+.fi
+.RE
+
+.SS External Stylesheets
+Create external stylesheets that are linked from your HTML documents:
+.RS
+.nf
+mint publish document.md --style-destination css
+mint publish document.md --style-destination styles/main.css
+.fi
+.RE
+
+External stylesheets are useful when you want to share stylesheets across multiple documents, keep HTML files smaller, or allow separate caching of styles.
+.SH EXAMPLES
+.TP
+Transform a single Markdown file:
+.nf
+mint publish document.md
+.fi
+.TP
+Transform multiple files:
+.nf
+mint publish doc1.md doc2.md doc3.md
+.fi
+.TP
+Use a specific template:
+.nf
+mint publish resume.md --template resume
+.fi
+.TP
+Create external stylesheet:
+.nf
+mint publish document.md --style-destination css
+.fi
+.TP
+Recursively process all Markdown files:
+.nf
+mint publish --recursive
+.fi
+.SH TEMPLATES
+Mint comes with several built-in templates:
+.IP \(bu 2
+.B default
+\- Clean, professional styling
+.IP \(bu 2
+.B zen
+\- Minimalist design
+.IP \(bu 2
+.B protocol
+\- Technical documentation style
+.IP \(bu 2
+.B newspaper
+\- Multi-column layout
+.IP \(bu 2
+.B nord/nord-dark
+\- Modern color schemes
+.PP
+Templates can be written in any format accepted by the Tilt template interface library (ERB, Haml, etc.).
+.SH FILES
+.TP
+.I ~/.config/mint/
+User-specific configuration and templates
+.TP
+.I .mint/
+Project-specific configuration and templates
+.TP
+.I config.yaml
+Configuration file (can exist at global, user, or local levels)
+.SH SEE ALSO
+.BR markdown (1),
+.BR tilt (1)
+.SH AUTHOR
+David Jacobs <david@wit.io>
+.SH HOMEPAGE
+https://github.com/davejacobs/mint