- Astro 55.3%
- TypeScript 22.3%
- CSS 12.2%
- Python 3.6%
- JavaScript 2.8%
- Other 3.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
k4wit0
653996ca35
All checks were successful
CI / build (push) Successful in 18s
Astro names a built asset after the URL it came from, not after what is inside it, and the host serves those names with `cache-control: immutable, max-age=1 year`. Documentation images arrive from stable Forgejo raw URLs, so replacing one in the repo left its published URL unchanged — and every reader whose browser had already cached it went on being shown the old picture, for a year, with no way to know. The animation on the bookmarks page was byte-identical on the server and still wrong on screen. The file's git hash now rides along on the URL as `?v=`, taken from the tree listing that is already fetched, so the built name changes whenever the file does. Forgejo ignores the extra parameter. Verified: grid.webp moved from grid_1gXixU.webp to grid_CQYQF.webp on the next build. |
||
| .forgejo/workflows | ||
| public | ||
| scripts | ||
| src | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| astro.config.mjs | ||
| bun.lock | ||
| Caddyfile | ||
| CHANGELOG.md | ||
| Dockerfile | ||
| LICENSE | ||
| NOTICE | ||
| package.json | ||
| README.md | ||
| THIRD-PARTY-LICENSES.md | ||
| tsconfig.json | ||
codigosh-web
Official website for CodigoSH — a free-software collective building self-hosted, private tools. The site showcases the organization's projects hosted on Forgejo and their documentation, with a strong focus on SEO and performance.
Stack
- Astro (static output) — content-first, zero JS by default.
- Tailwind CSS v4 + the CodigoSH design system (
src/styles/theme.css). - Starlight for the documentation served at
/docs/. - English only — a single locale with no URL prefix. Shared chrome copy
(nav, buttons, labels) is centralized in
src/i18n/ui.ts. - Forgejo API integration at build time (
src/lib/forgejo.ts). - Self-hosted as a static site served by Caddy.
Development
Requires Bun (≥ 1.3).
bun install
bun run dev # local dev server
bun run sync-docs # pull project docs from Forgejo into the docs collection
bun run build # sync-docs + production build -> dist/
bun run preview # preview the build
bun run check # astro type/content check
The CodigoSH Forgejo instance allows anonymous API reads, so no token is required. If the API is unreachable the build falls back to bundled mock projects, so it always builds offline.
Configuration
Copy .env.example to .env and fill in as needed. See that file for the full
list. The most relevant variables:
| Variable | Purpose |
|---|---|
SITE_URL |
Canonical URL (canonical tags, sitemap, OG). |
FORGEJO_URL |
Forgejo instance base URL. |
FORGEJO_ORG |
Organization whose repos are listed. |
FORGEJO_TOPIC |
Curated topic; only repos with it are shown. |
FORGEJO_TOKEN |
Read-only API token (public repos). |
FORGEJO_MOCK |
Force mock data (1/true). |
Projects on the site
Projects are pulled at build time from Forgejo. Only repositories tagged with
the showcase topic appear. Each one gets a landing page at /projects/<slug>/,
built from the repo metadata plus an entry in the projects content collection
(src/content/projects/) that holds the long-form copy and screenshots.
Documentation
Docs are not written in this repo. bun run sync-docs (which bun run build
runs first) downloads the docs/ folder of every showcase project from the
Forgejo API into src/content/docs/docs/<project>/, and generates
src/generated/docs-sidebar.json for the Starlight sidebar. Both are generated
and git-ignored — edit the docs in the project's own repository. The only
hand-written page here is the docs landing, src/content/docs/docs/index.md.
The sync is non-fatal: if the API is unreachable it logs and continues, and
FORGEJO_MOCK=1 skips it entirely (used by CI and offline builds).
Deployment
The included Dockerfile builds the static site with Bun and serves dist/
with Caddy on port 80. Set the build variables above and point the
application's domain at the container.
The Caddyfile serves clean URLs and answers an unknown path with a real 404
(a static host that falls back to the 404 page with a 200 gets its dead URLs
indexed). It also sets the security headers — HSTS, CSP, nosniff, referrer and
framing policy — and caches in tiers: content-hashed assets under /_astro/ are
immutable for a year, assets on stable paths last a day, and HTML stays at five
minutes so a rebuild goes live quickly.
Because the docs are fetched at build time, republishing them is just a rebuild:
a push to main here — or to a project repo whose docs/ changed — triggers the
deploy webhook and the site comes back up with the new content.
.forgejo/workflows/ci.yml type-checks and builds every push to main with mock
data; release.yml publishes a release when a v* tag is pushed.
License & credits
CodigoSH web is released under the Apache License 2.0 — see LICENSE.
It self-hosts the Inter, Space Grotesk and JetBrains Mono fonts, each
under the SIL Open Font License 1.1. Full third-party notices live in
NOTICE and THIRD-PARTY-LICENSES.md.