A logical subdivison of textual content.
\nTypst automatically collects inline-level elements into paragraphs.\nInline-level elements include text, horizontal spacing,\nboxes, and inline equations.
\nTo separate paragraphs, use a blank line (or an explicit parbreak).\nParagraphs are also automatically interrupted by any block-level element\n(like block, place, or anything that shows itself as one of these).
The par element is primarily used in set rules to affect paragraph\nproperties, but it can also be used to explicitly display its argument as a\nparagraph of its own. Then, the paragraph's body may not contain any\nblock-level content.
As explained above, usually paragraphs only contain inline-level content.\nHowever, you can integrate any kind of block-level content into a paragraph\nby wrapping it in a box.
Conversely, you can separate inline-level content from a paragraph by\nwrapping it in a block. In this case, it will not become part of any\nparagraph at all. Read the following section for an explanation of why that\nmatters and how it differs from just adding paragraph breaks around the\ncontent.
When you add inline-level content to your document, Typst will automatically\nwrap it in paragraphs. However, a typical document also contains some text\nthat is not semantically part of a paragraph, for example in a heading or\ncaption.
\nThe rules for when Typst wraps inline-level content in a paragraph are as\nfollows:
\nAll text at the root of a document is wrapped in paragraphs.
\nText in a container (like a block) is only wrapped in a paragraph if the\ncontainer holds any block-level content. If all of the contents are\ninline-level, no paragraph is created.
In the laid-out document, it's not immediately visible whether text became\npart of a paragraph. However, it is still important for various reasons:
\nCertain paragraph styling like first-line-indent will only apply to\nproper paragraphs, not any text. Similarly, par show rules of course\nonly trigger on paragraphs.
A proper distinction between paragraphs and other text helps people who\nrely on Assistive Technology (AT) (such as screen readers) navigate and\nunderstand the document properly.
\nPDF export will generate a P tag only for paragraphs.
HTML export will generate a <p> tag only for paragraphs.
When creating custom reusable components, you can and should take charge\nover whether Typst creates paragraphs. By wrapping text in a block\ninstead of just adding paragraph breaks around it, you can force the absence\nof a paragraph. Conversely, by adding a parbreak after some content in a\ncontainer, you can force it to become a paragraph even if it's just one\nword. This is, for example, what non-tight lists do to\nforce their items to become paragraphs.
#set par(\n first-line-indent: 1em,\n spacing: 0.65em,\n justify: true,\n)\n\nWe proceed by contradiction.\nSuppose that there exists a set\nof positive integers $a$, $b$, and\n$c$ that satisfies the equation\n$a^n + b^n = c^n$ for some\ninteger value of $n > 2$.\n\nWithout loss of generality,\nlet $a$ be the smallest of the\nthree integers. Then, we ...\n![\"Preview\"](\"/en-US-v0.14.1/assets/cab222a5bd10633b8312040d645e7baf.png\")
The spacing between lines.
\nLeading defines the spacing between the bottom edge\nof one line and the top edge of the following line. By\ndefault, these two properties are up to the font, but they can also be\nconfigured manually with a text set rule.
\nBy setting top edge, bottom edge, and leading, you can also configure a\nconsistent baseline-to-baseline distance. You could, for instance, set\nthe leading to 1em, the top-edge to 0.8em, and the bottom-edge\nto -0.2em to get a baseline gap of exactly 2em. The exact\ndistribution of the top- and bottom-edge values affects the bounds of\nthe first and last line.
![\"Preview\"](\"/en-US-v0.14.1/assets/9c812905bc7a3255ec39739967cf00b1.png\")
0.65em","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"spacing","details":[{"kind":"html","content":"The spacing between paragraphs.
\nJust like leading, this defines the spacing between the bottom edge of a\nparagraph's last line and the top edge of the next paragraph's first\nline.
\nWhen a paragraph is adjacent to a block that is not a paragraph,\nthat block's above or below property\ntakes precedence over the paragraph spacing. Headings, for instance,\nreduce the spacing below them by default for a better look.
1.2em","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"justify","details":[{"kind":"html","content":"Whether to justify text in its line.
\nHyphenation will be enabled for justified paragraphs if the\ntext function's hyphenate property is set to\nauto and the current language is known.
Note that the current alignment still has an effect\non the placement of the last line except if it ends with a\njustified line break.
\nBy default, Typst only changes the spacing between words to achieve\njustification. However, you can also allow it to adjust the spacing\nbetween individual characters using the\njustification-limits property.
false","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"justification-limits","details":[{"kind":"html","content":"How much the spacing between words and characters may be adjusted during\njustification.
\nWhen justifying text, Typst needs to stretch or shrink a line to the\nfull width of the measure. To achieve this, by default, it adjusts the\nspacing between words. Additionally, it can also adjust the spacing\nbetween individual characters. This property allows you to configure\nlower and upper bounds for these adjustments.
\nThe property accepts a dictionary with two entries, spacing and\ntracking, each containing a dictionary with the keys min and max.\nThe min keys define down to which lower bound gaps may be shrunk while\nthe max keys define up to which upper bound they may be stretched.
The spacing entry defines how much the width of spaces between words\nmay be adjusted. It is closely related to text.spacing and its\nmin and max keys accept relative lengths, just like\nthe spacing property.
A min value of 100% means that spaces should retain their normal\nsize (i.e. not be shrunk), while a value of 90% - 0.01em would\nindicate that a space can be shrunk to a width of 90% of its normal\nwidth minus 0.01× the current font size. Similarly, a max value of\n100% + 0.02em means that a space's width can be increased by 0.02×\nthe current font size. The ratio part must always be positive. The\nlength part, meanwhile, must not be positive for min and not be\nnegative for max.
Note that spaces may still be expanded beyond the max value if there\nis no way to justify the line otherwise. However, other means of\njustification (e.g. spacing apart characters if the tracking entry\nis configured accordingly) are first used to their maximum.
The tracking entry defines how much the spacing between letters may\nbe adjusted. It is closely related to text.tracking and its min\nand max keys accept lengths, just like the tracking\nproperty. Unlike spacing, it does not accept relative lengths\nbecause the base of the relative length would vary for each character,\nleading to an uneven visual appearance. The behavior compared to\nspacing is as if the base was 100%.
Otherwise, the min and max values work just like for spacing. A\nmax value of 0.01em means that additional spacing amounting to\n0.01× of the current font size may be inserted between every pair of\ncharacters. Note that this also includes the gaps between spaces and\ncharacters, so for spaces the values of tracking act in addition to\nthe values for spacing.
If you only specify one of spacing or tracking, the other retains\nits previously set value (or the default if it was not previously set).
If you want to enable character-level justification, a good value for\nthe min and max keys is around 0.01em to 0.02em (negated for\nmin). Using the same value for both gives a good baseline, but\ntweaking the two values individually may produce more balanced results,\nas demonstrated in the example below. Be careful not to set the bounds\ntoo wide, as it quickly looks unnatural.
Using character-level justification is an impactful microtypographical\ntechnique that can improve the appearance of justified text, especially\nin narrow columns. Note though that character-level justification does\nnot work with every font or language. For example, cursive fonts connect\nletters. Using character-level justification would lead to jagged\nconnections.
"},{"kind":"example","content":{"body":"#let example(name) = columns(2, gutter: 10pt)[\n #place(top, float: true, scope: "parent", strong(name))\n /* Text from https://en.wikipedia.org/wiki/Anne_Bayley */\n]\n\n#set page(width: 440pt, height: 21em, margin: 15pt)\n#set par(justify: true)\n#set text(size: 0.8em)\n\n#grid(\n columns: (1fr, 1fr),\n gutter: 20pt,\n {\n // These are Typst's default limits.\n set par(justification-limits: (\n spacing: (min: 100% * 2 / 3, max: 150%),\n tracking: (min: 0em, max: 0em),\n ))\n example[Word-level justification]\n },\n {\n // These are our custom character-level limits.\n set par(justification-limits: (\n tracking: (min: -0.01em, max: 0.02em),\n ))\n example[Character-level justification]\n },\n)\n![\"Preview\"](\"/en-US-v0.14.1/assets/fb060df59ab97e6e1174e0a9031d64e3.png\")
(\n spacing: (min: 66.67% + 0pt, max: 150% + 0pt),\n tracking: (min: 0pt, max: 0pt),\n)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"linebreaks","details":[{"kind":"html","content":"How to determine line breaks.
\nWhen this property is set to auto, its default value, optimized line\nbreaks will be used for justified paragraphs. Enabling optimized line\nbreaks for ragged paragraphs may also be worthwhile to improve the\nappearance of the text.
#set page(width: 207pt)\n#set par(linebreaks: "simple")\nSome texts feature many longer\nwords. Those are often exceedingly\nchallenging to break in a visually\npleasing way.\n\n#set par(linebreaks: "optimized")\nSome texts feature many longer\nwords. Those are often exceedingly\nchallenging to break in a visually\npleasing way.\n![\"Preview\"](\"/en-US-v0.14.1/assets/afe7dac249a627a4a78b08bcfbe89be6.png\")
Determine the line breaks in a simple first-fit style.
"},{"string":"optimized","details":"Optimize the line breaks for the whole paragraph.
\nTypst will try to produce more evenly filled lines of text by\nconsidering the whole paragraph when calculating line breaks.
"}],"default":"auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"first-line-indent","details":[{"kind":"html","content":"The indent the first line of a paragraph should have.
\nBy default, only the first line of a consecutive paragraph will be\nindented (not the first one in the document or container, and not\nparagraphs immediately following other block-level elements).
\nIf you want to indent all paragraphs instead, you can pass a dictionary\ncontaining the amount of indent as a length and the pair\nall: true. When all is omitted from the dictionary, it defaults to\nfalse.
By typographic convention, paragraph breaks are indicated either by some\nspace between paragraphs or by indented first lines. Consider
\nspacing to the\nleading using set par(spacing: 0.65em)spacing (which inherits the\nparagraph spacing by default) to the original paragraph spacing using\nset block(spacing: 1.2em)#set block(spacing: 1.2em)\n#set par(\n first-line-indent: 1.5em,\n spacing: 0.65em,\n)\n\nThe first paragraph is not affected\nby the indent.\n\nBut the second paragraph is.\n\n#line(length: 100%)\n\n#set par(first-line-indent: (\n amount: 1.5em,\n all: true,\n))\n\nNow all paragraphs are affected\nby the first line indent.\n\nEven the first one.\n![\"Preview\"](\"/en-US-v0.14.1/assets/8d7d84d566dc85bdc1bc0863bc851879.png\")
(amount: 0pt, all: false)","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"hanging-indent","details":[{"kind":"html","content":"The indent that all but the first line of a paragraph should have.
"},{"kind":"example","content":{"body":"#set par(hanging-indent: 1em)\n\n#lorem(15)\n![\"Preview\"](\"/en-US-v0.14.1/assets/7bde69f34692105af6720864a7d17480.png\")
0pt","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"body","details":[{"kind":"html","content":"The contents of the paragraph.
"}],"types":["content"],"strings":[],"default":null,"positional":true,"named":false,"required":true,"variadic":false,"settable":false}],"returns":["content"],"scope":[{"path":["par"],"name":"line","title":"Paragraph Line","keywords":["line numbering"],"oneliner":"A paragraph line.","element":true,"contextual":false,"deprecationMessage":null,"deprecationUntil":null,"details":[{"kind":"html","content":"A paragraph line.
\nThis element is exclusively used for line number configuration through set\nrules and cannot be placed.
\nThe numbering option is used to enable line\nnumbers by specifying a numbering format.
#set par.line(numbering: "1")\n\nRoses are red. \\\nViolets are blue. \\\nTypst is there for you.\n![\"Preview\"](\"/en-US-v0.14.1/assets/6f6e7b60b1d411a81b15694f783e2013.png\")
The numbering option takes either a predefined\nnumbering pattern or a function returning styled content. You\ncan disable line numbers for text inside certain elements by setting the\nnumbering to none using show-set rules.
// Styled red line numbers.\n#set par.line(\n numbering: n => text(red)[#n]\n)\n\n// Disable numbers inside figures.\n#show figure: set par.line(\n numbering: none\n)\n\nRoses are red. \\\nViolets are blue.\n\n#figure(\n caption: [Without line numbers.]\n)[\n Lorem ipsum \\\n dolor sit amet\n]\n\nThe text above is a sample \\\noriginating from distant times.\n![\"Preview\"](\"/en-US-v0.14.1/assets/58937016f47739bbce0d3f8c6d6a9f94.png\")
This element exposes further options which may be used to control other\naspects of line numbering, such as its alignment\nor margin. In addition, you can control whether\nthe numbering is reset on each page through the\nnumbering-scope option.
How to number each line. Accepts a\nnumbering pattern or function taking a single number.
"},{"kind":"example","content":{"body":"#set par.line(numbering: "I")\n\nRoses are red. \\\nViolets are blue. \\\nTypst is there for you.\n![\"Preview\"](\"/en-US-v0.14.1/assets/3bea09a9873e3b0128c5aa69c4ae0064.png\")
#set par.line(\n numbering: i => if calc.rem(i, 5) == 0 or i == 1 { i },\n)\n\n#lorem(60)\n![\"Preview\"](\"/en-US-v0.14.1/assets/f38712049b18265eea5643ccc8ab4ef0.png\")
none","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"number-align","details":[{"kind":"html","content":"The alignment of line numbers associated with each line.
\nThe default of auto indicates a smart default where numbers grow\nhorizontally away from the text, considering the margin they're in and\nthe current text direction.
#set par.line(\n numbering: "I",\n number-align: left,\n)\n\nHello world! \\\nToday is a beautiful day \\\nFor exploring the world.\n![\"Preview\"](\"/en-US-v0.14.1/assets/5dfc01320623b767c6791805aff923e0.png\")
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"number-margin","details":[{"kind":"html","content":"The margin at which line numbers appear.
\nNote: In a multi-column document, the line numbers for paragraphs\ninside the last column will always appear on the end margin (right\nmargin for left-to-right text and left margin for right-to-left),\nregardless of this configuration. That behavior cannot be changed at\nthis moment.
#set par.line(\n numbering: "1",\n number-margin: right,\n)\n\n= Report\n- Brightness: Dark, yet darker\n- Readings: Negative\n![\"Preview\"](\"/en-US-v0.14.1/assets/bdfd1906b97281550007248cb244da29.png\")
start","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"number-clearance","details":[{"kind":"html","content":"The distance between line numbers and text.
\nThe default value of auto results in a clearance that is adaptive to\nthe page width and yields reasonable results in most cases.
#set par.line(\n numbering: "1",\n number-clearance: 4pt,\n)\n\nTypesetting \\\nStyling \\\nLayout\n![\"Preview\"](\"/en-US-v0.14.1/assets/3208940772e8c44d0944e5a81c93ec96.png\")
auto","positional":false,"named":true,"required":false,"variadic":false,"settable":true},{"name":"numbering-scope","details":[{"kind":"html","content":"Controls when to reset line numbering.
\nNote: The line numbering scope must be uniform across each page run (a\npage run is a sequence of pages without an explicit pagebreak in\nbetween). For this reason, set rules for it should be defined before any\npage content, typically at the very start of the document.
"},{"kind":"example","content":{"body":"#set par.line(\n numbering: "1",\n numbering-scope: "page",\n)\n\nFirst line \\\nSecond line\n#pagebreak()\nFirst line again \\\nSecond line again\n![\"Preview](\"/en-US-v0.14.1/assets/3269883aef94076b02e0694e837a23f4-0.png\")
![\"Preview](\"/en-US-v0.14.1/assets/3269883aef94076b02e0694e837a23f4-1.png\")
Indicates that the line number counter spans the whole document, i.e.,\nit's never automatically reset.
"},{"string":"page","details":"Indicates that the line number counter should be reset at the start of\nevery new page.
"}],"default":""document"","positional":false,"named":true,"required":false,"variadic":false,"settable":true}],"returns":["content"],"scope":[]}]}}}