Skip to content

Commit 9b17dce

Browse files
committed
Merge branch 'master' into lriggle-strib/master
2 parents 5775cf9 + 61bbe89 commit 9b17dce

File tree

10 files changed

+73
-22
lines changed

10 files changed

+73
-22
lines changed

CHANGELOG.md

+11
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,21 @@
11
# Unreleased
22

3+
### Features
4+
5+
- Added `headings` option to control optional headings, #2729.
6+
- Added a folder icon to page navigation elements which are not links, #2741.
7+
38
### Bug Fixes
49

510
- `externalSymbolLinkMappings` now uses the TypeScript reported link target if available, #2725.
611
- TypeDoc will no longer omit the modules page if a project contains only modules/documents, #2730.
712
- Fixed missing breadcrumbs on project page, #2728.
13+
- TypeDoc will no longer render an empty readme page if no readme was found.
14+
15+
### Thanks!
16+
17+
- @lriggle-strib
18+
- @mrfigg
819

920
## v0.26.8 (2024-10-04)
1021

scripts/build_themes.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
const esbuild = require("esbuild");
33
const fs = require("fs");
44

5-
const watch = process.argv.slice(2).includes("--watch");
5+
const watch = process.argv.slice(2).some((t) => t == "--watch" || t == "-w");
66

77
// It's convenient to be able to build the themes in watch mode without rebuilding the whole docs
88
// to test some change to the frontend JS.

src/lib/internationalization/locales/zh.cts

