Add dark website and documentation with GitHub Pages deployment

Include the updated desktop screenshot, active-monitor screenshot capture and editor locking, and Settings window drag areas.

site/README.md

@@ -0,0 +1,38 @@
+# Ferese website and handbook
+
+The public site is static HTML and CSS. The handbook is generated from the
+project's Markdown guides, so website and repository documentation stay in sync.
+There are no client frameworks, external fonts, or tracking scripts.
+
+## Local preview
+
+```sh
+python3 -m venv .site-venv
+.site-venv/bin/pip install -r site/requirements.txt
+.site-venv/bin/python scripts/build-site.py
+python3 -m http.server 8080 --bind 127.0.0.1 --directory build/site
+```
+
+Open http://localhost:8080 or http://localhost:8080/docs/. Rebuild after editing
+site sources or Markdown guides, then refresh the browser.
+
+- `site/index.html` and `site/styles.css`: homepage and shared visual design.
+- `site/content/index.md`: handbook introduction.
+- `docs/{installation,configuration,desktop-widgets,notifications}.md`: source guides.
+- `scripts/build-site.py`: renders Markdown, resolves links, generates section
+  navigation, previous/next links, and the search index.
+- `site/app.js`: handbook search and code copying. Reading and navigation work
+  without JavaScript. Search is local to the browser, with no third-party service.
+
+## GitHub Pages
+
+Select **Settings → Pages → Source → GitHub Actions**. The Pages workflow
+publishes site and documentation changes pushed to `main`, or can run manually.
+Expected URL: https://borngraced.github.io/ferese/.
+
+Local links are relative, including documentation search, so publishing under
+the `/ferese/` project path works. Screenshots are copied from `docs/images`
+during the build; the generated `build/site` directory is ignored by Git.
+
+See [GitHub's custom workflow documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages)
+for deployment setup.

site/app.js

@@ -0,0 +1,130 @@
+// Progressive enhancement for the handbook. Navigation and content work without JS.
+const search = document.querySelector("#docs-search");
+const results = document.querySelector("#search-results");
+const status = document.querySelector("#search-status");
+let indexPromise;
+if (search) {
+  search.closest(".docs-search").hidden = false;
+  const loadIndex = () =>
+    (indexPromise ||= fetch("search-index.json")
+      .then((response) => {
+        if (!response.ok) throw new Error("Search index unavailable");
+        return response.json();
+      })
+      .catch((error) => {
+        indexPromise = null;
+        throw error;
+      }));
+  search.addEventListener("focus", () => {
+    loadIndex().catch(() => {});
+  });
+  search.addEventListener("input", async () => {
+    const query = search.value.trim().toLocaleLowerCase();
+    if (!query) {
+      results.hidden = true;
+      results.replaceChildren();
+      status.textContent = "";
+      return;
+    }
+    try {
+      const index = await loadIndex();
+      if (search.value.trim().toLocaleLowerCase() !== query) return;
+      const words = query.split(/\s+/);
+      const matches = index
+        .filter((item) =>
+          words.every((word) =>
+            `${item.page} ${item.heading} ${item.text}`
+              .toLocaleLowerCase()
+              .includes(word),
+          ),
+        )
+        .sort(
+          (a, b) =>
+            Number(b.heading.toLocaleLowerCase().includes(query)) -
+            Number(a.heading.toLocaleLowerCase().includes(query)),
+        )
+        .slice(0, 10);
+      results.replaceChildren();
+      for (const item of matches) {
+        const link = document.createElement("a");
+        link.href = item.url;
+        const title = document.createElement("strong");
+        title.textContent = `${item.page} / ${item.heading}`;
+        const snippet = document.createElement("span");
+        const position = Math.max(
+          0,
+          item.text.toLocaleLowerCase().indexOf(words[0]) - 45,
+        );
+        snippet.textContent = `${position ? "…" : ""}${item.text.slice(position, position + 165)}${item.text.length > position + 165 ? "…" : ""}`;
+        link.append(title, snippet);
+        results.append(link);
+      }
+      if (!matches.length) {
+        const empty = document.createElement("p");
+        empty.textContent =
+          "No matching sections. Try “wallpaper”, “shortcuts”, or “notifications”.";
+        results.append(empty);
+      }
+      results.hidden = false;
+      status.textContent = `${matches.length} matching sections.`;
+    } catch {
+      if (search.value.trim().toLocaleLowerCase() !== query) return;
+      results.hidden = true;
+      status.textContent = "Search is unavailable. Browse the guides below.";
+    }
+  });
+  document.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") {
+      results.hidden = true;
+      search.focus();
+    }
+    if (
+      event.key === "/" &&
+      !["INPUT", "TEXTAREA"].includes(document.activeElement.tagName) &&
+      !event.ctrlKey &&
+      !event.metaKey &&
+      !event.altKey
+    ) {
+      event.preventDefault();
+      search.focus();
+    }
+    if (
+      event.key === "ArrowDown" &&
+      document.activeElement === search &&
+      !results.hidden
+    ) {
+      const first = results.querySelector("a");
+      if (first) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+  });
+  document.addEventListener("click", (event) => {
+    if (!event.target.closest(".docs-search")) results.hidden = true;
+  });
+}
+if (navigator.clipboard?.writeText) {
+  for (const block of document.querySelectorAll(".prose pre")) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "code-copy";
+    button.textContent = "Copy";
+    button.setAttribute("aria-label", "Copy code example");
+    button.addEventListener("click", async () => {
+      try {
+        await navigator.clipboard.writeText(
+          block.querySelector("code").textContent,
+        );
+        button.textContent = "Copied";
+        if (status) status.textContent = "Code example copied.";
+      } catch {
+        button.textContent = "Select to copy";
+        if (status)
+          status.textContent =
+            "Copy failed. Select the code to copy it manually.";
+      }
+    });
+    block.append(button);
+  }
+}

