Dedicated component to document API references

[ArmandPhilippot]

The format used to document each item on References pages is now documented in DocsDocs.

Proposition: dedicated component

@florian-lefebvre has suggested on Discord to create a dedicated component to handle the formatting. For example:

<ApiReferenceType version="5.0.0">`() => URL;`</ApiReferenceType>

Instead of:

<p>

**Type:** `() => URL;`<br />
<Since v="5.0.0" />
</p>

I think this is a great idea to:

• avoid a bad formatting
• reduce translation efforts (since Type: and Default: become UI strings like Added in: there is nothing left to translate)

However, we might still need an empty line to avoid a potential bug when rendering Markdown passed as a child.
The empty line after <p> was made "official" after a discussion with Chris in a previous PR. To quote him:

the newline made sure subsequent markup is treated as Markdown IIRC

So the component should be used this way:

<ApiReferenceType version="5.0.0">

`() => URL;`
</ApiReferenceType>

In practice, I haven't seen any rendering bugs without this line... so either things have changed, or it's a rare bug. So I don't know if we should be strict about the empty line.

What we need

A component that handles formatting to reduce the effort of writers when they have to fill in the type, default value and version.

• Type should be optional because some entries only uses <Since />
• Type should be passed using the default <slot /> because some of them might contain links.
• Default and Since are also optional

Implementation

I made some tests using the following component:

---
import Since from './Since.astro';

export interface Props {
  default?: string;
  pkg?: string;
  version?: string;
}

const { default: defaultValue, pkg, version } = Astro.props;
const type = await Astro.slots.render('default');
---

<p>
  {
    type ? (
      <>
        <strong>Type:</strong>
        <span set:html={type} />
        {defaultValue || version ? <br /> : null}
      </>
    ) : null
  }
  {
    defaultValue ? (
      <>
        <strong>Default:</strong> <code>{defaultValue}</code>
        {version ? <br /> : null}
      </>
    ) : null
  }
  {version ? <Since pkg={pkg} v={version} /> : null}
</p>

That seems to do the trick! Well, almost...

In this implementation I expect "Default:" to always be a code so we can retrieve it from a property and put it in a <code /> tag. This is not always the case. At the moment I'm not sure how to handle this:

• I don't know if it's easy to compile Markdown from a property and if that's what we want to do.
• Maybe we should assume every backtick (`) in a string represent code and replace them with a <code /> tag then use set:html...

About the implementation: We need an extra element to render the slot due to Astro.slots.has limitations. Astro.slots.has("default") always returns true. So we need to render the slot and check if the result exists ("" is falsy).

Also, we could update the docgen script to use this component. I saw that it uses a CLI field, so we should add that to the component.

I've never worked with RTL languages so... is there anything we can add to the component to make sure it renders properly in those languages? (i.e. is the order the same?) I wanted to check on the Arabic pages, but it seems the references are not translated. On the other hand, the current <Since /> component doesn't seem to do anything for layout so I guess it should be ok.

Naming

I'm not sure about the component name...

• it handles not only the "type" but also the default, version (and CLI command if we use it for docgen)
• we could use this component on other pages when a Default: or a <Since /> is useful...

So <ApiReferenceType /> doesn't seem adequate and maybe a bit long. What do you think of <ApiMeta /> or maybe just <Meta />? If you have any other suggestions, I'm all ears! 😄

Optional proposition: evolve the syntax

While I was writing the code, I realized that this was a perfect case (semantically) to use <dl /> instead of some <br /> and <strong /> tags. The output would look like:

<dl>
  <div>
    <dt>Type:</dt>
    <dd><code>() => URL</code></dd>
  </div>
  <div>
    <dt>Default:</dt>
    <dd><code>undefined</code></dd> // Just for the example
  </div>
  <div>
    <dt>Version:</dt>
    <dd>5.0.0</dd>
  </div>
</dl>

• <div /> is valid as direct child of <dl /> so we don't need <br /> anymore
• we could use some CSS to ensure:
  • each <dt /> is bold
  • each <dt />/<dd /> couple is rendered inline
  • a margin is rendered after this block
• we can use set:html directly to <dd /> to render the Type.

Pros:
If in RTL languages ​​the order is reversed, it might be easier to control this.

Caveats:
If we do this, <Since /> should no longer be used alone or it should be wrapped with <dl /> because we need to update its syntax. Also, the code will no longer be valid in translated pages (while waiting for translators).

I see two solutions:

• Everything will have to be updated at once at least where <Since /> is in use. I can give it a try but I'm not comfortable with most of the languages so... reviewers will be welcome! And maybe updating translated pages should be done in a separate PR (with I18nIgnore) but merged at the same time as the other one.
• Another solution would be to duplicate the logic of the <Since /> component in our new component and wait until <Since /> disappears from the documentation to remove it or to update our component code with an updated <Since /> component.

[sarah11918]

This is an amazing initiative and analysis, @ArmandPhilippot ! I would be very open to a component that was easy to author!

[ArmandPhilippot]

Thank you! 💜 I will probably make a PR early next week (because I don't think I'll have time this weekend and that leaves time for possible comments/ideas).

If no one minds <dl />, I'll probably use that syntax and I'll go with my second solution (duplicate <Since /> code). It's probably better if the update is done by someone who speaks the language to avoid errors. We can always force the update for languages ​​with fewer active contributors with the first solution, doing it language by language to facilitate reviews.

If by then, you think of a name more meaningful/easy to remember than Meta, don't hesitate. I had also thought about ApiDoc but I don't know if it's better knowing that the component could be used under a section (not necessarily a function/an option) just to display Since for example. And then Doc seems redundant to me... everything is doc! 😄

[ArmandPhilippot]

Should we support cases where there are multiple types, like getEntries()?

I did a first test by retrieving the content of each <li> and using several <dd>:

On large screens, it is not a problem. On small screens (like a smartphone), however, the display is not great:

I did a second test keeping the list (so only one <dd>), the display corresponds more or less to what we already have. So the question is: is it better to have Added in: before or after (like below)? So should the component support multiple types or do we leave it as it is (types outside the block)?

(I can display Type: in plural if needed, for this test I did not do it)

[ArmandPhilippot]

Another edge case: custom badges.

In Content collections, we have a <Since /> component with a custom badge. I don't think we can extend Since's logic to detect experimental features.

So, I see two options:

• either the badge is displayed before or after Meta,
• or we need an additional prop to display the badge next to Added in:.

In this specific case, it's not too annoying since the functionality disappears in v5 if I don't make a mistake. But maybe this case appears elsewhere or may be necessary in the future.

[ArmandPhilippot]

A possible solution would be to add a status prop. If provided, we use the value as a badge. If it is not provided, we use the current Since logic to check if "beta" or "new" should be added. Otherwise, we do not display a badge.

However, currently, in addition to the custom value a class is added to Badge. Maybe we should move this logic into the Badge component using tokens. Depending on the token we apply or not the class. The token would also be used to provide the translation.

We could also move the badge to a new "Status:" field instead of placing it next to "Since". But that is beside the point. It's just an idea that came to me while thinking about the problem... And it's more of a design choice.

[sarah11918]

Sorry that I'm just catching up with this now.. I haven't yet read through here entirely and I have scanned the PR.

First of all, thank you @ArmandPhilippot for taking the initiative here to help devs add their content in an easier way! And secondly, nothing is going to happen until Chris is back to contribute to this discussion. 😄

Just want to point out a bit of authoring weirdness from the PR:

1. It feels like the default "Since" authoring has become less intuitive. I know you asked about the name, and I haven't been in here yet to suggest otherwise, but seeing how many places the PR would simply update "Since" with "Meta" does feel like maybe it's not a significant authoring gain here?

2. Similarly, I understand the decision to make the child content the type because it's typically the most complicated thing, but it also feels like an unintuitive replacement:

and

I think this is a less intuitive solution when just Since and Type were previously on their own, and when combined, I think it makes it actually harder to read and see clearly what's going on?

I think maybe where a new component makes sense is something like <ApiReference> (only?) that can replace the very specific formatting we need, and only replaces the <Since/> component when it occurs inside that?

I will also note that as you said, we do not author config reference directly, but rather we get HTML from the source file. That means we don't need a component there, and I think it would be worse to ask translators to use a component rather than just copy exactly what they see in the file they're translating? So I don't think any component on that page makes sense.

I'm sorry if this sounds more negative than encouraging! But I'm trying to figure out exactly when/where this improves the authoring experience. I do think the "prompting devs to fill in the attributes of the component" is helpful, and they don't need to know about that leading blank line etc. But looking at the replacements in the PR, in most places the source now makes less sense and is less readable. So I fear this may be a "component because we can" rather than something that is yet truly helpful.

What do you think, now that you've crafted something and seen it in use?

[ArmandPhilippot]

Sorry that I'm just catching up with this now.. I haven't yet read through here entirely and I have scanned the PR.

First of all, thank you @ArmandPhilippot for taking the initiative here to help devs add their content in an easier way! And secondly, nothing is going to happen until Chris is back to contribute to this discussion. 😄

No worries I understand that this change may require further discussion!
And I didn't know Chris wasn't there! I understand better why he didn't come by! 😄

1. It feels like the default "Since" authoring has become less intuitive. I know you asked about the name, and I haven't been in here yet to suggest otherwise, but seeing how many places the PR would simply update "Since" with "Meta" does feel like maybe it's not a significant authoring gain here?

The name of the component is the main problem I think. I also thought about using a prop named since (to keep the semantics) that accepts an object since pkg and version are related but I figured it might be less intuitive to use than two separate props.

Looking at the screenshot, I have mixed feelings. I share your impression because the component name is probably not meaningful enough (so it may not be more intuitive). On the other hand, writers no longer have to worry about whether to use a p around the component or not, about blank line or about <br /> (so it's easier to write and remember).

So I don't have a strong opinion on the matter. I would tend to say that it's a matter of point of view. (but yes, a better name could be useful) And perhaps the opinion of those concerned would be useful here...

2. Similarly, I understand the decision to make the child content the **type** because it's typically the most complicated thing, but it also feels like an unintuitive replacement:

I think this is a less intuitive solution when just Since and Type were previously on their own, and when combined, I think it makes it actually harder to read and see clearly what's going on?

On this point I agree.

The "easiest" (not necessarily the most readable if the Type is long) would have been to have another prop named type but handling Markdown would have been more complicated than for default (for example). If we only use the type, it's doable... but if we start adding links, I think using Regex to replace with HTML tags becomes quite fragile.

So in the absence of another solution, I would tend to think that this is an acceptable problem (and one that could perhaps be reduced with a better name). Between that, and remembering to surround the block with a p tag followed by a blank line, adding <br /> after each line, I'm not sure which is easier to write.

I totally understand your point of view, and again, I tend to agree. Then I tell myself that those who write do not want to waste time wondering if the formatting is correct, so I don't know what is better.

I think maybe where a new component makes sense is something like <ApiReference> (only?) that can replace the very specific formatting we need, and only replaces the <Since/> component when it occurs inside that?

Reading two different ideas come to mind, so I'm not sure I understood correctly. (I put my two interpretations in bold)

For the name, what bothered me (but maybe it's just me) is that we find this type of formatting on pages other than the references (like in integrations-guide for example). So I'm not sure it's more meaningful than Meta. Or rather, it suggests that it shouldn't be used on other pages.

If by replace you meant overwrite: Overriding the Since syntax only when it is used in this component seems tricky. Maybe I am not familiar enough with how Astro works, but it doesn't seem to me that there is a way to detect the type of the children... or even iterate through them. Maybe by adding slot="since" to the <Since /> component... but does that make it easier to use? I'm not sure...

So if we write something like:

<ApiReference>
`boolean`
<Since v="5.0.0" />
</ApiReference>

I would say it's even less intuitive... And it doesn't seem easy to me to know where to insert a line break without knowing what is received as a child. So if we want Since in the same block, the information must be passed as props.

And if we completely abandon the idea of ​​props:

<ApiReference>
**Type:** `boolean`
**Default**: `false`
<Since v="5.0.0" />
</ApiReference>

I would say it is worse than the original syntax:

• Might as well write p instead of ApiReference, it's shorter
• How do I know where to insert line breaks? Again, I don't think you can iterate through children with Astro... So editors will have to add line breaks.

So, might as well keep the current syntax!

On the other hand, what is possible is to abandon the idea of ​​dl/dt/dd. So Since can still be used as is, no need to replace it (when used alone at least). And maybe that's what you were saying.

But that doesn't reduce the problems:

• how to declare the type? Its syntax is still too complicated to be assigned to a prop I think.
• When "Since" is no longer enough and a writer needs to add a Type, then he should remember to remove Since and use another component instead?

I will also note that as you said, we do not author config reference directly, but rather we get HTML from the source file. That means we don't need a component there, and I think it would be worse to ask translators to use a component rather than just copy exactly what they see in the file they're translating? So I don't think any component on that page makes sense.

I'm not sure I understand.

Regarding the component, there is already one: Since. This simply overrides the generated syntax to be consistent with the rest of the documentation. Instead of Type:/Default:/CLI:/Since we have Meta. And this does not change anything in the writing of the JSDoc.

In my opinion, it simplifies the translation work: translators don't have to do anything, they just have to copy/paste the component without modification. "Type:", "Default:", "Added in:"... are translated only once in ui.ts so there is no more consistency problem in the translation.

While in the current state, translators have to translate "Type:", "Default:", etc. every time. Which leads to some consistency issues. To take the example of the French translation, sometimes a space is forgotten before the colon while in French we should put one. Other times, "Default:" is literally translated "Défaut :" when it should be "Par défaut :". Reviews can help correct these problems but sometimes there are omissions... So on this point, I would say that on the contrary it makes the translation easier.

This works exactly like Since. Except for a possible link in the type... So the component should be imported into the file in all cases (as for Since).

I'm sorry if this sounds more negative than encouraging! But I'm trying to figure out exactly when/where this improves the authoring experience.

Don't worry, since there was no other feedback I figured I could start a PR. I suspected that there would be things to change after!

So I fear this may be a "component because we can" rather than something that is yet truly helpful.

Yeah maybe it is... But I still have the impression that the current syntax is not to everyone's taste. So exploring the idea of ​​a replacement isn't a bad idea... even if it doesn't come to anything this time.

What do you think, now that you've crafted something and seen it in use?

To summarize:

• I agree setting the type as a child with the current name doesn't seem intuitive.
• Using Markdown inside props can be confusing (e.g. default="`'server'`" ... a lot of different "quotes"...)
• On the other hand, a single component seems to me to make the work of editors and translators easier:
  • Writers no longer have to worry about whether there is another component to use, where to insert Since in the block, what is the order of the fields, etc.
  • Translators don't have to do anything else: once the labels have been translated in ui.ts, they just have to copy/paste the component without touching it (in most cases, when there is no link).

So yes, the current implementation may not be the best... there may be other solutions. For now, it doesn't come to me... otherwise I would have tried something else. 😆 And whatever the outcome, it remains an interesting attempt!

As always, thanks for you feedback! 😄

[sarah11918]

Just wanted to leave a quick comment and say that I expect to have time to loop Chris in on this in the coming week!