Semantic paragraphs (#5746)

1 files changed, 7 insertions, 3 deletions

diff --git a/crates/typst-library/src/layout/container.rs b/crates/typst-library/src/layout/container.rs
index c8c74269..725f177b 100644
--- a/crates/typst-library/src/layout/container.rs
+++ b/crates/typst-library/src/layout/container.rs
@@ -14,9 +14,9 @@ use crate::visualize::{Paint, Stroke};
 /// An inline-level container that sizes content.
 ///
 /// All elements except inline math, text, and boxes are block-level and cannot
-/// occur inside of a paragraph. The box function can be used to integrate such
-/// elements into a paragraph. Boxes take the size of their contents by default
-/// but can also be sized explicitly.
+/// occur inside of a [paragraph]($par). The box function can be used to
+/// integrate such elements into a paragraph. Boxes take the size of their
+/// contents by default but can also be sized explicitly.
 ///
 /// # Example
 /// ```example
@@ -184,6 +184,10 @@ pub enum InlineItem {
 /// Such a container can be used to separate content, size it, and give it a
 /// background or border.
 ///
+/// Blocks are also the primary way to control whether text becomes part of a
+/// paragraph or not. See [the paragraph documentation]($par/#what-becomes-a-paragraph)
+/// for more details.
+///
 /// # Examples
 /// With a block, you can give a background to content while still allowing it
 /// to break across multiple pages.