site/content/index.md

@@ -0,0 +1,59 @@
+# The Ferese handbook
+
+Ferese is a complete Wayland desktop built around personalization. Its custom shell, native Settings, live themes, and flexible layouts work together as one cohesive experience.
+
+This handbook covers installing Ferese, finding your way around, and making the desktop your own.
+
+## Start with your first session
+
+1. Read [Installation](installation.md) for the supported setup, building, and recovery.
+2. Open **Control Center → Settings** to choose a theme and configure your desktop.
+3. Explore the [configuration reference](configuration.md) for layouts, shortcuts, window rules, and displays.
+
+Want to try it before switching desktops? The [preview instructions](installation.md#preview-and-logs) cover running Ferese inside an existing Wayland session.
+
+## Find your way around
+
+Ferese supports scrolling columns, tree tiling, floating windows, and a workspace overview. These are the built-in keyboard shortcuts; all can be changed in Settings.
+
+| Shortcut | Action |
+| --- | --- |
+| Super + Enter | Open a terminal |
+| Super + H / J / K / L | Focus a window |
+| Super + R | Cycle column width |
+| Super + Tab | Open workspace and window overview |
+| Super + M | Switch scrolling / tree layout |
+| Super + Shift + S | Select a screenshot area |
+
+Three-finger swipes move between workspaces and windows. Open **Control Center → Settings → Shortcuts** to change the defaults or assign gestures to other actions.
+
+## Make it feel like yours
+
+Use **Settings** for everyday customization. Choose an appearance preset, change the wallpaper, adjust shell and window corners, or add a clock and sticky notes through [Desktop widgets](desktop-widgets.md).
+
+[Notifications](notifications.md) explains popup cards, history, Do Not Disturb, and app actions.
+
+If you prefer a text editor, your configuration lives at:
+
+```text
+~/.config/ferese/config.kdl
+```
+
+Ferese reloads changes as you make them. An invalid edit keeps the last working configuration. Settings also preserves a backup of your previous save. See [Saving and validation](configuration.md#saving-and-validation).
+
+## Keep a recovery path
+
+Keep another desktop session available while testing hardware behavior. Save your work before logging out: `feresectl exit` and **Super + Shift + E** end the current session immediately.
+
+The [recovery guide](installation.md#logout-and-recovery) explains logs, installed releases, and rollback.
+
+## Work on Ferese
+
+Ferese is built in Rust on Smithay. Use release builds when evaluating motion and startup performance. From the repository checkout:
+
+```sh
+cargo test --workspace --locked
+cargo fmt --all --check
+```
+
+The [source repository](https://github.com/borngraced/ferese) is the place to explore implementation details and report issues. When reporting a problem, include how to reproduce it, whether you used the nested or DRM backend, and relevant logs.

site/index.html

@@ -0,0 +1,128 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#10151c" />
+    <meta
+      name="description"
+      content="Ferese is a beautiful, fluid Wayland desktop made to feel like yours. Explore the desktop, then get started with the documentation."
+    />
+    <meta
+      property="og:title"
+      content="Ferese — A desktop that feels like yours"
+    />
+    <meta
+      property="og:description"
+      content="A complete Wayland desktop built around personalization."
+    />
+    <meta property="og:type" content="website" />
+    <meta
+      property="og:image"
+      content="https://borngraced.github.io/ferese/assets/ferese-desktop.png"
+    />
+    <meta name="twitter:card" content="summary_large_image" />
+    <title>Ferese — A desktop that feels like yours</title>
+    <link rel="icon" href="assets/ferese.svg" type="image/svg+xml" />
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <a class="skip" href="#main">Skip to content</a>
+    <header class="site-header">
+      <div class="header-inner">
+        <a class="wordmark" href="./" aria-label="Ferese home"
+          ><svg viewBox="0 0 24 24" aria-hidden="true">
+            <path d="M3 3h6v18H3zM11 3h10v6H11zM11 11h7v6h-7z" /></svg
+          >ferese</a
+        >
+        <nav aria-label="Main navigation">
+          <a href="./" aria-current="page">Overview</a
+          ><a href="docs/">Documentation</a
+          ><a href="https://github.com/borngraced/ferese"
+            >GitHub <span aria-hidden="true">↗</span></a
+          >
+        </nav>
+      </div>
+    </header>
+    <main id="main" class="simple-home">
+      <section class="product-intro page-width">
+        <h1>Ferese</h1>
+        <p class="product-tagline">
+          A beautiful, fluid Wayland desktop made to feel like yours.
+        </p>
+        <p class="product-description">
+          A complete Linux desktop with a custom shell, native settings,
+          scrolling and tiling layouts, and live-reloading themes.
+        </p>
+        <div class="product-links">
+          <a class="button" href="docs/installation.html">Install Ferese</a>
+          <a class="button secondary" href="docs/">Documentation</a>
+          <a class="source-link" href="https://github.com/borngraced/ferese"
+            >Source code ↗</a
+          >
+        </div>
+      </section>
+      <figure class="product-screenshot page-width">
+        <a
+          href="assets/ferese-desktop.png"
+          aria-label="View the full-resolution Ferese desktop screenshot"
+        >
+          <img
+            src="assets/ferese-desktop.png"
+            width="2880"
+            height="1800"
+            alt="Ferese Blue desktop with the default wallpaper, Settings, Control Center and clock widget"
+            fetchpriority="high"
+          />
+        </a>
+        <figcaption>
+          Ferese Blue with Settings, Control Center, and the default wallpaper.
+        </figcaption>
+      </figure>
+      <section class="product-features page-width" aria-label="Features">
+        <article>
+          <h2>Flexible layouts</h2>
+          <p>
+            Scrolling columns, tree tiling, floating windows, and a workspace
+            overview. Use keyboard shortcuts or gestures to move around.
+          </p>
+          <a href="docs/configuration.html#layout">Configure layouts →</a>
+        </article>
+        <article>
+          <h2>A native desktop</h2>
+          <p>
+            A menu bar, Control Center, Settings, notifications, and desktop
+            widgets, designed to work together.
+          </p>
+          <a href="docs/">Explore the handbook →</a>
+        </article>
+        <article>
+          <h2>Make it yours</h2>
+          <p>
+            Choose your theme, wallpaper, colors, and motion. Change settings
+            through the app or a KDL config, with live reload.
+          </p>
+          <a href="docs/configuration.html#appearance">Customize Ferese →</a>
+        </article>
+      </section>
+      <section class="product-getting-started page-width">
+        <h2>Getting started</h2>
+        <p>
+          The <a href="docs/installation.html">installation guide</a> covers
+          Fedora with SDDM. You can also
+          <a href="docs/installation.html#preview-and-logs">preview Ferese</a>
+          inside an existing Wayland session before installing.
+        </p>
+        <p>
+          Built in Rust on Smithay. Development happens
+          <a href="https://github.com/borngraced/ferese">on GitHub</a>.
+        </p>
+      </section>
+    </main>
+    <footer class="site-footer page-width">
+      <a class="wordmark" href="./">ferese</a>
+      <p>A beautiful, fluid Wayland desktop.</p>
+      <a href="docs/">Read the handbook <span aria-hidden="true">↗</span></a>
+    </footer>
+  </body>
+</html>

site/requirements.txt

@@ -0,0 +1,2 @@
+markdown-it-py==3.0.0
+mdurl==0.1.2