pontil/summary

Build job summaries for GitHub Actions.

See adding a job summary for more details.

Builder API

Summaries should be built using the builder API, which always starts with summary.new().

Use new to start a builder, pipe through element functions, then append or overwrite to the GITHUB_STEP_SUMMARY file:

summary.new()
|> summary.h2("Test Results")
|> summary.raw("<b>All tests passed.</b>")
|> summary.append()

Tables

Tables can be built with new_table followed by header_row, row, or cells. Pass the result directly to the table function:

summary.new()
|> summary.table(
  summary.new_table()
  |> summary.header_row(["Name", "Status"])
  |> summary.row(["Tests", "Passing"])
)
|> summary.append()

For cells that span multiple columns or rows, use cells with explicit cell constructors:

summary.new_table()
|> summary.cells([
  summary.th("Category"),
  summary.th("Result") |> summary.colspan(2),
])
|> summary.cells([
  summary.td("Unit"),
  summary.td("Pass"),
  summary.td("100%"),
])

Direct Construction

It is also possible to build a summary of List(SummaryElement) values and pass it to append.

[H1("Title"), Raw("Some text")]
|> summary.to_string()

Types

SummaryElement

</>

An element in a job summary.

pub type SummaryElement {
  Builder
  Raw(text: String)
  Eol
  H1(text: String)
  H2(text: String)
  H3(text: String)
  H4(text: String)
  H5(text: String)
  H6(text: String)
  CodeBlock(code: String, lang: option.Option(String))
  UnorderedList(items: List(String))
  OrderedList(items: List(String))
  Table(rows: List(List(TableCell)))
  Details(label: String, content: String)
  Image(
    src: String,
    alt: String,
    width: option.Option(String),
    height: option.Option(String),
  )
  Separator
  Break
  Quote(text: String, cite: option.Option(String))
  Link(text: String, href: String)
}

Constructors

```
Builder
```
Sentinel marking a builder-constructed list. Do not use for manual summary construction.
```
Raw(text: String)
```
Raw text.
```
Eol
```
A newline.
```
H1(text: String)
```
A level 1 heading.
```
H2(text: String)
```
A level 2 heading.
```
H3(text: String)
```
A level 3 heading.
```
H4(text: String)
```
A level 4 heading.
```
H5(text: String)
```
A level 5 heading.
```
H6(text: String)
```
A level 6 heading.

CodeBlock(code: String, lang: option.Option(String))

A code block with optional language.

```
UnorderedList(items: List(String))
```
An unordered list.
```
OrderedList(items: List(String))
```
An ordered list.
```
Table(rows: List(List(TableCell)))
```
A table.
```
Details(label: String, content: String)
```
A collapsible details element.

Image(
  src: String,
  alt: String,
  width: option.Option(String),
  height: option.Option(String),
)

An image.

```
Separator
```
A thematic break.
```
Break
```
A line break.

Quote(text: String, cite: option.Option(String))

A blockquote.

```
Link(text: String, href: String)
```
A link.

TableBuilder

opaque </>

A Table builder for internal use only.

pub opaque type TableBuilder

TableCell

opaque </>

A cell in a summary table. It is recommended that cells be created with the td and th functions and modified with the colspan or rowspan functions.

summary.th("Name")
summary.td("Value") |> summary.colspan(2)
summary.td_span("Big", colspan: 2, rowspan: 3)

pub opaque type TableCell

Values

append

</>

pub fn append(
  elements: List(SummaryElement),
) -> Result(Nil, command.PontilCoreError)

Appends summary elements to the GITHUB_STEP_SUMMARY file. Works with both builder pipelines and direct element lists.

break

</>

pub fn break(
  elements: List(SummaryElement),
) -> List(SummaryElement)

Adds a line break (<br>).

cells

</>

pub fn cells(
  table builder: TableBuilder,
  row row_cells: List(TableCell),
) -> TableBuilder

Adds a row of explicit cells. Use this when you need mixed header/data cells or cells with spans:

summary.new_table()
|> summary.cells([
  summary.th("Category"),
  summary.th("Result") |> summary.colspan(2),
])
|> summary.cells([
  summary.td("Unit"),
  summary.td("Pass"),
  summary.td("100%"),
])

clear

</>

pub fn clear() -> Result(Nil, command.PontilCoreError)

Clears the summary file.

code_block

</>

pub fn code_block(
  summary elements: List(SummaryElement),
  code code: String,
) -> List(SummaryElement)

Adds a code block.

code_block_with_lang

</>

pub fn code_block_with_lang(
  summary elements: List(SummaryElement),
  code code: String,
  lang lang: String,
) -> List(SummaryElement)

Adds a code block with a language annotation.

summary.new()
|> summary.code_block_with_lang("let x = 1", "gleam")

colspan

</>

pub fn colspan(cell cell: TableCell, span span: Int) -> TableCell

Sets the colspan on a cell.

summary.td("Wide") |> summary.colspan(3)

