diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..4fdbef2 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,23 @@ +# Each Cloudhal release arrives as one PR bumping every @cloudhal/* package together: the fallback +# for the release PR cloudhal-dev/cloudhal opens here (with its cloudhal/template-check status), +# dependencies only (no theme). A person checks and merges it; merging deploys. +version: 2 +updates: + - package-ecosystem: npm + directory: / + schedule: + interval: daily + time: "06:00" + timezone: Europe/Istanbul + allow: + - dependency-name: "@cloudhal/*" + groups: + cloudhal: + patterns: ["@cloudhal/*"] + # Cloudhal's own releases install on the day they ship. + cooldown: + exclude: ["@cloudhal/*"] + versioning-strategy: increase + open-pull-requests-limit: 2 + commit-message: + prefix: chore diff --git a/README.md b/README.md index ceceb4e..6a2abb1 100644 --- a/README.md +++ b/README.md @@ -34,34 +34,11 @@ In Studio, create a key for each agent and connect them to the MCP server at `ht The [deploy button guide](https://github.com/cloudhal-dev/cloudhal/blob/main/docs/guides/deploy-button.md) covers how the build works and its limits: custom domains need more token permissions, and there is no downgrade check or cache purge between builds. -## Theme reference - -### Routes -- `[...path].astro` — pages at their path, posts at `//`, category and tag archives at `/category/` and `/tag/` (`/page/` for older posts). Anything else follows the site's redirects (301), answers 410 for a retired term, or 404. -- `[...path]/rss.xml.ts` — a feed per category and tag (`/category//rss.xml`). -- `rss.xml.ts`, `sitemap.xml.ts`, `robots.txt.ts` — the site feed, the sitemap (pages, posts and indexable archives) and robots rules. -- `search.json.ts` — the search modal's answers (RFC-0029), where the deployment answers searches (`cloudhal dev`, the Cloudflare Site Worker). `components/SearchDialog.astro` is the modal's markup and words; Cloudhal's `/_cloudhal/search.1.js` wires it, and without it the header form opens `/search`. - -### Styles (`src/styles`) -`global.css` (imported by `layouts/Base.astro`) loads Tailwind, `fonts.css` and one file per feature from `styles/features/` (`tokens.css` with `@theme`, `prose.css`, `surfaces.css`, `motion.css`, `chrome.css`, `carousel.css` …) in cascade order. The rules are unlayered and later files override earlier ones, so keep the order; add a feature as a new file and import it from `global.css`. `source("..")` on the Tailwind import is relative to `global.css`, so that import stays there. +## Staying current -### Theme settings (`src/theme.ts`) -- `ARCHIVE_PAGE_SIZE` — posts per archive page (20). -- `NAV_CATEGORIES` — append top-level categories (by position) to the header after the pages; `false` for a pages-only menu. -- `RELATED_POSTS` — how many related posts to show under an article (0 hides the list). +- **This repository**: every Cloudhal release opens a PR here that moves `@cloudhal/*` to the new version and replaces `src/`, `public/`, `astro.config.mjs` and `tsconfig.json` with that version's blog starter. Its `cloudhal/template-check` status (`npm ci`, then `cloudhal deploy --dry-run` in Workers Builds mode, run by Cloudhal's release workflow) must be green before it is merged, so the button always deploys the latest release. +- **Your copy**: the theme is yours from the moment the copy is made. If the copy has `.github/dependabot.yml`, Dependabot opens a PR for each `@cloudhal/*` release (dependencies only). Nothing checks it in your copy, and merging it deploys: run `npm ci` and `WORKERS_CI=1 npx cloudhal deploy --dry-run` on its branch first. Releases keep older themes working; in 0.x a minor version may break, so read the [release notes](https://github.com/cloudhal-dev/cloudhal/releases) before merging a minor bump. Delete `.github/dependabot.yml` to stop the PRs. -### Blocks (`src/blocks.ts`) -Typed blocks (RFC-0015) go in page sections and inside article and rich-text bodies. Cloudhal ships `callout`, `button`, `embed` and `faq`; this theme adds `testimonial`. -- **Declare** a type in `src/blocks.ts` (`blockTypes`): a plain English name shared by every theme (`pricing-table`, never `mytheme-pricing`), where it may go, its props in the JSON Schema subset, whether it wraps text, and an example. The file is data only, with type imports only (`import type { BlockType }`); the CLI checks every type. -- **Render** it with a component in `theme.ts` → `blocks` (`{ testimonial: Testimonial }`). The component gets `{ props, content, contentHtml, media }`. `contentHtml` is the wrapped text, already rendered safely; props are checked against the type first. A built-in may be listed there too, to restyle it. -- `embed` shows a link card; Cloudhal's small player module turns it into the YouTube (no-cookie) or Vimeo player on click, and the page's CSP allows those two frames only where a video is shown. The page route sets `x-cloudhal-embeds` for that (`usesEmbeds`); keep it if you rewrite the route. -- `cloudhal studio` and `cloudhal mcp` read the file, so Studio's forms and `/` menu and agents (`list_block_types`) offer the type. `cloudhal deploy` checks it and bundles it into the admin Worker. - -### Design settings (`src/settings.ts`) -What Studio's Settings › Appearance, agents (`set_theme_settings`) and the generator may change about the look (RFC-0017): brand, link, background and text colors, the typeface and the corners. The file is data only, in the same JSON Schema subset as block props, with `x-contrast` rules that hold color pairs to WCAG AA and `x-labels` for the choices' words. `layouts/Base.astro` turns the site's values into `--ch-*` CSS variables and `data-ch-*` attributes (`themeVariables`), and the stylesheets in `styles/features/` use them. Add a setting by declaring it here and using its variable or attribute in your CSS. - -### Analytics -Themes need nothing for analytics (RFC-0006). Deployed with `cloudhal deploy`, the Site Worker adds the first-party script tag to published pages while analytics are on (`cloudhal.json` → `analytics`, then per site in Studio). `cloudhal dev` records your own visits only with `"dev": true` in that block, which `astro.config.mjs` passes to the `cloudhal()` integration. Static builds (`cloudhal build`) carry no script. What is collected, and a paragraph for your privacy policy: `docs/guides/analytics-privacy.md` in the Cloudhal repository. +## Theme reference -### Redirects in static builds -A static host cannot be told to answer with a status code by HTML alone. `cloudhal build` therefore writes each redirected path as a small meta-refresh page and also writes `dist/_redirects`, which Cloudflare (Workers/Pages static assets) and Netlify turn into real 301s. Deployed with `cloudhal deploy`, the Site Worker answers redirects itself. +The theme in `src/` is Cloudhal's blog starter, as released with the version in `package.json` when the copy was made. Its reference (routes, styles and fonts, theme settings, blocks, design settings, analytics, redirects in static builds) is the starter's README: [`starters/blog/README.md`](https://github.com/cloudhal-dev/cloudhal/blob/main/starters/blog/README.md) on `main`, or the same file under that version's tag (`https://github.com/cloudhal-dev/cloudhal/tree/v/starters/blog`). diff --git a/package-lock.json b/package-lock.json index 8f78f3f..f316526 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3353,6 +3353,7 @@ "version": "13.0.3", "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-13.0.3.tgz", "integrity": "sha512-RbOBxmLBG8uvFUc15X9+9SFemKcQ0WBuISBVkpuiaUB2qblC8UWlHEjdWVoZ8AdhSwmoEgsiXKfopX0CQxaACQ==", + "hasInstallScript": true, "license": "MIT", "dependencies": { "node-addon-api": "^8.0.0"