Enhance documentation guidelines for Nextra usage in CONTRIBUTING.md, SKILL.md, and related references

- Added instructions to utilize existing Nextra Markdown, MDX, and components for styling and layout before proposing custom solutions.
- Clarified that changes to theme, layout, route, component, or CSS should not be included in content-only documentation updates.
- Emphasized the need to create separate Linear tickets for any required Nextra functionality not currently supported.

Author: mdroidian

CONTRIBUTING.md

@@ -59,6 +59,10 @@ Sidebar order comes from the nearest `_meta.ts` file in the content tree. If you
 
 Flat legacy redirects, such as `/docs/obsidian/<slug>` to `/docs/obsidian/<section>/<slug>`, are maintained in `apps/website/docsRouteMap.ts`.
 
+Use existing Nextra Markdown, MDX, and `nextra/components` features for styling and layout before proposing anything custom. For example, use Nextra callouts, cards, steps, tabs, tables, and file trees when those fit the content.
+
+If the docs need a styling or presentation feature that Nextra does not currently provide, create a separate Linear ticket to add that Nextra functionality. Do not include theme, layout, route, component, or CSS changes in a content-only docs update.
+
 Detailed guidance for plugin docs lives next to the update-user-docs skill:
 
 - **[llm-authoring-guide.md](./skills/update-user-docs/references/llm-authoring-guide.md)** - a short guide non-devs can give to an LLM before asking it to write or update docs

skills/update-user-docs/SKILL.md

@@ -19,6 +19,8 @@ If no argument is provided, use the current branch's diff against main, commit m
 - Put Roam docs under `apps/website/content/roam/**`.
 - Do not edit legacy docs route shells or deleted legacy docs paths such as `apps/website/app/(docs)/docs/*/pages`, `docMap.ts`, `navigation.ts`, or `sharedPages`.
 - Do not update runtime code, app routes, or package interfaces unless the dev explicitly asks for that separately.
+- Use existing Nextra Markdown, MDX, and `nextra/components` features before proposing custom styling or layout.
+- Do not add or change theme, layout, route, component, or CSS code while adding documentation content. If existing Nextra features are not enough, flag the author to create a separate Linear ticket for new Nextra functionality.
 
 ## When to Run
 

skills/update-user-docs/references/doc-conventions.md

@@ -31,6 +31,22 @@ published: true
 
 Use sentence case for page titles unless the title includes an official product name, plugin name, or UI label.
 
+## Nextra styling and formats
+
+Use existing Nextra Markdown, MDX, and `nextra/components` features before proposing custom styling.
+
+Good first choices include:
+
+- Standard Markdown headings, lists, links, tables, and code fences
+- Nextra `Callout` for warnings, tips, notes, and important context
+- Nextra `Cards` for small sets of high-level navigation options
+- Nextra `Steps` for ordered setup or workflow instructions
+- Nextra `Tabs` for compact platform or mode variants
+- Nextra `Table` and `FileTree` when structured data or file paths need clearer presentation
+
+Do not change docs structural code, theme files, route shells, app layouts, shared components, or CSS as part of adding content.
+If the content needs a styling or presentation feature that existing Nextra features cannot support, stop and flag the author to create a separate Linear ticket for adding that Nextra functionality.
+
 ## Links
 
 - Prefer absolute docs routes for cross-page links, such as `/docs/obsidian/core-features/node-tags`.

skills/update-user-docs/references/llm-authoring-guide.md

@@ -13,10 +13,14 @@ Use these paths:
 - Sidebar order: nearest _meta.ts file
 - Flat legacy redirects: apps/website/docsRouteMap.ts
 
-Do not edit route shells or legacy docs paths. Do not use app/(docs)/docs/*/pages, docMap.ts, navigation.ts, or sharedPages.
+Use existing Nextra Markdown, MDX, and nextra/components features first for styling and layout, such as Callout, Cards, Steps, Tabs, Table, and FileTree when appropriate.
+
+Do not edit route shells, theme/layout code, shared components, CSS, or legacy docs paths. Do not use app/(docs)/docs/*/pages, docMap.ts, navigation.ts, or sharedPages.
 
 If adding a page, choose the right platform section, create a kebab-case .md or .mdx file, update the nearest _meta.ts, and update docsRouteMap.ts only when a flat /docs/<platform>/<slug> redirect should exist.
 
+If existing Nextra features are not enough for the requested styling, do not implement new styling in the docs change. Ask for a separate Linear ticket to add the needed Nextra functionality.
+
 For screenshots, use real files in apps/website/public/docs/<platform>/ when available. If screenshots are missing, add an HTML TODO comment and list the needed screenshots in your summary. Do not add broken placeholder images.
 
 Before finishing, verify links, sidebar registration, route redirects, and stale legacy path references.
@@ -65,6 +69,7 @@ If the screenshot is not available yet, add a comment like:
 - Docs edits are under `apps/website/content/**`.
 - New pages are registered in the nearest `_meta.ts`.
 - Needed flat redirects are in `apps/website/docsRouteMap.ts`.
+- Styling uses existing Nextra features and does not change structural code.
 - New links resolve to existing routes or files.
 - Screenshot TODOs are comments, not broken images.
 - No positive instructions point to legacy docs paths.

skills/update-user-docs/references/scope-detection.md

@@ -23,6 +23,8 @@ Use this question to determine whether a code change requires a documentation up
 
 If no docs update is needed, inform the dev and stop.
 
+If a docs content request requires new styling, layout, component, theme, route, or CSS behavior that existing Nextra features cannot provide, do not fold that work into the docs content update. Flag it as a separate Linear ticket for adding new Nextra functionality.
+
 ## File path to docs scope mapping
 
 | Changed file path pattern          | Docs scope                | Target docs location                                                                   |