Initial commit

README.md

@@ -0,0 +1,105 @@
+# ricehub
+
+A collection of color themes for your digital environment. Each theme gets a
+card on the overview page, and a page of its own with the full palette and
+links to ready-made configs for your favorite themed programs.
+
+The site is generated from plain JSON files by a single Python script. There is
+no framework, no dependencies and no JavaScript build step.
+
+## Quick start
+
+Requires Python 3.8 or newer.
+
+```sh
+python build.py
+```
+
+Options (with default values):
+
+```sh
+python build.py --themes ./themes --assets ./assets --out ./dist
+```
+
+## Output
+
+```
+dist/
+├── index.html
+├── style.css
+├── script.js
+├── logo.svg
+├── theme1/
+│   └── index.html
+└── theme2/
+    └── index.html
+```
+
+Every `themes/<name>.json` becomes `dist/<name>/index.html`
+
+The generator overwrites files but never deletes any. If you remove or rename a
+theme, delete `dist/` before rebuilding.
+
+## Adding a theme
+
+1. Copy `themes/_template.json` to `themes/<name>.json`.
+2. Fill in the values.
+3. Run `python build.py`.
+
+Files in `themes/` whose names start with `_` are ignored.
+
+### Theme file format
+
+```json
+{
+  "name": "Nord",
+  "description": "An arctic, north-bluish color palette.",
+  "site": "https://www.nordtheme.com",
+
+  "palette": {
+    "nord0 · Polar Night": "#2E3440",
+    "nord1": "#3B4252"
+  },
+
+  "configs": {
+    "Vim": "https://github.com/nordtheme/vim",
+    "Alacritty": "https://github.com/nordtheme/alacritty"
+  },
+
+  "colors": {
+    "background": "#2E3440",
+    "foreground": "#D8DEE9",
+    "surface": "#3B4252",
+    "accent": "#88C0D0",
+    "muted": "#4C566A"
+  },
+  "syntax": ["#81A1C1", "#88C0D0", "#A3BE8C", "#B48EAD", "#616E88"]
+}
+```
+
+| Key | Required | Description |
+| --- | --- | --- |
+| `name` | yes | Display name. Themes are listed alphabetically by name. |
+| `description` | yes | A short description of the color theme. Shown on the card and on the theme page. |
+| `site` | yes | Link to the theme's project site. Must start with `http://` or `https://`. |
+| `palette` | yes | Color name → hex code (`#RRGGBB`). Shown in the order written. |
+| `configs` | no | Program name → link, shown as a list on the theme page. |
+| `colors` | no | Colors used to style the card and theme page: `background`, `foreground`, `surface`, `accent`, `muted`. All of these are optional. |
+| `syntax` | no | Colors for the code snippet on the card, in the order keyword, function, string, number, comment. The comment color may be left out and then falls back to `muted`. |
+
+If `colors` or `syntax` are missing, the script guesses from the palette. The
+darkest color becomes the background, the lightest the text color and the most
+saturated the accent. This works for most dark themes, but light themes or
+unusual palettes usually look better with explicit values.
+
+## Deploying
+
+`dist/` is plain static files, so you can just serve it directly.
+
+## License
+
+The generator and the site code are licensed under the
+[GNU General Public License v3.0](COPYING)
+
+The theme names and palettes belong to their respective projects and stay under
+their own licenses.