+1
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,7 @@ export = buildIncompleteTranslation({
287287
help_sidebarLinks: "定义要包含在侧边栏中的链接",
288288
help_navigationLeaves: "导航树中不应扩展的分支",
289289
help_navigation: "确定导航侧边栏的组织方式",
290+
help_headings: "确定标题是否需要被渲染",
290291
help_visibilityFilters:
291292
"根据修饰符标签指定内置过滤器和附加过滤器的默认可见性",
292293
help_searchCategoryBoosts: "配置搜索以提高所选类别的相关性",

src/lib/internationalization/translatable.ts

+1
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,7 @@ export const translatable = {
300300
help_navigationLeaves:
301301
"Branches of the navigation tree which should not be expanded",
302302
help_navigation: "Determines how the navigation sidebar is organized",
303+
help_headings: "Determines which optional headings are rendered",
303304
help_visibilityFilters:
304305
"Specify the default visibility for builtin filters and additional filters according to modifier tags",
305306
help_searchCategoryBoosts:

src/lib/output/themes/default/DefaultTheme.tsx

+1-5
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ export class DefaultTheme extends Theme {
205205
const urls: UrlMapping[] = [];
206206
this.sluggers.set(project, new Slugger());
207207

208-
if (!hasReadme(this.application.options.getValue("readme"))) {
208+
if (!project.readme?.length) {
209209
project.url = "index.html";
210210
urls.push(new UrlMapping<ContainerReflection>("index.html", project, this.reflectionTemplate));
211211
} else {
@@ -507,10 +507,6 @@ export class DefaultTheme extends Theme {
507507
}
508508
}
509509

510-
function hasReadme(readme: string) {
511-
return !readme.endsWith("none");
512-
}
513-
514510
function getReflectionClasses(
515511
reflection: DeclarationReflection | DocumentReflection,
516512
filters: Record<string, boolean>,

src/lib/output/themes/default/assets/typedoc/Navigation.ts

+3-2
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,8 @@ function addNavText(
103103
}
104104
a.appendChild(document.createElement("span")).textContent = el.text;
105105
} else {
106-
parent.appendChild(document.createElement("span")).textContent =
107-
el.text;
106+
const span = parent.appendChild(document.createElement("span"));
107+
span.innerHTML = `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon"><use href="#icon-folder"></use></svg>`;
108+
span.appendChild(document.createElement("span")).textContent = el.text;
108109
}
109110
}

src/lib/output/themes/default/partials/header.tsx

+30-10
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,39 @@ import { classNames, getDisplayName, hasTypeParameters, join } from "../../lib";
22
import { JSX } from "../../../../utils";
33
import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
44
import type { PageEvent } from "../../../events";
5-
import { type Reflection, ReflectionKind } from "../../../../models";
5+
import type { Reflection } from "../../../../models";
66

77
export const header = (context: DefaultThemeRenderContext, props: PageEvent<Reflection>) => {
8-
const HeadingLevel = props.model.isProject() ? "h2" : "h1";
8+
const opts = context.options.getValue("headings");
9+
10+
// Don't render on the index page or the class hierarchy page
11+
// We should probably someday render on the class hierarchy page, but currently breadcrumbs
12+
// are entirely dependent on the reflection hierarchy, so it doesn't make sense today.
13+
const renderBreadcrumbs = props.url !== "index.html" && props.url !== "hierarchy.html";
14+
15+
// Titles are always rendered on DeclarationReflection pages and the modules page for the project.
16+
// They are also rendered on the readme + document pages if configured to do so by the user.
17+
let renderTitle: boolean;
18+
let titleKindString = "";
19+
if (props.model.isProject()) {
20+
if (props.url === "index.html" && props.model.readme?.length) {
21+
renderTitle = opts.readme;
22+
} else {
23+
renderTitle = true;
24+
}
25+
} else if (props.model.isDocument()) {
26+
renderTitle = opts.document;
27+
} else {
28+
renderTitle = true;
29+
titleKindString = " " + context.internationalization.kindSingularString(props.model.kind);
30+
}
31+
932
return (
1033
<div class="tsd-page-title">
11-
{props.url !== "index.html" && props.url !== "hierarchy.html" && (
12-
<ul class="tsd-breadcrumb">{context.breadcrumb(props.model)}</ul>
13-
)}
14-
{!props.model.isDocument() && (
15-
<HeadingLevel class={classNames({ deprecated: props.model.isDeprecated() })}>
16-
{props.model.kind !== ReflectionKind.Project &&
17-
`${context.internationalization.kindSingularString(props.model.kind)} `}
34+
{renderBreadcrumbs && <ul class="tsd-breadcrumb">{context.breadcrumb(props.model)}</ul>}
35+
{renderTitle && (
36+
<h1 class={classNames({ deprecated: props.model.isDeprecated() })}>
37+
{titleKindString}
1838
{getDisplayName(props.model)}
1939
{hasTypeParameters(props.model) && (
2040
<>
@@ -24,7 +44,7 @@ export const header = (context: DefaultThemeRenderContext, props: PageEvent<Refl
2444
</>
2545
)}
2646
{context.reflectionFlags(props.model)}
27-
</HeadingLevel>
47+
</h1>
2848
)}
2949
</div>
3050
);

src/lib/output/themes/default/partials/icon.tsx

+11-4
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ export function buildRefIcons<T extends Record<string, () => JSX.Element>>(
4747
}
4848

4949
export const icons: Record<
50-
ReflectionKind | "chevronDown" | "checkbox" | "menu" | "search" | "chevronSmall" | "anchor",
50+
ReflectionKind | "chevronDown" | "checkbox" | "menu" | "search" | "chevronSmall" | "anchor" | "folder",
5151
() => JSX.Element
5252
> = {
5353
[ReflectionKind.Accessor]: () =>
@@ -282,14 +282,21 @@ export const icons: Record<
282282
),
283283
[ReflectionKind.Document]: () =>
284284
kindIcon(
285-
<g stroke="var(--color-icon-text)" fill="var(--color-icon-background)">
286-
<polygon points="6,5 6,19 18,19, 18,9 15,5" />
287-
<line x1="9" y1="9" x2="14" y2="9" />
285+
<g stroke="var(--color-text)" fill="none" stroke-width="1.5">
286+
<polygon points="6,5 6,19 18,19, 18,10 13,5" />
287+
<line x1="9" y1="9" x2="13" y2="9" />
288288
<line x1="9" y1="12" x2="15" y2="12" />
289289
<line x1="9" y1="15" x2="15" y2="15" />
290290
</g>,
291291
"var(--color-document)",
292292
),
293+
folder: () =>
294+
kindIcon(
295+
<g stroke="var(--color-text)" fill="none" stroke-width="1.5">
296+
<polygon points="5,5 10,5 12,8 19,8 19,18 5,18" />
297+
</g>,
298+
"var(--color-document)",
299+
),
293300
chevronDown: () => (
294301
<svg width="20" height="20" viewBox="0 0 24 24" fill="none">
295302
<path

src/lib/utils/options/declaration.ts

+4
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,10 @@ export interface TypeDocOptionMap {
185185
compactFolders: boolean;
186186
excludeReferences: boolean;
187187
};
188+
headings: {
189+
readme: boolean;
190+
document: boolean;
191+
};
188192
visibilityFilters: ManuallyValidatedOption<{
189193
protected?: boolean;
190194
private?: boolean;

src/lib/utils/options/sources/typedoc.ts

+10
Original file line numberDiff line numberDiff line change
@@ -564,6 +564,16 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
564564
},
565565
});
566566

567+
options.addDeclaration({
568+
name: "headings",
569+
help: (i18n) => i18n.help_headings(),
570+
type: ParameterType.Flags,
571+
defaults: {
572+
readme: true,
573+
document: false,
574+
},
575+
});
576+
567577
options.addDeclaration({
568578
name: "visibilityFilters",
569579
help: (i18n) => i18n.help_visibilityFilters(),

0 commit comments

Comments
 (0)