Snoooopy/winutil
1
0
Fork 0
mirror of https://github.com/ChrisTitusTech/winutil.git synced 2026-08-09 17:41:14 +10:00
Code Issues Packages Projects Releases Wiki Activity

Fix alignment issues, update links, and enhance documentation (#4898)

Browse Source 
* Fix the same arrow-icon alignment issue on the "Read the Docs" button

Same root cause as the hero/final-CTA buttons: the label was plain
markdown text, which MDX wrapped in a <p>, and the icon was missing
the size/nudge applied elsewhere. Match it to the other two buttons.

* Rename known-issues page slug to knownissues

Update the sidebar config, nav dropdown, and every internal link that
pointed at /known-issues/ to match.

* Fix image paths in root-level markdown to match the new docs site

The Hugo docs site (docs/assets/images/...) has been replaced by the
Astro site (docs/src/assets/...); update CONTRIBUTING.md,
READMEITALIAN.md, and README.md to point at the new asset locations.

* Remove unused houston.webp asset

Leftover Starlight default-theme asset with no references anywhere
in the docs site.

* Fix docs site reference in generator docs

Updates `tools/devdocs-generator.md` to describe link generation correctly: links now point to the Astro/Starlight documentation site instead of the old Hugo site.

* Point docs homepage CTAs to guides hub

Updates the docs landing page CTA links to use `/guides/` instead of `/guides/getting-started/` in the hero action and both “Get Started”/“Read the Docs” buttons, routing users to the guides index.

* Add reusable YouTube embeds to docs guides

Introduces a new `YouTubeEmbed.astro` component for responsive 16:9 video embeds using the privacy-enhanced `youtube-nocookie.com` domain. The User Guide index and Tweaks guide now import and use this component instead of plain YouTube links, and the component includes styling that overrides Starlight’s iframe reset so embedded videos render at the correct size.

* Fix YouTube embed iframe height via not-content

Add the `not-content` class to the embed wrapper so Starlight's markdown reset no longer overrides `iframe { height: auto }`. Drop the `@layer starlight.core` wrapper and `!important` overrides that were compensating for the same issue.

* Clarify docs comments across Astro components

Adds and refines inline comments in the docs site config, custom Starlight components, and theme styles to better explain layout structure, navigation dropdown behavior, hero composition, and theme initialization. Also normalizes a few multi-line comments into single-line form for readability without changing functionality.

* Set secondary docs button background color

Update `.wu-btn-secondary` in the docs theme to use `var(--sl-color-gray-6)` instead of a transparent background, improving button visibility and contrast while keeping existing border and hover behavior.

* Move User Guides into docs dropdown

Updates the docs header navigation so the “User Guides” link is grouped under the existing “Documentation” dropdown instead of appearing as a separate top-level nav item. This keeps related documentation links together and simplifies the top navigation.

* Fix hero margin and center trust section

Remove the automatic 1.5rem top margin Starlight adds between the hero and the content column. Also flex-center the trust section so its content is properly aligned.

* Disable edit links in generated dev docs

Update `tools/devdocs-generator.ps1` to include `editUrl: false` in the frontmatter for generated tweak and feature docs pages. This prevents Starlight from showing edit links on these auto-generated pages.

* Move docs update PRs to pre-release flow

The docs Pages workflow is simplified to only build and deploy the docs site: it now triggers only on docs changes, drops extra permissions/default shell settings, and removes the dev-docs generation + auto-PR steps. The pre-release workflow now owns that automation by expanding its PR step to include generated code-reference docs alongside JSON link updates, with updated commit/title/body text and a documentation label.

* Shorten generated docs source note

Simplify the autogenerated DevDocs notice so generated pages only warn against direct edits while still linking back to the source file.

* Improve docs header dropdown behavior

Reworked the header nav dropdown triggers to use native `<details>/<summary>` instead of buttons, then updated menu visibility logic to use `details[open]` for no-JS support on touch and keyboard while preserving hover behavior. Also renamed the “Developer Docs” link to “Code Reference” and tightened related CSS comments.

* Refresh contribution and docs workflow docs

Updated contributor-facing docs to use consistent Markdown admonition blocks, cleaned Mermaid fence formatting, and fixed minor wording/capitalization in contribution steps. Clarified `devdocs-generator` behavior so workflow ownership is explicit: generation now documented as part of `pre-release.yaml` (via docs-update PR), while `docs.yaml` is documented as build/deploy only.

* Fix contributing guide grammar

Correct the "it's" to "its" typo in both contributing guides so the pull request guidance is consistent across the GitHub and docs versions.
This commit is contained in:
Sean (ANGRYxScotsman)
2026-08-03 10:23:31 -05:00
committed by GitHub
parent e591161dac
commit e96f990c60
23 changed files with 182 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/src/components/CornerCard.astro
+4
View File
@@ -12,11 +12,13 @@ const { icon, title } = Astro.props;
---
<div class="wu-corner-card">
{/* Corner brackets decoration. */}
<span class="wu-corner-marks" aria-hidden="true">
<span class="mark top-left" /><span class="mark top-right" /><span class="mark bottom-left" /><span
class="mark bottom-right"
/>
</span>
{/* Icon badge + heading + description. */}
<div class="wu-corner-card-icon">
<Icon name={icon} size="1.25rem" />
</div>
@@ -36,6 +38,7 @@ const { icon, title } = Astro.props;
background-color: var(--sl-color-bg);
}
/* Corner brackets decoration (four small L-shaped marks). */
.wu-corner-marks {
position: absolute;
inset: 0;
@@ -93,6 +96,7 @@ const { icon, title } = Astro.props;
right: 0;
}
/* Icon badge + heading + description. */
.wu-corner-card-icon {
display: flex;
align-items: center;
docs/src/components/Footer.astro
+7 -4
View File
@@ -9,12 +9,14 @@ const year = new Date().getFullYear();
---
<footer class="sl-flex">
{/* Edit link + last-updated timestamp, and prev/next pagination. */}
<div class="meta sl-flex">
<EditLink />
<LastUpdated />
</div>
<Pagination />
{/* "Built with Starlight" credit (only shown if Starlight's `credits` config is enabled). */}
{
config.credits && (
<a class="kudos sl-flex" href="https://starlight.astro.build">
@@ -23,11 +25,13 @@ const year = new Date().getFullYear();
)
}
{/* Copyright line. */}
<div class="site-footer-copyright">© {year} <a href="https://christitus.com">Chris Titus Tech</a>. All rights reserved.</div>
</footer>
<style>
@layer starlight.core {
/* Footer layout: stacked meta row + pagination. */
footer {
flex-direction: column;
gap: 1.5rem;
@@ -44,6 +48,7 @@ const year = new Date().getFullYear();
margin-inline-start: auto;
}
/* "Built with Starlight" credit link. */
.kudos {
align-items: center;
gap: 0.5em;
@@ -63,16 +68,14 @@ const year = new Date().getFullYear();
}
}
/* Collapse the meta/pagination rows entirely when they have nothing in them
(e.g. editUrl: false and no prev/next), instead of leaving an empty gap. */
/* Collapse the meta/pagination rows entirely when they have nothing in them (e.g. editUrl: false and no prev/next), instead of leaving an empty gap. */
footer .meta:empty,
footer :global(.pagination-links):empty {
display: none;
margin: 0;
}
/* Site-wide copyright line, matching the previous Hugo docs site's footer.
The divider above it comes from Starlight's own .content-panel border. */
/* Site-wide copyright line, matching the previous Hugo docs site's footer. The divider above it comes from Starlight's own .content-panel border. */
.site-footer-copyright {
font-size: var(--sl-text-xs);
color: var(--sl-color-gray-3);
docs/src/components/Header.astro
+36 -17
View File
@@ -7,35 +7,42 @@ import SiteTitle from 'virtual:starlight/components/SiteTitle';
import SocialIcons from 'virtual:starlight/components/SocialIcons';
import ThemeSelect from 'virtual:starlight/components/ThemeSelect';
/**
* Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
*/
// Render the `Search` component if Pagefind is enabled or the default search component has been overridden.
const shouldRenderSearch =
config.pagefind || config.components.Search !== '@astrojs/starlight/components/Search.astro';
---
<div class="header">
{/* Site title. */}
<div class="title-wrapper sl-flex">
<SiteTitle />
</div>
{/* Search box. */}
<div class="sl-flex print:hidden">
{shouldRenderSearch && <Search />}
</div>
{/* Right-side group: nav links, social icons, theme/language pickers. */}
<div class="sl-hidden md:sl-flex print:hidden right-group">
<nav class="site-nav" aria-label="Top">
<a class="site-nav-link" href="/guides/">User Guides</a>
{/* "Documentation" dropdown. */}
<div class="site-nav-dropdown">
<button type="button" class="site-nav-link" aria-haspopup="true">Documentation</button>
<details name="site-nav-dropdown">
<summary class="site-nav-link">Documentation</summary>
</details>
<div class="site-nav-menu">
<a href="/guides/">User Guides</a>
<a href="/contributing/">Contribution Guides</a>
<a href="/code-reference/architecture/">Developer Docs</a>
<a href="/code-reference/architecture/">Code Reference</a>
</div>
</div>
{/* "Help" dropdown. */}
<div class="site-nav-dropdown">
<button type="button" class="site-nav-link" aria-haspopup="true">Help</button>
<details name="site-nav-dropdown">
<summary class="site-nav-link">Help</summary>
</details>
<div class="site-nav-menu">
<a href="/faq/">FAQ</a>
<a href="/known-issues/">Known Issues</a>
<a href="/knownissues/">Known Issues</a>
<a href="https://forum.christitus.com/" target="_blank" rel="noreferrer">Forums</a>
</div>
</div>
@@ -51,6 +58,7 @@ const shouldRenderSearch =
<style>
@layer starlight.core {
/* Header shell: title, search, right-side nav group. */
.header {
display: flex;
gap: var(--sl-nav-gap);
@@ -60,14 +68,14 @@ const shouldRenderSearch =
}
.title-wrapper {
/* Prevent long titles overflowing and covering the search and menu buttons on narrow viewports. */
/* Clips long titles instead of overflowing onto the search/menu buttons; padding/negative margin avoids clipping the focus ring. */
overflow: clip;
/* Avoid clipping focus ring around title wrapper. */
padding: 0.25rem;
margin: -0.25rem;
min-width: 0;
}
/* Right-side group: nav + social icons, divided by a hairline. */
.right-group,
.social-icons {
gap: 1rem;
@@ -86,6 +94,7 @@ const shouldRenderSearch =
:global(:root:not([data-has-toc])) {
--__toc-width: 0rem;
}
/* Columns: site title */
.header {
--__sidebar-width: max(0rem, var(--sl-content-inline-start, 0rem) - var(--sl-nav-pad-x));
--__main-column-fr: calc(
@@ -97,21 +106,18 @@ const shouldRenderSearch =
);
display: grid;
grid-template-columns:
/* 1 (site title): runs up until the main content column’s left edge or the width of the title, whichever is the largest */
minmax(
calc(var(--__sidebar-width) + max(0rem, var(--__main-column-fr) - var(--sl-nav-gap))),
auto
)
/* 2 (search box): all free space that is available. */
1fr
/* 3 (right items): use the space that these need. */
auto;
align-content: center;
}
}
}
/* Top nav links + dropdowns, matching the previous Hugo docs site's navbar. */
/* Top nav links + dropdowns. */
.site-nav {
display: flex;
align-items: center;
@@ -120,6 +126,7 @@ const shouldRenderSearch =
border-inline-end: 1px solid var(--sl-color-hairline-light);
}
/* Top nav trigger: shared style for plain links and dropdown triggers. */
.site-nav-link {
font-size: var(--sl-text-sm);
font-weight: 500;
@@ -136,13 +143,25 @@ const shouldRenderSearch =
color: var(--sl-color-white);
}
/* Extends the hoverable box down to the menu, closing the dead zone between trigger and menu. */
.site-nav-dropdown {
position: relative;
/* Extends the dropdown's own hoverable box down to meet the menu, so the
cursor never crosses a dead zone between the trigger and the menu. */
padding-bottom: 0.75rem;
margin-bottom: -0.75rem;
}
/* No box of its own; only the <summary> lays out. Its `open` state (no JS) is read by .site-nav-menu below. */
.site-nav-dropdown > details {
display: contents;
}
.site-nav-dropdown > details > summary {
display: inline-flex;
align-items: center;
list-style: none;
}
.site-nav-dropdown > details > summary::-webkit-details-marker {
display: none;
}
/* Dropdown menu panel: shown on hover (mouse) or when the sibling <details> is toggled open (touch/keyboard). */
.site-nav-menu {
display: none;
position: absolute;
@@ -160,7 +179,7 @@ const shouldRenderSearch =
z-index: 10;
}
.site-nav-dropdown:hover .site-nav-menu,
.site-nav-dropdown:focus-within .site-nav-menu {
.site-nav-dropdown:has(details[open]) .site-nav-menu {
display: flex;
}
.site-nav-menu a {
docs/src/components/Hero.astro
+7
View File
@@ -6,6 +6,7 @@ import { Icon } from '@astrojs/starlight/components';
// Matches Starlight's internal PAGE_TITLE_ID (used by the skip-to-content link).
const PAGE_TITLE_ID = '_top';
// Resolve hero content: Starlight's built-in hero fields plus our custom schema extensions.
const { data } = Astro.locals.starlightRoute.entry;
const { title = data.title, tagline, image, actions = [] } = data.hero || {};
const { heroEyebrow, heroCaption, heroBadges = [] } = data;
@@ -15,9 +16,11 @@ if (image && 'file' in image) heroImage = image.file;
---
<section class="wu-hero">
{/* Full-bleed grid/glow background layer. */}
<div class="wu-hero-grid" aria-hidden="true"></div>
<div class="wu-hero-glow" aria-hidden="true"></div>
<div class="wu-hero-inner">
{/* Copy column: eyebrow, heading, tagline, actions, caption. */}
<div class="wu-hero-copy">
{heroEyebrow && <p class="wu-eyebrow">{heroEyebrow}</p>}
<h1 id={PAGE_TITLE_ID} data-page-title set:html={title} />
@@ -42,6 +45,7 @@ if (image && 'file' in image) heroImage = image.file;
}
{heroCaption && <p class="wu-hero-caption">{heroCaption}</p>}
</div>
{/* Screenshot framed as a fake browser/app window. */}
{
heroImage && (
<div class="wu-hero-media">
@@ -66,6 +70,7 @@ if (image && 'file' in image) heroImage = image.file;
)
}
</div>
{/* Badge row (shields.io / dcbadge images) below the two-column layout. */}
{
heroBadges.length > 0 && (
<div class="wu-hero-bottom">
@@ -138,6 +143,7 @@ if (image && 'file' in image) heroImage = image.file;
padding-block: 3rem 2rem;
}
/* Hero copy: eyebrow, heading, tagline, actions, caption. */
.wu-hero-copy {
text-align: center;
}
@@ -198,6 +204,7 @@ if (image && 'file' in image) heroImage = image.file;
box-shadow: 0 25px 50px -12px hsl(0 0% 0% / 0.5);
}
/* Window chrome: title bar + traffic-light buttons. */
.wu-window-bar {
display: flex;
align-items: center;
docs/src/components/ThemeProvider.astro
+2
View File
@@ -5,10 +5,12 @@ import { Icon } from '@astrojs/starlight/components';
<script is:inline>
window.StarlightThemeProvider = (() => {
// Apply the resolved theme to <html> immediately, before paint, to avoid a flash of the wrong theme.
const storedTheme =
typeof localStorage !== 'undefined' && localStorage.getItem('starlight-theme');
const theme = storedTheme || 'dark';
document.documentElement.dataset.theme = theme === 'light' ? 'light' : 'dark';
// Re-syncs each theme-select picker's icon + value after the visitor changes theme.
return {
updatePickers(theme = storedTheme || 'auto') {
document.querySelectorAll('starlight-theme-select').forEach((picker) => {
docs/src/components/YouTubeEmbed.astro
+39
View File
@@ -0,0 +1,39 @@
---
// Responsive 16:9 YouTube embed using the privacy-enhanced (nocookie) domain.
interface Props {
id: string;
title: string;
}
const { id, title } = Astro.props;
---
<div class="wu-video-embed not-content">
<iframe
src={`https://www.youtube-nocookie.com/embed/${id}`}
title={title}
loading="lazy"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowfullscreen
></iframe>
</div>
<style>
/* `not-content` on the wrapper opts it out of Starlight's markdown reset, which otherwise forces `iframe { height: auto }`. */
.wu-video-embed {
position: relative;
width: 100%;
aspect-ratio: 16 / 9;
margin: 1.5rem 0;
border: 1px solid var(--sl-color-hairline-light);
background-color: var(--sl-color-black);
}
.wu-video-embed iframe {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
border: 0;
}
</style>