Emoji-Free Zone

A simple linter that checks your markdown files for the presence of emojis.

Can be used as a CLI, as part of your CI/CD, or as a GitHub Action.

Features

• Config file support - Use .emoji-lint.json for project-specific settings
• Emoji allowlist - Permit specific emojis like checkmarks or warnings while banning others
• Custom file extensions - Lint .txt, .rst, or any other file types
• Severity levels - Use warning mode to report without failing CI
• Auto-fix mode - Replace emojis with text equivalents or remove them entirely
• Respects .gitignore - Automatically skips files and directories in your .gitignore (enabled by default)
• Inline disable directives - Exempt specific sections with <!-- disable-emoji-lint --> comments
• GitHub Actions integration - Available as a marketplace action with PR annotations
• JSON output - Machine-readable output for CI integration
• AI-powered fixes - Optional agent plugin for context-aware replacements
• Zero dependencies - Just Node.js 18+

Installation

Option 1: GitHub Action (Recommended)

# .github/workflows/emoji-lint.yml
name: Emoji-Free Zone

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hesreallyhim/emoji-free-zone@v1
        with:
          verbose: true

Option 2: Copy the script

Copy lint-emoji.js to your project (e.g., ./scripts/lint-emoji.js).

Option 3: npm install (if published)

npm install --save-dev emoji-free-zone

Usage

Command Line

# Lint current directory
node lint-emoji.js

# Lint specific directory
node lint-emoji.js ./docs

# Verbose output (shows context)
node lint-emoji.js -v

# Ignore .gitignore patterns
node lint-emoji.js --no-gitignore

# Allow specific emojis
node lint-emoji.js --allow=✅ --allow=⚠️

# Lint additional file types
node lint-emoji.js --ext=.txt --ext=.rst

# Report only (don't fail CI)
node lint-emoji.js --severity=warning

# Auto-fix: replace emojis with [name]
node lint-emoji.js --fix

# Auto-fix: remove emojis entirely
node lint-emoji.js --fix=remove

# Preview fixes without changing files
node lint-emoji.js --dry-run

# JSON output for CI integration
node lint-emoji.js --json

# Show help
node lint-emoji.js --help

npm script

Add to your package.json:

{
  "scripts": {
    "lint:emoji": "node ./scripts/lint-emoji.js -v"
  }
}

Then run:

npm run lint:emoji

Configuration

Create a .emoji-lint.json file in your project root to configure default settings:

{
  "severity": "error",
  "allowlist": ["✅", "⚠️", "❌"],
  "extensions": [".md", ".mdx", ".txt"],
  "exclude": ["**/drafts/**", "**/samples/**"],
  "verbose": false,
  "gitignore": true,
  "fixMode": "text"
}

