API Reference¶

This page documents the public Typst functions exported by brilliant-CV. For metadata keys read from metadata.toml, see the Configuration Reference.

Only the root exports documented here are compatibility commitments. Underscore-prefixed helpers and dependency symbols are implementation details. Import Font Awesome icons from fontawesome directly.

Entry Point Functions¶

`cv()`¶

Render a CV document with header, footer, and page layout applied.

Parameter	Type	Default	Description
`metadata`	dictionary	—	The metadata dictionary read from `metadata.toml`.
`doc`	content	—	The body content of the CV (typically the imported modules).
`profile-photo`	image \| none	`none`	The profile photo to display in the header. Defaults to `none`; pass an `image(...)` to render. When `none`, the photo column is hidden regardless of `display_profile_photo`.
`custom-icons`	dictionary	`(:)`	Custom icons to override or extend the default icon set.
`header-info`	auto \| none \| str \| content	`auto`	(optional) customize the contact-information row. `auto` (default) renders `metadata.personal.info`; `none` removes the row; a string or content value replaces it while inheriting the default info typography. Use explicit `text(fill: ...)`, `h-bar()`, and `linebreak()` calls inside custom content for granular styling and layout.

`letter()`¶

Render a cover letter document with header, footer, and page layout applied.

Parameter	Type	Default	Description
`metadata`	dictionary	—	The metadata dictionary read from `metadata.toml`.
`doc`	content	—	The body content of the letter.
`sender-address`	str \| content \| auto	`auto`	The sender's mailing address. Defaults to `auto`, which reads from `metadata.personal.address` (falls back to `"Your Address Here"` if unset). Pass a string or content to override.
`recipient-name`	str	`"Company Name Here"`	The recipient's name or company displayed in the header.
`recipient-address`	str	`"Company Address Here"`	The recipient's mailing address displayed in the header. Supports multiline content.
`date`	str	`datetime.today().display()`	The date displayed in the letter header. Defaults to today's date.
`subject`	str	`"Subject: Hey!"`	The subject line of the letter.
`signature`	str \| content	`""`	(optional) content to display as the signature. Pass `image("signature.png")` for an image; a string is rendered as text.
`address-style`	str	`"smallcaps"`	Address rendering style. `"smallcaps"` (default) or `"normal"`.

CV Components¶

`cv-section()`¶

Add the title of a section.

The visual treatment of the title is driven by [layout.section] in the profile metadata. Three modes are supported:

"first-letters" (default): the first title_highlight_letters grapheme clusters of the title are rendered in the accent color, the rest in black. This is the conventional Latin-script appearance.
"full": the entire title is rendered in the accent color. Use this for CJK / non-Latin scripts where splitting the first N grapheme clusters feels unnatural.
"none": the entire title is rendered in black, no accent highlighting.

Per-section overrides: pass highlight and/or highlight-letters to override the metadata defaults for a single section.

Accepts "first-letters", "full", or "none".

Parameter	Type	Default	Description
`title`	str	—	The title of the section.
`highlight`	str	`none`	(optional) override `[layout.section].title_highlight`.
`highlight-letters`	int	`none`	(optional) override `[layout.section].title_highlight_letters`.
`color`	color	`none`	(optional) override the accent color for this section.
`metadata`	dictionary	`none`	(optional) the metadata read from the TOML file.
`awesome-colors`	dictionary	`_awesome-colors`	(optional) the awesome colors of the CV.

#block(width: 300pt)[
  #cv-section("Professional Experience", metadata: _metadata)
]

`cv-entry()`¶

Add an entry to the CV.

When display_entry_society_first = true is set in metadata.toml, the society field appears bold/first and title appears as the subtitle. When false (the default), the title field is bold/first and society is the subtitle.

Parameter	Type	Default	Description
`title`	str	`"Title"`	The title of the entry (role or position).
`society`	str	`"Society"`	The society of the entry (company, university, etc.).
`date`	str \| content	`"Date"`	The date(s) of the entry.
`location`	str	`"Location"`	The location of the entry.
`description`	str \| array	`""`	The description of the entry. It can be a string or an array of content items.
`logo`	content \| str	`""`	The logo of the society. If empty, no logo will be displayed.
`tags`	array	`()`	The tags of the entry.
`color`	color	`none`	(optional) override the accent color for this entry.
`metadata`	dictionary	`none`	(optional) the metadata read from the TOML file.
`awesome-colors`	dictionary	`_awesome-colors`	(optional) the awesome colors of the CV.

#block(width: 300pt)[
  #cv-entry(
    title: [Data Analyst],
    society: [ABC Company],
    date: [2017 - 2020],
    location: [New York, NY],
    description: list(
      [Analyzed datasets with SQL and Python],
    ),
    tags: ("Python", "SQL"),
    metadata: _metadata,
  )
]

`cv-entry-start()`¶

Add the start of an entry to the CV. Use this together with one or more cv-entry-continued calls to list multiple roles at the same company. The start renders the company name and location, while each continued entry adds a role with its own dates, description, and tags.

Requires display_entry_society_first = true in metadata.toml.

Parameter	Type	Default	Description
`society`	str	`"Society"`	The society of the entry (company, university, etc.).
`location`	str	`"Location"`	The location of the entry.
`logo`	content \| str	`""`	The logo of the society. If empty, no logo will be displayed.
`color`	color	`none`	(optional) override the accent color for this entry.
`metadata`	dictionary	`none`	(optional) the metadata read from the TOML file.
`awesome-colors`	dictionary	`_awesome-colors`	(optional) the awesome colors of the CV.

