From 4849bb6610100367f72ed923a1f91900dc05c96f Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Wed, 8 Jul 2026 17:40:53 -0600 Subject: [PATCH 1/4] Update documentation structure and guidelines in CONTRIBUTING.md, SKILL.md, and related references - Added sections for plugin documentation locations and sidebar order management in CONTRIBUTING.md. - Enhanced SKILL.md with guardrails for editing live docs and clarified steps for determining documentation needs. - Updated doc-conventions.md to specify file locations and naming conventions for user-facing plugin docs. - Revised navigation-mapping.md to reflect new content structure and sidebar registration processes. - Improved scope-detection.md with detailed mapping for file paths to documentation scope and clarified when to update docs for both platforms. --- CONTRIBUTING.md | 20 ++- skills/update-user-docs/SKILL.md | 62 +++++++--- .../references/doc-conventions.md | 58 ++++++--- .../references/llm-authoring-guide.md | 72 +++++++++++ .../references/navigation-mapping.md | 115 +++++++++--------- .../references/scope-detection.md | 50 +++++--- 6 files changed, 264 insertions(+), 113 deletions(-) create mode 100644 skills/update-user-docs/references/llm-authoring-guide.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9869a4cc..e198a4501 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,11 +50,21 @@ Blog posts are located in `/apps/website/content/blog/` ### Plugin Documentation +Plugin docs live in the Nextra content tree: + +- **Obsidian docs:** `apps/website/content/obsidian/...` +- **Roam docs:** `apps/website/content/roam/...` + +Sidebar order comes from the nearest `_meta.ts` file in the content tree. If you add a page, add the Markdown or MDX file in the right section and update that section's `_meta.ts`. + +Flat legacy redirects, such as `/docs/obsidian/` to `/docs/obsidian/
/`, are maintained in `apps/website/docsRouteMap.ts`. + Detailed guidance for plugin docs lives next to the update-user-docs skill: -- **[navigation-mapping.md](./skills/update-user-docs/references/navigation-mapping.md)** — where files live, `docMap.ts` (shared pages), and `navigation.ts` (every new page) -- **[doc-conventions.md](./skills/update-user-docs/references/doc-conventions.md)** — filenames, frontmatter, screenshots, and cross-links -- **[scope-detection.md](./skills/update-user-docs/references/scope-detection.md)** — how changed file paths map to Obsidian vs Roam vs shared docs (useful when unsure where a doc belongs) +- **[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 +- **[navigation-mapping.md](./skills/update-user-docs/references/navigation-mapping.md)** - how `_meta.ts` controls sidebar registration and when `docsRouteMap.ts` needs a redirect +- **[doc-conventions.md](./skills/update-user-docs/references/doc-conventions.md)** - filenames, frontmatter, screenshots, and cross-links +- **[scope-detection.md](./skills/update-user-docs/references/scope-detection.md)** - how changed file paths map to Obsidian, Roam, both-platform, or docs-site updates ### Documentation Images @@ -74,8 +84,8 @@ When referencing images in your documentation, use relative paths from the publi To preview your changes locally: 1. **Environment setup**: Copy `/apps/website/.env.example` to `/apps/website/.env` and configure any necessary environment variables -2. **Install dependencies**: Run `npm install` from the project root -3. **Start development server**: Run `npm run dev` or `npx turbo dev` to start the website locally +2. **Install dependencies**: Run `pnpm install` from the project root +3. **Start development server**: Run `pnpm dev` or `pnpm exec turbo dev` to start the website locally 4. **View your changes**: Navigate to `http://localhost:3000` to see your documentation The website uses Next.js with the App Router, so changes to Markdown files should be reflected automatically during development. diff --git a/skills/update-user-docs/SKILL.md b/skills/update-user-docs/SKILL.md index 8d7b68a6f..663ee176d 100644 --- a/skills/update-user-docs/SKILL.md +++ b/skills/update-user-docs/SKILL.md @@ -12,12 +12,20 @@ If `$ARGUMENTS` is provided, treat it as a GitHub PR number. Use `gh pr view $AR If no argument is provided, use the current branch's diff against main, commit messages, and any linked Linear ticket to determine what changed. +## Guardrails + +- Edit live docs only under `apps/website/content/**`. +- Put Obsidian docs under `apps/website/content/obsidian/**`. +- 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. + ## When to Run On demand. Two modes: -- **Current branch** — Run while on a feature branch that's ready for PR or review. -- **Merged PR** — Pass a PR number to generate docs for an already-merged PR that's missing documentation. +- **Current branch** - Run while on a feature branch that's ready for PR or review. +- **Merged PR** - Pass a PR number to generate docs for an already-merged PR that's missing documentation. ## Step 1: Gather Context @@ -25,41 +33,57 @@ On demand. Two modes: Collect information from three sources: -1. **Changed files** — Run `git diff main...HEAD --name-only` to identify what changed. Use file paths to determine the affected platform (see [scope-detection.md](references/scope-detection.md) for mapping). -2. **Commit messages** — Run `git log main...HEAD --oneline` for a summary of what was done. -3. **Linear ticket** — If a Linear ticket is linked (branch name or PR description), pull the title, description, and acceptance criteria for additional context. Use Linear MCP if available. If it's not available, prompt the dev to install Linear MCP using these instructions: https://linear.app/docs/mcp +1. **Changed files** - Run `git diff main...HEAD --name-only` to identify what changed. Use file paths to determine the affected platform (see [scope-detection.md](references/scope-detection.md) for mapping). +2. **Commit messages** - Run `git log main...HEAD --oneline` for a summary of what was done. +3. **Linear ticket** - If a Linear ticket is linked by branch name or PR description, pull the title, description, and acceptance criteria for additional context. Use the Linear connector if available. If it is not available, prompt the dev to install Linear MCP using these instructions: https://linear.app/docs/mcp ### If running for a merged PR Use the PR number to gather context via `gh`: -1. **PR details** — Run `gh pr view ` to get the title, description, and linked issues. -2. **Changed files** — Run `gh pr diff --name-only` to identify what changed. Use file paths to determine the affected platform. -3. **Linear ticket** — If a Linear ticket is referenced in the PR title, branch name, or description, pull additional context from it. +1. **PR details** - Run `gh pr view ` to get the title, description, and linked issues. +2. **Changed files** - Run `gh pr diff --name-only` to identify what changed. Use file paths to determine the affected platform. +3. **Linear ticket** - If a Linear ticket is referenced in the PR title, branch name, or description, pull additional context from it. ## Step 2: Determine If Docs Are Needed -Apply the scope detection heuristic. See [scope-detection.md](references/scope-detection.md) for the full yes/no lists and file path → platform mapping. +Apply the scope detection heuristic. See [scope-detection.md](references/scope-detection.md) for the full yes/no lists and file path to platform mapping. If no docs update is needed, inform the dev and stop. ## Step 3: New Page vs Update Existing -1. Search existing documentation for content related to the change. See [doc-conventions.md](references/doc-conventions.md) for file locations. -2. **Ask the dev:** "I found these existing pages that might be related: [list]. Should I update one of these, or create a new page?" -3. Defaults: - - Completely new feature with no existing coverage → new page - - Extending or modifying an already-documented feature → update existing page +1. Search existing docs only under `apps/website/content/**`. +2. Prefer updating an existing page when the change extends or corrects an already-documented feature. +3. Create a new page when the feature or workflow has no natural existing home. +4. If multiple plausible homes exist, ask the dev which page or section should own the content. + +Defaults: + +- Completely new feature with no existing coverage -> new page. +- Extending or modifying an already-documented feature -> update the existing page. +- Change applies to both platforms -> update both platform docs unless the existing docs already share a conceptual page through both sidebars. ## Step 4: Write or Update the Doc -Follow the formatting rules in [doc-conventions.md](references/doc-conventions.md) (frontmatter, filenames, screenshot placeholders, cross-link integrity, side observations). +Follow the formatting rules in [doc-conventions.md](references/doc-conventions.md). + +For an **existing page**: + +1. Edit the Markdown or MDX file under the relevant `apps/website/content/**` path. +2. Preserve existing frontmatter and local style. +3. Verify any new links point to live docs routes or existing files. + +For a **new page**: -If a **new page** is created, register it in navigation. See [navigation-mapping.md](references/navigation-mapping.md) for `docMap.ts` and `navigation.ts` patterns and examples. +1. Choose the correct platform and section directory, such as `apps/website/content/obsidian/core-features/` or `apps/website/content/roam/guides/`. +2. Add a kebab-case `.md` or `.mdx` file with frontmatter. +3. Add the page slug to the nearest `_meta.ts` file so it appears in the sidebar. See [navigation-mapping.md](references/navigation-mapping.md). +4. Update `apps/website/docsRouteMap.ts` only when a flat legacy redirect like `/docs//` should continue to resolve to the new sectioned route. ## Step 5: Verification 1. Present the draft changes to the dev for review. -2. List any screenshot placeholders that need filling. -3. Flag any broken cross-links or stale content observed. -4. **Leave all changes as unstaged modifications** — do not commit. The dev reviews and commits themselves. +2. List any screenshots that still need to be captured. +3. Flag broken cross-links, missing route map redirects, or stale content observed while editing. +4. Leave all changes as unstaged modifications. The dev reviews and commits themselves. diff --git a/skills/update-user-docs/references/doc-conventions.md b/skills/update-user-docs/references/doc-conventions.md index 26f6bb03a..756661c1c 100644 --- a/skills/update-user-docs/references/doc-conventions.md +++ b/skills/update-user-docs/references/doc-conventions.md @@ -1,49 +1,73 @@ # Documentation Conventions -## File Locations +## File locations -Platform-specific docs live in their respective directories: +User-facing plugin docs live in the Nextra content tree: -- **Obsidian:** `apps/website/app/(docs)/docs/obsidian/pages/` -- **Roam:** `apps/website/app/(docs)/docs/roam/pages/` -- **Shared (cross-platform):** `apps/website/app/(docs)/docs/sharedPages/` +- Obsidian: `apps/website/content/obsidian/**` +- Roam: `apps/website/content/roam/**` +- Blog posts: `apps/website/content/blog/**` +- Site-wide docs landing pages: `apps/website/content/**` -Only place docs in `sharedPages/` if the content applies identically to both platforms and is explicitly specified as shared. +Do not create plugin docs outside `apps/website/content/**`. -## Filename Convention +## Filename convention -Use **kebab-case** for all doc filenames (e.g., `creating-discourse-nodes.md`). +Use kebab-case for doc filenames, such as `creating-discourse-nodes.md`. +Use `.md` for normal prose pages and `.mdx` only when the page needs components. ## Frontmatter -Every doc file **must** include this frontmatter block: +Every plugin doc file should include this frontmatter block unless nearby files in the same section use a different required shape: ```yaml --- -title: "Page Title" +title: "Page title" date: "YYYY-MM-DD" author: "" published: true --- ``` -## Screenshot Placeholders +Use sentence case for page titles unless the title includes an official product name, plugin name, or UI label. -For UI changes or new features with visual elements, insert a placeholder: +## Links + +- Prefer absolute docs routes for cross-page links, such as `/docs/obsidian/core-features/node-tags`. +- Use relative links only when the target is in the same local section and the existing section already uses relative links. +- Verify every new link points to an existing file or route. +- Do not link to old flat routes when the current sectioned route is known. + +## Screenshots and media + +Place documentation images in `apps/website/public/docs//`. + +Use public paths in Markdown: ```markdown -![Screenshot placeholder](placeholder) +![Screenshot placeholder](/docs/roam/my-image.png) ``` -Always inform the dev that there are screenshot placeholders to fill in. +For UI changes or visual features: -## Cross-Link Integrity +- Use a real screenshot when one is available. +- If no screenshot is available, add an HTML TODO comment describing what should be captured. +- Tell the dev exactly which screenshots still need to be captured. + +## Cross-link integrity - When adding or updating cross-links (e.g., `[text](./other-page)`), verify that the target page exists. - If a link target does not exist, flag it to the dev. +- + +## Cross-platform content + +If a change applies to both Obsidian and Roam, update both platform docs unless there is already a shared conceptual page surfaced from both sidebars. +Keep platform-specific commands, settings names, and screenshots in the relevant platform section. -## Side Observations +## Side observations -If while editing an existing doc you notice stale or incorrect content unrelated to the current change, flag it as a side observation to the dev. Do not silently fix unrelated content. +If you notice stale or incorrect content unrelated to the current change, flag it as a side observation. +Do not silently fix unrelated docs content unless the dev asks you to broaden the scope. diff --git a/skills/update-user-docs/references/llm-authoring-guide.md b/skills/update-user-docs/references/llm-authoring-guide.md new file mode 100644 index 000000000..f20c28cf8 --- /dev/null +++ b/skills/update-user-docs/references/llm-authoring-guide.md @@ -0,0 +1,72 @@ +# LLM Authoring Guide + +Use this guide when asking an LLM to write or update Discourse Graphs docs. + +## Copy/paste prompt + +```text +Write or update Discourse Graphs user docs in the live Nextra content tree only. + +Use these paths: +- Obsidian docs: apps/website/content/obsidian/** +- Roam docs: apps/website/content/roam/** +- 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. + +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// redirect should exist. + +For screenshots, use real files in apps/website/public/docs// 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. +``` + +## Correct path examples + +- Existing Obsidian page: `apps/website/content/obsidian/core-features/creating-discourse-nodes.md` +- New Obsidian page: `apps/website/content/obsidian/core-features/my-new-feature.md` +- Existing Roam page: `apps/website/content/roam/guides/querying-discourse-graph.md` +- Nested Roam section: `apps/website/content/roam/guides/exploring-discourse-graph/discourse-context.md` +- Sidebar metadata: `apps/website/content/obsidian/core-features/_meta.ts` +- Redirect map: `apps/website/docsRouteMap.ts` +- Screenshots: `apps/website/public/docs/obsidian/my-screenshot.png` + +## Updating an existing page + +1. Search `apps/website/content/**` for the feature, setting, command, or workflow. +2. Edit the closest existing platform page. +3. Preserve frontmatter and the page's current tone. +4. Verify every new link points to a live docs route or existing file. +5. Mention any screenshot TODOs or unrelated stale content in the final summary. + +## Adding a new page + +1. Pick the platform: `obsidian` or `roam`. +2. Pick the section that matches the user's workflow. +3. Create a kebab-case `.md` or `.mdx` file. +4. Add frontmatter with title, date, author, and published fields. +5. Add the slug to the nearest `_meta.ts` file. +6. Update `apps/website/docsRouteMap.ts` only if a flat legacy route should redirect to the sectioned route. + +## Screenshot handling + +Use screenshots only when the file exists or the dev provides it. +If the screenshot is not available yet, add a comment like: + +```markdown + + +![Screenshot placeholder](/docs/obsidian/example-screenshot.png) +``` + +## Final review checklist + +- 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`. +- New links resolve to existing routes or files. +- Screenshot TODOs are comments, not broken images. +- No positive instructions point to legacy docs paths. + +Legacy warning: route shells and deleted legacy docs paths such as `app/(docs)/docs/*/pages`, `docMap.ts`, `navigation.ts`, and `sharedPages` are not docs authoring targets. diff --git a/skills/update-user-docs/references/navigation-mapping.md b/skills/update-user-docs/references/navigation-mapping.md index 1f28e0bf8..1b9242288 100644 --- a/skills/update-user-docs/references/navigation-mapping.md +++ b/skills/update-user-docs/references/navigation-mapping.md @@ -1,86 +1,85 @@ # Navigation Mapping -When a **new page** is created, it must be registered in two places: `docMap.ts` (for shared pages) and `navigation.ts` (for all new pages). +The live docs use Nextra content files under `apps/website/content/**`. +Sidebar structure comes from `_meta.ts` files placed next to the Markdown and MDX files they describe. -## docMap.ts — Slug-to-directory mapping +## Content locations -Maps page slugs to their content directories. Platform-specific pages use the `default` path automatically, so you only need to add entries here for **shared pages**. +- Obsidian docs: `apps/website/content/obsidian/**` +- Roam docs: `apps/website/content/roam/**` +- Shared top-level docs: `apps/website/content/**` only when the page is intentionally site-wide, not plugin-specific -### File locations +## Sidebar registration with `_meta.ts` -- Obsidian: `apps/website/app/(docs)/docs/obsidian/docMap.ts` -- Roam: `apps/website/app/(docs)/docs/roam/docMap.ts` -- Shared: `apps/website/app/(docs)/docs/shared/docMap.ts` +Each directory can include a `_meta.ts` file that controls page titles, section labels, order, and hidden index pages. -### How it works - -Each platform's `docMap.ts` spreads in `sharedDocMap` from the shared module. Platform-specific pages resolve via the `default` key. - -**Obsidian example:** +Top-level example: ```ts -import { DocMapType, sharedDocMap } from "~/(docs)/docs/shared/docMap"; +import type { MetaRecord } from "nextra"; -const OBSIDIAN_DOCS = "app/(docs)/docs/obsidian/pages"; - -export const docMap: DocMapType = { - default: OBSIDIAN_DOCS, - ...sharedDocMap, +const meta: MetaRecord = { + index: { + title: "Overview", + display: "hidden", + }, + welcome: "Welcome", + "core-features": "Core features", + "use-cases": "Use cases", }; + +export default meta; ``` -**Shared docMap (`apps/website/app/(docs)/docs/shared/docMap.ts`):** +Section example: ```ts -export const SHARED_DOCS = "app/(docs)/docs/sharedPages"; - -export const sharedDocMap = { - "what-is-a-discourse-graph": SHARED_DOCS, - "base-grammar": SHARED_DOCS, - "literature-reviewing": SHARED_DOCS, - "research-roadmapping": SHARED_DOCS, - "reading-clubs": SHARED_DOCS, - "lab-notebooks": SHARED_DOCS, -} as const; +import type { MetaRecord } from "nextra"; + +const meta: MetaRecord = { + "creating-discourse-nodes": "Creating nodes", + "creating-discourse-relationships": "Creating relationships", + "querying-discourse-graph": "Querying", +}; + +export default meta; ``` -**When to update:** Only when adding a shared page. Add the slug → `SHARED_DOCS` mapping in `sharedDocMap`. +When adding a new page: -## navigation.ts — Sidebar navigation +1. Add the `.md` or `.mdx` file in the correct section directory. +2. Add the file slug to that directory's `_meta.ts`. +3. Add parent section entries in parent `_meta.ts` files only if you created a new directory. +4. Keep titles short enough for the sidebar. -Controls what appears in the docs sidebar. **Must be updated for every new page.** +## Redirects with `docsRouteMap.ts` -### File locations +The docs now use sectioned routes such as `/docs/obsidian/core-features/creating-discourse-nodes`. +Some older flat routes, such as `/docs/obsidian/creating-discourse-nodes`, are preserved by redirects in `apps/website/docsRouteMap.ts`. -- Obsidian: `apps/website/app/(docs)/docs/obsidian/navigation.ts` -- Roam: `apps/website/app/(docs)/docs/roam/navigation.ts` +Update `docsRouteMap.ts` when: -### Structure +- You add a new page that should keep or introduce a flat `/docs//` redirect. +- You move an existing page to a different section and need its old URL to resolve. +- You add a nested page whose old URL had a custom location. -Navigation is an array of sections, each with a title and links: +Do not update `docsRouteMap.ts` when: -```ts -import { NavigationList } from "~/components/Navigation"; +- You only edit existing page content. +- The new page does not need a legacy flat URL. +- The route is already covered by the platform section maps or custom redirects. -const ROOT = "/docs/obsidian"; +For most new pages, add the slug under the correct platform section map: -export const navigation: NavigationList = [ - { - title: "🏠 Getting started", - links: [ - { title: "Getting started", href: `${ROOT}/getting-started` }, - { title: "Installation", href: `${ROOT}/installation` }, - ], - }, - { - title: "⚙️ Configuration", - links: [ - { title: "Node types & templates", href: `${ROOT}/node-types-templates` }, - { title: "Relationship types", href: `${ROOT}/relationship-types` }, - ], - }, - // ...more sections -]; +```ts +export const OBSIDIAN_DOC_SECTIONS = { + "core-features": ["creating-discourse-nodes", "new-page-slug"], +} as const; ``` -**To add a new page:** Insert a ``{ title: "Page Title", href: `${ROOT}/slug` }`` entry in the appropriate section's `links` array. +Use `createRedirect` for custom or nested redirects that cannot be represented by the section maps. + +## Legacy warning + +Do not use the deleted legacy docs mapping files: `docMap.ts`, `navigation.ts`, or `sharedPages`. +They are no longer the source of truth for docs navigation. diff --git a/skills/update-user-docs/references/scope-detection.md b/skills/update-user-docs/references/scope-detection.md index 0018443a0..266e6bab1 100644 --- a/skills/update-user-docs/references/scope-detection.md +++ b/skills/update-user-docs/references/scope-detection.md @@ -1,6 +1,6 @@ # Scope Detection -## Heuristic: "Would a user notice this change?" +## Heuristic: would a user notice this change? Use this question to determine whether a code change requires a documentation update. @@ -9,27 +9,49 @@ Use this question to determine whether a code change requires a documentation up - New user-facing feature - Changed behavior of an existing feature - Removed feature -- New, changed, or removed settings/configuration -- Changed setup or prerequisites -- Deprecation of a feature (add a warning note, don't remove content) +- New, changed, or removed settings or configuration +- Changed setup, installation, permissions, or prerequisites +- Deprecation of a feature, which should be documented with a warning note -## Do NOT update docs for +## Do not update docs for - Internal refactor with no user-visible change - Bug fix that restores already-documented behavior - Test-only changes -- Dev tooling changes (CI, linting, build config) +- Dev tooling changes, CI, linting, or build config - Performance optimization with no user-facing behavior change If no docs update is needed, inform the dev and stop. -## File Path to Platform Mapping +## File path to docs scope mapping -Use changed file paths to determine which platform's docs are affected: +| Changed file path pattern | Docs scope | Target docs location | +| ---------------------------------- | ------------------------- | -------------------------------------------------------------------------------------- | +| `apps/obsidian/**` | Obsidian | `apps/website/content/obsidian/**` | +| `apps/roam/**` | Roam | `apps/website/content/roam/**` | +| `apps/website/content/obsidian/**` | Obsidian docs site | `apps/website/content/obsidian/**` | +| `apps/website/content/roam/**` | Roam docs site | `apps/website/content/roam/**` | +| `apps/website/content/blog/**` | Blog | `apps/website/content/blog/**` | +| `apps/website/docsRouteMap.ts` | Docs redirects | Usually no prose docs update unless a route move needs explanation | +| `packages/content-model/**` | Both platforms | Check whether both plugin docs need the same conceptual update | +| `packages/database/**` | Both platforms or website | Ask whether the change affects plugin users, website users, or internal APIs | +| `packages/ui/**` | Docs site or product UI | Update docs only if user-facing docs behavior changed | +| `packages/**` | Ask dev | Could affect Obsidian, Roam, both platforms, or internal code only | +| `apps/website/app/**` | Website or docs site | Update prose docs only if public docs behavior or user-facing website behavior changed | +| `skills/update-user-docs/**` | Docs authoring guidance | Update this skill's references, not live product docs | -| File path pattern | Platform | Doc directory | -| ----------------- | -------- | --------------------------------------------------------------- | -| `apps/obsidian/` | Obsidian | `apps/website/app/(docs)/docs/obsidian/pages/` | -| `apps/roam/` | Roam | `apps/website/app/(docs)/docs/roam/pages/` | -| `packages/` | Ask dev | Could affect either or both platforms | -| `apps/website/` | Website | Usually not user-facing docs (unless it's the docs site itself) | +## Both-platform updates + +When a feature exists in both plugins, check both platform content trees before editing. +Do not assume the Roam and Obsidian docs have identical structure or screenshots. + +Common both-platform targets: + +- Shared concepts: `apps/website/content//fundamentals/**` +- Similar workflows: `apps/website/content//core-features/**` or `apps/website/content/roam/guides/**` +- Use cases: `apps/website/content//use-cases/**` + +## Docs-site updates + +For changes that only affect the docs website, search `apps/website/content/**`, `_meta.ts` files, and `apps/website/docsRouteMap.ts`. +Do not update plugin feature docs unless the user-facing plugin instructions changed. From 71ef9311eca4fa335b2d5a99951ef1a178a855cb Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Wed, 8 Jul 2026 17:44:50 -0600 Subject: [PATCH 2/4] 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. --- CONTRIBUTING.md | 4 ++++ skills/update-user-docs/SKILL.md | 2 ++ .../references/doc-conventions.md | 16 ++++++++++++++++ .../references/llm-authoring-guide.md | 7 ++++++- .../references/scope-detection.md | 2 ++ 5 files changed, 30 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e198a4501..da12c521b 100644 --- a/CONTRIBUTING.md +++ b/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/` to `/docs/obsidian/
/`, 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 diff --git a/skills/update-user-docs/SKILL.md b/skills/update-user-docs/SKILL.md index 663ee176d..e682f7b7f 100644 --- a/skills/update-user-docs/SKILL.md +++ b/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 diff --git a/skills/update-user-docs/references/doc-conventions.md b/skills/update-user-docs/references/doc-conventions.md index 756661c1c..e4a68ea18 100644 --- a/skills/update-user-docs/references/doc-conventions.md +++ b/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`. diff --git a/skills/update-user-docs/references/llm-authoring-guide.md b/skills/update-user-docs/references/llm-authoring-guide.md index f20c28cf8..16cbf6ea9 100644 --- a/skills/update-user-docs/references/llm-authoring-guide.md +++ b/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// 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// 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. diff --git a/skills/update-user-docs/references/scope-detection.md b/skills/update-user-docs/references/scope-detection.md index 266e6bab1..1d7566962 100644 --- a/skills/update-user-docs/references/scope-detection.md +++ b/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 | From bb687aa5a9d947da6b47fece48966fed9870c149 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Wed, 8 Jul 2026 17:53:34 -0600 Subject: [PATCH 3/4] . --- skills/update-user-docs/references/doc-conventions.md | 4 +--- skills/update-user-docs/references/llm-authoring-guide.md | 5 ++--- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/skills/update-user-docs/references/doc-conventions.md b/skills/update-user-docs/references/doc-conventions.md index e4a68ea18..d8210df2d 100644 --- a/skills/update-user-docs/references/doc-conventions.md +++ b/skills/update-user-docs/references/doc-conventions.md @@ -62,8 +62,7 @@ Use public paths in Markdown: ```markdown - -![Screenshot placeholder](/docs/roam/my-image.png) + ``` For UI changes or visual features: @@ -76,7 +75,6 @@ For UI changes or visual features: - When adding or updating cross-links (e.g., `[text](./other-page)`), verify that the target page exists. - If a link target does not exist, flag it to the dev. -- ## Cross-platform content diff --git a/skills/update-user-docs/references/llm-authoring-guide.md b/skills/update-user-docs/references/llm-authoring-guide.md index 16cbf6ea9..3fc23facc 100644 --- a/skills/update-user-docs/references/llm-authoring-guide.md +++ b/skills/update-user-docs/references/llm-authoring-guide.md @@ -59,9 +59,8 @@ Use screenshots only when the file exists or the dev provides it. If the screenshot is not available yet, add a comment like: ```markdown - - -![Screenshot placeholder](/docs/obsidian/example-screenshot.png) + + ``` ## Final review checklist From 145fba8d9169642ada5334d6bbd11975fa94df89 Mon Sep 17 00:00:00 2001 From: Michael Gartner Date: Wed, 8 Jul 2026 18:22:20 -0600 Subject: [PATCH 4/4] minor update --- CONTRIBUTING.md | 6 +++--- skills/update-user-docs/references/llm-authoring-guide.md | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da12c521b..e297abeda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ If you’re uncertain about the value of your proposed change, don’t hesitate Here’s how to contribute: -1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) and [clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) the repository. +1. [Fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) or [clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) the repository. 2. [Create a new branch](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/managing-branches) for your updates. 3. Implement your changes, making sure your code: - Is formatted with [Prettier](https://prettier.io) @@ -63,7 +63,7 @@ Use existing Nextra Markdown, MDX, and `nextra/components` features for styling 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: +Preferred: Use the `$update-user-docs` skill to update plugin docs. 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 - **[navigation-mapping.md](./skills/update-user-docs/references/navigation-mapping.md)** - how `_meta.ts` controls sidebar registration and when `docsRouteMap.ts` needs a redirect @@ -89,7 +89,7 @@ To preview your changes locally: 1. **Environment setup**: Copy `/apps/website/.env.example` to `/apps/website/.env` and configure any necessary environment variables 2. **Install dependencies**: Run `pnpm install` from the project root -3. **Start development server**: Run `pnpm dev` or `pnpm exec turbo dev` to start the website locally +3. **Start development server**: Run `pnpm exec turbo dev -F website` or navigate to `apps/website` and run `pnpm dev` to start the website locally 4. **View your changes**: Navigate to `http://localhost:3000` to see your documentation The website uses Next.js with the App Router, so changes to Markdown files should be reflected automatically during development. diff --git a/skills/update-user-docs/references/llm-authoring-guide.md b/skills/update-user-docs/references/llm-authoring-guide.md index 3fc23facc..4d7de62a9 100644 --- a/skills/update-user-docs/references/llm-authoring-guide.md +++ b/skills/update-user-docs/references/llm-authoring-guide.md @@ -5,6 +5,8 @@ Use this guide when asking an LLM to write or update Discourse Graphs docs. ## Copy/paste prompt ```text +Preferred: Use the $update-user-docs skill to update plugin docs. If you cannot use the skill, follow these instructions: + Write or update Discourse Graphs user docs in the live Nextra content tree only. Use these paths: