{"id":13610088,"url":"https://github.com/mateosss/matter","last_synced_at":"2025-04-12T22:32:46.347Z","repository":{"id":35424643,"uuid":"210710964","full_name":"mateosss/matter","owner":"mateosss","description":"Customizable GRUB theme inspired by Material Design","archived":false,"fork":false,"pushed_at":"2022-07-25T13:23:28.000Z","size":1168,"stargazers_count":864,"open_issues_count":18,"forks_count":50,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2024-08-01T19:54:18.708Z","etag":null,"topics":["google-fonts","grub","grub-themes","hacktoberfest","material-design","material-design-icons"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mateosss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-24T22:49:43.000Z","updated_at":"2024-07-25T14:47:59.000Z","dependencies_parsed_at":"2022-08-08T08:01:11.201Z","dependency_job_id":null,"html_url":"https://github.com/mateosss/matter","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateosss%2Fmatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateosss%2Fmatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateosss%2Fmatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateosss%2Fmatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mateosss","download_url":"https://codeload.github.com/mateosss/matter/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223549113,"owners_count":17163598,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["google-fonts","grub","grub-themes","hacktoberfest","material-design","material-design-icons"],"created_at":"2024-08-01T19:01:41.098Z","updated_at":"2024-11-07T16:30:37.775Z","avatar_url":"https://github.com/mateosss.png","language":"Python","funding_links":[],"categories":["Python","GRUB"],"sub_categories":["VSCode"],"readme":"# Matter\n\nMinimalist grub theme originally inspired by material design 2.\n\n![Matter Gif](.docs/matter.gif)\n\nFeel free to open issues for any problem or request you have and/or submit pull\nrequests.\n\n# Index\n\n- [Matter](#matter)\n- **[Download](#download)**\n- [Usage](#usage)\n  - [Help](#help)\n  - **[Quick Start](#quick-start)**\n  - [Uninstall](#uninstall)\n  - [Fonts](#fonts)\n  - [Colors](#colors)\n  - [Images](#images-unfinished)\n  - [Testing Without Rebooting](#testing-without-rebooting)\n- [What does Matter do to my system\n  files?](#what-does-matter-do-to-my-system-files)\n- [Gallery](#gallery): [1](#example-1), [2](#example-2), [3](#example-3),\n  [4](#example-4), [5](#example-5), [6](#example-6), [7](#example-7),\n  [8](#example-8), [9](#example-9), [10](#example-10), [11](#example-11)\n- [Contributing](#contributing)\n- [Thanks](#thanks)\n\n# Download\n\n[Click here to download Matter](https://github.com/mateosss/matter/releases/latest/download/matter.zip)\n\nIt is **strongly advised** to put the downloaded files in some folder that will\nnot get deleted, as the main script `matter.py` is needed for future grub\nupdates made by your system. Also if you want to uninstall matter you could do\nit from there as well.\n\n## Dependencies\n\nMatter will inform you of any missing dependencies, but here is a list anyways:\n\n- `inkscape` (**Main dependency**): This brings the `convert` command from\n  `imagemagick` with best svg to png conversion.\n- `grub-mkconfig` and `grub-mkfont`: General grub utilities needed. If you\n  don't have these, please create an issue with more information about your\n  system as I've only worked with ones that have these commands.\n- `PIL` (Optional): For image conversions with the `--downloadbackground/-dlbg`\n  option. Can be installed with either of: `pip install Pillow`, `sudo apt\n  install python3-pil` (Ubuntu), `pacman -S python-pillow` (Arch).\n- [`grub2-theme-preview`](https://github.com/hartwork/grub2-theme-preview)\n  (Optional): For testing results (`--test/-t` argument) without rebooting.\n\n# Usage\n\n## Help\n\nYou always can see the command reference with `./matter.py -h`, next up are some\nsections that may be useful, or may not be very well documented in the command's\nhelp.\n\n## Quick Start\n\n\u003cdetails\u003e\n\n\u003csummary\u003eNote for Fedora users (click to show)\u003c/summary\u003e\n\n*Matter does not yet support [The Boot Loader\nSpecification](https://systemd.io/BOOT_LOADER_SPECIFICATION/) so before executing\n`matter.py` you should set `GRUB_ENABLE_BLSCFG=\"false\"` in `/etc/default/grub` and then\nupdate your grub file with `sudo grub2-mkconfig -o /boot/grub2/grub.cfg`*\n\n*See [this issue](https://github.com/mateosss/matter/issues/41) for updates\nor if you want to help out with fedora support*\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eNote for users with screen resolution other than 1920x1080 (click to show)\u003c/summary\u003e\n\n*Matter layout might break in other resolutions with the default installation,\nyou might need to tweak the [`grub.template`](grub.template) `GRUB_GFXMODE`\nproperty and [`theme.txt.template`](theme.txt.template) percentages*\n\n*See [this issue](https://github.com/mateosss/matter/issues/4) for more\ninformation.*\n\n\u003c/details\u003e\n\nFollowing is a Matter installation with default values. Don't worry, it is very\neasy to rollback or overwrite this installation later if you want to.\n\nThe script that does all the work is `matter.py`, so let's start by running it\n\n```sh\n./matter.py\n```\n\nIt outputs almost everything you need to know for later, but for now let's focus\non the list it shows, those are your grub entries. It should look similar to\nthis one:\n\n```sh\n1. Ubuntu\n2. Windows\n3. More Options\n4. Ubuntu, with Linux 5.3.0-61-generic\n5. Ubuntu, with Linux 5.3.0-61-generic (recovery mode)\n6. Ubuntu, with Linux 5.3.0-59-generic\n7. Ubuntu, with Linux 5.3.0-59-generic (recovery mode)\n8. System Setup\n```\n\nNow you should pick some icons from \u003chttps://materialdesignicons.com\u003e for each entry\nlisted (you only need the icon's name, use the search panel and hover over any\nicon you like to see its name). For this example I will pick `ubuntu` for entry\n1, `microsoft-windows` for 2, `folder` for 3 (as it is a submenu in my\nparticular case), and `cog` for 8. I don't care about all the remaining entries\nso I will just use \"`_`\" (underscore) for those.\n\n```sh\n# Installs matter with icons matching the corresponding entries\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ cog\n```\n\n**And thats it!** If you reboot now, you should get something like this:\n\n![Quick Start Result](.docs/quickstartresult.png)\n\n*Tip: If you need to tidy up your grub entries hierarchy and names I recommend\nusing [grub-customizer](https://launchpad.net/grub-customizer)\n([tutorial](https://vitux.com/how-to-install-grub-customizer-on-ubuntu/))*.\n\n## Uninstall\n\nYou can completely remove Matter from your system with `./matter.py -u`\n\n## Fonts\n\nMatter uses `.ttf` fonts and only one, the default, comes prepackaged. You can\nspecify your own fonts by giving a `.ttf` file, the font name, and an optional\nfont size like so:\n\n```sh\n./matter.py -ff ~/fonts/Cinzel/Cinzel-Regular.ttf -fn Cinzel Regular -fs 40\n```\n\n- `--fontfile/-ff`: The `.ttf` path\n- `--fontname/-fn`: The name of the font, in this case `Cinzel Regular` but\n  could be `Open Sans Bold` (*Tip: If you don't know the font name, you can\n  specify any name, go to the grub, press C to open console, and type `lsfonts`\n  to list the font names*)\n- `--fontsize/-fs`: By default it is 32, recommended values are multiples of 4.\n- `--font/-f`: This argument is not used in this example as it is used to select\n  prepackaged fonts. Note that after giving a ttf file to `-ff`, matter will\n  save it as a prepackaged font, so it could be referenced later on with this\n  flag. See prepackaged (available) fonts at the end of `--help/-h` output\n\n*Tip: [Google Fonts](https://fonts.google.com/) is a good place to get fonts*\n\n## Colors\n\nYou can specify the color of 4 elements: `--foreground/-fg`, `--background/-bg`,\n`--iconcolor/-ic` and `--highlight/-hl` (selected text color), there are some\nMaterial Design colors prepackaged that you can see at the end of the\n`--help/-h` output, you can also specify custom colors. Here is an example of\nthe syntax:\n\n```sh\n./matter.py -hl FFC107 -fg white -bg 2196f3 -ic pink\n```\n\n## Images (unfinished)\n\nYou can specify a background image with `--image/-im`, the supported image\nformats/extensions are PNG, JPG, JPEG, and TGA. This feature is considered\n*unfinished* because it does not yet work as well as it could *(see\n[#58](https://github.com/mateosss/matter/issues/58))*\n\nHere is an example of the syntax:\n\n```sh\n./matter.py -im ~/Pictures/some-cool-image-that-has-good-contrast-with-my-text-color.png\n```\n\nYou can also specify an URL with --downloadbackground/-dlbg to automatically download an image from the internet. The image will be converted to png so it doesn't need to be a grub-compatible 8-bit jpg. It should be in the `jpg` or `png` format though. This feature is also considered *unfinished*.\n\n```sh\n./matter.py -dlbg \"https://source.unsplash.com/1920x1080/?nature\"\n```\n\n## Testing Without Rebooting\n\nIf you install the `pip` package\n[`grub2-theme-preview`](https://github.com/hartwork/grub2-theme-preview) you can\ntest combinations of fonts and colors with the `--buildonly/-b` and `--test/-t`\nflags like so:\n\n```sh\n./matter.py -t -b -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl FFC107 -fg white -bg 2196F3 \\\n-ff ~/fonts/MuseoModerno/static/MuseoModerno-Regular.ttf \\\n-fn MuseoModerno Regular -fs 40\n```\n\n*Note: it will use your system's grub.cfg, so set your icons beforehand*.\n\n# What does Matter do to my system files?\n\nBesides the need for the extracted files to be in a persistent location, Matter\nneeds to edit three files:\n\n1. `/etc/default/grub`: For setting theme and resolution.\n2. `/boot/grub/grub.cfg`: For setting icons.\n3. `/usr/sbin/grub-mkconfig`: For making icons persistent across grub updates.\n4. `/etc/grub.d/99_matter`: For making icons persistent across grub upgrades.\n\nAlso it places the theme files in `/boot/grub/themes/Matter/`, this one is\nstandard to grub themes in general.\n\nBoth **(1)** and **(3)** are clearly distinguished with special `BEGIN`/`END`\ncomments at the end of each file. **(2)** Adds a `--class` flag to each entry,\nbut it can be restored as new with `update-grub`. And **(4)** is a custom file.\n\n*All of these modifications are **completely** cleaned up by uninstalling*\n\n# Gallery\n\nHere are some examples with their respective commands that you can copy or get\ninspired from.\n\n## Example 1\n\n![Example 1](.docs/gallery1.gif)\n\n*Font: [Josefin Sans Regular\n400](https://fonts.google.com/specimen/Josefin+Sans)*\n\n```sh\n# Light version, invert -fg and -bg for dark one\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl ef233c -fg 2b2d42 -bg edf2f4 \\\n-ff ~/fonts/Josefin_Sans/static/JosefinSans-Regular.ttf \\\n-fn Josefin Sans Regular -fs 32\n```\n\n## Example 2\n\n![Example 2](.docs/gallery2.png)\n\n*Font: [Comfortaa Medium 500](https://fonts.google.com/specimen/Comfortaa)*\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl white -fg f0f0f0 -bg ff0d7b \\\n-ff ~/fonts/Comfortaa/static/Comfortaa-Medium.ttf \\\n-fn Comfortaa Regular -fs 32\n```\n\n## Example 3\n\n![Example 3](.docs/gallery3.png)\n\n*Font: [Lobster Regular 400](https://fonts.google.com/specimen/Lobster)*\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl 118ab2 -fg ffd166 -bg 073b4c \\\n-ff ~/fonts/Lobster/Lobster-Regular.ttf \\\n-fn Lobster Regular -fs 32\n```\n\n## Example 4\n\n![Example 4](.docs/gallery4.gif)\n\n*Fonts: [Bebas Neue Regular 400](https://fonts.google.com/specimen/Bebas+Neue)\nand [Russo One Regular 400](https://fonts.google.com/specimen/Russo+One)*\n\n```sh\n# Using Bebas Neue font (more compact), the other uses Russo One\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl 2c251b -fg 2c251b -bg ffe70b \\\n-ff ~/fonts/Bebas_Neue/BebasNeue-Regular.ttf \\\n-fn Bebas Neue Regular -fs 36\n# -ff ~/fonts/Russo_One/RussoOne-Regular.ttf \\\n# -fn Russo One Regular -fs 36\n\n```\n\n## Example 5\n\n![Example 5](.docs/gallery5.png)\n\n*Font: [Poiret One Regular 400](https://fonts.google.com/specimen/Poiret+One)*\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl black -fg 101010 -bg fce1e0 \\\n-ff ~/fonts/Poiret_One/PoiretOne-Regular.ttf \\\n-fn Poiret One Regular -fs 48\n```\n\n## Example 6\n\n![Example 6](.docs/gallery6.png)\n\n*Font: [Josefin Sans Medium\n500](https://fonts.google.com/specimen/Josefin+Sans)*\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl ffe78a -fg fdf7f9 -bg 582335 \\\n-ff ~/fonts/Josefin_Sans/static/JosefinSans-Medium.ttf \\\n-fn Josefin Sans Regular -fs 32\n```\n\n## Example 7\n\n![Example 7](.docs/gallery7.png)\n\n*Font: [Josefin Slab Bold 700](https://fonts.google.com/specimen/Josefin+Slab)*\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl A4E11E -fg white -bg 5b1ee1 \\\n-ff ~/fonts/Josefin_Slab/JosefinSlab-Bold.ttf \\\n-fn Josefin Slab Bold -fs 36\n```\n\n## Example 8\n\n![Example 8](.docs/gallery8.png)\n\n*Font: [MuseoModerno Regular\n400](https://fonts.google.com/specimen/MuseoModerno)*\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl FFC107 -fg white -bg 2196F3 \\\n-ff ~/fonts/MuseoModerno/static/MuseoModerno-Regular.ttf \\\n-fn MuseoModerno Regular -fs 32\n```\n\n## Example 9\n\n![Example 9](.docs/gallery9.png)\n\n*Font: [Amatic SC Regular 400](https://fonts.google.com/specimen/Amatic+SC)*\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-bg FFF8E1 -fg 263238 -hl E91E63 \\\n-ff ~/fonts/Amatic_SC/AmaticSC-Regular.ttf \\\n-fn Amatic SC Regular -fs 64\n```\n\n## Example 10\n\n![Example 10](.docs/gallery10.gif)\n\n*Font: [Cinzel Regular 400](https://fonts.google.com/specimen/Cinzel)*\n\n```sh\n# This is the light version, the dark one uses -bg 1a1d21 -fg c9a45b instead\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-hl c28f2c -bg white -fg d0a85c \\\n-ff ~/fonts/Cinzel/Cinzel-Regular.ttf \\\n-fn Cinzel Regular -fs 40\n# -hl c28f2c -bg 1a1d21 -fg c9a45b \\\n```\n\n## Example 11\n\n![Example 11](.docs/gallery11.png)\n\n```sh\n./matter.py -i ubuntu microsoft-windows folder _ _ _ _ _ _ cog \\\n-im ~/images/material-background.png\n```\n\n# Contributing\n\nFeel free to submit any pull request that improves in any way the project.\n\nRead the wiki \u003chttps://github.com/mateosss/matter/wiki\u003e, that's where any useful\ninformation for developers will reside.\n\nIf you think you got a nice result out of Matter and would like to share it,\nplease create an issue with it! I would love to see your results.\n\n# Thanks\n\n- Originally inspired by \u003chttps://github.com/vinceliuice/grub2-themes\u003e\n- Icons from \u003chttps://materialdesignicons.com/\u003e\n- Fonts mainly from \u003chttps://fonts.google.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateosss%2Fmatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmateosss%2Fmatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateosss%2Fmatter/lists"}