BIRD.nvim

Neovim syntax highlighting for BIRD 2 and BIRD 3 configuration files

Version: English | 简体中文

---

Table of Contents

• BIRD.nvim
  • Table of Contents
  • Overview
  • Features
  • Installation
    • Using lazy.nvim
    • Using native packages
  • Updating
  • Filetype Detection
  • Documentation
  • Configuration
    • Disable heuristic detection
    • Custom file extensions
  • Contributing
  • License
  • Related Projects

---

Overview

BIRD.nvim provides Neovim syntax highlighting, filetype detection, and filetype plugin support for BIRD 2 and BIRD 3 configuration files.

This is the Neovim plugin component of the BIRD-tm-language-grammar project by the BIRD Chinese Community.

[!NOTE] This repository was renamed from BIRD2.nvim to reflect support for both BIRD 2 and BIRD 3. GitHub redirects the old URL, while the bird2 filetype, require("bird2"), commands, and configuration keys remain compatible.

---

Features

• :rainbow: Syntax highlighting aligned with current BIRD 2.19 and BIRD 3.3 syntax
• :mag: Automatic filetype detection for .bird, .bird2, .bird3, and .conf files
• :brain: Smart heuristic detection for generic .conf files
• :wrench: Filetype-specific settings (comments, format options, etc.)
• :book: Built-in help documentation accessible via :help bird2

---

Installation

Choose your preferred plugin manager:

Using lazy.nvim

{
  "bird-chinese-community/BIRD.nvim",
  version = "^1.0.14",
  lazy = false,
  config = function()
    require("bird2").setup()
  end,
}

The plugin must load before filetype detection runs; using ft = "bird2" alone creates a detection/loading cycle for BIRD-specific filenames.

Using native packages

Clone the repository into a start package directory; Neovim loads it during startup:

git clone https://github.com/bird-chinese-community/BIRD.nvim \
  ~/.local/share/nvim/site/pack/plugins/start/BIRD.nvim

# Clone the repository
git clone https://github.com/bird-chinese-community/BIRD.nvim.git
cd BIRD.nvim

# Add this directory to your Neovim runtime path

This repository can be used directly as a Neovim package directory.

Every GitHub Release also includes standalone ZIP and tar.gz archives plus SHA256SUMS. Release archives exclude the development-only shared/ submodule and include generated doc/tags. See the release runbook for the verified package contract.

---

Updating

GitHub redirects the former BIRD2.nvim repository URL, so existing checkouts continue to fetch. Update the repository name in your plugin-manager configuration, then refresh it:

" lazy.nvim
:Lazy sync

" packer.nvim
:PackerSync

For an existing native package checkout, rename its directory, update the remote, and then refresh the repository:

If an older vimdoc installation uses the lowercase directory bird2.nvim, substitute that name for BIRD2.nvim in the first command.

mv ~/.local/share/nvim/site/pack/plugins/start/BIRD2.nvim \
  ~/.local/share/nvim/site/pack/plugins/start/BIRD.nvim
git -C ~/.local/share/nvim/site/pack/plugins/start/BIRD.nvim \
  remote set-url origin https://github.com/bird-chinese-community/BIRD.nvim.git
git -C ~/.local/share/nvim/site/pack/plugins/start/BIRD.nvim pull --ff-only

For a manual checkout at another path, the directory name can remain unchanged; update its remote:

git -C /path/to/BIRD2.nvim remote set-url origin \
  https://github.com/bird-chinese-community/BIRD.nvim.git
git -C /path/to/BIRD2.nvim pull --ff-only

The shared/ submodule is only needed when contributing syntax changes; it is not required to use the plugin.

The compatibility API remains unchanged: keep require("bird2"), filetype=bird2, :Bird2, and :checkhealth bird2 in existing configurations.

---

Filetype Detection

• :page_facing_up: Extension: .bird, .bird2, .bird3
• :file_folder: Filename: bird.conf, bird2.conf, bird3.conf, bird6.conf, and explicit bird-*/*.bird*.conf variants
• :open_file_folder: Known paths: configuration files below bird, bird2, or bird3 directories
• :mag: Content: scans the first 200 lines of generic .conf files. Strong BIRD-only constructs are accepted immediately; generic constructs require two independent signals to reduce false positives.

---

Documentation

After installation, view the help documentation:

:help bird2

To regenerate help tags:

:helptags ~/.local/share/nvim/site/doc

See the changelog for release history. Contributors should add a bilingual fragment following the change-fragment guide for user-visible or release-worthy changes.

---

Configuration

No configuration is required. The plugin works out of the box.

Disable heuristic detection

If you want to disable content-based detection for .conf files:

require("bird2").setup({
  heuristic_detect = false,
})

Custom file extensions

To add custom file extensions:

vim.filetype.add({
  extension = {
    myext = "bird2",
  },
})

---

Contributing

Sync Syntax Source

syntax/bird2.vim is stored as a regular file so this repository works when installed standalone.

To sync syntax updates from the initialized shared/bird2.vim (BIRD.vim) submodule:

bash scripts/sync-syntax.sh

Or use an explicit source path:

bash scripts/sync-syntax.sh /path/to/BIRD.vim/syntax/bird2.vim

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

• Plugin files: Mozilla Public License 2.0
• Copyright (c) BIRD Chinese Community (BIRDCC)

---

Related Projects

• :bookmark: BIRD-tm-language-grammar - TextMate grammar for BIRD 2 and BIRD 3
• :star: BIRD.vim - Vim syntax source
• :electric_plug: vscode-bird2 - VS Code extension

---

Maintained with :heart: by the BIRD Chinese Community