docs
docs copied to clipboard
feat: add a `<Meta />` component to document APIs
This PR implements #9498. Feel free to check out this discussion for more context and some implementation details.
Description (required)
Changes
- Adds a
<Meta />component to ease the authoring of theType:/Default:/Sinceblock - Updates English documentation to use the new component
- Converts all
Signature:toType:indev-toolbar-app-reference.mdxto be consistent (and to be able to use the component) - Updates
docgenscript to use our new component
Supported Syntaxes
<Meta /> can be used:
- without children if there is no type (e.g.
<Meta version="5.0.0" />) - on one line (e.g.
<Meta>`number`</Meta>) or adding line breaks (after<Meta>and before</Meta>) to make it easier to read/write when the type is long - with HTML tags inside to use links
The available props are:
availableFor(to supportintegrations-guide/vercel.mdx)clidefaultpkgandversion(both are related to Since, withoutversionthepkgdo nothing)
Both cli and default properties can have backticks (Markdown syntax) to use inline code (e.g. <Meta default="`10`">`number`</Meta>) so more complicated values like <Meta default='`"development"` when running `astro dev`, `"production"` when running `astro build`'> are also supported.
Not supported
- Multiple types like
getEntry()
We could, but the rendering on smartphone is not great... You can see some previews of my tests in the discussion.
- The syntax used in
Collection Entry Type
Available for: is already supported by the component. The problem is the different variants for the type (Example type:/ Example Types:/Type: and which is sometimes on multiple lines). Should we add a new prop exampleType? Even if we do this, there remains the problem of multiple examples/types.
Future
- We let active contributors update the documentation in their language to avoid errors
- For languages with fewer contributors, we can create a language-by-language PR with
i18nIgnore - Once the documentation is updated in all languages, we can remove
<Since />component OR update its syntax to usedt/ddand remove the duplicated logic from<Meta />
Related issues & labels (optional)
- Closes #9498
- Suggested label: consistency/formatting and feedback-improvement