mint

KO | EN

gitlite — search

#hacktoberfest #react #typescript #golang #android #machine-learning #rust #deep-learning #linux #macos #nodejs #windows #awesome-list #pytorch

(★ 15)

📚 Publish stylish documents and digital gardens from Markdown

mint Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Mint

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?

Mint lets you create and edit your documents in plain text, which has tons of benefits. A few of my favorites:

- Focus on the text, not the style, until you're ready to preview or publish
- Tailor your final design to your heart's content with custom templates
- Store your document history in Git
- Automate document processing and analysis through scripts

Mint also makes it easy to publish cross-linked collections of documents as a single page without a full-blown static site generator.

## Installation

```bash
gem install mint
```

## Documentation

- **Complete usage guide:** [TUTORIAL.md](doc/TUTORIAL.md)
- **Man page:** `man mint`
- **API documentation:** [RubyDoc](http://www.rubydoc.info/gems/mint)

## Get started

Transform a Markdown document into styled HTML:

```bash
mint Document.md
```

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

```bash
# Preview a document in the browser on a local server
mint Document.md --serve

# Preview on a specific port
mint Document.md --serve --serve-port 8080

# Publish a single document with a default template
mint Document.md

# Publish with a non-default template
mint Document.md --template nord

# Publish to the public directory
mint Document.md --destination public

# Publish multiple files, specifying them using a glob pattern
mint *.md --destination final-drafts

# Read Markdown content piped from STDIN and print the resulting HTML and CSS
# to STDOUT; note that this is limited to a single file
echo "# Document" | mint - --output-file -

# Publish multiple files and generate a left-hand navigation panel in the default
# template using a template-specific option. Shell globs allow you to recursively include
# nested files. Note that by default nested directories structure be preserved in the output,
# but any directories common to all files (in this case, `content`), will be automatically removed
# from the output ("autodropped") for convenience.
mint content/**/*.md --destination public --opt navigation --opt navigation-title "Documentation"

# Publish nested files without preserving structure
mint content/**/*.md --destination public --no-preserve-structure
```

### Common options

| Flag | Description |
|------|-------------|
| `--serve` | Publish files and preview them on a local HTTP server |
| `--serve-port PORT` | Port for the local server (default: 4000) |
| `-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, or `-` for STDOUT |
| `--opt OPT[=VAL]` | Specify template-specific options, e.g., --opt navigation for the default template |
| `--no-preserve-structure` | Flatten all published files into one directory rather than preserving structure |
| `--no-autodrop` | Do not automatically drop common parent directories from published files |
| `-v, --verbose` | Show where documents were published |

### Built-in templates

- `default` – Clean layout with serif font
- `nord` – Modern layout with sans-serif font; uses Nord color scheme and sans text
- `nord-dark` – Dark version of Nord

### Custom 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.

Mint layouts are written in ERB-flavored HTML, and stylesheets are written in CSS.

## Configuration

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):

1. **Global**: Built-in defaults
2. **User**: `~/.config/mint/config.toml`  
3. **Local**: `.mint/config.toml`
4. **Commandline**: Explicit flags override any other configuration

### Example configuration file

Create `.mint/config.toml` in your project directory:

```toml
# Template and styling
template = "nord"

# File output handling
destination = "public"
preserve-structure = false
output-file = "%{basename}_processed.%{new_extension}"
style-mode = "external"

[options]                          # These are options for the default layout
navigation = true
navigation-title = "Documents"
navigation-depth = 3               # Maximum depth for items in navigation sidebar
insert-title-heading = true        # Add the document title as an <h1> above document content
```

### Overriding configuration file settings

For most flags, overriding the configuration file is simple: Simply
specify a new value via commandline flags. Boolean flags require a slightly
different approach: use the `--no-[option]` variant of the relevant flag.

For example, if you've set the layout option `preserve-structure = true` in `config.toml`,
you can override that at the commandline:

```bash
mint docs.md --no-preserve-structure
```

You can do the same with layout options via `--opt no-*` variants of your template's
specific options.

### 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 into a single external file in your destination directory and is
  automatically linked from your document with `<link>` tags
- `original` – Links directly to original CSS template files without processing

The `original` mode is particularly useful for template development, as it allows you to edit CSS
files and see changes immediately without republishing. In this mode, `@import` statements in CSS
files will be included as additional `<link>` tags.

## License

MIT License. See [LICENSE](LICENSE) for details.

mint

mint Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

mint

mint Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README