Optimizing Vitepress Layout and Typography Improvements

[nschimme]

Description

Optimizing Vitepress Layout and Typography Improvements

Related Issue

Checklist

• Wiki Rules: I have followed the Content Rules (mortal knowledge only) and Spoiler Rules (using ::: details Spoiler) as defined in the Contributing Guide.
• Content Accuracy: I have verified the information added/changed is accurate to the game.
• Visual Check: I have verified that the page renders correctly (no broken tables, lists, or styling).
• Local Build: (For coders) Ran docker compose up --build wiki (or npm run docs:build) and verified changes locally.
• Index Pages: Updated top-level index pages (e.g., docs/guides.md, docs/classes.md) if a major new page was added.

---

Summary by Sourcery

Optimize VitePress documentation layout and typography for improved readability and skimmability across screen sizes.

Enhancements:

• Adjust documentation font size and heading hierarchy for better readability and visual hierarchy within .vp-doc pages.
• Refine spacing and flow between paragraphs, lists, code blocks, and custom blocks to reduce visual clutter and cumulative gaps.
• Increase documentation content width and container sizing while keeping homepage and ultra-wide layouts distinct and readable.
• Style the sidebar outline ('On this page') section with adjusted typography and hover/active states for clearer navigation.
• Align hero and feature titles with the updated gold color and typographic tuning on the homepage.
• Constrain documentation layout width on very large screens while preserving a wider layout for non-doc pages.

[sourcery-ai]

Reviewer's Guide

Refines VitePress documentation layout and typography by narrowing doc font size, restructuring heading and body spacing, widening the doc content width while constraining it on ultra-wide screens, and restyling the "On this page" aside and hero/feature headings for better readability and visual hierarchy.

State diagram for responsive documentation layout breakpoints

stateDiagram-v2
  direction LR

  [*] --> viewport_lt_960

  state viewport_lt_960 {
    [*] --> mobile_layout
    mobile_layout: VPDoc_content_width_default
    mobile_layout: VPDoc_container_width_default
  }

  viewport_lt_960 --> viewport_960_to_1439: viewport_width_ge_960
  viewport_960_to_1439 --> viewport_ge_1440: viewport_width_ge_1440

  state viewport_960_to_1439 {
    [*] --> doc_with_sidebar
    doc_with_sidebar: VPDoc_has_sidebar_true
    doc_with_sidebar: content_max_width_mume_doc_max_width
    doc_with_sidebar: container_max_width_mume_doc_container_max_width

    doc_with_sidebar --> doc_without_sidebar: toggle_sidebar_off

    state doc_without_sidebar {
      [*] --> doc_without_sidebar_inner
      doc_without_sidebar_inner: VPDoc_has_sidebar_false
      doc_without_sidebar_inner: content_max_width_mume_doc_max_width
      doc_without_sidebar_inner: container_max_width_mume_doc_container_max_width
    }

    doc_without_sidebar --> doc_with_sidebar: toggle_sidebar_on
  }

  state viewport_ge_1440 {
    [*] --> ultra_wide_home_or_other
    ultra_wide_home_or_other: root_vp_layout_max_width_2400

    ultra_wide_home_or_other --> ultra_wide_doc

    state ultra_wide_doc {
      [*] --> doc_layout_constrained
      doc_layout_constrained: VPDoc_vp_layout_max_width_1440
      doc_layout_constrained: content_max_width_mume_doc_max_width
      doc_layout_constrained: container_max_width_mume_doc_container_max_width
    }
  }

Loading

File-Level Changes

Change	Details	Files
Adjust documentation typography (font sizing, headings, and text flow) for improved readability and skimming.	Introduce documentation-specific CSS custom properties for max widths and base font size, including --mume-doc-max-width, --mume-doc-container-max-width, and --mume-font-size-doc. Scope a reduced base font size to .vp-doc and adjust heading styles (weights, letter-spacing, margins, font-sizes, and line-heights) for h1–h3 within .vp-doc. Standardize vertical rhythm in .vp-doc by using top margins on paragraphs, summaries, blockquotes, tables, code blocks, and custom blocks, and tweak list spacing to avoid cumulative gaps while preserving multi-paragraph list items.	docs/.vitepress/theme/style.css
Reconfigure documentation layout widths and ultra-wide behavior for better line length and separation between docs and other pages.	Remove the previous global wide-screen layout overrides and instead add media-query-based max-width adjustments for #VPContent .VPDoc .content, .container, and .content-container to achieve ~1000px text width at appropriate breakpoints. Add ultra-wide (min-width: 1920px) behavior that maintains a 2400px layout max width globally while constraining .VPDoc pages to a 1440px layout max width for improved readability.	docs/.vitepress/theme/style.css
Restyle the documentation aside outline and hero/feature titles to align with the new typography system.	Add styles for #VPContent .VPDocAside, including a left border, smaller uppercase outline title with muted color, and refined outline link colors, sizes, and hover/active behaviors. Ensure the home hero name and feature titles use the gold color, Georgia-based typography, and consistent weight/letter-spacing to match the rest of the site’s visual hierarchy.	docs/.vitepress/theme/style.css

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}