mint 0.8.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49d66d53b189d1897ab9938358279f7dc0c4ede1d44926eba5f1b9b6f7d8344b
-  data.tar.gz: '08b1882ec1972dbedd02c87e0e6a4cf1f61ca0a631c7f56bca20b4dfeb1ea36b'
+  metadata.gz: 49ea6b9145cae1e2d818755c3e58b4e4188bfc67a64f4a21920618a49dff5ff8
+  data.tar.gz: f87f2f93b543033c511616c846bf7a29162adced84bca4442702f0e7f1f903ff
 SHA512:
-  metadata.gz: 3acb8ce3fc1856014e0efe3aa94d3720faeb8f677e2f9e3a46c541ecc8bd62f65a187558421ac10acc0599f813a8d161bed142bf44c75b51e6bc8f140351cc7f
-  data.tar.gz: 3851e818c5bad026bfde0302c8fe3184dfe4d79e93ca87479e85590015bb3fd082926fe88f7397144b8fbbb4163ae9e602bbb510bf23da009d20943b334896c2
+  metadata.gz: 4388535cb5372e7ef4448ed7ce10e1cd82a807803656772005e8356fafe7015f9a504c1cd6580f8e701cc36714e9d06fc0e2e46310dddfdd0997714324c2611a
+  data.tar.gz: 02da67bfde18bf22c7639a5b653ebd5e4d4af3da208b54e0e0501c99572f786e537839012302c7c4c529c932f12ba9a84f26215ee9b30921df403b510b5fa47d

data/Gemfile

@@ -1,27 +1,2 @@
 source "https://rubygems.org"
-
-# General
-gem "rubyzip", "~> 3.0", ">= 3.0.1"
-gem "hashie", "~> 5.0"
-gem "nokogiri", "1.15.5"
-
-# Templates
-gem "tilt", "~> 2.6", ">= 2.6.1"
-gem "redcarpet", "~> 3.6", ">= 3.6.1"
-gem "erubis", "~> 2.7"
-gem "haml", "~> 6.3"
-gem "sass-embedded", '~> 1.90'
-
-# Helpers
-gem "activesupport", "~> 8.0", ">= 8.0.2.1"
-
-group :development do
-  gem "pry"
-end
-
-# Testing dependencies
-group :test do
-  gem "rspec", "~> 3.13", ">= 3.13.1"
-  gem "rspec-its", "~> 1.3"
-  gem "colorize", "~> 1.1"
-end
+gemspec

data/README.md

@@ -2,13 +2,30 @@
 
 Transform your plain text documents into beautiful HTML documents with customizable styling and templates.
 
