Components
वे बुनियादी इकाइयाँ जिनकी ओर आप documentation लिखते (authoring) समय बढ़ते हैं — prose में (आपका README, tutorials, और docs files) और JSDoc / TypeDoc doc comments में। ये दो रूपों में आती हैं:
- Visual components — वह markup जिसे आप prose या किसी comment में डालते हैं और जो एक समृद्ध UI element के रूप में render होता है (callouts, steppers, tabs, live embeds, runnable playgrounds)।
- Custom tags — doc-comment block tags जिन्हें आधार JSDoc/TypeDoc परिभाषित नहीं करते, जिन्हें theme sidebar को आकार देने या आपके code से live content embed करने के लिए पढ़ता है।
Visual components
prose और doc-comment descriptions के अंदर एक ही तरह लिखे जाते हैं (वे एक ही converter से बहते हैं):
| Component | What it does | Page |
|---|---|---|
| Callouts | Note / tip / warning / error admonitions (GitHub-style > [!TIP]). | Callouts |
| Steps | A numbered <steps> / <step> stepper. | Steps |
| Tabs | A tabbed <tabs> / <tab> view. | Tabs |
| Embeds | A sandboxed <iframe> live demo — a ```iframe fence or the @iframe tag. | Embeds |
| Playgrounds | "Open in CodePen / JSFiddle / CodeSandbox" from an @example or a code fence. | Playground |
Custom tags
वे block tags जिन्हें आधार JSDoc और TypeDoc परिभाषित नहीं करते — theme उन्हें आपके source comments से पढ़ता है। दो sidebar को आकार देते हैं; दो live content embed करते हैं (और इनके prose समतुल्य हैं):
| Tag | What it does | Page |
|---|---|---|
@category <path> [order=N] | Put a symbol's page in an explicit sidebar group (and optionally order it). | @category |
@order N | A standalone within-group sort key for any symbol. | @order |
@iframe <url> key=value | Embed a sandboxed live demo from a source comment. | Embeds |
@playground <providers> [filename=] [highlight=] | Open an @example in a live playground. | Playground |
पहले custom tags चालू करें — allowUnknownTags
एक ही setup कदम है, और यही इन tags के "काम न करने" का सबसे आम कारण है: आधार JSDoc theme के चलने से पहले ही किसी भी ऐसे tag को छील देता है जिसे वह नहीं पहचानता। अपने jsdoc.json में unknown tags चालू करें:
{
"tags": { "allowUnknownTags": true }
}इसके बिना, @category default kind sections में सिमट जाता है, @order कुछ नहीं करता, और @iframe / @playground कभी render नहीं होते — चुपचाप। इस site का jsdoc.json इसे सेट करता है।
TypeDoc को ऐसे किसी flag की ज़रूरत नहीं — यह इन tags को पास-थ्रू कर देता है।
allowUnknownTagsकी आवश्यकता सिर्फ़ JSDoc के लिए है।
Tags बनाम prose — अंदर जाने के दो रास्ते
custom tags source-comment रूप हैं। जब आप इसके बजाय prose लिख रहे हों (एक README, एक tutorial, या एक docs file), तो वही क्षमताएँ बिना tags के उपलब्ध हैं:
group/orderfrontmatter किसी guide page पर@category/@orderको प्रतिबिंबित करते हैं (देखें Build a guides site)।```iframefence@iframeको प्रतिबिंबित करता है (देखें Embeds)।```js playgroundfence और<playground>container@playgroundको प्रतिबिंबित करते हैं (देखें Playground)।
ये भी देखें
- Structure your sidebar — कैसे
@category/@ordersectionOrder,docGroups,clubSidebarItems, औरmenuके साथ जुड़ते हैं। - Embeds — पूरा साझा
@iframe/```iframeconfig grammar। - Playground — पूरा
@playgroundfeature:opts.playground, prose रूप, और प्रति-provider options।