Skip to content

Commit 8027ee4

Browse files
authored
Merge branch 'main' into indent/next-version-matrix
2 parents dcfafc9 + 3885164 commit 8027ee4

3 files changed

Lines changed: 42 additions & 2 deletions

File tree

‎content/(dynamic)/environment-variables.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ Pass the value as an argument or read it from stdin, never both and never neithe
3232

3333
Passing a secret on the command line prints a warning naming the variable, because it lands in your shell history. Prefer `--value-from-stdin`.
3434

35-
:::warning[A write applies at the next finalize]
36-
Setting or deleting a variable does not touch the running site. The live version keeps the values it was sealed with. The change reaches visitors when a version next finalizes, which the write itself queues.
35+
:::note[No republish needed for a Space variable]
36+
A version keeps the values it was sealed with, so a write never edits the running version. Setting or deleting a Space variable queues a new version with the new values, and that version replaces the live one when it is ready. A team variable change does not queue one. It reaches each Space at that Space's next publish.
3737
:::
3838

3939
## Secret or plain
@@ -59,6 +59,8 @@ So a brand new variable with no flag is write-only. Pass `--no-secret` when you
5959

6060
## Build time and runtime are different lanes
6161

62+
A plain variable reaches both lanes. It is filled into template files when a version finalizes, and server code reads it at runtime. A secret reaches server code only. A template that references one is blocked with `secret_variable_in_template`.
63+
6264
### Build time, `{{ vars.NAME }}`
6365

6466
List a file under `templates` in `sf.jsonc`. Every `{{ vars.NAME }}` token in it is substituted when the version finalizes.

‎scripts/redirect-rules.mjs‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { redirects as retiredPageRedirects } from "../redirects.ts";
12
import referenceAliases from "./reference-aliases.json" with { type: "json" };
23

34
export const deploymentBase = "/docs";
@@ -25,6 +26,24 @@ const authoredRedirectRules = [
2526
},
2627
];
2728

29+
// `route` is relative to the deployment base; a `#fragment` has no Markdown form.
30+
function markdownRoute(route) {
31+
const pathname = route.split("#")[0];
32+
return `${deploymentBase}${pathname === "/" ? "/index" : pathname}.md`;
33+
}
34+
35+
function unbased(route) {
36+
return route.slice(deploymentBase.length) || "/";
37+
}
38+
39+
// Blume emits HTML meta-refresh stubs for retired Markdown URLs. Agents need
40+
// an HTTP redirect instead of HTML at those URLs. Moved pages also need a rule,
41+
// so both kinds get a 301 to the replacement's Markdown file.
42+
export const markdownTwinRules = [
43+
...authoredRedirectRules.map(({ from, to }) => ({ from: unbased(from), to: unbased(to) })),
44+
...retiredPageRedirects,
45+
].map(({ from, to }) => ({ from: markdownRoute(from), status: 301, to: markdownRoute(to) }));
46+
2847
const aliasFamilies = [
2948
{
3049
sourcePrefix: "/api/operations/",
@@ -117,6 +136,7 @@ function applyRule(rule, source) {
117136
export function buildRoutingRules(redirects) {
118137
return [
119138
...authoredRedirectRules,
139+
...markdownTwinRules,
120140
...compileRedirectRules(redirects).map(({ from, status, to }) => ({
121141
from: `${deploymentBase}${from}`,
122142
status,

‎scripts/verify-routes.mjs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
buildRoutingRules,
1010
compileRedirectRules,
1111
deploymentBase,
12+
markdownTwinRules,
1213
resolveRedirect,
1314
} from "./redirect-rules.mjs";
1415
import { discoveryFileForUrl } from "./build-llms-index.mjs";
@@ -504,6 +505,23 @@ for (const [route, target, hopCount] of [
504505
}
505506
await requireFile(localTargetFor(url.pathname));
506507
}
508+
for (const { from, to } of markdownTwinRules) {
509+
const matched = matchRedirect({
510+
compilation,
511+
request: {
512+
url: new URL(`${docsRoot}${from.slice(deploymentBase.length)}?source=markdown&value=a%2Fb`),
513+
headers: new Headers(),
514+
},
515+
});
516+
const destination = matched?.action === "redirect" ? new URL(matched.target, docsRoot) : null;
517+
if (
518+
matched?.action !== "redirect" || matched.status !== 301 ||
519+
destination?.pathname !== to || destination.search !== "?source=markdown&value=a%2Fb"
520+
) {
521+
throw new Error(`A retired page's Markdown URL must 301 to its replacement: ${from} -> ${to}`);
522+
}
523+
await requireFile(localTargetFor(to.slice(deploymentBase.length)));
524+
}
507525
const runtimesZeroHtml = await readBuilt("runtimes/zero/index.html");
508526
if (!runtimesZeroHtml.includes(`<meta http-equiv="refresh" content="0;url=${deploymentBase}/zero-runtime">`)) {
509527
throw new Error("The former runtimes/zero page must navigate to the canonical Zero page.");

0 commit comments

Comments
 (0)