howzit 2.1.48 → 2.1.49

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a6dffed9d9ce31f4704b3388bbf330f87d86f054067444073ea34b8cba13a54
-  data.tar.gz: 87cdb843c109e8f0b88e482634d0f35b676ffcd6e2732009f5a7aa60932f7fff
+  metadata.gz: 91e3e382d6e58e8a3a50cb663de149af066ee02b80bafcdbf6db5d68c79426af
+  data.tar.gz: ebaf51a69ba374ba5fa64a548560cfa0b8e03f70b85a77de3a1f43aa94baf944
 SHA512:
-  metadata.gz: 4e278c055f9647bb784cfac2f1fe00616dde57023a5cd08e714097ccc3f32181ad67898da2507fe23c5496a235cdee5143c29918149a0a15d1e70574e3d535d8
-  data.tar.gz: 409df1fe83a7e46ba317d2c9cceb8346ea94c7578376f1836b7d9bb6cb17b83b51020955470d1371a27abb46150ec6af49da1e5b15ac8108eff9b9fccb625cc9
+  metadata.gz: 96e353abbe3fec9eb5cce2c1fcbbdc45d425394594f394251dc2719937ba69a2acbf87e7d3ccae437baf25b33c400ef0ddf7c01cd42765cc4f39009968f703cf
+  data.tar.gz: 48c8b7253abbd0adfe88a0b5ccb1108684db73252c87823ef29aa59507feefd814bc689831585255e73624136f55cd39ee0797ab84666c49dc3a56107b76fa31

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+### 2.1.49
+
+2026-10-21 05:15
+
+#### CHANGED
+
+- **Markdown highlighting** tries `apex` first when `:highlighter:` is `auto`, then mdcat, then mdless. mdless is still installed with the gem
+- **Directives inside a code fence** are shown as code instead of being turned into tasks
+
+#### FIXED
+
+- **Apex output** uses `-t terminal256 --no-paginate`, including when `:highlighter:` is set to `apex` alone, so topics render as terminal color instead of HTML
+- **Placeholders inside fenced code** are left as written, so a syntax highlighter such as Pygments does not print howzit's color codes as text like `[1m`
+
 ### 2.1.48
 
 2026-10-09 07:20

data/README.md

