Skip to content

Commit 0d0faf4

Browse files
committed
fix(docs): prefix internal links with site base, repair broken targets
Internal absolute links in markdown were not getting the /simpledeploy base prefix, 404ing on GitHub Pages. Add a remark plugin that rewrites absolute internal URLs and JSX href/src/link attrs at build time. Hero frontmatter patched directly since remark skips frontmatter. Also fix stale link targets surfaced by the link validator: - /guides/users/roles/ -> /guides/users-roles/ - /guides/backups/ -> /guides/backups/overview/ - /simpledeploy/concepts/backups/ -> /guides/backups/overview/ - /trust -> inline note (runtime route, not a docs page) Exclude blog index and localhost dev URLs from the validator.
1 parent fc29e41 commit 0d0faf4

9 files changed

Lines changed: 78 additions & 9 deletions

File tree

docs-site/astro.config.mjs

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,17 @@ import starlightOpenAPI, { openAPISidebarGroups } from "starlight-openapi";
66
import starlightBlog from "starlight-blog";
77
import starlightLinksValidator from "starlight-links-validator";
88
import starlightImageZoom from "starlight-image-zoom";
9+
import remarkPrefixBase from "./plugins/remark-prefix-base.mjs";
910

1011
const githubRepo = "https://github.com/vazra/simpledeploy";
12+
const siteBase = "/simpledeploy";
1113

