madman 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47049987d632e62ea57b613c96170b95031acaa20b0390fdbf55d430d02c45ec
-  data.tar.gz: 53856412c8eb24b3ee946f24b554f80fa66aad09ee93bfe0b7ff0bc30ae90bb1
+  metadata.gz: 8d2cbbb3df05900e21afcc52747a66d7e29966f89e16f479cf5fdf55dfcbf3d0
+  data.tar.gz: 48a7d30f17a8b31909d11ea296c424cbb5611d931d4b1ab101166bb192e43f57
 SHA512:
-  metadata.gz: a2df596bb8c46b703e2e708199a945d95534bf5a294ce40580b3693bb7390087a46b1fce1e6dc31cc33adca2106fc36c64210e78a9d433597006463026af88a5
-  data.tar.gz: daca0122ce6af5f38f9aeeed54c87fc818784c93a29e89da89eb6babe71ab0f6359c9686a5a9889cb5a77e295ca373fdd99903df4bb55b0a74416257d6e496a4
+  metadata.gz: 6e2fe3266fe89d3ba1c9cfa776e533d52919dbc0af47609ea5057f07bb6b8d420bd6cbcceb9914a9e53c94975a85ea245df4d91e0025ff0a50427e88051f9fa3
+  data.tar.gz: 59ae594fc5021740a4b980e914b8309a404f1399bfd99a322286307d99a84715f0452eb7131d5f0343715d6c5f221d3614768d10024a45f6bc6034b9e1280aa7

data/README.md

@@ -35,10 +35,10 @@ Key Features
 - Convert markdown to a single HTML file (including CSS).
 - Ad-hoc server to serve a markdown file locally for preview.
 - Markdown generation with GitHub API (optional).
