madness 1.1.4 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78a49ca36d07d11662ba98136593790a316586d4f17cff8bd7a3febc02916c01
-  data.tar.gz: 03adaa519d407baa99337a9eae0beba3edfcb91c22f73fe54049d78d3fd0f103
+  metadata.gz: 76896d82203c749d37aa6bb4a321deee5e544f9763ff9ab9544bd28ae90c613d
+  data.tar.gz: a1a8c4093bc5dbef67489096658f057860945125c6de6e5376f362287b207be2
 SHA512:
-  metadata.gz: 88b64055acfc24a132c11bfcc91e81dcbef93343c3b1c857921fb0257befd21d85c3c9651891c54eabb9bfd558e21e4f299fc706dd4f8655e7b2dc426eb388f7
-  data.tar.gz: a155163d534295118fc2082a0bce08533bfffe06a45b934ea68b6d7deffb301075b8aff1635bb6d95e841a479eaafa36055c7f6f650a30e153f72792425016d8
+  metadata.gz: 7a0e267fcdd6e0568f348e03d2b67b99e3bbc7ca6cbc7eefef3d8f00f1661b5193c281800520fa7b4ad266083eb174dc62d65314d1a6883e91d986e5e6719203
+  data.tar.gz: 55db2eb7681263246b3fbae1881c811e62c5d39974439ad7279ecf6ba48c43c6e69d18866c09e9d110aa3e26674ec127e251343f88ccdc8d9da3a5926359b182

data/README.md

@@ -78,9 +78,6 @@ Madness expects to be executed in a documentation directory.
 A documentation directory contains only markdown files (`*.md`) and sub
 directories that contain more markdown files.
 
-The server will consider the file `index.md` or `README.md` in any directory as
-the main file describing this directory, where `index.md` has priority.
-
 The navigation sidebar will show all the sub directories and files in the same
 directory as the viewed file.
 
@@ -129,6 +126,11 @@ bind: 0.0.0.0
 # base_uri: /docs
 base_uri: ~
 
+# choose navigation sort order:
+# sort_order: dirs_first     # alphabetic directories then alphabetic files
+# sort_order: mixed          # alphabetic regardless of type
+sort_order: dirs_first
+
 # enable sidebar
 sidebar: true
 
@@ -195,6 +197,23 @@ exclude: ['^[a-z_\-0-9]+$']
 
 ## Features
 
+### Cover Pages
+
+Cover pages are specially named markdown files that serve as the introduction
+to the contents of a specific directory.
+
+The server will consider any of the following files as cover pages (prioritized):
+
+- A markdown file with the same name as the directory (adjacent to it).
+- `index.md`
+- `README.md`
+
+For example, for a directory named "API Documentation":
+
+- `/API Documentation.md`
+- `/API Documentation/index.md`
+- `/API Documentation/README.md`
+
 ### Search
 
 Madness comes with a full text search page.