#block(width: 300pt)[
  #cv-entry-start(
    society: [XYZ Corporation],
    location: [San Francisco, CA],
    metadata: _metadata,
  )
  #cv-entry-continued(
    title: [Data Scientist],
    date: [2017 - 2020],
    description: list(
      [Analyzed large datasets with SQL and Python],
    ),
    metadata: _metadata,
  )
]

`cv-entry-continued()`¶

Add a continued entry to the CV. Must be used after a cv-entry-start call to add an additional role at the same company. Multiple cv-entry-continued calls can follow a single cv-entry-start.

Requires display_entry_society_first = true in metadata.toml.

Parameter	Type	Default	Description
`title`	str	`"Title"`	The title of the entry (role or position).
`date`	str \| content	`"Date"`	The date(s) of the entry.
`description`	str \| array	`""`	The description of the entry. Can be a string or an array of strings.
`tags`	array	`()`	The tags of the entry.
`color`	color	`none`	(optional) override the accent color for this entry.
`metadata`	dictionary	`none`	(optional) the metadata read from the TOML file.
`awesome-colors`	dictionary	`_awesome-colors`	(optional) the awesome colors of the CV.

`cv-skill()`¶

Add a skill to the CV.

Parameter	Type	Default	Description
`type`	str	`"Type"`	The type of the skill. It is displayed on the left side.
`info`	str \| content	`"Info"`	The information about the skill. It is displayed on the right side. Items can be separated by `#h-bar()`.
`type-width`	relative \| fraction \| auto	`17%`	The width of the type column.

#block(width: 300pt)[
  #cv-skill(
    type: [Tech Stack],
    info: [Python #h-bar() SQL #h-bar() Tableau],
  )
]

`cv-skill-with-level()`¶

Add a skill with a level to the CV.

The level is rendered as a row of 5 circles: filled circles for the skill level and empty circles for the remainder (e.g., level 3 shows 3 filled and 2 empty circles).

Parameter	Type	Default	Description
`type`	str	`"Type"`	The type of the skill. It is displayed on the left side.
`level`	int	`3`	The level of the skill (0--5). Rendered as filled/empty circles in the middle column.
`info`	str \| content	`"Info"`	The information about the skill. It is displayed on the right side.
`type-width`	relative \| fraction \| auto	`17%`	The width of the type column.

#block(width: 300pt)[
  #cv-skill-with-level(
    type: [Languages],
    level: 4,
    info: [English #h-bar() French #h-bar() Chinese],
  )
]

`cv-skill-tag()`¶

Add a skill tag to the CV.

Parameter	Type	Default	Description
`skill`	str \| content	—	The skill to be displayed.

#block(width: 300pt)[
  #cv-skill-tag([AWS Certified])
  #cv-skill-tag([Python])
]

`cv-honor()`¶

Add a Honor to the CV.

Parameter	Type	Default	Description
`date`	str	`"1990"`	The date of the honor.
`title`	str	`"Title"`	The title of the honor.
`issuer`	str	`""`	The issuer of the honor.
`url`	str	`""`	The URL of the honor.
`location`	str	`""`	The location of the honor.
`color`	color	`none`	(optional) override the accent color for this honor.
`awesome-colors`	dictionary	`_awesome-colors`	(optional) The awesome colors of the CV.
`metadata`	dictionary	`none`	(optional) The metadata read from the TOML file.

#block(width: 300pt)[
  #cv-honor(
    date: [2022],
    title: [AWS Certified Security],
    issuer: [Amazon Web Services],
    location: [Online],
    metadata: _metadata,
  )
]

`cv-publication()`¶

Add the publications to the CV by reading a bib file.

When ref-full is true, all entries in the bib file are displayed. When ref-full is false, only the entries whose keys appear in key-list are included, allowing selective publication lists.

Parameter	Type	Default	Description
`bib`	bibliography	`""`	The `bibliography` object with the path to the bib file.
`key-list`	list	`()`	The list of bib keys to include when `ref-full` is `false`.
`ref-style`	str	`"apa"`	The reference style of the publication list (e.g., `"apa"`).
`ref-full`	bool	`true`	Whether to show all entries (`true`) or only those in `key-list` (`false`).

Utility Functions¶

`h-bar()`¶

Render a compact vertical separator for inline skill or info lists.

[Python #h-bar() SQL #h-bar() Tableau]

`overwrite-fonts()`¶

Overwrite the default fonts when the metadata supplies custom font values.

Each field in [layout.fonts] is independently optional: a profile that only sets regular_fonts keeps the default header_font, and vice versa. A profile with no [layout.fonts] block at all gets pure defaults.

Parameter	Type	Default	Description
`metadata`	dictionary	—	the metadata object
`latin-fonts`	array	—	the default list of latin fonts
`latin-header-font`	string	—	the default header font

#let fonts = overwrite-fonts(
  (layout: (:)),
  ("Source Sans 3",),
  "Roboto",
)
#assert.eq(fonts.header-font, "Roboto")

API Reference¶

Entry Point Functions¶

cv()¶

letter()¶

CV Components¶

cv-section()¶

cv-entry()¶

cv-entry-start()¶

cv-entry-continued()¶

cv-skill()¶

cv-skill-with-level()¶

cv-skill-tag()¶

cv-honor()¶

cv-publication()¶