1214
export default defineConfig({
1315
site: "https://vazra.github.io",
14-
base: "/simpledeploy",
16+
base: siteBase,
17+
markdown: {
18+
remarkPlugins: [[remarkPrefixBase, { base: siteBase }]],
19+
},
1520
integrations: [
1621
svelte(),
1722
starlight({
@@ -45,7 +50,14 @@ export default defineConfig({
4550
failOnError: false,
4651
errorOnRelativeLinks: false,
4752
errorOnInvalidHashes: false,
48-
exclude: ["/reference/api", "/reference/api/**"],
53+
exclude: [
54+
"/reference/api",
55+
"/reference/api/**",
56+
"/simpledeploy/blog",
57+
"/simpledeploy/blog/",
58+
"http://localhost:**",
59+
"https://localhost:**",
60+
],
4961
}),
5062
starlightOpenAPI([
5163
{
Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
// Rewrites absolute internal links (e.g. "/start/quickstart/") in markdown
2+
// and MDX content to be prefixed with the configured site base, so that
3+
// hosting under a subpath like /simpledeploy/ does not produce 404s.
4+
//
5+
// Skips: external URLs, protocol-relative URLs, fragment-only links,
6+
// already-prefixed paths, and asset paths Astro handles itself (_astro, etc).
7+
8+
const DEFAULT_SKIP_PREFIXES = ["/_astro/", "/@", "/api/"];
9+
10+
function shouldRewrite(url, base) {
11+
if (typeof url !== "string" || url.length === 0) return false;
12+
if (!url.startsWith("/")) return false;
13+
if (url.startsWith("//")) return false;
14+
if (url.startsWith(base + "/") || url === base) return false;
15+
for (const p of DEFAULT_SKIP_PREFIXES) if (url.startsWith(p)) return false;
16+
return true;
17+
}
18+
19+
function rewrite(url, base) {
20+
return base + url;
21+
}
22+
23+
function visitNode(node, base) {
24+
if (!node || typeof node !== "object") return;
25+
26+
if ((node.type === "link" || node.type === "image") && shouldRewrite(node.url, base)) {
27+
node.url = rewrite(node.url, base);
28+
}
29+
30+
if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
31+
if (Array.isArray(node.attributes)) {
32+
for (const attr of node.attributes) {
33+
if (
34+
attr &&
35+
attr.type === "mdxJsxAttribute" &&
36+
(attr.name === "href" || attr.name === "src" || attr.name === "link") &&
37+
typeof attr.value === "string" &&
38+
shouldRewrite(attr.value, base)
39+
) {
40+
attr.value = rewrite(attr.value, base);
41+
}
42+
}
43+
}
44+
}
45+
46+
if (Array.isArray(node.children)) {
47+
for (const child of node.children) visitNode(child, base);
48+
}
49+
}
50+
51+
export default function remarkPrefixBase(options = {}) {
52+
const base = (options.base || "").replace(/\/$/, "");
53+
if (!base) return () => {};
54+
return (tree) => {
55+
visitNode(tree, base);
56+
};
57+
}

docs-site/src/content/docs/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ hero:
88
file: ../../assets/logo.svg
99
actions:
1010
- text: 5-Minute Quickstart
11-
link: /start/quickstart/
11+
link: /simpledeploy/start/quickstart/
1212
icon: right-arrow
1313
variant: primary
1414
- text: Star on GitHub

docs/concepts/state-and-storage.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,4 +56,4 @@ The DB is itself a backup target via the System page. SimpleDeploy uses SQLite `
5656
Copying the raw `simpledeploy.db` file while the process is running is unsafe. WAL pages may not yet be checkpointed. Use the System backup endpoint (which calls `VACUUM INTO`) or stop the process first.
5757
</Aside>
5858

59-
For backing up your apps' data (postgres volumes, redis dumps, app files), see [Backups](/simpledeploy/concepts/backups/) and [Backup architecture](/simpledeploy/architecture/backup/).
59+
For backing up your apps' data (postgres volumes, redis dumps, app files), see [Backups](/guides/backups/overview/) and [Backup architecture](/architecture/backup/).

docs/first-deploy/admin.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,6 @@ The full key is shown only once. If you lose it, revoke it and create a new one.
7979
| `admin` | All apps + most settings (no user management) |
8080
| `user` | Only the apps explicitly granted to them |
8181

82-
Per-app access for `user` accounts is set under **Users &rarr; (user) &rarr; App access**. See [Roles and permissions](/guides/users/roles/).
82+
Per-app access for `user` accounts is set under **Users &rarr; (user) &rarr; App access**. See [Roles and permissions](/guides/users-roles/).
8383

8484
Next: [write your first compose file](/first-deploy/compose/).

docs/first-deploy/ui.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ The fastest way to deploy if you already have the dashboard open.
2424

2525
Templates ask you to pick an **Access mode** before continuing:
2626

27-
- **Quick test** (default): SimpleDeploy auto-generates a `<slug>.<server-ip>.sslip.io` domain and issues a self-signed cert via Caddy's internal CA. No DNS setup needed. Browsers will warn about the certificate until you install the root cert from the [Trust page](/trust). Best for trying a template in minutes on a homelab, LAN, or VPS without public DNS.
27+
- **Quick test** (default): SimpleDeploy auto-generates a `<slug>.<server-ip>.sslip.io` domain and issues a self-signed cert via Caddy's internal CA. No DNS setup needed. Browsers will warn about the certificate until you install the root cert from the **Trust** page on your SimpleDeploy server (`/trust` on the server URL). Best for trying a template in minutes on a homelab, LAN, or VPS without public DNS.
2828
- **Custom domain**: You supply a real public domain and point its DNS at the server. TLS is provisioned automatically via Let's Encrypt. Best for production.
2929
- **Port only**: Skips the Caddy proxy entirely. Docker picks a random host port; you reach the app at `http://<server>:<port>`. Disabled for multi-endpoint templates. Best for SSH-tunnel or LAN-only testing.
3030

docs/first-deploy/verify.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,6 @@ For deeper troubleshooting: [Operations &rarr; Troubleshooting](/operations/trou
6767
That is the full happy path. Next, dig in:
6868

6969
- [Add backups](/guides/backups/overview/) for stateful services.
70-
- [Invite teammates](/guides/users/roles/) and scope per-app access.
70+
- [Invite teammates](/guides/users-roles/) and scope per-app access.
7171
- [Wire up a private registry](/guides/registries/) for non-public images.
7272
- [Front SimpleDeploy with a load balancer](/guides/load-balancer/) if you outgrow one VPS.

docs/reference/directory-layout.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,5 +77,5 @@ Managed via `simpledeploy context add|use|list`. Permissions `0600` are recommen
7777
## See also
7878

7979
- [Configuration](/reference/configuration/) for `data_dir` and `apps_dir` config keys.
80-
- [Backups](/guides/backups/) for the `backups/` layout in detail.
80+
- [Backups](/guides/backups/overview/) for the `backups/` layout in detail.
8181
- [TLS and HTTPS](/guides/tls/) for Caddy storage paths.

docs/start/quickstart.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -132,5 +132,5 @@ Before you start: make sure ports 80 and 443 are open, Docker is installed, and
132132
<LinkCard title="Deploy more apps" href="/first-deploy/compose/" description="Multi-service stacks, env vars, port mappings." />
133133
<LinkCard title="Configure backups" href="/guides/backups/overview/" description="Postgres, MySQL, Mongo, volume tarballs to S3." />
134134
<LinkCard title="Add alerts" href="/guides/alerts/rules/" description="CPU, memory, error rate, custom webhooks." />
135-
<LinkCard title="Invite your team" href="/guides/users/roles/" description="Per-app RBAC, API keys for CI." />
135+
<LinkCard title="Invite your team" href="/guides/users-roles/" description="Per-app RBAC, API keys for CI." />
136136
</CardGrid>

0 commit comments

Comments
 (0)