CONTRIBUTING.md

Contributing

• Guidelines
• Adding new filetypes
• Adding new plugins

By default, the theme aims to stay true to the original One Dark Pro theme ("the original"). Any new functionality, colors or design decisions will always be reconciled back to the original. If you notice any discrepencies, please submit a PR.

Guidelines

The following is a set of guidelines for contributing to this project:

• When highlighting discrepencies between the theme and the original, please include screenshots and your settings in both Neovim and Visual Studio Code
• When adding any new highlight groups (which are not plugin related), please include screenshots for both Neovim and Visual Studio Code
• Format your code using stylua to keep the formatting consistent
• Make sure that the project's stylua.toml file is used for stylua settings
• Run make all prior to submitting a pull request to ensure the tests are passing
• If you're adding functionality, please ensure you have written plenary tests for it

Recommendations

• If you're adding new functionality, please open an issue to discuss the design of the new feature
• Also consider how the end user will consume your new feature. It's often easier to start with the API and work backwards
• Consider the use of conventional commits to make your commit messages more descriptive

Adding new filetypes

Filetype highlights are the feature that allows a colorscheme to get as close to the original as possible, thanks to Treesitter and support for LSP semantic tokens.

When adding new filetypes, they must stay as close to the original Visual Studio Code theme as possible. Even with the inclusion of opinionated styles (such as bolds and italics).

Initial setup

• Firstly, create a code snippet in the language you're adding support for and load it in Visual Studio Code and Neovim
• For the colorscheme, save the snippet in the examples dir. E.g. examples/typescript.ts
• Ensure that the following settings in Visual Studio Code are enabled:

• Ensure that your Neovim version is 0.9+

Adding highlights

• Create the new filetype file in the lua/onedarkpro/highlights/filetypes/ dir
• The filetype should implement the following interface:

local M = {}

---Get the highlight groups for the filetype
---@param theme table
---@return table
function M.groups(theme)
    return {
    -- Add your filetype highlight groups here
    }
end

return M

• Comparing the code snippet in Neovim and Visual Studio Code, you can use the :Inspect command from within Neovim to determine which highlight group is being applied:

• Highlight groups may then be added with the highlight name from the output (with an @ symbol), followed by the filetype:

return {
    ["@property.typescript"] = { fg = theme.palette.red },
}

• The colorscheme enables users to be able to apply styles to match enable a closer match to Visual Studio Code, whilst still enabling the user to apply customisations:

local config = require("onedarkpro.config").config

return {
    ["@method.call.typescript"] = { fg = theme.palette.blue, style = config.styles.methods },
}

• For highlight groups that do not have any styling in Visual Studio Code, you should allow for the user to apply their own custom styles (as per the README)
• This would fallback to style = config.styles.methods for a highlight group such as ["@method.call.typescript]

Final configuration

• To ensure the filetype is loaded by default, go to lua/onedarkpro/config.lua and add the filetype to the filetypes table and set it to true by default:

filetypes = {
    markdown = true,
    python = true,
    -- ...
    typescript = true,
},

Note: The name of the filetype should be its filename without the .lua extension

• Update the README.md file to list the new filetype. Please follow the existing format
• Finally, create a pull request and be sure to include a screenshot of the language in both Visual Studio Code and Neovim (after your modifications)

Adding new plugins

It can be difficult to keep track of all of the amazing new plugins which enter the Neovim ecosystem. To add support for a new plugin in the theme:

• Create the plugin file in lua/onedarkpro/highlights/plugins/
• The plugin should implement the following interface:

local M = {}

---Get the highlight groups for the plugin
---@param theme table
---@return table
function M.groups(theme)
    return {
    -- Add your highlight groups here
    }
end

return M

• Highlight groups can be added like so:

TelescopeSelection = {
    bg = theme.palette.bg,
    fg = theme.palette.purple,
}

See lua/onedarkpro/themes/onedark.lua for the list of available colors in the colorschemes

• To incorporate styles from a user's config:

local config = require("onedarkpro.config").config

return {
    AerialClass = {
        fg = theme.palette.purple,
        style = config.styles.keywords,
    }
}

Reference the editor.lua and syntax.lua files to see how to add highlight groups and styles from a user's config

• To load the plugin by default, go to lua/onedarkpro/config.lua and add the plugin to the plugins table and set it to true by default:

plugins = {
    aerial = true,
    barbar = true,
    -- ...
    my_new_plugin = true,
},

Note: The name of the plugin should be its filename without the .lua extension

• Update the README.md file to include the new plugin; This should include the Default Configuration and Supported Plugins sections
• Finally, create a pull request