details

</>

pub fn details(
  summary elements: List(SummaryElement),
  label label: String,
  content content: String,
) -> List(SummaryElement)

Adds a collapsible details element.

summary.new()
|> summary.details("Click to expand", "Hidden content here")

eol

</>

pub fn eol(
  elements: List(SummaryElement),
) -> List(SummaryElement)

Adds a newline.

h1

</>

pub fn h1(
  summary elements: List(SummaryElement),
  text text: String,
) -> List(SummaryElement)

Adds a level 1 heading.

h2

</>

pub fn h2(
  summary elements: List(SummaryElement),
  text text: String,
) -> List(SummaryElement)

Adds a level 2 heading.

h3

</>

pub fn h3(
  summary elements: List(SummaryElement),
  text text: String,
) -> List(SummaryElement)

Adds a level 3 heading.

h4

</>

pub fn h4(
  summary elements: List(SummaryElement),
  text text: String,
) -> List(SummaryElement)

Adds a level 4 heading.

h5

</>

pub fn h5(
  summary elements: List(SummaryElement),
  text text: String,
) -> List(SummaryElement)

Adds a level 5 heading.

h6

</>

pub fn h6(
  summary elements: List(SummaryElement),
  text text: String,
) -> List(SummaryElement)

Adds a level 6 heading.

header_row

</>

pub fn header_row(
  table builder: TableBuilder,
  row headers: List(String),
) -> TableBuilder

Adds a row of header cells from strings.

summary.new_table()
|> summary.header_row(["Name", "Status", "Count"])

image

</>

pub fn image(
  summary elements: List(SummaryElement),
  src src: String,
  alt alt: String,
) -> List(SummaryElement)

Adds an image.

image_with_size

</>

pub fn image_with_size(
  summary elements: List(SummaryElement),
  src src: String,
  alt alt: String,
  width width: String,
  height height: String,
) -> List(SummaryElement)

Adds an image with width and height.

link

</>

pub fn link(
  summary elements: List(SummaryElement),
  text text: String,
  href href: String,
) -> List(SummaryElement)

Adds a link.

new

</>

pub fn new() -> List(SummaryElement)

Creates a new summary builder.

new_table

</>

pub fn new_table() -> TableBuilder

Creates a new table builder.

ordered_list

</>

pub fn ordered_list(
  summary elements: List(SummaryElement),
  items items: List(String),
) -> List(SummaryElement)

Adds an ordered list.

overwrite

</>

pub fn overwrite(
  elements: List(SummaryElement),
) -> Result(Nil, command.PontilCoreError)

Writes summary elements to the GITHUB_STEP_SUMMARY file, replacing existing content.

quote

</>

pub fn quote(
  summary elements: List(SummaryElement),
  text text: String,
) -> List(SummaryElement)

Adds a blockquote.

quote_with_cite

</>

pub fn quote_with_cite(
  summary elements: List(SummaryElement),
  text text: String,
  cite cite: String,
) -> List(SummaryElement)

Adds a blockquote with a citation URL.

raw

</>

pub fn raw(
  summary elements: List(SummaryElement),
  body body: String,
) -> List(SummaryElement)

Adds raw text.

row

</>

pub fn row(
  table builder: TableBuilder,
  row data: List(String),
) -> TableBuilder

Adds a row of data cells from strings.

summary.new_table()
|> summary.header_row(["Name", "Value"])
|> summary.row(["Tests", "42"])

rowspan

</>

pub fn rowspan(cell cell: TableCell, span span: Int) -> TableCell

Sets the rowspan on a cell.

summary.th("Tall") |> summary.rowspan(2)

separator

</>

pub fn separator(
  elements: List(SummaryElement),
) -> List(SummaryElement)

Adds a thematic break (<hr>).

table

</>

pub fn table(
  summary elements: List(SummaryElement),
  table builder: TableBuilder,
) -> List(SummaryElement)

Adds a table from a table builder.

summary.new()
|> summary.table(
  summary.new_table()
  |> summary.header_row(["Name", "Status"])
  |> summary.row(["Tests", "Passing"])
)

td

</>

pub fn td(data: String) -> TableCell

Creates a data cell.

td_span

</>

pub fn td_span(
  text data: String,
  colspan colspan: Int,
  rowspan rowspan: Int,
) -> TableCell

Creates a data cell with colspan and rowspan.

th

</>

pub fn th(data: String) -> TableCell

Creates a header cell.

th_span

</>

pub fn th_span(
  text data: String,
  colspan colspan: Int,
  rowspan rowspan: Int,
) -> TableCell

Creates a header cell with colspan and rowspan.

to_string

</>

pub fn to_string(elements: List(SummaryElement)) -> String

Renders a list of summary elements to an HTML string.

unordered_list

</>

pub fn unordered_list(
  summary elements: List(SummaryElement),
  items items: List(String),
) -> List(SummaryElement)

Adds an unordered list.