From 895c6d3a3a1712d96273e32251ec086aadeeb438 Mon Sep 17 00:00:00 2001 From: dev Date: Thu, 1 Oct 2026 11:00:09 +0800 Subject: [PATCH] web: fix the outline anchors, level the outline, and fold the sidebar chapters --- content/concepts/keplerian-elements.zh.md | 4 +- docs/design.md | 21 ++++ frontend/src/App.svelte | 40 +++++-- frontend/src/app.css | 137 +++++++++++++++++++++- frontend/src/lib/i18n.ts | 3 + frontend/src/lib/types.ts | 10 +- frontend/src/lib/uniformCards.ts | 13 +- frontend/src/pages/Document.svelte | 75 ++++++++++-- frontend/src/pages/Tools.svelte | 21 +++- src/api/mod.rs | 8 +- src/docs/document.rs | 54 +++++++-- src/docs/markdown.rs | 44 ++++++- 12 files changed, 382 insertions(+), 48 deletions(-) diff --git a/content/concepts/keplerian-elements.zh.md b/content/concepts/keplerian-elements.zh.md index c09ced9..48bf559 100644 --- a/content/concepts/keplerian-elements.zh.md +++ b/content/concepts/keplerian-elements.zh.md @@ -19,7 +19,7 @@ summary: 六个经典轨道元素、二体解与三种近点角。 | 近地点幅角 | `omega` | 轨道面内从升交点到近地点的角度 | rad | | 真近点角 | `nu` | 从近地点到卫星的角度 | rad | -前两个给出形状与大小，接下来两个给出轨道面的朝向，最后两个给出近地点在轨道面内的位置与卫星沿轨道的位�置。 +前两个给出形状与大小，接下来两个给出轨道面的朝向，最后两个给出近地点在轨道面内的位置与卫星沿轨道的位置。 轨道是以地心为一个焦点的椭圆，即开普勒第一定律。离地球最近的点是近地点，最远的是远地点。 @@ -110,7 +110,7 @@ M = E - e sin(E) | 赤道元素 | 状态矢量 | 二体 | 是 | 否 | | 时间网格上的位置 | 任意传播器 | 任意 | 是 | 插值，见 [[ephemeris-interpolation]] | -赤道元素避免了经典元素在倾角为零和偏心率�为零时的奇异。此处使用经典形式，因为两行元素格式与已发表文献都采用这种形式，且地球轨道几乎总有非零倾角。 +赤道元素避免了经典元素在倾角为零和偏心率为零时的奇异。此处使用经典形式，因为两行元素格式与已发表文献都采用这种形式，且地球轨道几乎总有非零倾角。 ## 来源 diff --git a/docs/design.md b/docs/design.md index b69ccbd..f6c86ad 100644 --- a/docs/design.md +++ b/docs/design.md @@ -325,6 +325,27 @@ settles into a roughly round cluster while the canvas is wide, so the layout is widened to the canvas shape before it is fitted; the change is a uniform scale, which leaves relative distances readable. +## Anchors and outlines + +A heading anchor is reduced from the heading text, and a table of contents +carries that anchor. Two rules make the link land where the reader expects. + +The reduction **keeps the letters of every script**. Keeping only the ASCII +ones meant every Chinese heading reduced to the same fallback, so the whole +table of contents pointed at the first section and clicking an entry always +scrolled to the top of the document. The document text and the outline are +reduced by the same rule, so an entry names an anchor the document carries. + +A repeated heading is **numbered on both sides**. Two headings with the same +text would otherwise share one anchor, and the second entry would scroll to +the first. The document and the outline number the repeat the same way, so +the mapping stays exact. + +An outline carries the **level** of each heading, so a nested heading is +indented under its parent rather than listed beside it. A fold control is +shown only for a heading that has a child, because a control that hides +nothing is worse than no control. + ## Language coverage A user facing string falls into three classes, and each is handled diff --git a/frontend/src/App.svelte b/frontend/src/App.svelte index ef7a58b..7954eec 100644 --- a/frontend/src/App.svelte +++ b/frontend/src/App.svelte @@ -45,6 +45,16 @@ let searchLoading = $state(false); let status = $state(null); + /** The chapters whose documents are hidden in the sidebar. */ + let collapsed = $state([]); + + /** Folds a chapter, or unfolds it when it is already folded. */ + function toggleChapter(id: string) { + collapsed = collapsed.includes(id) + ? collapsed.filter((entry) => entry !== id) + : [...collapsed, id]; + } + /** Loads the content every page shares. */ async function loadShared() { try { @@ -178,15 +188,27 @@ {#if index}

