fix(integrations-guide): add/format API references blocks

[ArmandPhilippot]

Description (required)

• Updates the integrations guide to add or format the API reference blocks.
• Updates slightly two descriptions in integrations-guide/db to remove the inline types and to make the description more accurate based on the types.

This looks like a big update but it's not (each block is ~4-7 added lines) that's why I've updated all the integrations guides in one PR.

What you might want to double check is foreignKeys in db, recmaPlugins in mdx and the options in partytown (see the details for why). I think the choices are reasonable but you might have another opinion!

Show details

For each integration API, I added a link so you can easily check there is no errors. I've added some comments for some to explain my choice.

• In alpinejs:

  • entrypoint, see [ci] release astro#9802

• In db:

  • columns: thankfully the type is exported from @astrojs/db/types so we don't need something more complex
  • indexes: we could use keyof ColumnsConfig for on, but I think keeping string as we had before in the description is less confusing, so I reused that.
  • foreignKeys: this one is complex, we don't have a type to reference a single column defined in columns. In the description, we had Column but the type doesn't exist. I don't have a better idea so I reused that, NWTWWHB. And I updated the description to be more accurate (the type allows a single column, this is not always an array).
  • isDbError(), see db: expose isDbError() utility astro#10498

• In markdoc: (technically speaking, both are not set to false by default but rather left undefined... which would have the same behavior as false: only true does something.)

  • allowHTML, see Add "allowHTML" option for Markdoc with HTML parsing/processing astro#7597
  • ignoreIndentation, see feat(markdoc): allowIndentation integration option astro#8802

• In mdx:

  • extendMarkdownConfig, see Markdown and MDX configuration rework astro#5684
  • recmaPlugins, see [MDX] Support recmaPlugins config astro#5146 (note: PluggableList is not an Astro type but a unified one and I don't think we reexport it, but I don't have a better idea to describe the type)
  • optimize, see Add MDX optimize option astro#7151

• In partytown: this one is tricky because all the config options comes directly from partytown... so no Since, and it's possible that the types change if partytown is updated! But I still added the type for the few config options we describe based on https://github.com/QwikDev/partytown/blob/main/src/lib/types.ts#L398

• In preact:

  • compat, see [ci] release astro#3759

• In solid-js: I only formatted an API reference block

• In vercel: the missing Since are corrects, I only formatted the API reference blocks

• In vue:

  • appEntrypoint, see [Vue] add support for appEntrypoint astro#5075
  • jsx: the second type is a renamed imported type, so I think object is enough since we explain below what the object is.
  • devtools: same, we explain the object type in "Customizing Vue DevTools" so I think this is enough

I haven't updated the other integrations guide because the API references were already there!

Related issues & labels (optional)

• Suggested label: consistency/formatting, improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	fb2357d
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68d2d04cf3942a0008debead
😎 Deploy Preview	https://deploy-preview-12319--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/integrations-guide/alpinejs.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/db.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/markdoc.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/mdx.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/partytown.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/preact.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/solid-js.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/vercel.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/vue.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[sarah11918]

This looks great, @ArmandPhilippot ! I've reviewed for syntax, and left thoughts about Partytown.

It would be great if someone had thoughts on the db and mdx (recmaPlugins) types, since that's out of my comfort zone!

[ArmandPhilippot]

Thanks Sarah! I've answered for partytown. Now, for mdx and db, I'm not sure.

Maybe @Adammatthiesen (if you have time to look at it) would have an idea for the foreignKeys type since he's working on db.

For Adam, to avoid you reading all the details: In the description, we had Column to describe the return type of foreignKeys but the type doesn't exist. I don't have a better idea so I reused what we had. Do you know if there is a more explicit type here we could use? Or do you think it's fine even if the type doesn't exist? Any ideas are welcome!

But for mdx I don't know who we could ask... I hesitated to use unified.PluggableList, but I wasn't sure this would be more explicit for people.

[sarah11918]

But for mdx I don't know who we could ask... I hesitated to use unified.PluggableList, but I wasn't sure this would be more explicit for people.

Let's ask @delucis !

(Armand's concern is regarding the entry for recmaPlugins: "PluggableList is not an Astro type but a unified one and I don't think we reexport it, but I don't have a better idea to describe the type.)

[Adammatthiesen]

Thanks Sarah! I've answered for partytown. Now, for mdx and db, I'm not sure.

Maybe @Adammatthiesen (if you have time to look at it) would have an idea for the foreignKeys type since he's working on db.

For Adam, to avoid you reading all the details: In the description, we had Column to describe the return type of foreignKeys but the type doesn't exist. I don't have a better idea so I reused what we had. Do you know if there is a more explicit type here we could use? Or do you think it's fine even if the type doesn't exist? Any ideas are welcome!

But for mdx I don't know who we could ask... I hesitated to use unified.PluggableList, but I wasn't sure this would be more explicit for people.

Yeah, im not sure where the original docs writer got that type from 😅 But the new description looks correct, since there really is no proper external type for that. (as currently ALL of the astro:db types are virtual only and cannot be directly referenced. I also plan to change this when i do my rebuild of DB... because it annoy's me 😅 )

[ArmandPhilippot]

Thanks @Adammatthiesen

Yeah, im not sure where the original docs writer got that type from

I think the idea was to illustrate a single column configured inside columns in the absence of an actual type to use. And to be clear, I removed it from the description... but I'm reusing it inside Type: because we don't have an exported type for that and so I'm not sure what we could show here.

ALL of the astro:db types are virtual only and cannot be directly referenced

Well, I was able to import ColumnsConfig from @astrojs/db/types while checking the types to use! 😄 (I'm using it for indexes). But, yeah, I wasn't able to find a meaningful type for foreignKeys...
So I guess the question would be should we use:

Type: { columns: string | string[]; references: () => Column | Column[]; }[]

even if Column doesn't exist. Or should we remove that type (while waiting for you to finish the DB rebuild 😀 ) because it's not really accurate? Do you think it's confusing/harmful to use that?

[Adammatthiesen]

Well, I was able to import ColumnsConfig from @astrojs/db/types while checking the types to use! 😄 (I'm using it for indexes). But, yeah, I wasn't able to find a meaningful type for foreignKeys... So I guess the question would be should we use:

Type: { columns: string | string[]; references: () => Column | Column[]; }[]

even if Column doesn't exist. Or should we remove that type (while waiting for you to finish the DB rebuild 😀 ) because it's not really accurate? Do you think it's confusing/harmful to use that?

yeah... there is a few very specific types available, but the primary table/column types are not at the moment.

For now probably fine to just keep the Mock Column type as long as we are explaining that the user is using a existing table's column (as shown in the code snippet example)

[sarah11918]

@ArmandPhilippot Shall we NWTWWHB this one and get it merged? I know there was one outstanding question, but maybe we merge as-is then change if we find it's not helpful or have a better idea?

[sarah11918]

I'll give an explicit approval that I'm happy with what I reviewed!

[ArmandPhilippot]

@sarah11918 If someone is using a recmaPlugin (which is less known than remark/rehype), I assume they are already familiar with the unified ecosystem (and PluggableList should talk to them). So, I don't think the recmaPlugin question is really a blocker.
At worth, if someone find this confusing I'm sure we'll see a post about it on Discord or here and so we can find a better solution later if necessary.

So yes, I think we can merge this one! 🫡