[Docs Site] Upgrade to Astro 5 #19496
Conversation
KianNH
requested review from
a team,
G4brym,
GregBrimble,
WalshyDev,
daisyfaithauma,
dcpena,
haleycode,
irvinebroque,
kathayl,
kodster28,
kokolocomotion1,
kristianfreeman,
marciocloudflare,
maxvp,
mchenco,
mikenomitch,
pedrosousa and
ranbel
as code owners
| async function autogenSections() { | ||
| const sections = ( | ||
| await readdir("./src/content/docs/", { | ||
| withFileTypes: true, | ||
| }) | ||
| ) | ||
| .filter((x) => x.isDirectory()) | ||
| .map((x) => x.name); | ||
| return sections.map((x) => { | ||
| return { | ||
| label: x, | ||
| autogenerate: { | ||
| directory: x, | ||
| collapsed: true, | ||
| }, | ||
| }; | ||
| }); | ||
| } | ||
|
|
||
| const sidebar = await autogenSections(); |
There was a problem hiding this comment.
We had to move this back into astro.config.ts since this file cannot use Astro or Vite specific imports, like astro:content which we now use in sidebar.ts.
| contentLayer: true, | ||
| directRenderScript: true, |
There was a problem hiding this comment.
These flags are now defaults.
| if (!entry) { | ||
| throw new Error(`[AvailableNotifications] Unable to fetch notifications`); | ||
| } |
There was a problem hiding this comment.
This is a common change as the types for getEntry now include undefined.
| --- | ||
| import { z } from "astro:schema"; | ||
| import { getCollection } from "astro:content"; | ||
| import { getCollection, render } from "astro:content"; |
There was a problem hiding this comment.
render is no-longer on an entry.
| const markdown = (content: any) => { | ||
| if (typeof content !== "string") return content; | ||
| return marked.parse(content); | ||
| }; |
There was a problem hiding this comment.
Moving this down stopped the type Props from being reported as unused.
| _build: | ||
| publishResources: false | ||
| render: never | ||
| list: never | ||
|
|
There was a problem hiding this comment.
Tabs are not valid YAML and this is now enforced strictly.
There was a problem hiding this comment.
We have editorconfig enforcing tabs... are editors smart enough to treat this section as yaml and not tab as per editorconfig?
There was a problem hiding this comment.
From my experience with prettier, it won't fix tabs to spaces (in MDX frontmatter), but at least it won't break spaces into tabs again.
| @@ -1 +0,0 @@ | |||
| /// <reference path="../.astro/types.d.ts" /> | |||
There was a problem hiding this comment.
|
|
||
| export const getStaticPaths = (async () => { | ||
| const entries = await getCollection("docs"); | ||
| const entries = await getCollection("docs", (e) => Boolean(e.body)); |
There was a problem hiding this comment.
Stops a getStaticPaths warning that an endpoint returned an empty response.
There was a problem hiding this comment.
Does this mean that there are collection entries that are empty? Do they correspond to "empty files" (or equivalent) that we should fix?
There was a problem hiding this comment.
They're mostly pages that are either hidden index pages or only use external_link: https://github.com/cloudflare/cloudflare-docs/blob/5c5b52632dcd1e9e21c0cd9c2d50834cdccd8100/src/content/docs/stream/stream-api.mdx?plain=1
| export const GET: APIRoute = async () => { | ||
| const notes = await getCollection("changelogs-next"); | ||
|
|
||
| notes.sort((a, b) => a.data.date.getTime() - b.data.date.getTime()); |
There was a problem hiding this comment.
getCollection now returns with a non-deterministic order.
| type SidebarEntry = Link | Group; | ||
| type Badge = Link["badge"]; | ||
|
|
||
| const sidebars = new Map<string, Group>(); |
There was a problem hiding this comment.
We're now caching the result of filtering and sorting a per-product sidebar, and each request will only update the current entry in the cached sidebar instead.
github-actions
bot
assigned
GregBrimble,
haleycode,
kodster28,
kristianfreeman,
marciocloudflare,
maxvp,
pedrosousa,
WalshyDev and
irvinebroque
| [] | ||
| --- | ||
|
|
||
| While user tokens act on behalf of a particular user and inherit a subset of that user's permissions, account owned tokens allow you to set up durable integrations that can act as service principals with their own specific set of permissions. This approach is ideal for scenarios like CI/CD, or building integrations with external services like SEIMs where it is important that the integration continues working, even long after the user who configured the integration may have left your organization altogether. User tokens are better for ad hoc tasks like scripting, where acting as the user is ideal and durability is less of a concern. |
There was a problem hiding this comment.
We usually add the following frontmatter to partials:
---
{}
---
Can we immediately start with the content, without adding any frontmatter? Are there any edge cases?
There was a problem hiding this comment.
Starting with frontmatter immediately is fine, if you are not using params, but {} is also fine.
This one was using [], not {}, which does not match the object containing params we're expecting.
| if ( | ||
| e.slug === "warp-client/legal/3rdparty" || | ||
| e.slug === "magic-wan/legal/3rdparty" | ||
| e.id === "warp-client/legal/3rdparty" || |
There was a problem hiding this comment.
Nit (for later): We should probably have a const array somewhere with these specific values, since they appear in more than one file.
kodster28
left a comment
kodster28
left a comment
There was a problem hiding this comment.
Looked through the main components / features and didn't see any issues:
- Pages languages / build outputs
- changelogs
- Compatibility dates
- Tutorials / list examples
KianNH
requested review from
a team,
ToriLindsay,
angelampcosta,
patriciasantaana and
securitypedant
as code owners
github-actions
bot
added
product:ddos-protection
product:load-balancing
KianNH
force-pushed
the
kian/PCX-15576
branch
from
734e47c to
4db325c
Compare
11 participants
Summary
Upgrades to Astro 5 and all related Astro dependencies like Starlight.