{tr('nav.documents', lang)}

- {#each index.chapters as chapter} -
-
{pick(chapter.title, lang)}
- {#each chapter.documents as entry} - {pick(entry.title, lang)} - {/each} + {#each index.chapters as chapter (chapter.id)} +
+
+ + {pick(chapter.title, lang)} + + +
+ {#if !collapsed.includes(chapter.id)} + {#each chapter.documents as entry} + {pick(entry.title, lang)} + {/each} + {/if}
{/each}
diff --git a/frontend/src/app.css b/frontend/src/app.css index 696e2ab..65fc0d9 100644 --- a/frontend/src/app.css +++ b/frontend/src/app.css @@ -227,14 +227,60 @@ hr { } .sidebar-chapter { - margin-bottom: 0.75rem; + margin-bottom: 0.5rem; +} + +/* The chapter head is a row: the title is a link to the chapter listing + and the chevron folds the group. They sit apart so the two do not look + like one control. */ +.sidebar-chapter-head { + display: flex; + align-items: center; + gap: 0.1rem; + margin-bottom: 0.15rem; + padding-left: 0.35rem; + border-left: 2px solid var(--border-strong); } .sidebar-chapter-title { - font-size: 0.82rem; - color: var(--text-muted); - margin: 0 0 0.2rem 0.5rem; - font-weight: 600; + flex: 1 1 auto; + font-size: 0.78rem; + color: var(--text); + margin: 0; + font-weight: 700; + letter-spacing: 0.02em; + text-transform: uppercase; + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; +} + +.sidebar-chapter-title:hover { + color: var(--accent); + text-decoration: none; +} + +.sidebar-chapter-toggle { + flex: 0 0 auto; + width: 1.1rem; + height: 1.1rem; + padding: 0; + border: none; + background: none; + color: var(--text-faint); + font-size: 0.65rem; + line-height: 1; + cursor: pointer; + transition: transform 0.12s ease; +} + +.sidebar-chapter.collapsed .sidebar-chapter-toggle { + transform: rotate(-90deg); +} + +.sidebar-chapter-toggle:hover { + color: var(--accent); + background: none; } .sidebar a.item { @@ -1061,11 +1107,33 @@ tbody tr:hover { } .tool-card h4 { + display: flex; + align-items: baseline; + gap: 0.35rem; margin: 0 0 0.35rem; font-size: 0.98rem; color: var(--accent); } +/* The chevron marks the card as an entry point to a page of its own, which + is what a reader cannot otherwise tell from a heading. */ +.tool-go { + color: var(--text-faint); + font-size: 1.05rem; + line-height: 1; + transition: transform 0.12s ease, color 0.12s ease; +} + +.tool-card:hover .tool-go { + color: var(--accent); + transform: translateX(2px); +} + +/* The form a tool opens, given room to breathe under the index. */ +.tool-form { + scroll-margin-top: 4.5rem; +} + .tool-card p { margin: 0; color: var(--text-muted); @@ -1077,6 +1145,65 @@ tbody tr:hover { background: var(--accent-soft); } +/* The table of contents beside a document. */ + +.toc-list { + list-style: none; + padding: 0; + margin: 0; +} + +/* A deeper heading is indented, so the levels of the document are visible + without reading the text. */ +.toc-item { + display: flex; + align-items: baseline; + gap: 0.15rem; + margin: 0.1rem 0; +} + +.toc-item.level-3 { + padding-left: 0.85rem; +} + +.toc-item.level-4 { + padding-left: 1.7rem; +} + +.toc-item.level-5, +.toc-item.level-6 { + padding-left: 2.55rem; +} + +.toc-toggle { + flex: 0 0 auto; + width: 1rem; + height: 1rem; + padding: 0; + border: none; + background: none; + color: var(--text-faint); + font-size: 0.7rem; + line-height: 1; + cursor: pointer; + transition: transform 0.12s ease; +} + +.toc-toggle.collapsed { + transform: rotate(-90deg); +} + +.toc-toggle:hover { + color: var(--accent); + background: none; +} + +.toc-link { + color: var(--text-muted); + font-size: 0.85rem; + line-height: 1.4; +} + /* A row of links that wrap, used for the item filter results. */ .chip-row { display: flex; diff --git a/frontend/src/lib/i18n.ts b/frontend/src/lib/i18n.ts index a423626..97bb4f2 100644 --- a/frontend/src/lib/i18n.ts +++ b/frontend/src/lib/i18n.ts @@ -108,6 +108,7 @@ const STRINGS: Record = { 'nav.api': { zh: '接口文档', en: 'Interface' }, 'nav.tools': { zh: '在线工具', en: 'Online tools' }, 'nav.documents': { zh: '文档', en: 'Documents' }, + 'nav.toggleChapter': { zh: '展开或折叠该章', en: 'Expand or collapse the chapter' }, 'search.placeholder': { zh: '搜索文档', en: 'Search the documentation' }, 'search.button': { zh: '搜索', en: 'Search' }, 'search.title': { zh: '搜索', en: 'Search' }, @@ -171,6 +172,7 @@ const STRINGS: Record = { 'docs.back': { zh: '返回列表', en: 'Back to the listing' }, 'docs.readFirst': { zh: '先读：', en: 'Read first:' }, 'docs.onThisPage': { zh: '本页目录', en: 'On this page' }, + 'docs.toggle': { zh: '展开或折叠该节', en: 'Expand or collapse the section' }, 'docs.noSections': { zh: '无小节。', en: 'No sections.' }, 'docs.translationMissing': { zh: '本文档暂无中文版本，显示英文原文。', @@ -295,6 +297,7 @@ const STRINGS: Record = { 'kind.type': { zh: '类型别名', en: 'type' }, 'api.itemCount': { zh: '个接口项', en: 'items' }, + 'tools.open': { zh: '打开', en: 'Open' }, 'tools.choose': { zh: '共 {count} 个工具，按类别分组。', en: '{count} tools, grouped by category.' }, }; diff --git a/frontend/src/lib/types.ts b/frontend/src/lib/types.ts index b87e300..be356e9 100644 --- a/frontend/src/lib/types.ts +++ b/frontend/src/lib/types.ts @@ -34,6 +34,13 @@ export interface Health { frontend_embedded: boolean; } +/** One section heading of a document. */ +export interface DocumentHeading { + anchor: string; + text: string; + level: number; +} + /** One language form of a document. */ export interface DocumentForm { language: 'zh' | 'en'; @@ -41,7 +48,8 @@ export interface DocumentForm { summary: string; html: string; markdown: string; - headings: { anchor: string; text: string }[]; + /** Section headings, each with the anchor, text, and level. */ + headings: { anchor: string; text: string; level: number }[]; } /** One document, with a rendered form per embedded language. */ diff --git a/frontend/src/lib/uniformCards.ts b/frontend/src/lib/uniformCards.ts index d9ad75c..809fed3 100644 --- a/frontend/src/lib/uniformCards.ts +++ b/frontend/src/lib/uniformCards.ts @@ -12,6 +12,15 @@ * height is a property of the rendering, not of the content. */ +/** + * The cards the measurement covers. + * + * The interface page groups its items under a kind and lays them out in its + * own grid, so both grids take part; a card in either is made the height of + * the tallest. + */ +const CARD_SELECTOR = '.grid.cards > .card, .item-grid > .api-item'; + /** * Returns the height of the tallest card under `root`, in pixels, or `0` when * there is no card. @@ -20,7 +29,7 @@ export function tallestCardHeight(root: ParentNode): number { let tallest = 0; // The card is laid out at its natural height here, because the uniform // height is not applied yet. - for (const card of root.querySelectorAll('.grid.cards > .card')) { + for (const card of root.querySelectorAll(CARD_SELECTOR)) { tallest = Math.max(tallest, card.getBoundingClientRect().height); } return Math.ceil(tallest); @@ -31,7 +40,7 @@ export function tallestCardHeight(root: ParentNode): number { * inline height when there is no card. */ export function applyUniformHeight(root: ParentNode): void { - const cards = [...root.querySelectorAll('.grid.cards > .card')]; + const cards = [...root.querySelectorAll(CARD_SELECTOR)]; if (cards.length === 0) { return; } diff --git a/frontend/src/pages/Document.svelte b/frontend/src/pages/Document.svelte index b87a323..770bda3 100644 --- a/frontend/src/pages/Document.svelte +++ b/frontend/src/pages/Document.svelte @@ -11,7 +11,7 @@ * the reader's language is shown, with the English form as the fallback * when a translation is absent. */ - import type { Document, DocumentForm } from '../lib/types'; + import type { Document, DocumentForm, DocumentHeading } from '../lib/types'; import { navigate } from '../lib/router'; import { language, pickList, setLanguage, tr, type Language } from '../lib/i18n'; @@ -38,6 +38,47 @@ !!document && !!form && form.language !== lang, ); + /** Which top level sections of the table of contents are expanded. */ + let openSections = $state>({}); + + /** + * Returns `true` when a heading has a child under it. + * + * A fold control is only shown for a heading that actually has children, + * so a flat document does not carry controls that do nothing. + */ + function hasChildren(heading: DocumentHeading, index: number): boolean { + const next = form?.headings[index + 1]; + return next !== undefined && next.level > heading.level; + } + + /** + * Returns `true` when a heading is visible in the table of contents. + * + * A heading is visible when it is a top level entry, when its section is + * expanded, or when it is the first child of a section so that a section + * never looks empty while it is collapsed. + */ + function isVisible(heading: DocumentHeading, index: number): boolean { + if (heading.level <= 2) return true; + const parent = form?.headings + .slice(0, index) + .reverse() + .find((candidate) => candidate.level <= 2); + if (!parent) return true; + const open = openSections[parent.anchor]; + if (open !== false) return true; + // Keep the first child visible so a collapsed section still shows where + // it starts. + const firstChild = form?.headings.findIndex((candidate) => candidate.level > 2); + return firstChild === index; + } + + /** Flips a section open or closed. */ + function toggleSection(anchor: string) { + openSections = { ...openSections, [anchor]: openSections[anchor] === false }; + } + /** True when a form in the other language is available to switch to. */ const otherLanguage = $derived.by((): Language | null => { if (!document || !form) return null; @@ -143,17 +184,27 @@ {#if form.headings.length > 0} diff --git a/frontend/src/pages/Tools.svelte b/frontend/src/pages/Tools.svelte index 7420403..41a0b95 100644 --- a/frontend/src/pages/Tools.svelte +++ b/frontend/src/pages/Tools.svelte @@ -74,6 +74,19 @@ values = defaultsFor(found); }); + /** + * Moves the form into view after a tool is chosen. + * + * The index and the form share the page, so a reader who picks a tool from + * the list would otherwise stay on the index and not see the form. This + * runs only when the route names a tool, which is what a click does. + */ + let form = $state(null); + $effect(() => { + if (!id || !form) return; + form.scrollIntoView({ behavior: 'smooth', block: 'start' }); + }); + /** Runs the selected tool. */ async function run() { if (!tool) return; @@ -147,8 +160,12 @@ class="card tool-card" class:selected={id === candidate.id} href={`#/tools/${candidate.id}`} + aria-label="{tr('tools.open', lang)}: {pick(candidate.name, lang)}" > -

{pick(candidate.name, lang)}

+

+ {pick(candidate.name, lang)} + +

{pick(candidate.summary, lang)}

{/each} @@ -161,7 +178,7 @@

{tr('tools.select', lang)}

{:else} -
+

{pick(tool.name, lang)}

{pick(tool.category, lang)} diff --git a/src/api/mod.rs b/src/api/mod.rs index dc0e414..7b3c45e 100644 --- a/src/api/mod.rs +++ b/src/api/mod.rs @@ -191,7 +191,13 @@ impl Router { "headings" => variant .headings .iter() - .map(|(anchor, text)| json_object! { "anchor" => anchor.clone(), "text" => text.clone() }) + .map(|heading| { + json_object! { + "anchor" => heading.anchor.clone(), + "text" => heading.text.clone(), + "level" => heading.level as f64, + } + }) .collect::>(), }); } diff --git a/src/docs/document.rs b/src/docs/document.rs index ccfa197..b347825 100644 --- a/src/docs/document.rs +++ b/src/docs/document.rs @@ -60,8 +60,8 @@ pub struct DocumentVariant { pub markdown: String, /// Rendered HTML. pub html: String, - /// Section headings, in order, as pairs of anchor identifier and text. - pub headings: Vec<(String, String)>, + /// Section headings, in order. + pub headings: Vec, /// Concept identifiers referenced by the body. pub references: Vec, } @@ -279,9 +279,8 @@ fn split_list(value: &str) -> Vec { .collect() } -/// Collects the headings of a Markdown body as pairs of anchor and text. -fn collect_headings(markdown: &str) -> Vec<(String, String)> { - let mut headings = Vec::new(); +fn collect_headings(markdown: &str) -> Vec { + let mut headings: Vec = Vec::new(); let mut in_code = false; for line in markdown.lines() { let trimmed = line.trim_end(); @@ -298,20 +297,53 @@ fn collect_headings(markdown: &str) -> Vec<(String, String)> { .count(); if (1..=6).contains(&hashes) && trimmed[hashes..].starts_with(' ') { let text = trimmed[hashes..].trim(); - headings.push((slug(text), text.to_string())); + // The anchor must match the one the renderer emits, and two + // headings can reduce to the same text, so a repeat is numbered + // the way the renderer numbers it. + let base = slug(text); + let repeats = headings + .iter() + .filter(|heading| heading.base == base) + .count(); + let anchor = if repeats == 0 { + base.clone() + } else { + format!("{base}-{}", repeats + 1) + }; + headings.push(Heading { + base, + anchor, + text: text.to_string(), + level: hashes as u32, + }); } } headings } +/// One heading of a document. +#[derive(Debug, Clone)] +pub struct Heading { + /// The anchor before the uniqueness suffix, used to detect a repeat. + pub base: String, + /// The anchor the document carries for this heading. + pub anchor: String, + /// The heading text. + pub text: String, + /// The heading level, from one to six. + pub level: u32, +} + /// Returns a URL friendly slug, matching the anchors the Markdown renderer /// emits. fn slug(text: &str) -> String { let mut slug = String::with_capacity(text.len()); let mut last_dash = true; for character in text.chars() { - if character.is_ascii_alphanumeric() { - slug.push(character.to_ascii_lowercase()); + if character.is_alphanumeric() { + for lowered in character.to_lowercase() { + slug.push(lowered); + } last_dash = false; } else if !last_dash { slug.push('-'); @@ -889,7 +921,7 @@ BSTAR 项。 assert_eq!(document.prerequisites, vec!["tle"]); assert_eq!(document.references(), vec!["tle"]); assert_eq!(document.english.headings.len(), 2); - assert_eq!(document.english.headings[1].0, "drag"); + assert_eq!(document.english.headings[1].anchor, "drag"); assert!(document.english.html.contains(" String { /// shortcut link whose name is not in the set is left as a code span, so a /// doc comment can write `[`0, 1`]` without producing a link to nothing. pub fn render_with(markdown: &str, items: Option<&std::collections::HashSet>) -> String { + // Anchors must be unique within the document: two headings that reduce + // to the same text would otherwise share one anchor, and the second + // entry of a table of contents would scroll to the first. + let mut seen: std::collections::HashMap = std::collections::HashMap::new(); let lines: Vec<&str> = markdown.lines().collect(); let mut output = String::with_capacity(markdown.len() + markdown.len() / 2); let mut index = 0; @@ -70,7 +74,17 @@ pub fn render_with(markdown: &str, items: Option<&std::collections::HashSet{}#\n", escape(&id), @@ -609,8 +623,14 @@ fn slug(text: &str) -> String { let mut slug = String::with_capacity(text.len()); let mut last_dash = true; for character in text.chars() { - if character.is_ascii_alphanumeric() { - slug.push(character.to_ascii_lowercase()); + // Letters of any script are kept, so a Chinese heading keeps its own + // characters instead of collapsing to the fallback. Keeping only the + // ASCII ones gave every Chinese heading the same anchor, so the + // table of contents pointed every entry at the first section. + if character.is_alphanumeric() { + for lowered in character.to_lowercase() { + slug.push(lowered); + } last_dash = false; } else if !last_dash { slug.push('-'); @@ -791,6 +811,24 @@ mod tests { assert!(!html.contains("data-api"), "{html}"); } + #[test] + fn a_chinese_heading_keeps_its_own_anchor() { + // Only ASCII letters were kept, so every Chinese heading reduced to + // the fallback and the whole table of contents pointed at the first + // section. + let html = render("# 时间尺度\n\n正文。\n\n# 单位约定\n\n更多。\n"); + assert!(html.contains("id=\"时间尺度\""), "{html}"); + assert!(html.contains("id=\"单位约定\""), "{html}"); + assert!(!html.contains("id=\"section\""), "{html}"); + } + + #[test] + fn a_repeated_heading_gets_a_distinct_anchor() { + let html = render("# 说明\n\n甲。\n\n# 说明\n\n乙。\n"); + assert!(html.contains("id=\"说明\""), "{html}"); + assert!(html.contains("id=\"说明-2\""), "{html}"); + } + #[test] fn renders_concept_links() { let html = render("See [[sgp4]] and [[tle|the element set]].\n");