Skip to content

README.md

Latest commit

 

History

History
82 lines (62 loc) · 4.36 KB

README.md

File metadata and controls

82 lines (62 loc) · 4.36 KB
Raw

Contributing themes

The themes/ directory is the official downloadable theme registry. The default classic theme remains embedded in every cac installation and is maintained under crates/cac-render/src/typst/themes/.

Add a theme

  1. Create themes/<theme-name>/theme.typ
  2. Create themes/<theme-name>/preview.jpg with a representative rendered CV
  3. Create themes/<theme-name>/README.md using the manifest information and display the preview directly below the description
  4. Create themes/<theme-name>/theme.json
  5. Add the theme name and description to themes/index.json
  6. Run shasum -a 256 on every downloadable file and record each digest in theme.json
  7. Run cac theme test --shared in the theme-development project, review the fixture PDFs, and run the repository test and lint commands
  8. Open a pull request with the theme, manifest, registry entry, README, preview, and a short description of the design

Theme names use lowercase ASCII letters, numbers, hyphens, and underscores. New shared themes follow the data and styling contract, include an explicit license, provide a README.md and preview image, export theme from theme.typ, and inherit from the bundled base:

#import "/.cac/base.typ" as base

#let theme = base.extend(
  tokens: (...),
  styles: (...),
  page: (...),
  components: (...),
)

The manifest format is:

{
  "name": "example",
  "description": "A short searchable description",
  "author": "Contributor name",
  "author_url": "https://example.com/contributor",
  "license": "MIT",
  "preview": "preview.jpg",
  "files": [
    {
      "path": "theme.typ",
      "sha256": "64 lowercase hexadecimal characters"
    },
    {
      "path": "README.md",
      "sha256": "64 lowercase hexadecimal characters"
    },
    {
      "path": "preview.jpg",
      "sha256": "64 lowercase hexadecimal characters"
    }
  ]
}

author_url is optional and, when provided, must be an HTTP or HTTPS URL. Link the author name to it in the theme README. preview names the image shown in the theme README. Use a repository-relative path inside the theme directory and include that image and README.md in files. Display it with an HTML img element that sets width and height to its intrinsic dimensions. The README must show the manifest's name, description, author, license, and entrypoint without duplicating file checksums.

Files may be placed under the theme directory, including assets/ and fonts/. Absolute paths and parent-directory traversal are rejected. cac verifies every checksum before writing an installed theme.

Test a registry checkout

Point cac at a local registry while developing:

$ CAC_THEME_REGISTRY="file:///path/to/code-a-cv/themes" cac theme search
$ CAC_THEME_REGISTRY="file:///path/to/code-a-cv/themes" cac theme install example --local
$ cac build

After a contribution is merged, users install it from the default GitHub registry without setting the environment variable.

See the shared theme contract for strict acceptance requirements, regression checks, and visual review before publishing.

Shared-theme admission

Registry themes must follow the shared-theme contract: preserve every visible field and source order, handle mixed and optional content through generic fallback, and honor applicable common settings. Keep presentation labels in a theme-owned dictionary and document the language. Literal title comparisons must not select layouts. Installation location is independent of shared-theme suitability.

Theme projects start with the same rich Ada Lovelace sample as cac init. Edit the generated cv.md to choose the content shown in preview.jpg; shared acceptance fixtures are separate.

Start with cac theme init, complete the manifest description, then run cac theme test --shared before cac theme pack. The shared fixture PDFs stay under offering/ and outside the package. Conformance depends on preserving the documented CV data and honoring styling settings, without a version declaration.

CI renders the corpus for every registry theme, including theme-only changes. Review the complete, mixed, long, and settings PDFs for clipping, glyphs, order, page breaks, and readable repeated headers. A passing finite corpus supplements source review.