Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/retrowin/llms.txt

Use this file to discover all available pages before exploring further.

RetroWin is deployed as a static site on GitHub Pages. GitHub Pages serves files directly from the repository — it cannot intercept unknown paths and rewrite them to index.html the way a Node server would. That means HTML5 history-mode routing (URLs like /about) would return a 404 for any direct link or refresh that lands outside the repo root. To work around this, RetroWin uses React Router v6’s HashRouter, which stores the current route in the URL fragment (/#/about). The browser never sends the fragment to the server, so the page load always succeeds and React Router reads the hash client-side.
Hash-based URLs look like https://yoursite.github.io/#/about. The part after # is never sent to the server — it is purely a client-side signal that React Router reads on load and on every navigation.

​
Route definitions

Routes are declared inside the root ud() component, nested inside HashRouter. There are four named routes, each rendering a RetroWindow-wrapped page: 
<Routes>
  <Route path="/about"    element={<AboutWindow />} />
  <Route path="/projects" element={<ProjectsWindow />} />
  <Route path="/skills"   element={<SkillsWindow />} />
  <Route path="/contact"  element={<ContactWindow />} />
</Routes>
When no route matches (i.e. the hash is #/ or empty), <Routes> renders nothing from this block. The Desktop component independently checks useLocation().pathname === "/" and, when true, renders the welcome.htm RetroWindow directly — not through a <Route>.

​
Navigation

There are two ways to trigger a route change in RetroWin: useNavigate() hook — used in Taskbar (Start menu items) and in RetroWindow (the “X” close button). useNavigate returns an imperative navigate function that pushes a new entry into the router history. 
// Taskbar.js — Start menu button
const navigate = useNavigate();
const handleNav = (path) => {
  navigate(path);
  setIsOpen(false);
};

// RetroWindow.js — close button
const navigate = useNavigate();
const handleClose = () => {
  onClose ? onClose() : navigate("/");
};
DesktopIcon double-click — DesktopIcon also calls useNavigate() internally. Double-clicking any desktop icon (or single-tapping on mobile, where window.innerWidth < 768) calls navigate(to) with the icon’s to prop: 
// DesktopIcon.js
const navigate = useNavigate();
const handleOpen = () => {
  if (to) navigate(to);
  if (onClick) onClick();
};
Hash anchor links — the welcome window uses plain <a href="#/about"> anchors for its navigation list. These bypass React Router entirely and update the URL hash directly, which HashRouter then picks up automatically: 
<a href="#/about"    className="underline hover:text-win-pink">Read about me</a>
<a href="#/projects" className="underline hover:text-win-pink">See my projects</a>
<a href="#/contact"  className="underline hover:text-win-pink">Sign the guestbook</a>

​
Static HTML pages

GitHub Pages can serve individual HTML files directly. RetroWin ships a static HTML page for each route under pages/: 
pages/
  About.html
  Projects.html
  Skills.html
  Contact.html
Each file loads the full React bundle (assets/main.js) and sets a window.__STATIC_PAGE_ROUTE__ flag, then redirects the hash so the correct window opens when the page loads. This means a link to pages/About.html will land on the teal desktop with the About window already open: 
<script>
  window.__STATIC_PAGE_ROUTE__ = "/about";
  if (!window.location.hash || window.location.hash === "#/" || window.location.hash === "#") {
    window.location.hash = "/about";
  }
</script>
If the user already has a hash in their URL (e.g. they navigated there from within the app), the script leaves it untouched — only a bare or root hash triggers the redirect.

​
Adding a new route

1

Create the page component

Add a new function component in main.js (or as a separate file imported into it). Wrap the content in <RetroWindow>, giving it a title, url, defaultPosition, width, and height:
function ResumeWindow() {
  return (
    <RetroWindow
      title="resume.pdf"
      url="http://127.0.0.1/resume.pdf"
      defaultPosition={{ x: 180, y: 90 }}
      width={640}
      height={480}
    >
      {/* page content */}
    </RetroWindow>
  );
}
2

Register the route

Add a <Route> inside the existing <Routes> block in ud():
<Route path="/resume" element={<ResumeWindow />} />
3

Add a desktop icon

In the Desktop component (ed() in main.js), add a <DesktopIcon> with a matching to prop:
<DesktopIcon icon="exe" label="resume.pdf" to="/resume" />
4

Add a Start menu entry

In Taskbar.js, add a button inside the Start menu popup that calls handleNav("/resume"):
<button onClick={() => handleNav("/resume")} className="text-left px-4 py-2 hover:bg-win-navy hover:text-white font-sans text-sm flex items-center gap-2">
  <span className="w-4 h-4 bg-win-light inline-block border border-black" />
  Resume
</button>
5

Create a static HTML page (optional)

Copy pages/About.html to pages/Resume.html and update the __STATIC_PAGE_ROUTE__ value and the hash redirect target to /resume. This enables direct linking to the resume page on GitHub Pages.

Build docs developers (and LLMs) love

Get started for freeTalk to us