Files
gitea-custom-theme/README.md
T
2026-10-21 00:12:36 -04:00

133 lines
6.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# scienting theme for git.scient.ing
This repository serves as the custom folder for Gitea.
Clone the repository once on your server and mount it into the container.
To update, use `git pull` and then restart the container.
No Gitea files are overwritten.
If you remove the mount, the default settings are restored.
| Path in the repo | What it does |
| --- | --- |
| `public/assets/css/theme-scienting-auto.css` | follows each visitor's light or dark setting; the default |
| `public/assets/css/theme-scienting-light.css` | the computation pad |
| `public/assets/css/theme-scienting-dark.css` | the greenboard |
| `public/assets/fonts/scienting/` | Atkinson Hyperlegible Next and Mono, self-hosted, with their license |
| `public/assets/img/` | the custom scienting git logo and favicons in place of Gitea's teacup |
| `templates/home.tmpl` | the signed-out home page, in the studio's voice |
| `templates/custom/extra_links_footer.tmpl` | adds a scienting link and the company's legal name, Scientific Computing Studio, LLC, to the footer |
These themes are based on Gitea 28.1.0’s original theme files, with changes only to brand colors, fonts, corner radius, and a faint graph-paper grid behind every page except the home page.
The named colors for status, diffs, and syntax highlighting remain as Gitea originally set them.
All text colors meet WCAG AA standards for contrast with their backgrounds in both themes.
## How it is wired
The server uses the rootless Gitea image, mounting `/opt/gitea/data` to `/var/lib/gitea`.
This means Gitea’s custom folder is located at `/opt/gitea/data/custom` on the host.
The cloned repository is stored at `/opt/gitea/theme` and mounted as read-only over the custom folder.
## First-time setup
Perform these steps on the server as the root user.
Back up your current custom folder.
The mount will hide it, so nothing is lost, but it’s good to keep a copy:
```bash
cp -a /opt/gitea/data/custom /opt/gitea/custom.bak
```
Clone the repository:
```bash
git clone https://git.scient.ing/core/gitea-custom-theme.git /opt/gitea/theme
```
The files need to be readable by UID 1000, which is the default for a standard clone.
Add the following line under `volumes:` for the `server` service in `/opt/gitea/docker-compose.yml`:
```yaml
- /opt/gitea/theme:/var/lib/gitea/custom:ro
```
Merge the contents of `app.ini.scienting` into `/opt/gitea/config/app.ini`.
This sets three main options:
- `APP_NAME = scienting git`, which replaces "Scienting Git" in page titles.
It goes at the top of the file, before any `[section]`.
The brand writes the name lowercase, with the dot.
- `[ui] DEFAULT_THEME = scienting-auto`.
Your `app.ini` has no `THEMES` line, so Gitea offers every theme it finds.
If you add one later, it must list the three scienting themes.
- `[ui.meta]`, the author, description, and keywords search engines see.
Recreate the container to apply the new mount:
```bash
cd /opt/gitea && docker compose up -d
```
## Update
```bash
git -C /opt/gitea/theme pull
docker restart gitea
```
Gitea caches templates in production mode, so you need to restart the container for `.tmpl` changes to take effect.
CSS and images are loaded directly from disk. Restarting the container is safe, and you may need to hard refresh your browser.
## Preview changes locally
Before pushing, you can run a throwaway Gitea on your computer with this repository mounted as its custom folder, the same way the server mounts it.
You need Docker Desktop.
First, set the `image:` line in `preview/compose.yml` to match the one in `/opt/gitea/docker-compose.yml`, so the preview runs the same Gitea version as the server.
```bash
docker compose -f preview/compose.yml up -d
```
Open http://localhost:3000.
The first visit shows Gitea's install page.
Keep SQLite, set the site title to `scienting git`, create an administrator account under "Administrator Account Settings," and click Install.
The preview keeps its data in Docker volumes, so you only do this once.
The preview starts empty, so give it something to show:
- Push any local clone, and Gitea creates the repository: `git push http://localhost:3000/<username>/<repo>.git main`.
- Or use New Migration in the + menu to copy a repository from git.scient.ing with its issues, pull requests, and releases. Private repositories need an access token.
After you edit a file:
- CSS and images: reload the page. Keep the browser's developer tools open with "Disable cache" checked, so it doesn't serve an old copy.
- Templates: run `docker compose -f preview/compose.yml restart`, then reload.
The auto theme follows your system's light or dark setting.
To check the other mode without changing it, open the developer tools, run "Show Rendering" from the command menu (Cmd+Shift+P), and set "Emulate CSS media feature prefers-color-scheme."
Pages worth a look after a change:
- signed out: the home page, the sign-in page, and Explore
- signed in: the dashboard, your profile, and Settings, including Appearance
- in a repository: the file list, a file, the commit list, one commit's diff, the issue list, one issue, and a pull request's Files Changed tab
- Site Administration, and a missing page such as http://localhost:3000/nothing-here
To stop the preview, run `docker compose -f preview/compose.yml down`.
Add `-v` to delete its data and start over.
## License
This repo is released under the MIT License (`LICENSE`). Because the theme files start from Gitea's own CSS, the notice also carries the copyright of The Gitea Authors and The Gogs Authors. Unlike the studio's tools, this repo is not under the Prosperity Public License, and you may use its source under the MIT License.
The fonts in `public/assets/fonts/scienting/` are Atkinson Hyperlegible Next and Mono, copyright 2020-2024 The Atkinson Hyperlegible Mono Project Authors, under the SIL Open Font License 1.1. The license text and copyright notice are in `public/assets/fonts/scienting/OFL.txt`.
## Credits
- [Gitea](https://about.gitea.com/), whose theme files, templates, and variables this builds on.
- [Atkinson Hyperlegible Next and Mono](https://github.com/googlefonts/atkinson-hyperlegible-next-mono), from the Braille Institute and the Atkinson Hyperlegible Project Authors.
## Contributing
We are not accepting external contributions at this time.
We will update this section if that changes.