+![Status](https://github.com/davejacobs/mint/actions/workflows/build.yml/badge.svg)
+
+## Why Mint?
+
+- **Focus on writing** – Keep documents as plain text
+- **Beautiful output** – Professional-looking HTML ready for print or web
+- **Digital gardens** – Easily publish linked sets of HTML documents from tools like Obsidian
+- **Version control-friendly** – Text documents work great with Git
+- **Scriptable** – Automate document processing and analysis
+- **Highly customizable** – Create your own templates and styles
+
 ## Installation
 
 ```bash
 gem install mint
 ```
 
-## Quick Start
+## Documentation
+
+- **Complete usage guide:** [TUTORIAL.md](doc/TUTORIAL.md)
+- **Man page:** `man mint`
+- **API documentation:** [RubyDoc](http://www.rubydoc.info/github/davejacobs/mint)
+
+## Get started
 
 Transform a Markdown document into styled HTML:
 
@@ -16,17 +33,19 @@ Transform a Markdown document into styled HTML:
 mint publish Document.md
 ```
 
-This creates `Document.html` in your current directory with beautiful default styling.
+This creates `Document.html` in your current directory with beautiful default styling. The styles
+are inlined by default, so you can send your document to anyone you'd like, and they'll see the
+same thing.
 
 ## Usage
 
-### Basic Commands
+### Basic commands
 
 ```bash
-# Publish a single document
+# Publish a single document with a default template
 mint publish Document.md
 
-# Publish with a template
+# Publish with a non-default template
 mint publish Document.md --template nord
 
 # Publish to a specific directory
@@ -35,57 +54,118 @@ mint publish Document.md --destination public
 # Publish multiple files
 mint publish *.md --destination final-drafts
 
-# Publish a digital garden, with linked navigation
-mint publish content/**/*.md --template garden --destination public
+# Read Markdown content piped from STDIN, limited to a single file; note the `-`
+# as a special filename
+echo "# Document" | mint publish - --output-file Document.html
+
+# Publish multiple files and generate a left-hand navigation panel; use globs
+# to recursively include nested files. By default, nested directories will
+# be preserved, but any common directories for all files (in this case, `content`),
+# will be automatically removed from the output ("autodropped").
+mint publish content/**/*.md --destination public --navigation --navigation-title "Documentation"
+
+# Guess document title (and h1 header) from filename
+mint publish Document.md --file-title
 ```
 
-### Common Options
+### Common options
 
 | Flag | Description |
 |------|-------------|
 | `-t, --template TEMPLATE` | Use a built-in template (combines layout + style) |
-| `-l, --layout LAYOUT` | Specify only the layout |
-| `-s, --style STYLE` | Specify only the style |
+| `-l, --layout LAYOUT` | Specify only the template layout, by name |
+| `-s, --style STYLE` | Specify only the template style, by name |
+| `-m, --style-mode MODE` | How styles are included (inline, external, original) |
 | `-d, --destination DIR` | Output directory |
-| `-o, --output-file FORMAT` | Custom output filename format |
-| `--style-mode MODE` | How styles are included (inline, external, original) |
-| `--style-destination PATH` | Create external stylesheet and link it (sets mode to external) |
-| `-r, --recursive` | Find all Markdown files in any directories specified |
+| `-o, --output-file FORMAT` | Custom output filename, with substitutions available |
+| `--no-autodrop` | Do not automatically drop common parent directories from published files |
+| `--no-preserve-structure` | Flatten all published files into one directory rather than preserving structure |
+| `--file-title` | Extract title from filename and inject into template |
+| `--navigation` | Enable navigation panel showing all files |
+| `--navigation-title TITLE` | Set title for navigation panel |
+| `--navigation-depth N` | Maximum depth to show in navigation after dropping levels (default: 3) |
+| `-v, --verbose` | Show where documents were published |
 
-### Style modes
+### Built-in templates
 
-Mint offers three ways to include styles in your HTML output:
+- `default` – Clean, centered, modern layout
+- `basic` – Clean, minimal styling, focuses on text
+- `nord` – Clean, uses Nord color scheme and sans text
+- `nord-dark` – Dark version of Nord
+- `magazine` – Refined & easy to adapt for publications
 
-- **`inline`** (default) – CSS is embedded directly in the HTML document as `<style>` tags
-- **`external`** – CSS is compiled and saved as separate files, linked with `<link>` tags
-- **`original`** – Links directly to original CSS template files without processing (for live editing)
+### Custom templates
 
-The `original` mode is particularly useful for template development, as it allows you to edit CSS files and see changes immediately without republishing. Only `.css` files are supported in this mode, and `@import` statements in CSS files will be included as additional `<link>` tags.
+It's easy to write a custom template: simply create a directory in `~/.config/mint/templates` or `./mint/templates`
+with the name of your new template. Create a `style.css` file and an optional `layout.html` file (which uses ERB
+to include variables like the document title and body). If you opt not to create a new `layout.html`, the 
+layout from the default template will be used.
 
-### Built-in templates
+Mint layouts are written in ERB-flavored HTML, and stylesheets are written in CSS.
 
-- `default` – Clean, minimal styling
-- `nord` – Clean, uses Nord color scheme
-- `nord-dark` – Dark version of Nord
-- `garden` – For digital gardens; includes navigation
+## Configuration
 
-## Documentation
+Mint can be configured using TOML configuration files that specify defaults for commandline options.
+Configuration options are loaded in the following order (later files override earlier ones):
 
-- **Complete usage guide:** [TUTORIAL.md](doc/TUTORIAL.md)
-- **Man page:** `man mint` (after installation)
-- **API documentation:** [RubyDoc](http://www.rubydoc.info/github/davejacobs/mint)
+1. **Global**: Built-in defaults
+2. **User**: `~/.config/mint/config.toml`  
+3. **Local**: `.mint/config.toml`
+4. **Commandline**: Explicit flags override any other configuration
 
-## Why Mint?
+### Example configuration file
 
-- **Focus on writing** – Keep documents as plain text
-- **Version control friendly** – Text files work great with Git
-- **Scriptable** – Automate document processing
-- **Beautiful output** – Professional-looking HTML ready for print or web
-- **Highly customizable** – Create your own templates and styles
+Create `.mint/config.toml` in your project directory:
+
+```toml
+# Template and styling
+template = "nord"
+
+# File output handling
+destination = "public"
+preserve-structure = true
+output-file = "%{basename}_processed.%{new_extension}"
+style-mode = "external"
+
+# Navigation
+navigation = true
+navigation-title = "My Docs"
+navigation-autodrop = true          # Automatically drop common directory levels (default: true)
+navigation-depth = 3               # Maximum depth after dropping levels (default: 3)
+navigation-drop = 1                # Alternative to autodrop - manually specify levels to drop
+
+# Other options
+file-title = true
+working-dir = "/path/to/source"
+```
+
+### Overriding configuration file settings
 
-## Templates and customization
+For most flags, overriding your configuration file is simple: You can simply
+specify a new value via commandline flags. Boolean flags require a slightly
+different approach, the use of `--no-[option]` flags.
 
-Mint supports layouts written in HAML or ERB and stylesheets can be written in CSS, SCSS, or SASS.
+If you've set `navigation = true` in `config.toml`, you can override that
+at the commandline:
+
+```bash
+mint publish docs.md --no-navigation
+```
+
+Available `--no-` flags:
+- `--no-preserve-structure` - Don't preserve directory structure 
+- `--no-navigation` - Disable navigation panel
+- `--no-file-title` - Don't extract titles from filenames
+
+### Style modes
+
+Mint offers three ways to include styles in your HTML output:
+
+- `inline` (default) – CSS is embedded directly in the HTML document as `<style>` tags
+- `external` – CSS is compiled and saved as separate files, linked with `<link>` tags
+- `original` – Links directly to original CSS template files without processing (for live editing)
+
+The `original` mode is particularly useful for template development, as it allows you to edit CSS files and see changes immediately without republishing. Only `.css` files are supported in this mode, and `@import` statements in CSS files will be included as additional `<link>` tags.
 
 ## Contributing
 

data/bin/mint

@@ -1,87 +1,8 @@
 #!/usr/bin/env ruby
 
-# Add /lib to path to override any local installations of Mint
+# Override any local installations of Mint
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 
 require "mint"
-require "shellwords"
 
-argv, commandline_options, help = 
-  Mint::CommandLine.parse(ARGV).values_at(:argv, :options, :help)
-
-original_command = argv.first
-case (argv.shift || "help").downcase.to_sym
-when :publish
-  # Aruba chokes here, so we use this hack to convince Mint we're
-  # not in a pipeline
-  files = 
-    if $stdin.tty? || ENV["MINT_NO_PIPE"]
-      argv
-    else
-      $stdin.each_line.reduce [] do |list, line|
-        list.concat(Shellwords.split(line))
-      end
-    end
-  Mint::CommandLine.publish!(files, commandline_options)
-when :preview
-  # Preview mode uses live CSS links instead of inline styles
-  Mint.rendering_mode = :preview
-  files = 
-    if $stdin.tty? || ENV["MINT_NO_PIPE"]
-      argv
-    else
-      $stdin.each_line.reduce [] do |list, line|
-        list.concat(Shellwords.split(line))
-      end
-    end
-  Mint::CommandLine.publish!(files, commandline_options)
-when :help
-  Mint::CommandLine.help(help)
-when :install
-  file = argv.shift
-  name = argv.shift
-  scope = commandline_options[:scope] || :local
-  Mint::CommandLine.install(file, name, scope)
-when :uninstall
-  name = argv.shift
-  scope = commandline_options[:scope] || :local
-  Mint::CommandLine.uninstall(name, scope)
-when :templates
-  filter = argv.shift
-  scope = commandline_options[:scope] || :local
-  Mint::CommandLine.templates(filter, scope)
-when :"edit-layout"
-  name = argv.shift
-  scope = commandline_options[:scope] || :local
-  Mint::CommandLine.edit(name, :layout, scope)
-when :"edit-style" 
-  name = argv.shift
-  scope = commandline_options[:scope] || :local
-  Mint::CommandLine.edit(name, :style, scope)
-when :set
-  key = argv.shift
-  value = argv.shift
-  scope = commandline_options[:scope] || :local
-  Mint::CommandLine.set(key, value, scope)
-when :config
-  Mint::CommandLine.config
-else
-  # If no commands were found, search the PATH for commands prefixed
-  # with mint-. If no matching executables are found, we know we've
-  # been passed a set of documents, so parse the commandline options, 
-  # merge them with the config options, and start minting the 
-  # document list.
-  
-  begin
-    if File.executable? "mint-#{original_command}"
-      system "mint-#{original_command} #{argv[1..-1].join ' '}"
-    else
-      $stderr.puts "Error: Unknown command '#{original_command}'"
-      Mint::CommandLine.help(help)
-      exit 1
-    end
-  rescue
-    Mint::CommandLine.help(help)
-    exit 1
-  end
-end
+Mint::Commandline.run!(ARGV)

data/config/templates/base/navigation.css

@@ -0,0 +1,136 @@
+/* Base Navigation Layout - Structural styles only */
+/* Colors, fonts, and borders should be overridden in individual templates */
+
+/* Navigation container positioning and dimensions */
+#navigation {
+  position: fixed;
+  left: 0;
+  top: 0;
+  width: var(--navigation-width);
+  height: 100vh;
+  overflow-y: auto;
+  padding: var(--space-base) 0;
+  z-index: var(--z-navigation);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-weight: 400;
+  background-color: var(--color-nav-bg);
+  border-right: 1px solid var(--color-nav-border);
+}
+
+/* Navigation header */
+#navigation h3 {
+  margin: 0 0 var(--space-sm) 0;
+  padding: 0 var(--space-base);
+  font-size: var(--font-size-sm);
+  font-weight: 600;
+  color: var(--color-nav-text);
+}
+
+/* Navigation list structure */
+#navigation ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+#navigation li {
+  margin: 0;
+}
+
+/* Navigation links layout */
+#navigation a {
+  display: block;
+  padding: var(--space-xs) var(--space-base);
+  text-decoration: none;
+  border-left: 2px solid transparent;
+  border-bottom: none;
+  transition: var(--transition-fast);
+  font-weight: 400;
+  color: var(--color-nav-text);
+  font-size: var(--font-size-sm);
+}
+
+#navigation a:hover {
+  color: var(--color-nav-text-hover);
+  background-color: var(--color-nav-bg-hover);
+  border-left-color: var(--color-nav-border);
+}
+
+#navigation a.current {
+  color: var(--color-nav-text-active);
+  background-color: var(--color-nav-bg-active);
+  border-left-color: var(--color-nav-border-active);
+  font-weight: 500;
+}
+
+/* Directory names (non-clickable) */
+#navigation .directory-name {
+  display: block;
+  padding: var(--space-xs) var(--space-base);
+  font-weight: 600;
+  color: var(--color-nav-text-hover);
+  font-size: var(--font-size-xs);
+}
+
+/* Depth-based indentation */
+#navigation .depth-0 a,
+#navigation .depth-0 .directory-name {
+  padding-left: var(--space-base);
+}
+
+#navigation .depth-1 a,
+#navigation .depth-1 .directory-name {
+  padding-left: calc(var(--space-base) * 2);
+}
+
+#navigation .depth-2 a,
+#navigation .depth-2 .directory-name {
+  padding-left: calc(var(--space-base) * 3);
+}
+
+#navigation .depth-3 a,
+#navigation .depth-3 .directory-name {
+  padding-left: calc(var(--space-base) * 4);
+}
+
+/* Container adjustments when navigation is present */
+body:has(#navigation) #container {
+  margin-left: var(--navigation-width);
+  padding-left: var(--navigation-gap);
+}
+
+/* Fallback for browsers that don't support :has() */
+@supports not selector(:has(#navigation)) {
+  body.has-navigation #container {
+    margin-left: var(--navigation-width);
+    padding-left: var(--navigation-gap);
+  }
+}
+
+/* Responsive navigation */
+@media (max-width: 960px) {
+  #navigation {
+    position: static;
+    width: 100%;
+    height: auto;
+    border-right: none;
+    padding: var(--space-sm) 0;
+  }
+
+  body:has(#navigation) #container,
+  body.has-navigation #container {
+    margin-left: auto;
+  }
+}
+
+/* Hide navigation in print */
+@media print {
+  #navigation {
+    display: none !important;
+  }
+  
+  body:has(#navigation) #container,
+  body.has-navigation #container {
+    margin-left: auto !important;
+  }
+}

data/config/templates/base/print.css

@@ -0,0 +1,152 @@
+/* Print Styles
+ * Shared print styles that all templates inherit
+ * Templates can override specific aspects while maintaining consistency
+ */
+
+@media print {
+  /* Reset font sizes to print-optimized values */
+  :root {
+    --base-font-size: var(--print-font-size);
+    --base-line-height: var(--print-line-height);
+    --base-unit: calc(var(--print-font-size) * var(--print-line-height));
+  }
+
+  /* Force print-friendly colors */
+  body {
+    background-color: white !important;
+    color: #000 !important;
+    font-size: var(--print-font-size) !important;
+    line-height: var(--print-line-height) !important;
+  }
+
+  /* Hide navigation completely */
+  #navigation {
+    display: none !important;
+  }
+
+  /* Reset container for print */
+  #container,
+  body:has(#navigation) #container,
+  body.has-navigation #container {
+    margin: 0 !important;
+    padding: 0 !important;
+    max-width: none !important;
+    background-color: white !important;
+    box-shadow: none !important;
+    border: none !important;
+    border-radius: 0 !important;
+  }
+
+  /* Page break control */
+  h1, h2, h3, h4, h5, h6 {
+    page-break-after: avoid;
+    page-break-inside: avoid;
+    color: #000 !important;
+  }
+
+  /* Keep content together */
+  pre, blockquote, img, table, figure {
+    page-break-inside: avoid;
+  }
+
+  /* Orphans and widows control */
+  p, li, td, th {
+    widows: 3;
+    orphans: 3;
+  }
+
+  /* Links should be readable in print */
+  a {
+    color: #000 !important;
+    text-decoration: underline !important;
+    border-bottom: none !important;
+  }
+
+  /* Show URL after links (optional - can be overridden) */
+  a[href^="http"]:after {
+    content: " (" attr(href) ")";
+    font-size: 0.8em;
+    color: #666;
+  }
+
+  /* Code blocks */
+  code {
+    background-color: #f5f5f5 !important;
+    border: 1px solid #ddd !important;
+    border-radius: 0 !important;
+    color: #000 !important;
+    padding: 0.1em 0.3em !important;
+  }
+
+  pre {
+    background-color: #f8f8f8 !important;
+    border: 1px solid #ddd !important;
+    border-radius: 0 !important;
+    color: #000 !important;
+    white-space: pre-wrap !important;
+    word-wrap: break-word !important;
+  }
+
+  pre code {
+    background-color: transparent !important;
+    border: none !important;
+    padding: 0 !important;
+  }
+
+  /* Tables */
+  table {
+    background-color: white !important;
+    border-collapse: collapse !important;
+    width: 100% !important;
+  }
+
+  th, td {
+    border: 1px solid #000 !important;
+    padding: 0.3em 0.5em !important;
+    color: #000 !important;
+    background-color: transparent !important;
+  }
+
+  th {
+    background-color: #f0f0f0 !important;
+    font-weight: bold !important;
+  }
+
+  /* Blockquotes */
+  blockquote {
+    border-left: 3px solid #000 !important;
+    background-color: transparent !important;
+    color: #333 !important;
+    font-style: italic !important;
+    margin: 1em 0 !important;
+    padding: 0.5em 0 0.5em 1em !important;
+  }
+
+  /* Images */
+  img {
+    max-width: 100% !important;
+    height: auto !important;
+    display: block !important;
+    margin: 0.5em 0 !important;
+  }
+
+  /* Page margins and size */
+  @page {
+    margin: var(--print-margin);
+    size: letter;
+  }
+
+  /* First page special handling */
+  @page :first {
+    margin-top: calc(var(--print-margin) * 1.5);
+  }
+
+  /* Footnotes area if needed */
+  @page {
+    @bottom-right {
+      content: counter(page);
+      font-size: 0.8em;
+      color: #666;
+    }
+  }
+}

data/config/templates/{reset.css → base/reset.css}

@@ -1,4 +1,4 @@
-html, body, div, span, object, iframe,
+html, body, div, span, object, iframe,
 h1, h2, h3, h4, h5, h6, p, blockquote, pre,
 abbr, address, cite, code,
 del, dfn, em, img, ins, kbd, q, samp,