Config Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | severity | "error" | "warning" | "error" | Exit code behavior. "warning" reports violations but exits 0 | | allowlist | string[] | [] | Emojis to permit (e.g., ["✅", "⚠️"]) | | extensions | string[] | [".md", ".mdx", ".markdown"] | File extensions to lint | | exclude | string[] | [] | Glob patterns to skip (paths are resolved relative to the config file's directory) | | verbose | boolean | false | Show detailed output with context | | gitignore | boolean | true | Respect .gitignore patterns | | fixMode | "text" | "remove" | "text" | How --fix handles emojis |

Config File Locations

The linter searches for config files in this order:

1. .emoji-lint.json
2. .emojilintrc
3. .emojilintrc.json
4. emoji-lint.config.json

Notes:

• Exclude patterns in a config file are resolved relative to the config file's directory.
• You can point the Action/CLI at a specific config with --config <path> or the Action config-file input.
• For GitHub Actions, config-file is resolved relative to the repository root (e.g., config-file: packages/emoji-free-zone/.emoji-lint.json).

CLI options always override config file settings.

Inline Directives

You can disable emoji linting for specific sections of your markdown files:

# My Document

This emoji will be caught: 🚀

<!-- disable-emoji-lint -->

This section is exempt from linting.
Feel free to use emojis here: 🎉 🔥 💯

This is useful for:
- Documentation about emojis and emoji-related linguistic crimes
- Examples and tutorials about how *not* to write
- Documentation that's written for babies

<!-- enable-emoji-lint -->

Back to normal - this emoji will be caught: 👍

GitHub Action

Inputs

| Input | Description | Default | |-------|-------------|---------| | directory | Directory to scan | . | | verbose | Enable verbose output | false | | use-gitignore | Respect .gitignore patterns | true | | fail-on-emoji | Fail workflow if emojis found | true | | config-file | Path to config file (relative to repo root) | "" |

Outputs

| Output | Description | |--------|-------------| | has-emoji | Whether emojis were found (true/false) | | emoji-count | Total number of emojis found | | file-count | Number of files with violations |

Example with all options

- uses: hesreallyhim/emoji-free-zone@v1
  id: emoji-lint
  with:
    directory: './docs'
    verbose: true
    use-gitignore: true
    fail-on-emoji: true
    config-file: packages/emoji-free-zone/.emoji-lint.json

- name: Check results
  if: always()
  run: |
    echo "Found emojis: ${{ steps.emoji-lint.outputs.has-emoji }}"
    echo "Emoji count: ${{ steps.emoji-lint.outputs.emoji-count }}"

PR Annotations

When emojis are found, the action creates annotations that appear directly on the PR diff:

::error file=README.md,line=5,col=25::Found emoji: "rocket"

.gitignore Support

The linter automatically respects your .gitignore file. This means:

• Files in node_modules/, dist/, etc. are automatically skipped
• You can add patterns to exclude specific markdown files
• Use --no-gitignore to disable this behavior

If no .gitignore is found, these defaults are used:

• node_modules, vendor, dist, build, coverage
• .next, .nuxt, __pycache__, .venv, venv, env

What It Checks

By default, the linter scans .md, .mdx, and .markdown files. Use --ext or the extensions config option to add more file types.

The linter detects:

• Standard emoji (😀 🎉 🚀 etc.)
• Symbol emoji (⭐ ❤️ ⚡ etc.)
• Flag emoji (🇺🇸 🇬🇧 etc.)
• Skin tone modifiers
• ZWJ sequences (👨‍💻 etc.)

Automatically Skipped

• Fenced code blocks (```)
• Inline code (`code`)
• Content between disable/enable directives
• Common typographic symbols (©, ®, ™, →, etc.)

Example Output

Clean repo:

Emoji-Free Zone Linter
======================

Scanning 12 markdown file(s)...

[PASS] No emojis found! This repo is an emoji-free zone.

Checked 12 file(s) in 23ms

Violations found:

Emoji-Free Zone Linter
======================

Scanning 12 markdown file(s)...

[FAIL] Emoji violations found:

  README.md
    Line 1, Col 25: "rocket emoji"
    Line 3, Col 35: "party emoji"

  docs/guide.md
    Line 15, Col 10: "fire emoji"

--------------------------------------------------

[FAIL] Found 3 emoji(s) in 2 file(s)
  (1 disabled region(s) skipped)
  Checked 12 file(s) in 28ms

This repo is NOT an emoji-free zone! Please remove the emojis.

AI-Powered Fixes (Agent Plugin)

Although the emoji blight is largely powered by AI-generated slop-umentation, they can also be used to help mitigate the damage. For auto-fix functionality that offers context-aware linguistic substitutes for emojis, you can use the emoji-free-zone-agent:

# Install the agent
npm install emoji-free-zone-agent

# Run linter with JSON output, pipe to agent
npx emoji-lint --json . | npx emoji-free-zone-agent --stdin

# Or review interactively
npx emoji-lint --json . | npx emoji-free-zone-agent --stdin --interactive

The agent uses AI (Anthropic, OpenAI, or local Ollama models) to analyze context and suggest meaningful replacements instead of generic [rocket] substitutions.

See emoji-free-zone-agent/README.md for full documentation.

Other CI/CD Systems

See ci-examples.md for integration with:

• GitLab CI
• CircleCI
• Azure Pipelines
• Travis CI
• Husky pre-commit hooks

Exit Codes

• 0 - Success (no emojis found, or --severity=warning mode, or --fix successfully applied)
• 1 - Failure (emojis detected with default --severity=error)

Requirements

• Node.js 18.0.0 or higher

Badges

Add a badge to show your repo is emoji-free:

![Emoji-Free Zone](./badges/emoji-free-zone-light.svg)

See the badges/ directory for light and dark mode variants.

Feedback & Contributing

Sponsorships are welcome!