feat: Generic API page schema #9267
Conversation
yufeih
added
the
new-feature
Codecov ReportAll modified lines are covered by tests ✅ 📢 Thoughts on this report? Let us know!. |
| /** Code text */ | ||
| code: string; | ||
|
|
||
| /** Code [langauge identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */ |
There was a problem hiding this comment.
| /** Code [langauge identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */ | |
| /** Code [language identifier](https://code.visualstudio.com/docs/languages/identifiers#_known-language-identifiers) */ |
| /** Opaque metadata about the API as HTML data-* attributes */ | ||
| metadata?: { [key: string]: string }; |
There was a problem hiding this comment.
Not clear whether the "data-" prefix is part of the key here, or added during the conversion to HTML.
There was a problem hiding this comment.
data- is added to key, will adjust the comment to clarify.
| /** Page title */ | ||
| title: string; | ||
|
|
||
| /** Opaque metadata about the page as HTML <meta> tags */ |
There was a problem hiding this comment.
Willl this documentation be parsed as Markdown? If so, <meta> should be quoted or escaped.
There was a problem hiding this comment.
No, properties using markdown formats are explicitly typed as markdown, such as parameters.description.
There was a problem hiding this comment.
I meant the documentation of the property, not the value of the property.
/** Opaque metadata about the page as HTML `<meta>` tags */because you used Markdown syntax for hyperlinks in the documentation of other properties.
| /** Represents a heading */ | ||
| type Heading = | ||
| | { /** Heading title */ h1: string; /** URL fragment */ id?: string } | ||
| | { /** Heading title */ h2: string; /** URL fragment */ id?: string } | ||
| | { /** Heading title */ h3: string; /** URL fragment */ id?: string } | ||
| | { /** Heading title */ h4: string; /** URL fragment */ id?: string } | ||
| | { /** Heading title */ h5: string; /** URL fragment */ id?: string } | ||
| | { /** Heading title */ h6: string; /** URL fragment */ id?: string }; |
There was a problem hiding this comment.
Does "URL fragment" mean it is expected to match the fragment definition in https://www.rfc-editor.org/rfc/rfc3986#section-3.5? I.e. does not include #, and can contain pct-encoded.
There was a problem hiding this comment.
Yes, renderers are not expected to change this id to match rfc3986, renders MAY encode the id to produce valid HTML.
This PR proposes the draft shape of the
ApiPageschema.#9266