+- Table of Contents generation for a folder of markdown files.
+- Web server for an entire folder (like [Madness](https://github.com/DannyBen/madness))
 - [Planned] Table of Contents generation for a single file.
-- [Planned] Table of Contents generation for a folder of markdown files.
 - [Planned] Combine multiple markdown files to one.
-- [Considered] Web server for an entire folder (like [Madness][1])
 
 
 
@@ -46,21 +46,40 @@ Usage
 --------------------------------------------------
 
 <!-- usage -->
+
 ```
 $ madman
 Commands:
-  render  Render markdown to HTML
-  serve   Run a webserver and serve the markdown file as HTML
+  nav      Add site-wide navigation links to README files
+  preview  Serve a markdown file using a local server
+  render   Render markdown to HTML
+  serve    Serve a markdown folder using a local server
 ```
 
----
+<!-- usage -->
+
+### Render Markdown to File
+
+<!-- render -->
+
+```
+$ madman render
+Usage:
+  madman render FILE [--github --save OUTFILE]
+  madman render (-h|--help|--version)
+```
+
+<!-- render -->
+
+<details><summary>Show full usage</summary>
+<!-- render-help -->
 
 ```
 $ madman render --help
 Render markdown to HTML
 
 Usage:
-  madman render INFILE [OUTFILE] [--rtl --github]
+  madman render FILE [--github --save OUTFILE]
   madman render (-h|--help|--version)
 
 Options:
@@ -68,20 +87,16 @@ Options:
     Render using the GitHub API
     Requires setting the GITHUB_ACCESS_TOKEN environment variable
 
-  --rtl
-    Render text Right to Left
+  --save OUTFILE
+    Save the output to a file
 
   -h --help
     Show this help
 
 Parameters:
-  INFILE
+  FILE
     The input markdown file
 
-  OUTFILE
-    The output HTML file
-    If not provided, the input filename will be used with .html extension
-
 Environment Variables:
   GITHUB_ACCESS_TOKEN
     Your GitHub API access token
@@ -90,26 +105,93 @@ Environment Variables:
 Examples:
   madman render README.md
   madman render README.md --github
-  madman render README.md out.html --rtl
+  madman render README.md --save out.html
 ```
 
----
+<!-- render-help -->
+</details>
+
+### Preview Markdown in Browser
+
+<!-- preview -->
 
 ```
-$ madman serve --help
-Run a webserver and serve the markdown file as HTML
+$ madman preview
+Usage:
+  madman preview FILE [--port N --bind ADDRESS]
+  madman preview (-h|--help|--version)
+```
+
+<!-- preview -->
+
+<details><summary>Show full usage</summary><!-- preview-help -->
+
+```
+$ madman preview --help
+Serve a markdown file using a local server
 
 This command will start a local server with two endpoints:
   /         will render the markdown with the default renderer
   /github   will render with the GitHub API
 
 Usage:
-  madman serve INFILE [--port N --bind ADDRESS --rtl]
+  madman preview FILE [--port N --bind ADDRESS]
+  madman preview (-h|--help|--version)
+
+Options:
+  -p --port N
+    Set server port [default: 3000]
+
+  -b --bind ADDRESS
+    Set server listen address [default: 0.0.0.0]
+
+  -h --help
+    Show this help
+
+Parameters:
+  FILE
+    The input markdown file
+
+Environment Variables:
+  GITHUB_ACCESS_TOKEN
+    Your GitHub API access token
+    Required only if you wish to use the '/github' endpoint
+    Generate one here: https://github.com/settings/tokens
+
+Examples:
+  madman preview README.md
+  madman preview README.md -p4000
+```
+
+<!-- preview-help --></details>
+
+
+### Personal Wiki (Serve a complete Markdown folder)
+
+<!-- serve -->
+
+```
+$ madman serve
+Usage:
+  madman serve FOLDER [--port N --bind ADDRESS --github]
+  madman serve (-h|--help|--version)
+```
+
+<!-- serve -->
+
+<details><summary>Show full usage</summary><!-- serve-help -->
+
+```
+$ madman serve --help
+Serve a markdown folder using a local server
+
+Usage:
+  madman serve FOLDER [--port N --bind ADDRESS --github]
   madman serve (-h|--help|--version)
 
 Options:
-  --rtl
-    Render text Right to Left.
+  --github
+    Use the GitHub API renderer instead of the default one
 
   -p --port N
     Set server port [default: 3000]
@@ -121,8 +203,8 @@ Options:
     Show this help
 
 Parameters:
-  INFILE
-    The input markdown file
+  FOLDER
+    The folder containing markdown files
 
 Environment Variables:
   GITHUB_ACCESS_TOKEN
@@ -131,13 +213,67 @@ Environment Variables:
     Generate one here: https://github.com/settings/tokens
 
 Examples:
-  madman serve README.md
-  madman serve README.md -p4000 --rtl
+  madman serve
+  madman serve path/to/docs -p4000 --github
 ```
 
----
+<!-- serve-help --></details>
 
-<!-- usage -->
 
+### Inject Site Navigation (Table of Contents)
+
+<!-- nav -->
+
+```
+$ madman nav
+Usage:
+  madman nav FOLDER [--marker TEXT --force --dry --verbose --depth N]
+  madman nav (-h|--help|--version)
+```
+
+<!-- nav -->
+
+<details><summary>Show full usage</summary><!-- nav-help -->
+
+```
+$ madman nav --help
+Add site-wide navigation links to README files
+
+This command will add a table of contents to all README files in the folder. The
+table of contents will link to all the pages and folders that are in the same
+folder as each README file.
+
+Usage:
+  madman nav FOLDER [--marker TEXT --force --dry --verbose --depth N]
+  madman nav (-h|--help|--version)
+
+Options:
+  -f --force
+    Add to all README files, even if they do not have a marker
+
+  -m --marker TEXT
+    Look for an HTML comment with <!-- TEXT --> [default: nav]
+
+  -d --depth N
+    The depth of the table of contents [default: 1]
+
+  --dry
+    Do not save the updated files, just show what will happen
+
+  -v --verbose
+    Show the updated README content
+
+  -h --help
+    Show this help
+
+Parameters:
+  FOLDER
+    The folder containing markdown files
+
+Examples:
+  madman nav
+  madman nav path/to/docs --force --marker toc
+  madman nav path/to/docs --dry -v -d2
+```
 
-[1]: https://github.com/DannyBen/madness
+<!-- nav-help --></details>

data/bin/madman-nav.rb

@@ -0,0 +1,48 @@
+require 'madman'
+
+summary "Add site-wide navigation links to README files"
+
+help "This command will add a table of contents to all README files in the folder. The table of contents will link to all the pages and folders that are in the same folder as each README file."
+
+usage "madman nav FOLDER [--marker TEXT --force --dry --verbose --depth N]"
+usage "madman nav (-h|--help|--version)"
+
+option "-f --force", "Add to all README files, even if they do not have a marker"
+option "-m --marker TEXT", "Look for an HTML comment with <!-- TEXT --> [default: nav]"
+option "-d --depth N", "The depth of the table of contents [default: 1]"
+option "--dry", "Do not save the updated files, just show what will happen"
+option "-v --verbose", "Show the updated README content"
+
+param "FOLDER", "The folder containing markdown files"
+
+example "madman nav"
+example "madman nav path/to/docs --force --marker toc"
+example "madman nav path/to/docs --dry -v -d2"
+
+action do |args|
+  dir     = args['FOLDER'] || '.'
+  force   = args['--force']
+  marker  = args['--marker']
+  dry     = args['--dry']
+  verbose = args['--verbose']
+  depth   = args['--depth'].to_i
+
+  candidates = Dir["#{dir}/**/README.md"]
+  candidates.each do |candidate|
+    say "Updating !txtgrn!#{candidate}"
+    candidate_dir = File.dirname candidate
+    toc = Madman::Navigation.new candidate_dir, depth: depth
+    doc = Madman::Document.from_file candidate
+    doc.inject toc.markdown, marker: marker, force: force
+
+    if verbose
+      say word_wrap "  !txtblu!#{doc.text}"
+      say ""
+    end
+
+    doc.save unless dry
+  end
+
+  say dry ? "Done (dry mode, nothing changed)" : "Done"
+end
+

data/bin/madman-preview.rb

@@ -0,0 +1,34 @@
+require 'madman'
+
+summary "Serve a markdown file using a local server"
+
+help "This command will start a local server with two endpoints:\n  /         will render the markdown with the default renderer\n  /github   will render with the GitHub API"
+
+usage "madman preview FILE [--port N --bind ADDRESS]"
+usage "madman preview (-h|--help|--version)"
+
+option "-p --port N", "Set server port [default: 3000]"
+option "-b --bind ADDRESS", "Set server listen address [default: 0.0.0.0]"
+
+param "FILE", "The input markdown file"
+
+environment "GITHUB_ACCESS_TOKEN", "Your GitHub API access token\nRequired only if you wish to use the '/github' endpoint\nGenerate one here: https://github.com/settings/tokens"
+
+example "madman preview README.md"
+example "madman preview README.md -p4000"
+
+action do |args|
+  file = args['FILE']
+  port = args['--port']
+  bind = args['--bind']
+
+  say "Starting server at !undblu!localhost:#{port}!txtrst!"
+  if ENV['GITHUB_ACCESS_TOKEN']
+    say "To view the GitHub API version go to !undblu!localhost:#{port}/github!txtrst!"
+  end
+  say ''
+
+  Madman::PreviewServer.set bind: bind, port: port, file: file
+  Madman::PreviewServer.run!
+end
+

data/bin/madman-render.rb

@@ -2,33 +2,34 @@ require 'madman'
 
 help "Render markdown to HTML"
 
-usage "madman render INFILE [OUTFILE] [--rtl --github]"
+usage "madman render FILE [--github --save OUTFILE]"
 usage "madman render (-h|--help|--version)"
 
 option "--github", "Render using the GitHub API\nRequires setting the GITHUB_ACCESS_TOKEN environment variable"
-option "--rtl", "Render text Right to Left"
+option "--save OUTFILE", "Save the output to a file"
 
-param "INFILE", "The input markdown file"
-param "OUTFILE", "The output HTML file\nIf not provided, the input filename will be used with .html extension"
+param "FILE", "The input markdown file"
 
 environment "GITHUB_ACCESS_TOKEN", "Your GitHub API access token\nGenerate one here: https://github.com/settings/tokens"
 
 example "madman render README.md"
 example "madman render README.md --github"
-example "madman render README.md out.html --rtl"
+example "madman render README.md --save out.html"
 
 action do |args|
-  infile = args['INFILE']
-  outfile = args['OUTFILE'] || "#{infile}.html"
+  infile = args['FILE']
+  outfile = args['--save']
   renderer = args['--github'] ? :github : :default
 
   doc = Madman::Document.from_file infile
-  template = Madman::Template.new :default
   
-  say "Rendering using the #{renderer} renderer"
-  output = template.render doc.render(renderer)
-
-  File.write outfile, output
-  say "Saved !txtgrn!#{outfile}"
+  output = doc.render renderer
+
+  if outfile
+    File.write outfile, output    
+    say "Saved !txtgrn!#{outfile}"
+  else
+    puts output
+  end
 end
 

data/bin/madman-serve.rb

@@ -1,38 +1,32 @@
 require 'madman'
 
-summary "Run a webserver and serve the markdown file as HTML"
+summary "Serve a markdown folder using a local server"
 
-help "This command will start a local server with two endpoints:\n  /         will render the markdown with the default renderer\n  /github   will render with the GitHub API"
-
-usage "madman serve INFILE [--port N --bind ADDRESS --rtl]"
+usage "madman serve FOLDER [--port N --bind ADDRESS --github]"
 usage "madman serve (-h|--help|--version)"
 
-option "--rtl", "Render text Right to Left."
+option "--github", "Use the GitHub API renderer instead of the default one"
 option "-p --port N", "Set server port [default: 3000]"
 option "-b --bind ADDRESS", "Set server listen address [default: 0.0.0.0]"
 
-param "INFILE", "The input markdown file"
+param "FOLDER", "The folder containing markdown files"
 
 environment "GITHUB_ACCESS_TOKEN", "Your GitHub API access token\nRequired only if you wish to use the '/github' endpoint\nGenerate one here: https://github.com/settings/tokens"
 
-example "madman serve README.md"
-example "madman serve README.md -p4000 --rtl"
+example "madman serve"
+example "madman serve path/to/docs -p4000 --github"
 
 action do |args|
-  opts = { 
-    file: args['INFILE'], 
-    port: args['--port'], 
-    bind: args['--bind'],
-    rtl:  args['--rtl']
-  }
-
-  say "Starting server at !undblu!localhost:#{opts[:port]}!txtrst!"
-  if ENV['GITHUB_ACCESS_TOKEN']
-    say "To view the GitHub API version go to !undblu!localhost:#{opts[:port]}/github!txtrst!"
-  end
-  say ''
-
-  Madman::Server.options opts
+  dir = args['FOLDER'] || '.'
+  port = args['--port']
+  bind = args['--bind']
+  renderer = args['--github'] ? :github : :default
+
+  say "Starting server at !undblu!localhost:#{port}!txtrst! using the !txtgrn!#{renderer}!txtrst! renderer\n"
+
+  Madman::Server.set bind: bind, port: port, 
+    dir: dir, renderer: renderer
+    
   Madman::Server.run!
 end
 

data/lib/madman/directory.rb

@@ -0,0 +1,32 @@
+module Madman
+  # Represents a directory with markdown file sand subflders.
+  class Directory
+    attr_reader :dir, :basedir
+
+    def initialize(dir, basedir=nil)
+      @dir = dir
+      @basedir = basedir || dir
+    end
+    
+    def list
+      @list ||= (dirs + files)
+    end
+
+    private
+
+    def files
+      result = Dir["#{dir}/*.md"]
+      result.reject! { |f| File.basename(f) == 'README.md' }
+      result.sort.map { |path| Item.new path, :file, basedir }
+    end
+
+    def dirs
+      result = Dir["#{dir}/*"].select { |f| File.directory? f }
+      result.reject! do |f| 
+        basename = File.basename(f)
+        basename =~ /^[a-z_\-0-9]+$/
+      end
+      result.sort.map { |path| Item.new path, :dir, basedir }
+    end
+  end
+end

data/lib/madman/document.rb

@@ -1,6 +1,9 @@
 module Madman
   class Document
-    attr_reader :text, :filename
+    include Injector
+
+    attr_reader :filename
+    attr_accessor :text
 
     def self.from_file(file)
       new File.read(file), file
@@ -15,8 +18,22 @@ module Madman
       renderers[renderer].render text
     end
 
+    def rtl?
+      detector.direction(text[0..200]) == 'rtl'
+    end
+
+    def save(save_as=nil)
+      save_as ||= filename
+      raise ArgumentError, "No filename provided" unless save_as
+      File.write save_as, text
+    end
+
     private
 
+    def detector
+      @detector ||= StringDirection::Detector.new :dominant
+    end
+
     def renderers
       Renderers.available_renderers
     end

data/lib/madman/injector.rb

@@ -0,0 +1,18 @@
+module Madman
+  module Injector
+    def inject(content, marker:, force: false)
+      marker = "<!-- #{marker} -->"
+      found_markers = text.scan(marker).size
+
+      content = [marker, content, marker].join "\n"
+
+      if found_markers == 0 and force
+        self.text += "\n\n#{content}"
+      elsif found_markers == 1
+        text.gsub! /#{marker}/im, content
+      elsif found_markers == 2
+        text.gsub! /#{marker}.*#{marker}/im, content
+      end
+    end
+  end
+end

data/lib/madman/item.rb

@@ -0,0 +1,32 @@
+module Madman
+  class Item
+    attr_reader :path, :type, :basedir
+
+    def initialize(path, type, basedir)
+      @path, @type, @basedir = path, type, basedir
+    end
+
+    def label
+      @label ||= File.basename(path_without_extension)
+    end
+
+    def href
+      URI.escape(path_without_extension.sub(/^#{basedir}\//, ''))
+    end
+
+    def dir?
+      type == :dir
+    end
+
+    def file?
+      type == :file
+    end
+
+    private
+
+    def path_without_extension
+      @path_without_extension ||= path.sub(/\.md$/, '')
+    end
+  end
+end
+

data/lib/madman/navigation.rb

@@ -0,0 +1,45 @@
+module Madman
+  # Generate a markdown Table of Contents
+  class Navigation
+    attr_reader :dir, :depth
+
+    def initialize(dir='.', depth: 10)
+      @dir, @depth = dir, depth
+    end
+
+    def toc
+      @toc ||= toc!
+    end
+
+    def markdown
+      @markdown ||= markdown!
+    end
+
+    private
+
+    def markdown!
+      result = []
+      toc.each do |item|
+        indent = item[:level] * 4
+        result.push "#{' ' * indent}1. [#{item[:item].label}](#{item[:item].href})"
+      end
+      result.join "\n"
+    end
+
+    def toc!(path=dir, level=0)
+      return [] unless level < depth
+      list = Directory.new(path, dir).list
+
+      result = []
+      list.each do |item|
+        if item.type == :dir
+          result.push level: level, item: item
+          result += toc! item.path, level+1
+        elsif item.type == :file
+          result.push level: level, item: item
+        end
+      end
+      result
+    end
+  end
+end

data/lib/madman/preview_server.rb

@@ -0,0 +1,19 @@
+module Madman
+  class PreviewServer < ServerBase
+    set :public_folder, -> { File.expand_path(File.dirname(settings.file)) }
+
+    before do
+      @doc = Document.from_file settings.file
+      @renderer = :default
+    end
+
+    get '/' do      
+      slim :template
+    end
+
+    get '/github' do
+      @renderer = :github
+      slim :template
+    end
+  end
+end

data/lib/madman/renderers/github.rb

@@ -2,7 +2,7 @@ module Madman
   module Renderers
     class GitHub
       def self.render(text, opts={})
-        self.client.markdown text
+        client.markdown text
       end
 
       private