Skip to content

feat: improve styling for library pages #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

feat: improve styling for library pages #28

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
1e428a7
feat: improve styling for library pages
3w36zj6 Oct 29, 2025
d6f67aa
Merge remote-tracking branch 'origin/main' into feature/improve-styli…
3w36zj6 Nov 2, 2025
13502c2
fix: layout list item contents horizontally
3w36zj6 Nov 4, 2025
1162d7c
refactor: inline function name decoration logic into function definit…
3w36zj6 Nov 4, 2025
2c9507b
fix: remove unnecessary margin classes from function page template
3w36zj6 Nov 4, 2025
c15054b
fix: align default value display to center vertically in function par…
3w36zj6 Nov 4, 2025
d80ee0e
fix: remove `pre` selector from code span styles
3w36zj6 Nov 4, 2025
9d3ff65
Merge remote-tracking branch 'origin/main' into feature/improve-styli…
3w36zj6 Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/components/templates/CategoryTemplate.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,9 @@ export const CategoryTemplate: FC<CategoryTemplateProps> = ({
{item.code ? <code>{item.name}</code> : item.name}
</a>
</div>
<div class="pl-4">{item.oneliner}</div>
<div>
<p>{item.oneliner}</p>
</div>
Copy link
Member

@YDX-2147483647 YDX-2147483647 Nov 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the original style looks better. It weakens item.oneliner by adding an indent and decreasing the distance to item.name, making it easier to scan quickly and locate an item.

Example: https://typst-docs-web.netlify.app/en-us-v0.14.0/reference/foundations/

Besides, it might be possible to unify the style here in <CategoryTemplate> and the style for param.strings in <FunctionParameters>.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I simply aligned the elements horizontally while respecting the styles of @tailwindcss/typography. I think this looks good, but what do you think?

image 
diff --git a/src/components/templates/CategoryTemplate.tsx b/src/components/templates/CategoryTemplate.tsx
index a0e777a..05ecbeb 100644
--- a/src/components/templates/CategoryTemplate.tsx
+++ b/src/components/templates/CategoryTemplate.tsx
@@ -32,16 +32,16 @@ export const CategoryTemplate: FC<CategoryTemplateProps> = ({
 					<h2 id="definitions">
 						<Translation translationKey="definitions" />
 					</h2>
-					<ul class="subgridded">
+					<ul>
 						{page.body.content.items.map((item) => (
 							<li key={item.route}>
-								<div>
-									<a href={item.route}>
-										{item.code ? <code>{item.name}</code> : item.name}
-									</a>
-								</div>
-								<div>
-									<p>{item.oneliner}</p>
+								<div class="flex">
+									<div class="min-w-[8rem]">
+										<a href={item.route}>
+											{item.code ? <code>{item.name}</code> : item.name}
+										</a>
+									</div>
+									<div>{item.oneliner}</div>
 								</div>
 							</li>
 						))}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That looks nice!

</li>
))}
</ul>
Expand Down
75 changes: 38 additions & 37 deletions src/components/templates/FuncTemplate.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,16 +69,18 @@ export const FuncTemplate: FC<FuncTemplateProps> = ({
}
})}

<h2 id="parameters" class="flex items-baseline gap-1">
<Translation translationKey="parameters" />
<Tooltip kind="parameters" />
<h2 id="parameters" class="flex">
<div class="flex items-baseline gap-1">
<Translation translationKey="parameters" />
<Tooltip kind="parameters" />
</div>
</h2>

<div class="mb-6">
<div class="my-4">
<FunctionDefinition func={content} />
</div>

<div class="my-6">
<div class="my-4">
<FunctionParameters params={content.params} />
</div>