@@ -286,6 +305,9 @@ will be omitted when they are displayed.
 └── 2. Another file or folder
 ```
 
+Note that by default, directories will appear above files. If you wish to
+change this, set `sort_order: mixed` in your configuration file.
+
 ### Displaying Additional File Types
 
 If you wish the navigation and search features to also show other documents

data/lib/madness/directory.rb

@@ -3,6 +3,7 @@ module Madness
   class Directory
     include ServerHelper
     using ArrayRefinements
+    using StringRefinements
 
     attr_reader :dir
 
@@ -17,17 +18,22 @@ module Madness
   private
 
     def files
-      result = Dir["#{dir}/#{config.dir_glob}"]
-      result.reject! do |f|
-        ['README.md', 'index.md'].include? File.basename(f)
+      @files ||= begin
+        result = Dir["#{dir}/#{config.dir_glob}"]
+        result.reject! do |f|
+          ['README.md', 'index.md'].include? File.basename(f)
+        end
+        result.reject! { |f| is_cover_page? f }
+        result.nat_sort.map { |path| Item.new path, :file }
       end
-      result.nat_sort.map { |path| Item.new path, :file }
     end
 
     def dirs
-      result = Dir["#{dir}/*"].select { |f| File.directory? f }
-      result.reject! { |f| exclude? f }
-      result.nat_sort.map { |path| Item.new path, :dir }
+      @dirs ||= begin
+        result = Dir["#{dir}/*"].select { |f| File.directory? f }
+        result.reject! { |f| exclude? f }
+        result.nat_sort.map { |path| Item.new path, :dir }
+      end
     end
 
     def exclude?(path)
@@ -40,6 +46,14 @@ module Madness
       false
     end
 
+    def is_cover_page?(path)
+      dir_paths.include? path.remove(/\.md$/)
+    end
+
+    def dir_paths
+      @dir_paths ||= dirs.map(&:path)
+    end
+
     def config
       @config ||= Settings.instance
     end

data/lib/madness/document.rb

@@ -55,10 +55,8 @@ module Madness
       @dir  = base
       @type = :readme
 
-      if File.exist? "#{base}/index.md"
-        @file = "#{base}/index.md"
-      elsif File.exist? "#{base}/README.md"
-        @file = "#{base}/README.md"
+      if cover_page
+        @file = cover_page
       else
         @type = :empty
       end
@@ -79,5 +77,25 @@ module Madness
     def md_filename
       File.extname(base) == '.md' ? base : "#{base}.md"
     end
+
+    def cover_page
+      @cover_page ||= cover_page!
+    end
+
+    def cover_page!
+      cover_page_candidates.each do |candidate|
+        return candidate if File.exist? candidate
+      end
+
+      nil
+    end
+
+    def cover_page_candidates
+      @cover_page_candidates ||= [
+        File.expand_path("../#{File.basename(base)}.md", base),
+        File.expand_path('index.md', base),
+        File.expand_path('README.md', base),
+      ]
+    end
   end
 end

data/lib/madness/navigation.rb

@@ -2,6 +2,7 @@ module Madness
   # Handle the navigation links for a given directory
   class Navigation
     include ServerHelper
+    using ArrayRefinements
     using StringRefinements
 
     attr_reader :dir
@@ -11,7 +12,11 @@ module Madness
     end
 
     def links
-      @links ||= directory.list
+      @links ||= if config.sort_order == 'mixed'
+        directory.list.nat_sort(by: :href)
+      else
+        directory.list
+      end
     end
 
     def caption
@@ -27,5 +32,9 @@ module Madness
     def directory
       @directory ||= Directory.new(dir)
     end
+
+    def config
+      Settings.instance
+    end
   end
 end

data/lib/madness/refinements/array_refinements.rb

@@ -3,8 +3,8 @@ require 'naturally'
 module Madness
   module ArrayRefinements
     refine Array do
-      def nat_sort
-        Naturally.sort self
+      def nat_sort(by: nil)
+        Naturally.sort self, by: by
       end
     end
   end

data/lib/madness/server_base.rb

@@ -16,7 +16,7 @@ module Madness
     set :static, false
 
     # Since we cannot use any config values in the main body of the class,
-    # since they will be updated later, we need to set anything that relys
+    # since they will be updated later, we need to set anything that relies
     # on the config values just before running the server.
     # The CommandLine class and the test suite should both call
     # `Server.prepare` before calling Server.run!

data/lib/madness/settings.rb

@@ -15,7 +15,7 @@ module Madness
       reset
     end
 
-    def method_missing(name, *args, &_blk)
+    def method_missing(name, *args, &_block)
       name_string = name.to_s
 
       if name_string.end_with? '='
@@ -57,6 +57,7 @@ module Madness
         port:              3000,
         bind:              '0.0.0.0',
         base_uri:          nil,
+        sort_order:        'dirs_first',
         sidebar:           true,
         auto_h1:           true,
         auto_nav:          true,

data/lib/madness/templates/madness.yml

@@ -15,6 +15,11 @@ bind: 0.0.0.0
 # base_uri: /docs
 base_uri: ~
 
+# choose navigation sort order:
+# sort_order: dirs_first     # alphabetic directories then alphabetic files
+# sort_order: mixed          # alphabetic regardless of type
+sort_order: dirs_first
+
 # enable sidebar
 sidebar: true
 

data/lib/madness/version.rb

@@ -1,3 +1,3 @@
 module Madness
-  VERSION = '1.1.4'
+  VERSION = '1.1.5'
 end

data/lib/madness.rb

@@ -1,11 +1,8 @@
-if ENV['BYEBUG']
-  require 'byebug'
-  require 'lp'
-end
-
 require 'requires'
 
 requires 'madness/refinements'
 requires 'madness/settings'
 requires 'madness/server_helper'
 requires 'madness'
+
+require 'debug' rescue nil if ENV['DEBUGGER']

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: madness
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.1.5
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-09 00:00:00.000000000 Z
+date: 2024-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -28,22 +28,16 @@ dependencies:
   name: colsole
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.8.1
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.8.1
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: extended_yaml
   requirement: !ruby/object:Gem::Requirement