> For the complete documentation index, see [llms.txt](https://docs.arcticons.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arcticons.com/other-platforms/linux/contribute.md). # Contribute ## Forking the Repository 1. In a web browser, open the [Arcticons-Linux](https://codeberg.org/Arcticons/Arcticons-Linux/) Codeberg repository. 2. You'll need to have a Codeberg account to click the **Fork** button in the top-right corner. You'll get your very own clone of Arcticons-Linux! 3. For simplicity, you probably want to use a Git GUI such as [Desktop Plus](https://desktop-plus.org/) (a fork of GitHub Desktop), [Gittyup](https://murmele.github.io/Gittyup/), or [Gitnuro](https://gitnuro.com/) (all suggestions are open source and cross-platform), though many others should also work. 4. Sync a local version of your fork. Now you have your local Arcticons-Linux project. This means you can add icons and edit `mappings.yaml`. ## Preparing the codebase For generating the icons, you may need to do a `git submodule init` followed by `git submodule update` to pull the Arcticons repo, which will be pulled into the `.arcticons` folder. We are using [uv](https://docs.astral.sh/uv/) for the dependency management of the Python scripts. Run `uv sync --dev` in the Arcticons-Linux repo folder to prepare the environment. ## Contributing your own icons To contribute icons, which don't fit into the Android icon pack, you can place them into the `icons_linux` folder. For matching the Arcticons style, you can follow the Android creation guide here: {% content-ref url="/pages/t9ydcPxkuNLU6GyD0X2v" %} [Creating icons](/contribute/creating-icons.md) {% endcontent-ref %} You need to export the icon with black lines (stroke color `#000`) inside the `icons_linux` folder. ## Mapping the icons Under Linux, there is no single nomenclature for the app names, and so the icons are often needed in multiple places to account for different packaging systems etc. For that, we have a mapping file called `mapping.yaml`, in which the icon names are mapped to different destinations. Here is an example of a mapping: ```yaml browser: - apps/org.gnome.Epiphany - categories/applications-internet - categories/applications-network ``` The `browser` icon is mapped to three destinations. To add a new icon, just add the icon name as a new section and then the destination(s) as a list. You can run `uv run scripts/validate_mapping.py` to validate the mapping file for correct syntax. ### Finding the icons There are multiple locations for icons on Linux, but there is an icon search script which helps to find mappings. Run `uv run scripts/icon_search.py ` to find icons containing the keyword as well as desktop files. This searches the most common places. You can use the parameters `-v` to see from which files the mappings were found, `--no-icons` to only search desktop files and `--no-desktop` to only search icon folders. One way to find them (on KDE), is by opening the properties for the app. * The name should match with the name inside the mappings.yaml file. * The prefix to the name corresponds to the location of the app.
## Generating icons Run `uv run scripts/generate_icons.py -c generate-icons.toml` to generate the icons. ## Necessary information for a PR ### New icons * You can create a PR as soon as you place the new icons inside the `icons_linux` directory. If you don't want to edit the mapping file, you can just give the mapping in the PR description. * You can edit the mapping file to include the mappings just at the bottom of the file. While generating the icons, the mapping file will be sorted automatically. * If you like, you can also generate the icons on your machine to include them in the PR. Be aware that for this to work, you need to have the main Arcticons repo pulled as a submodule; additionally, you need to have [Inkscape](https://inkscape.org/) installed. ### New mappings * If adding the mapping for an icon which doesn't exist yet in the mapping file, adding it to the bottom of the file is perfectly fine, it will be sorted automatically when generating the icons. * If adding a mapping to an icon which is already in the file, you can add the mapping to the list. It will be sorted automatically when generating the icons. ## Uploading to Codeberg Now you'll see a summary of the changes that you've made. 1. Give your commit a small summary to describe the work you did. 2. Press the Current branch button, then create a new branch. Give it a name and press Create. 3. Publish your branch and commit the changes. 4. Create a pull request and you're done! There you go, now all you have to do is wait for it to be merged into the Linux theme. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.arcticons.com/other-platforms/linux/contribute.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.