mint 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70a879d8b2c0b7150b6535b2c2c00c366d3e8484c499c7c0065e76bd5454b768
-  data.tar.gz: a2595df94714597a9937a232115b963c096b6b71acbe373878a700181653adb4
+  metadata.gz: 49ea6b9145cae1e2d818755c3e58b4e4188bfc67a64f4a21920618a49dff5ff8
+  data.tar.gz: f87f2f93b543033c511616c846bf7a29162adced84bca4442702f0e7f1f903ff
 SHA512:
-  metadata.gz: 1ca15ee5ad05556ca6d7aef47d2f74f048a2f2cd7c11fc78931ffd6af7a36417dc65c04dae0661b53a71c9515dcdef09557d7538e0607da161a424061e3049f6
-  data.tar.gz: 4d2b342e58022fde932ad266825bfed9d2b08ba029c0b0469868560a7d87e69383d8c0eab5fa3b28e63630283a33e808cb6319fd4ae9f0bc9734ca93dbea2598
+  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

@@ -1,137 +1,180 @@
-# What is Mint?
+# Mint
 
-Mint transforms your plain text documents into beautiful documents. It makes the process simple but customizable.
+Transform your plain text documents into beautiful HTML documents with customizable styling and templates.
 
-Why would you want to keep all of your documents as plain text?
+![Status](https://github.com/davejacobs/mint/actions/workflows/build.yml/badge.svg)
 
-- To focus on words and structure when you write
-- To control style with a single command, independently of document structure
-- To keep your text and formatting under version control
-- To make your text amenable to scripting--for example, text analysis
+## Why Mint?
 
-What does Mint create from these source files? Beautiful, styled HTML ready to print, e-mail, export, and present.
+- **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
 
-In a few words: *Mint processes words so you don't have to.*
+## Installation
 
-## The mint command
+```bash
+gem install mint
+```
 
-If you have a plain text document formatted in Markdown or Textile or almost any other templating
-language, you're ready to go.
+## Documentation
 
-The easiest Mint command doesn't require configuration. It transforms a document into HTML and links
-it to the default stylesheet, which I've designed for you.
+- **Complete usage guide:** [TUTORIAL.md](doc/TUTORIAL.md)
+- **Man page:** `man mint`
+- **API documentation:** [RubyDoc](http://www.rubydoc.info/github/davejacobs/mint)
 
-Simply type:
+## Get started
 
-    mint publish Document.md
+Transform a Markdown document into styled HTML:
 
-And voilà, Minimalism.html will show up next to Document.md.
+```bash
+mint publish Document.md
+```
 
-Opening Minimalism.html with your favorite web browser--[Firefox is best for typography][Firefox
-typography], but Webkit-based browsers (Chrome, Safari) work, too--will show what looks like a
-word-processed document, complete with big bold headers, italic emphasis, automatically indented
-and numbered lists, and bullets. If you're in a modern browser, you'll even see ligatures and
-proper kerning. The page will be on a white canvas that looks like a page, even though you are in a
-browser.
+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.
 
-Sending that page to a printer is as easy as clicking "Print" from your browser. What comes out of
-your printer will have a 12 pt base font, normal margins, and a not-too-cramped baseline. (Ah the
-wonder of print stylesheets.)
+## Usage
 
-You can throw as many files as you'd like in. Any commandline argument *not* preceded by an option
-(e.g., `--template`) or in the `mint` command vocabulary (more on that in a minute) will be
-interpreted as a file name:
+### Basic commands
 
-    mint publish Document.md Proposal.md
+```bash
+# Publish a single document with a default template
+mint publish Document.md
 
-This command can be tweaked with options and arguments to be more flexible:
+# Publish with a non-default template
+mint publish Document.md --template nord
 
-    mint publish Document.md --template resume                      # specifies a style template
-    mint publish Document.md --style-destination styles             # creates external stylesheet in styles directory
-    mint publish Document.md --style-destination styles/custom.css  # creates external stylesheet at specific path
+# Publish to a specific directory
+mint publish Document.md --destination public
 
-For a listing of mint options, take [a look at the tutorial][tutorial] or the [full API](http://www.rubydoc.info/github/davejacobs/mint).
+# Publish multiple files
+mint publish *.md --destination final-drafts
 
-## A basic Mint document
+# 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
 
-Mint is loaded with smart defaults, so if you don't want to configure something--say, the basic HTML
-skeleton of your document or the output directory--you don't have to. You'll probably be surprised
-at how easy it is to use out of the box, and how configurable it is.
+# 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"
 
-    document = Mint::Document.new("Document.md")
-    document.publish!
+# Guess document title (and h1 header) from filename
+mint publish Document.md --file-title
+```
 
-If you want to customize your document, though--and that's why I built this library--Mint makes that
-easy with explicit parameters:
+### Common options
 
-    # Create a document with external stylesheet
-    document = Mint::Document.new("Document.md", 
-                                  style_destination: "css",
-                                  template: "zen")
-    document.publish!
+| Flag | Description |
+|------|-------------|
+| `-t, --template TEMPLATE` | Use a built-in template (combines layout + 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, 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 |
 
-    # Create with specific layout and style
-    document = Mint::Document.new("Resume.md",
-                                  destination: "output",
-                                  layout: "resume",
-                                  style: "professional")
-    document.publish!
+### Built-in templates
 
-To understand Mint's flexibility, you'll want to [take a look at the API][API].
+- `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
 
-[Firefox typography]: http://opentype.info/blog/2008/06/14/kerning-and-opentype-features-in-firefox-3/ "Firefox 3 supports
-kerning and automatic ligatures"
+### Custom templates
 
-## Templates
+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.
 
-Templates can be written in any format accepted by the Tilt template interface library. (See [the
-Tilt TEMPLATES file][Tilt templates] for more information.)
+Mint layouts are written in ERB-flavored HTML, and stylesheets are written in CSS.
 
-In a template layouts, Ruby calls are sparse but necessary.
+## Configuration
 
-If you're designing a layout, you need to indicate where Mint should place your content. For that
-simple reason, raw HTML files cannot be layouts. Instead, if you want to use HTML templates, you
-should use the ERB format. These files are essentially HTML with the possibility for Ruby calls. You
-can even use the .html extension for your files. Just code the dynamic portion using ERB syntax.
+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):
 
-Inside your template, use the `content` method to place your source's content.
+1. **Global**: Built-in defaults
+2. **User**: `~/.config/mint/config.toml`  
+3. **Local**: `.mint/config.toml`
+4. **Commandline**: Explicit flags override any other configuration
 
-For stylesheets, use the `stylesheet_tag` method, which automatically handles both inline and external stylesheets based on the document's style mode:
+### Example configuration file
 
-So if you're writing your layout using Haml, the template might look like this:
+Create `.mint/config.toml` in your project directory:
 
-    !!! 
-    %html 
-      %head 
-        = stylesheet_tag
-      %body 
-        #container= content
+```toml
+# Template and styling
+template = "nord"
 
-The `stylesheet_tag` method will generate either:
-- `<style>...</style>` tags with inlined CSS for inline mode (default)
-- `<link rel="stylesheet" href="...">` tags for external stylesheets
+# File output handling
+destination = "public"
+preserve-structure = true
+output-file = "%{basename}_processed.%{new_extension}"
+style-mode = "external"
 
-You can create template stylesheets using [CSS][] or [SCSS][].
+# 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
 
-Mint comes preloaded with a few templates to get you started.
+# Other options
+file-title = true
+working-dir = "/path/to/source"
+```
 
-1. Default
-2. Zen
-3. Nord
-4. Nord Dark
+### Overriding configuration file settings
 
-## Plugins: A work in progress
+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.
 
-I've designed the beginnings of a plugin system. With this system, you can implement a callback or
-two and have full control over document creation and sharing. I'll get documentation going soon. For
-now, look to lib/mint/plugins/epub.rb and bin/mint-epub for an example of how to build one. It's not
-complete and I'm open to API suggestions.
+If you've set `navigation = true` in `config.toml`, you can override that
+at the commandline:
 
-This is going to be useful for things like creating actual office documents or e-books or even bound
-novels. I'm actually thinking that half the power of this library is its plugin system.
+```bash
+mint publish docs.md --no-navigation
+```
 
-[tutorial]: http://github.com/davejacobs/mint/tree/master/doc/API.md
-[Tilt templates]: http://github.com/rtomayko/tilt/blob/master/TEMPLATES.md "A listing of all templates supported by Tilt."
-[CSS]: http://en.wikipedia.org/wiki/Cascading_Style_Sheets
-[SASS/SCSS]: http://sass-lang.com/
-[Less]: http://lesscss.org/
+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
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run the tests: `rspec`
+5. Submit a pull request
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

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;
+  }
+}