Expand Down Expand Up @@ -109,48 +111,47 @@ function ScopedDefinitions({
// the following heading levels will _not_ increase with the scope level.
return (
<div class="mt-8">
<h2 id={`${parentId}definitions`} class="flex items-baseline gap-1">
{parent ? (
// Currently, the scope has at most two levels.
// Therefore, it is sufficient to only annotate the direct `parent`.
<Translation translationKey="definitionsOf" name={parent.name} />
) : (
<Translation translationKey="definitions" />
)}
<Tooltip kind="definitions" />
<h2 id={`${parentId}definitions`} class="flex">
<div class="flex items-baseline gap-1">
{parent ? (
// Currently, the scope has at most two levels.
// Therefore, it is sufficient to only annotate the direct `parent`.
<Translation translationKey="definitionsOf" name={parent.name} />
) : (
<Translation translationKey="definitions" />
)}
<Tooltip kind="definitions" />
</div>
</h2>

{scope.map((method, _index) => {
const methodId = `${parentId}definitions-${method.name}`;

return (
<div
key={method.name}
class="mb-8 pb-6 border-b border-gray-100 last:border-0"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here you've removed the border.
See outline.entry.{inner,body,page}. These border lines lines help distinguish the functions.

图片

↓ After the removal, body seems to be a parameter of inner?

I suggest adding the border back.
If you just don't like the border, please increase the spacing here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We plan to add decorative elements to the headings, so we will put this proposal on hold.

>
<h3 id={methodId} class="method-head mb-3 flex items-center gap-2">
<code
class="text-base font-medium"
style={
normalizeDeprecation(method) !== null
? { textDecoration: "line-through" }
: undefined
}
>
{method.name}
</code>

<small class="flex items-center">
{method.element && <Tooltip kind="element" />}
{method.contextual && <Tooltip kind="contextual" />}
</small>
<div key={method.name}>
<h3 id={methodId} class="flex">
<div class="flex items-center gap-2">
<code
class="text-base font-medium"
style={
normalizeDeprecation(method) !== null
? { textDecoration: "line-through" }
: undefined
}
>
{method.name}
</code>

<small class="flex items-center">
{method.element && <Tooltip kind="element" />}
{method.contextual && <Tooltip kind="contextual" />}
</small>
</div>
</h3>

{<DeprecationWarning item={method} level="scoped" />}

<div class="pl-2">
<FunctionDisplay func={method} prefix={methodId} />
</div>
<FunctionDisplay func={method} prefix={methodId} />

<ScopedDefinitions
scope={method.scope}
Expand Down
12 changes: 7 additions & 5 deletions src/components/templates/GroupTemplate.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,13 @@ export const GroupTemplate: FC<GroupTemplateProps> = ({

{content.functions.map((method, _index) => (
<div key={method.name}>
<h3 id={`functions-${method.name}`} class="method-head">
<code class="text-base font-medium">{method.name}</code>
<div class="flex flex-wrap items-center gap-2 text-sm">
{method.element && <Tooltip kind="element" />}
{method.contextual && <Tooltip kind="contextual" />}
<h3 id={`functions-${method.name}`} class="flex">
<div class="flex items-center gap-2">
<code class="text-base font-medium">{method.name}</code>
<div class="flex flex-wrap items-center gap-2 text-sm">
{method.element && <Tooltip kind="element" />}
{method.contextual && <Tooltip kind="contextual" />}
</div>
</div>
</h3>
<FunctionDisplay
Expand Down
31 changes: 17 additions & 14 deletions src/components/templates/TypeTemplate.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,11 @@ export const TypeTemplate: FC<TypeTemplateProps> = ({

{content.constructor && (
<>
<h2 id="constructor" class="flex items-center gap-1">
<Translation translationKey="constructor" />
<Tooltip kind="parameters" />
<h2 id="constructor" class="flex">
<div class="flex items-center gap-1">
<Translation translationKey="constructor" />
<Tooltip kind="parameters" />
</div>
</h2>

<FunctionDisplay
Expand All @@ -52,21 +54,22 @@ export const TypeTemplate: FC<TypeTemplateProps> = ({

{content.scope.length > 0 && (
<>
<h2 id="definitions" class="flex items-center gap-1">
<Translation translationKey="definitions" />
<Tooltip kind="definitions" />
<h2 id="definitions" class="flex">
<div class="flex items-center gap-1">
<Translation translationKey="definitions" />
<Tooltip kind="definitions" />
</div>
</h2>

{content.scope.map((method, _index) => (
<div key={method.name}>
<h3
id={`definitions-${method.name}`}
class="method-head flex items-center gap-2 mb-3"
>
<code class="text-base font-medium">{method.name}</code>
<div class="flex flex-wrap items-center gap-2">
{method.element && <Tooltip kind="element" />}
{method.contextual && <Tooltip kind="contextual" />}
<h3 id={`definitions-${method.name}`} class="flex">
<div class="flex items-center gap-2">
<code class="text-base font-medium">{method.name}</code>
<div class="flex flex-wrap items-center gap-2">
{method.element && <Tooltip kind="element" />}
{method.contextual && <Tooltip kind="contextual" />}
</div>
</div>
</h3>

Expand Down
65 changes: 30 additions & 35 deletions src/components/ui/FunctionDefinition.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,27 +20,26 @@ export const FunctionDefinition: FC<FunctionDefinitionProps> = ({
func,
prefix = undefined,
}) => {
const funcName = func.self ? "self" : genPath(func);
return (
<div class="bg-gray-50 p-4 rounded-md border border-gray-100 overflow-x-auto">
<div class="code code-definition font-mono text-base">
<span class="text-gray-500">{func.self ? "self." : genPath(func)}</span>
<span class="typ-func font-semibold text-blue-500">{func.name}</span>
<span class="text-gray-700">(</span>
<div class="arguments pl-4 md:pl-6 flex flex-col">
<pre>
<code>
<span>{funcName}</span>
{funcName !== "" && <span class="typ-punct">.</span>}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This style assumes that there is no additional . in funcName. According to the following, it's true at present.

$ jq '.. | select(type == "object" and has("path")) | .path | length' docs.json | sort | uniq --count
    101 0
    421 1

I suggest adding a comment to genPath.ts:

For Typst v0.14.0, the path is either empty or has only one item.

<span class="typ-func">{func.name}</span>
<span class="typ-punct">(</span>
<span class="arguments pl-4 md:pl-6 flex flex-col">
{func.params.map((param, index) => (
<div
<span
key={param.name}
class="overview-param flex flex-row items-center py-0.5"
>
{!param.positional && (
<div class="flex-shrink-0">
<a
href={`#${buildParamId(param.name, prefix)}`}
class="text-gray-800 hover:text-blue-500 transition-colors mr-1"
>
<span class="font-medium">{param.name}</span>
<span class="text-gray-500">:</span>
<div class="flex-shrink-0 mr-1">
<a href={`#${buildParamId(param.name, prefix)}`}>
<span>{param.name}</span>
</a>
<span class="typ-punct">:</span>
</div>
)}
<div class="flex flex-row flex-wrap gap-1">
Expand All @@ -58,38 +57,34 @@ export const FunctionDefinition: FC<FunctionDefinitionProps> = ({
})}
</div>
{index < func.params.length - 1 && (
<span class="text-gray-500 ml-1">,</span>
<span class="typ-punct">,</span>
)}
</div>
</span>
))}
</div>
<span class="text-gray-700">)</span>
</span>

<span class="typ-punct">)</span>

{func.returns.length > 0 && (
<>
<span class="text-gray-500 mx-1">-&gt;</span>
<div class="inline-flex flex-wrap gap-1">
{func.returns.map((ret, i) => {
<span class="typ-op mx-1">-&gt;</span>
<div class="inline-flex flex-wrap gap-1 py-0.5">
{func.returns.map((ret, _) => {
const href = type2href(ret);
return (
<>
<TypeIcon
key={ret}
type={ret}
href={
href ? joinPath(basePath, "reference", href) : undefined
}
/>
{i < func.returns.length - 1 && (
<span class="text-gray-500 mx-1">,</span>
)}
</>
<TypeIcon
key={ret}
type={ret}
href={
href ? joinPath(basePath, "reference", href) : undefined
}
/>
);
})}
</div>
</>
)}
</div>
</div>
</code>
</pre>
);
};
8 changes: 3 additions & 5 deletions src/components/ui/FunctionDisplay.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ export const FunctionDisplay: FC<FunctionDisplayProps> = ({
case "example":
return isExampleFolding ? (
<details class="folding-example group">
<summary class="flex items-center gap-1 text-sm font-medium text-blue-600 cursor-pointer hover:text-blue-800">
<summary class="flex items-center gap-1 text-sm font-medium cursor-pointer text-gray-600 hover:text-gray-800 transition-colors">
<div class="w-4 h-4 text-gray-400 transform transition-transform duration-200 group-open:rotate-90">
<ChevronRightIcon />
</div>
Expand All @@ -41,14 +41,12 @@ export const FunctionDisplay: FC<FunctionDisplayProps> = ({
title={block.content.title}
/>
</summary>
<div class="mt-2 bg-white p-3 rounded-md border border-gray-200 text-sm">
<div class="my-4">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The vertical margin has been increased here, but I think my-4 is too large.

See place.{float,dx}:

图片 图片

This also applies to example blocks in <FunctionParameters>.

Note

Typst v0.14.0 has changed the format here. In v0.13.1, there's at most one example block for each <FunctionDisplay>; but now, there might be multiple example blocks, and they are embeded in the description.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the wrapping around FunctionDefinition and FunctionParameters as it was redundant.

diff --git a/src/components/templates/FuncTemplate.tsx b/src/components/templates/FuncTemplate.tsx
index b294e04..8ebc8ce 100644
--- a/src/components/templates/FuncTemplate.tsx
+++ b/src/components/templates/FuncTemplate.tsx
@@ -52,14 +52,14 @@ export const FuncTemplate: FC<FuncTemplateProps> = ({
 				switch (block.kind) {
 					case "html":
 						return (
-							<div class="my-4 text-gray-700">
+							<div class="text-gray-700">
 								<HtmlContent html={block.content} />
 							</div>
 						);
 					case "example":
 						// This will never reach for Typst v0.13.1 and v0.14.0-rc.1 documentations.
 						return (
-							<div class="my-6 bg-gray-50 p-4 rounded-md border border-gray-200">
+							<div>
 								{block.content.title}
 								<HtmlContent html={block.content.body} />
 							</div>
@@ -75,15 +75,8 @@ export const FuncTemplate: FC<FuncTemplateProps> = ({
 					<Tooltip kind="parameters" />
 				</div>
 			</h2>
-
-			<div class="my-4">
-				<FunctionDefinition func={content} />
-			</div>
-
-			<div class="my-4">
-				<FunctionParameters params={content.params} />
-			</div>
-
+			<FunctionDefinition func={content} />
+			<FunctionParameters params={content.params} />
 			<ScopedDefinitions scope={content.scope} />
 		</BaseTemplate>
 	);
diff --git a/src/components/ui/FunctionDisplay.tsx b/src/components/ui/FunctionDisplay.tsx
index 36c3d84..6c1d7ca 100644
--- a/src/components/ui/FunctionDisplay.tsx
+++ b/src/components/ui/FunctionDisplay.tsx
@@ -41,7 +41,7 @@ export const FunctionDisplay: FC<FunctionDisplayProps> = ({
 										title={block.content.title}
 									/>
 								</summary>
-								<div class="my-4">
+								<div>
 									<HtmlContent html={block.content.body} />
 								</div>
 							</details>
@@ -52,14 +52,8 @@ export const FunctionDisplay: FC<FunctionDisplayProps> = ({
 						return null;
 				}
 			})}
-
-			<div class="my-4">
-				<FunctionDefinition func={func} prefix={prefix} />
-			</div>
-
-			<div class="my-4">
-				<FunctionParameters params={func.params} prefix={prefix} />
-			</div>
+			<FunctionDefinition func={func} prefix={prefix} />
+			<FunctionParameters params={func.params} prefix={prefix} />
 		</>
 	);
 };
diff --git a/src/components/ui/FunctionParameters.tsx b/src/components/ui/FunctionParameters.tsx
index 718054e..9ba498d 100644
--- a/src/components/ui/FunctionParameters.tsx
+++ b/src/components/ui/FunctionParameters.tsx
@@ -81,7 +81,7 @@ export const FunctionParameters: FC<FunctionParametersProps> = ({
 												title={block.content.title}
 											/>
 										</summary>
-										<div class="my-4">
+										<div>
 											<HtmlContent html={block.content.body} />
 										</div>
 									</details>

<HtmlContent html={block.content.body} />
</div>
</details>
) : (
<div class="bg-gray-50 p-4 rounded-md border border-gray-200">
<HtmlContent html={block.content.body} />
</div>
<HtmlContent html={block.content.body} />
);
default:
return null;
Expand Down
Loading
Loading