@@ -37,7 +37,7 @@ Howzit is a tool that allows you to keep Markdown-formatted notes about a projec
 - Ruby 2.4+ (It probably works on older Rubys, but is untested prior to 2.4.1.)
 - Optional: if [`fzf`](https://github.com/junegunn/fzf) is available, it will be used for handling multiple choice selections
 - Optional: if [`bat`](https://github.com/sharkdp/bat) is available it will page with that
-- Optional: [`mdless`](https://github.com/ttscoff/mdless) or [`mdcat`](https://github.com/lunaryorn/mdcat) for formatting output
+- Optional: [`apex`](https://github.com/ApexMarkdown/apex) is preferred for formatting output when it is installed. Otherwise howzit uses [`mdcat`](https://github.com/lunaryorn/mdcat) or [`mdless`](https://github.com/ttscoff/mdless). mdless is installed with the howzit gem.
 
 ### Installing
 

data/bin/howzit

@@ -210,7 +210,7 @@ OptionParser.new do |opts|
     Howzit.options[:header_format] = t
   end
 
-  opts.on('--[no-]md-highlight', 'Highlight Markdown syntax (default on), requires mdless or mdcat') do |m|
+  opts.on('--[no-]md-highlight', 'Highlight Markdown syntax (default on), prefers apex, then mdcat or mdless') do |m|
     Howzit.options[:highlight] = Howzit.options[:color] ? m : false
   end
 

data/lib/howzit/topic.rb

@@ -493,7 +493,18 @@ module Howzit
         topic.gsub!(/(?mix)^(`{3,})run([?!]*)\s*
                     ([^\n]*)[\s\S]*?\n\1\s*$/, '@@@run\2 \3')
       end
+      in_fence = false
+      fence_char = nil
+      fence_len = 0
       topic.split(/\n/).each do |l|
+        # Fenced code is passed through unchanged. Howzit color codes inside a
+        # fence get mangled by the syntax highlighter Apex shells out to.
+        if in_fence
+          output.push(l)
+          in_fence = false if closing_fence?(l, fence_char, fence_len)
+          next
+        end
+
         case l
         when /@(before|after|prereq|end|if|unless)/
           next
@@ -504,12 +515,22 @@ module Howzit
         when /(?<fence>`{3,})run(?<optional>[!?]{1,2})? *(?<title>.*?)$/i
           desc = title_code_block(Regexp.last_match.named_captures.symbolize_keys)
           output.push("{bmK}\u{25B6} {bwK}#{desc}{x}\n```".c)
+          fence_char = '`'
+          fence_len = Regexp.last_match[:fence].length
+          in_fence = true
         when /@@@run(?<optional>[!?]{1,2})? *(?<title>.*?)$/i
           output.push("{bmK}\u{25B6} {bwK}#{title_code_block(Regexp.last_match.named_captures.symbolize_keys)}{x}".c)
         else
-          l.wrap!(Howzit.options[:wrap]) if Howzit.options[:wrap].positive?
-          # Highlight variable placeholders in content
-          output.push(highlight_variables(l))
+          opened = opening_fence(l)
+          if opened
+            fence_char, fence_len = opened
+            in_fence = true
+            output.push(l)
+          else
+            l.wrap!(Howzit.options[:wrap]) if Howzit.options[:wrap].positive?
+            # Highlight variable placeholders in content
+            output.push(highlight_variables(l))
+          end
         end
       end
       Howzit.named_arguments = @named_args
@@ -620,6 +641,23 @@ module Howzit
 
     private
 
+    ##
+    ## A markdown opening fence (` ``` ` or `~~~`, up to three spaces of indent)
+    ##
+    ## @return     [Array(String, Integer), nil] fence character and length
+    ##
+    def opening_fence(line)
+      match = line.match(/\A {0,3}(?<marker>`{3,}|~{3,})/)
+      return unless match
+
+      marker = match[:marker]
+      [marker[0], marker.length]
+    end
+
+    def closing_fence?(line, char, length)
+      line.match?(/\A {0,3}#{Regexp.escape(char)}{#{length},}[ \t]*\z/)
+    end
+
     def run_topic(nested:, as_subtopic:)
       @results = { total: 0, success: 0, errors: 0, message: ''.c }
       output = []

data/lib/howzit/util.rb

@@ -50,31 +50,50 @@ module Howzit
         end
       end
 
-      # If either mdless or mdcat are installed, use that for highlighting
-      # markdown
+      # Prefer apex, then mdcat, then mdless. mdless ships with the gem,
+      # so highlighting still works when apex is not installed.
       def which_highlighter
-        if Howzit.options[:highlighter] =~ /auto/i
-          highlighters = %w[mdcat mdless]
-          highlighters.delete_if(&:nil?).select!(&:available?)
-          return nil if highlighters.empty?
+        command = if Howzit.options[:highlighter] =~ /auto/i
+                    auto_highlighter
+                  else
+                    configured_highlighter
+                  end
+        apex_command(command)
+      end
 
-          hl = highlighters.first
-          args = case hl
-                 when 'mdless'
-                   '--no-pager'
-                 end
+      # Apex defaults to HTML. Howzit always wants terminal escapes, and it
+      # pages the result itself, so add those flags unless the command
+      # already sets a format or a pagination option. This covers both
+      # auto and an explicit `:highlighter: apex`.
+      def apex_command(command)
+        return command if command.nil? || command.empty?
+        return command unless command.split.first == 'apex'
 
-          [hl, args].join(' ')
-        else
-          hl = Howzit.options[:highlighter].split(/ /)[0]
-          if hl.available?
-            Howzit.options[:highlighter]
-          else
-            Howzit.console.error Color.template("{Rw}Error:{xbw} Specified highlighter (#{Howzit.options[:highlighter]}) not found, switching to auto")
-            Howzit.options[:highlighter] = 'auto'
-            which_highlighter
-          end
-        end
+        args = command.split[1..]
+        has_format = args.any? { |arg| ['-t', '--to'].include?(arg) || arg.start_with?('--to=') }
+        args.push('-t', 'terminal256') unless has_format
+        has_pager = args.any? { |arg| ['--no-paginate', '--paginate', '-p'].include?(arg) }
+        args << '--no-paginate' unless has_pager
+        ['apex', *args].join(' ')
+      end
+
+      def auto_highlighter
+        highlighters = %w[apex mdcat mdless]
+        highlighters.delete_if(&:nil?).select!(&:available?)
+        return nil if highlighters.empty?
+
+        hl = highlighters.first
+        args = '--no-pager' if hl == 'mdless'
+        [hl, args].compact.join(' ')
+      end
+
+      def configured_highlighter
+        hl = Howzit.options[:highlighter].split(/ /)[0]
+        return Howzit.options[:highlighter] if hl.available?
+
+        Howzit.console.error Color.template("{Rw}Error:{xbw} Specified highlighter (#{Howzit.options[:highlighter]}) not found, switching to auto")
+        Howzit.options[:highlighter] = 'auto'
+        auto_highlighter
       end
 
       # When pagination is enabled, find the best (in my opinion) option,

data/lib/howzit/version.rb

@@ -3,5 +3,5 @@
 # Primary module for this gem.
 module Howzit
   # Current Howzit version.
-  VERSION = '2.1.48'
+  VERSION = '2.1.49'
 end

data/spec/topic_spec.rb

@@ -103,6 +103,36 @@ describe Howzit::Topic do
       Howzit.options[:show_all_code] = true
       expect(topic.print_out({ single: true, header: true }).join("\n").uncolor).to match(/▶ ls -1/)
     end
+
+    it 'leaves placeholders inside fenced code for the syntax highlighter' do
+      Howzit::Color.coloring = true
+      Howzit.options[:show_all_code] = true
+      note = Howzit::Topic.new('Widgets', <<~MD)
+        We set ${TEST_VAR} in a script block
+
+        ```bash
+        echo "${TEST_VAR}"
+        @run(ls) shown as code
+        ```
+
+        ```run Full capture script
+        if [[ -n ${only} ]]
+        ```
+      MD
+
+      lines = note.print_out({ single: true, header: false })
+      prose = lines.find { |line| line.include?('We set') }
+      echo_line = lines.find { |line| line.include?('echo') }
+      directive = lines.find { |line| line.include?('@run') }
+      condition = lines.find { |line| line.include?('only') }
+
+      expect(prose).to include("\e[")
+      expect(echo_line).to eq('echo "${TEST_VAR}"')
+      expect(directive).to eq('@run(ls) shown as code')
+      expect(condition).to eq('if [[ -n ${only} ]]')
+    ensure
+      Howzit::Color.coloring = false
+    end
   end
 
   describe '.arguments' do

data/spec/util_spec.rb

@@ -23,10 +23,50 @@ describe Howzit::Util do
   end
 
   describe '.which_highlighter' do
+    after { Howzit.options[:highlighter] = 'auto' }
+
     it 'finds mdless' do
       Howzit.options[:highlighter] = 'mdless'
       expect(util.which_highlighter).to eq 'mdless'
     end
+
+    it 'prefers apex with terminal256 output and pagination disabled' do
+      Howzit.options[:highlighter] = 'auto'
+      allow(util).to receive(:command_exist?).and_return(false)
+      allow(util).to receive(:command_exist?).with('apex').and_return(true)
+
+      expect(util.which_highlighter).to eq 'apex -t terminal256 --no-paginate'
+    end
+
+    it 'uses mdcat when apex is not installed' do
+      Howzit.options[:highlighter] = 'auto'
+      allow(util).to receive(:command_exist?).and_return(false)
+      allow(util).to receive(:command_exist?).with('mdcat').and_return(true)
+
+      expect(util.which_highlighter).to eq 'mdcat'
+    end
+
+    it 'uses mdless without its pager when apex and mdcat are not installed' do
+      Howzit.options[:highlighter] = 'auto'
+      allow(util).to receive(:command_exist?).and_return(false)
+      allow(util).to receive(:command_exist?).with('mdless').and_return(true)
+
+      expect(util.which_highlighter).to eq 'mdless --no-pager'
+    end
+
+    it 'adds terminal256 output when the highlighter is set to apex' do
+      Howzit.options[:highlighter] = 'apex'
+      allow(util).to receive(:command_exist?).with('apex').and_return(true)
+
+      expect(util.which_highlighter).to eq 'apex -t terminal256 --no-paginate'
+    end
+
+    it 'keeps an explicit apex output format' do
+      Howzit.options[:highlighter] = 'apex -t html'
+      allow(util).to receive(:command_exist?).with('apex').and_return(true)
+
+      expect(util.which_highlighter).to eq 'apex -t html --no-paginate'
+    end
   end
 
   describe '.which_pager' do

data/src/_README.md

@@ -37,7 +37,7 @@ Howzit is a tool that allows you to keep Markdown-formatted notes about a projec
 - Ruby 2.4+ (It probably works on older Rubys, but is untested prior to 2.4.1.)
 - Optional: if [`fzf`](https://github.com/junegunn/fzf) is available, it will be used for handling multiple choice selections
 - Optional: if [`bat`](https://github.com/sharkdp/bat) is available it will page with that
-- Optional: [`mdless`](https://github.com/ttscoff/mdless) or [`mdcat`](https://github.com/lunaryorn/mdcat) for formatting output
+- Optional: [`apex`](https://github.com/ApexMarkdown/apex) is preferred for formatting output when it is installed. Otherwise howzit uses [`mdcat`](https://github.com/lunaryorn/mdcat) or [`mdless`](https://github.com/ttscoff/mdless). mdless is installed with the howzit gem.
 
 ### Installing
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howzit
 version: !ruby/object:Gem::Version
-  version: 2.1.48
+  version: 2.1.49
 platform: ruby
 authors:
 - Brett Terpstra