feat: export CreateSitemapItemsOption type

[johnnyreilly]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This is a follow on from #10083

I realised when plugging it into my blog that I hadn't exported the type.

It's possible to do some type gymnastics to get to it:
https://github.com/johnnyreilly/blog.johnnyreilly.com/blob/e38e4615e8afb9d66a59e607de04f46ec927a96d/blog-website/createSitemapItems.mjs#L6C1-L10C49

But it would be nicer if it was just exposed. This PR exposes the type explicity.

Test Plan

I tried to import in docusaurus.config.ts and it worked!

Test links

Deploy preview: https://deploy-preview-_____--docusaurus-2.netlify.app/

Related issues/PRs

#10083

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	bf5d885
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/66367cf1884dfb000840cbfd
😎 Deploy Preview	https://deploy-preview-10105--docusaurus-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 site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 77	🟢 98	🟢 96	🟢 100	🟠 88	Report
/docs/installation	🟠 58	🟢 96	🟢 100	🟢 100	🟠 88	Report
/docs/category/getting-started	🟠 76	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog	🟠 69	🟢 100	🟢 100	🟢 90	🟠 88	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 63	🟢 96	🟢 100	🟢 100	🟠 88	Report
/blog/tags/release	🟠 70	🟢 100	🟢 100	🟠 80	🟠 88	Report
/blog/tags	🟠 75	🟢 100	🟢 100	🟢 90	🟠 88	Report

[slorber]

I'd prefer to not export it. Options are easily accessible and many other plugins to not export types. Once we export them, we must have a good name and maintain retrocompatibility.

The type gymnastic is not super hard, particularly when not using JSDoc but using plain TS

const createSitemapItems: Options['createSitemapItems'] = async (params) => {
  return params.defaultCreateSitemapItems(params);
};

If we expose this, then this means we'll also probably have users finding convenient to expose many other option types as well. And we end up with many exported types whose naming convention should be consistent, and for which we need to remain retrocompatible over time.

[johnnyreilly]

It sounds like you've made up your mind already, but I thought it worth mentioning that not exporting the type doesn't align with the createFeedItems hook which does export the type, and so can be used like so: (a straightforward import - no gymnastics)

import('@docusaurus/plugin-content-blog').CreateFeedItemsFn

Example usage of exported type here:
https://github.com/johnnyreilly/blog.johnnyreilly.com/blob/e38e4615e8afb9d66a59e607de04f46ec927a96d/blog-website/createFeedItems.mjs#L6

Given we exported the type for that (comparable) functionality, why differ this time?

See:

docusaurus/packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts

Line 289 in ab9a4e7

type CreateFeedItemsFn = (

[slorber]

We export many things from docs, blog and pages plugin. I'm not sure it's the right decision actually to export everything by default like we do. If we can avoid exporting more things in the future, I'd prefer to not export them (at least until we have a clear plan on how to handle exported types), particularly when there is an easy workaround to get the type.

Also those plugins have a .d.ts file so the public TS API surface is more explicit. If typedefs gets generated from implementation code and we just re-export types, it is more likely that a TS breaking change will sneak in without us noticing it.

[johnnyreilly]

Should we then look at removing the CreateFeedItemsFn type export for Docusaurus 4? We'd then be being more consistent which is always nice from a consumers perspective.

I guess I'm a little confused as to what the rationale is for when types should and should not be exported. Is it documented somewhere?

[slorber]

I don't know 🙈

I guess I'm a little confused as to what the rationale is for when types should and should not be exported. Is it documented somewhere?

I am too, the way we handle types atm is messy and not super consistent. Until we have a clear plan (which we haven't), I'd rather not export more types unless it's really necessary.

[johnnyreilly]

Fair enough!