Skip to content

Commit 833c88c

Browse files
clairekinde11clairekinde11
authored
Simplified instructions for frontmatter
1 parent a3aceee commit 833c88c

File tree

1 file changed

+39
-262
lines changed

1 file changed

+39
-262
lines changed

‎src/content/docs/contribute/index.mdx

Lines changed: 39 additions & 262 deletions
Original file line numberDiff line numberDiff line change
@@ -170,290 +170,67 @@ This helps us recognize and prioritize requests.
170170
This section describes some of our styles, elements, and conventions for docs content.
171171

172172
### Frontmatter
173+
The header/metadata part of the content helps the article appearing correctly in docs. It is also important for external AI tools and search optimization.
173174

174-
The header/metadata part of the content is critical to the article appearing correctly in docs.
175-
176-
#### <span class="text-lg font-bold">`title (required)`</span>
177-
178-
**type:** `string`
179-
180-
You must provide a title for every page. This will be displayed at the top of the page, in browser tabs, and in page metadata.
181-
182-
```md title="src/content/docs/developer-tools/about/our-sdks.mdx"
183-
---
184-
title: Kinde SDKs
185-
---
186-
```
187-
188-
#### <span class="text-lg font-bold">`page_id (required)`</span>
189-
190-
**type:** `uuid`
191-
192-
This is the internal unique `id` for the article. This will be used when referencing other articles within the `relatedArticles` frontmatter. You can use our [online UUID generator tool](https://kinde.com/tools/online-uuid-generator/) to use as the `page_id`.
175+
Copy the whole example below into the top of any new topic. And complete the required sections. Complete optional sections if you want.
193176

194177
```md title="src/content/docs/developer-tools/about/our-sdks.mdx"
195178
---
196-
title: Kinde SDKs
197-
page_id: 684fc526-a338-4a67-9af6-742a39b66aff
198-
---
199-
```
200-
201-
#### <span class="text-lg font-bold">`order` (optional)</span>
202-
203-
<Aside>
204-
205-
Providing the `order` frontmatter is completely optional and will be treated as a hint for us to where to place the file. We may update the article’s `order` upon further review.
206-
207-
</Aside>
208-
209-
**type:** `number`
210-
211-
Control the order of this article when sorting an autogenerated group of links under a specific topic or subtopic. Lower numbers are displayed higher up in the link group.
212-
213-
```md title="src/content/docs/developer-tools/about/our-sdks.mdx"
214-
---
215-
title: Kinde SDKs
216-
page_id: 684fc526-a338-4a67-9af6-742a39b66aff
179+
page_id:
180+
title:
181+
description: "description"
217182
sidebar:
218-
order: 1
219-
---
220-
```
221-
222-
#### <span class="text-lg font-bold">`tableOfContents` (optional)</span>
223-
224-
**type:** `object`
225-
226-
Controls the table of contents display for the page.
227-
228-
```md title="example.mdx"
229-
---
230-
title: Example Article
231-
page_id: 12345678-1234-1234-1234-123456789012
232-
tableOfContents:
233-
maxHeadingLevel: 3
234-
---
235-
```
236-
237-
#### <span class="text-lg font-bold">`topics` (optional)</span>
238-
239-
**type:** `array`
240-
241-
Array of topic tags that help categorize the content.
242-
243-
```md title="example.mdx"
244-
---
245-
title: Example Article
246-
page_id: 12345678-1234-1234-1234-123456789012
183+
order:
184+
relatedArticles:
185+
-
186+
-
187+
app_context:
188+
- m:
189+
s:
247190
topics:
248-
- contribute
249-
- documentation
250-
- community
251-
---
252-
```
253-
254-
#### <span class="text-lg font-bold">`description` (optional)</span>
255-
256-
**type:** `string`
257-
258-
A brief description of the article content, used for SEO and metadata.
259-
260-
```md title="example.mdx"
261-
---
262-
title: Example Article
263-
page_id: 12345678-1234-1234-1234-123456789012
264-
description: "Comprehensive guide to example functionality including setup, configuration, and best practices."
265-
---
266-
```
267-
268-
#### <span class="text-lg font-bold">`sdk` (optional)</span>
269-
270-
**type:** `array`
271-
272-
Array of SDKs that are relevant to this article. Use `[]` for no SDKs or `null` for not applicable.
273-
274-
```md title="example.mdx"
275-
---
276-
title: Example Article
277-
page_id: 12345678-1234-1234-1234-123456789012
191+
-
192+
-
193+
-
278194
sdk: []
279-
---
280-
```
281-
282-
#### <span class="text-lg font-bold">`languages` (optional)</span>
283-
284-
**type:** `array`
285-
286-
Array of programming languages covered in the article.
287-
288-
```md title="example.mdx"
289-
---
290-
title: Example Article
291-
page_id: 12345678-1234-1234-1234-123456789012
292-
languages:
293-
- javascript
294-
- typescript
295-
- python
296-
---
297-
```
298-
299-
#### <span class="text-lg font-bold">`audience` (optional)</span>
300-
301-
**type:** `string` or `array`
302-
303-
Target audience for the article. Can be a single value or array.
304-
305-
```md title="example.mdx"
306-
---
307-
title: Example Article
308-
page_id: 12345678-1234-1234-1234-123456789012
309-
audience: developers
310-
# or
311-
audience:
312-
- developers
313-
- admins
314-
- product managers
315-
---
316-
```
317-
318-
#### <span class="text-lg font-bold">`complexity` (optional)</span>
319-
320-
**type:** `string`
321-
322-
Difficulty level of the content. Common values: `beginner`, `intermediate`, `advanced`.
323-
324-
```md title="example.mdx"
325-
---
326-
title: Example Article
327-
page_id: 12345678-1234-1234-1234-123456789012
328-
complexity: beginner
329-
---
330-
```
331-
332-
#### <span class="text-lg font-bold">`keywords` (optional)</span>
333-
334-
**type:** `array`
335-
336-
Array of keywords for search optimization.
337-
338-
```md title="example.mdx"
339-
---
340-
title: Example Article
341-
page_id: 12345678-1234-1234-1234-123456789012
195+
languages: []
196+
audience:
197+
complexity:
342198
keywords:
343-
- example
344-
- guide
345-
- tutorial
346-
- setup
199+
-
200+
-
201+
-
202+
-
203+
-
204+
updated: yyyy-mm-dd
205+
featured:
206+
deprecated:
207+
ai-summary:
347208
---
348209
```
349210

350-
#### <span class="text-lg font-bold">`updated` (optional)</span>
211+
#### Required Fields
351212

352-
**type:** `string`
213+
**`title`** (string) - You must provide a title for every page. This will be displayed at the top of the page, in browser tabs, and in page metadata.
353214

354-
Date when the article was last updated in YYYY-MM-DD format.
215+
**`page_id`** (uuid) - This is the internal unique `id` for the article. This will be used when referencing other articles within the `relatedArticles` frontmatter. You can use our [online UUID generator tool](https://kinde.com/tools/online-uuid-generator/) to use as the `page_id`.
355216

356-
```md title="example.mdx"
357-
---
358-
title: Example Article
359-
page_id: 12345678-1234-1234-1234-123456789012
360-
updated: 2024-01-15
361-
---
362-
```
217+
**`description`** (string) - A brief description of the article content, used for SEO and metadata.
363218

364-
#### <span class="text-lg font-bold">`featured` (optional)</span>
219+
**`keywords`** (array) - Array of keywords for search optimization.
365220

366-
**type:** `boolean`
221+
#### Optional Fields
367222

368-
Whether the article should be featured in special displays.
223+
**`order`** (number) - Control the order of this article when sorting an autogenerated group of links under a specific topic or subtopic. Lower numbers are displayed higher up in the link group. Providing the `order` frontmatter is completely optional and will be treated as a hint for us to where to place the file. We may update the article's `order` upon further review.
369224

370-
```md title="example.mdx"
371-
---
372-
title: Example Article
373-
page_id: 12345678-1234-1234-1234-123456789012
374-
featured: false
375-
---
376-
```
225+
**`topics`** (array) - Array of topic tags that help categorize the content.
377226

378-
#### <span class="text-lg font-bold">`deprecated` (optional)</span>
227+
**`sdk`** (array) - Array of SDKs that are relevant to this article. Use `[]` for no SDKs or `null` for not applicable.
379228

380-
**type:** `boolean`
229+
**`languages`** (array) - Array of programming languages covered in the article.
381230

382-
Whether the article content is deprecated.
231+
**`ai-summary`** (string) - A summary of the article content for AI processing and search. Can be same as description.
383232

384-
```md title="example.mdx"
385-
---
386-
title: Example Article
387-
page_id: 12345678-1234-1234-1234-123456789012
388-
deprecated: false
389-
---
390-
```
391-
392-
#### <span class="text-lg font-bold">`ai-summary` (optional)</span>
393-
394-
**type:** `string`
395-
396-
A summary of the article content for AI processing and search.
397-
398-
```md title="example.mdx"
399-
---
400-
title: Example Article
401-
page_id: 12345678-1234-1234-1234-123456789012
402-
ai-summary: "Comprehensive guide to example functionality including setup, configuration, and best practices."
403-
---
404-
```
405-
406-
#### <span class="text-lg font-bold">`relatedArticles` (optional)</span>
407-
408-
**type:** `array`
409-
410-
Array of page IDs for related articles that should be displayed at the bottom of the page.
411-
412-
```md title="example.mdx"
413-
---
414-
title: Example Article
415-
page_id: 12345678-1234-1234-1234-123456789012
416-
relatedArticles:
417-
- 9fa41f57-5ee7-4c8b-a401-f5384e8db1bb
418-
- 8b1b2198-e919-484a-846b-e89422178707
419-
---
420-
```
421-
422-
#### <span class="text-lg font-bold">`app_context` (optional)</span>
423-
424-
**type:** `array`
425-
426-
Used to map documentation to specific application contexts within the Kinde platform. This helps with navigation and contextual linking.
427-
428-
```md title="example.mdx"
429-
---
430-
title: Example Article
431-
page_id: 12345678-1234-1234-1234-123456789012
432-
app_context:
433-
- m: properties
434-
s: properties
435-
---
436-
```
437-
438-
The `app_context` field uses:
439-
- `m`: Module (e.g., `properties`, `billing`, `authenticate`)
440-
- `s`: Section (e.g., `properties`, `plans`, `organizations`)
441-
442-
#### <span class="text-lg font-bold">`social_sharing_image_url` (optional)</span>
443-
444-
**type:** `string`
445-
446-
URL for a custom image to be used when the article is shared on social media platforms.
447-
448-
```md title="example.mdx"
449-
---
450-
title: Example Article
451-
page_id: 12345678-1234-1234-1234-123456789012
452-
social_sharing_image_url: "https://example.com/share-image.jpg"
453-
---
454-
```
455-
456-
<Divider />
233+
**`relatedArticles`** (array) - Array of page IDs for related articles that should be displayed at the bottom of the page.
457234

458235
### Code samples
459236

0 commit comments

Comments
 (0)