typst_library/layout/
columns.rs

1use std::num::NonZeroUsize;
2
3use crate::foundations::{Content, elem};
4use crate::layout::{Length, Ratio, Rel};
5
6/// Separates a region into multiple equally sized columns.
7///
8/// The `column` function lets you separate the interior of any container into
9/// multiple columns. It will currently not balance the height of the columns.
10/// Instead, the columns will take up the height of their container or the
11/// remaining height on the page. Support for balanced columns is planned for
12/// the future.
13///
14/// When arranging content across multiple columns, use [`colbreak`]($colbreak)
15/// to explicitly continue in the next column.
16///
17/// # Example
18/// ```example
19/// #columns(2, gutter: 8pt)[
20///   This text is in the
21///   first column.
22///
23///   #colbreak()
24///
25///   This text is in the
26///   second column.
27/// ]
28/// ```
29///
30/// # Page-level columns { #page-level }
31/// If you need to insert columns across your whole document, use the `{page}`
32/// function's [`columns` parameter]($page.columns) instead. This will create
33/// the columns directly at the page-level rather than wrapping all of your
34/// content in a layout container. As a result, things like
35/// [pagebreaks]($pagebreak), [footnotes]($footnote), and [line
36/// numbers]($par.line) will continue to work as expected. For more information,
37/// also read the [relevant part of the page setup
38/// guide]($guides/page-setup/#columns).
39///
40/// # Breaking out of columns { #breaking-out }
41/// To temporarily break out of columns (e.g. for a paper's title), use
42/// parent-scoped floating placement:
43///
44/// ```example:single
45/// #set page(columns: 2, height: 150pt)
46///
47/// #place(
48///   top + center,
49///   scope: "parent",
50///   float: true,
51///   text(1.4em, weight: "bold")[
52///     My document
53///   ],
54/// )
55///
56/// #lorem(40)
57/// ```
58#[elem]
59pub struct ColumnsElem {
60    /// The number of columns.
61    #[positional]
62    #[default(NonZeroUsize::new(2).unwrap())]
63    pub count: NonZeroUsize,
64
65    /// The size of the gutter space between each column.
66    #[default(Ratio::new(0.04).into())]
67    pub gutter: Rel<Length>,
68
69    /// The content that should be layouted into the columns.
70    #[required]
71    pub body: Content,
72}
73
74/// Forces a column break.
75///
76/// The function will behave like a [page break]($pagebreak) when used in a
77/// single column layout or the last column on a page. Otherwise, content after
78/// the column break will be placed in the next column.
79///
80/// # Example
81/// ```example
82/// #set page(columns: 2)
83/// Preliminary findings from our
84/// ongoing research project have
85/// revealed a hitherto unknown
86/// phenomenon of extraordinary
87/// significance.
88///
89/// #colbreak()
90/// Through rigorous experimentation
91/// and analysis, we have discovered
92/// a hitherto uncharacterized process
93/// that defies our current
94/// understanding of the fundamental
95/// laws of nature.
96/// ```
97#[elem(title = "Column Break")]
98pub struct ColbreakElem {
99    /// If `{true}`, the column break is skipped if the current column is
100    /// already empty.
101    #[default(false)]
102    pub weak: bool,
103}
typst_library/layout/columns.rs

typst_library/layout/
columns.rs
