An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): a Use integrations guide, so consumer queries find consumer docs first (#7153)
Joey0bf23bdbf686
diff --git a/.changeset/search-consumer-ranking.md b/.changeset/search-consumer-ranking.mdnew file mode 100644index 0000000000..fc645dae8f--- /dev/null+++ b/.changeset/search-consumer-ranking.md@@ -0,0 +1,13 @@+---+'@astryxdesign/cli': patch+---++[docs] A new "Use integrations" guide, so consumer queries find consumer docs first, not authoring content.++@josephfarina++Added a "Use integrations" guide (`use-integrations.doc.mjs`) that covers+discovering, installing, and using integration packages in an app. Search+now ranks it above authoring and API-function docs for consumer-phrased+queries like "add an integration" or "install a package". Authoring+queries like "build an integration" still rank authoring content first.diff --git a/apps/docsite/src/__tests__/route-resolution.test.ts b/apps/docsite/src/__tests__/route-resolution.test.tsindex d030ff1dee..1824ff7e64 100644--- a/apps/docsite/src/__tests__/route-resolution.test.ts+++ b/apps/docsite/src/__tests__/route-resolution.test.ts@@ -91,7 +91,8 @@ describe('route resolution', () => {// The Guide section as it was before the CLI integration guide and the// other topics were split into short guides. `styling-overview` and// `cli-host-entry` are topics added since; `global` is the Global mode- // page; `authoring` holds what CLI Integrations and Writing docs did.+ // page; `authoring` holds what CLI Integrations and Writing docs did;+ // `use-integrations` is the guide for apps that install one.const sidebarGuides = docTopics.filter(d => d.category === 'guide' && d.topic !== 'getting-started').map(d => d.topic)@@ -112,6 +113,7 @@ describe('route resolution', () => {'styling-libraries','styling-overview','theme',+ 'use-integrations','working-with-ai',].sort(),);@@ -121,7 +123,9 @@ describe('route resolution', () => {expect(pageBySlug.get('authoring')?.category).toBe('guide');let guides = 0;for (const route of docsTreeRoutes) {- if (!route.startsWith('authoring/')) {continue;}+ if (!route.startsWith('authoring/')) {+ continue;+ }guides++;const slug = route.replaceAll('/', '-');expect(pageBySlug.has(slug), slug).toBe(false);@@ -150,7 +154,9 @@ describe('route resolution', () => {expect(docRedirects['cli-global']).toBe('/docs/global');expect(docRedirects['cli-install-once']).toBe('/docs/global');for (const route of docsTreeRoutes) {- if (!route.startsWith('global/')) {continue;}+ if (!route.startsWith('global/')) {+ continue;+ }const slug = route.replaceAll('/', '-');expect(docRedirects[slug], slug).toMatch(/^\/docs\/global#/);}diff --git a/packages/cli/assets/docs/use-integrations.doc.mjs b/packages/cli/assets/docs/use-integrations.doc.mjsnew file mode 100644index 0000000000..097bacd486--- /dev/null+++ b/packages/cli/assets/docs/use-integrations.doc.mjs@@ -0,0 +1,120 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */++export const docs = {+ type: 'generic',+ name: 'use-integrations',+ title: 'Use integrations',+ category: 'guide',+ description:+ 'Install, discover, and use integration packages that add components, templates, themes, and docs to your app.',+ keywords: [+ 'install an integration',+ 'add an integration',+ 'install a package',+ 'use an integration',+ 'discover integrations',+ 'integration',+ 'package',+ 'third party',+ 'plugin',+ 'extension',+ ],++ sections: [+ {+ title: 'Discover integrations',+ content: [+ {+ type: 'prose',+ text: 'Integration packages extend Astryx with extra components, templates, themes, docs, and codemods. They are published as regular npm packages.',+ },+ {+ type: 'prose',+ text: 'Search for what you need:',+ },+ {+ type: 'code',+ lang: 'bash',+ code: 'astryx search carousel\nastryx discover',+ },+ {+ type: 'prose',+ text: '`search` looks across everything the CLI knows (components, docs, templates, themes, and hooks), so a word like "carousel" finds it whether it is a component, a template, or a doc page. `discover` lists every integration the project has, and, with a discover source, packages it could add.',+ },+ ],+ },+ {+ title: 'Install an integration',+ content: [+ {+ type: 'prose',+ text: 'Install the package with your package manager. Integrations autolink: the CLI finds them among your dependencies, so installing is all it takes:',+ },+ {+ type: 'code',+ lang: 'bash',+ code: 'npm install @acme/brand-integration',+ },+ {+ type: 'prose',+ text: 'Run `astryx doctor` to confirm everything is wired up. If you need to load a package that is not a direct dependency, add it explicitly to `astryx.config.mjs`:',+ },+ {+ type: 'code',+ lang: 'js',+ label: 'Optional: explicit config entry',+ code: "export default {\n integrations: ['@acme/brand-integration'],\n};",+ },+ ],+ },+ {+ title: 'Use what it adds',+ content: [+ {+ type: 'prose',+ text: 'Once installed, the integration\'s contributions appear alongside Core:',+ },+ {+ type: 'list',+ style: 'unordered',+ items: [+ '`astryx component --list` shows its components next to Core components.',+ '`astryx template --list` includes its page and block templates.',+ '`astryx theme list` lists its themes; add one with `astryx theme add <slug> --package @acme/brand-integration`.',+ '`astryx docs` shows any guides it provides.',+ '`astryx search <query>` finds everything, from every installed integration.',+ ],+ },+ {+ type: 'prose',+ text: 'Import components at the subpath the integration documents. Run `astryx component <Name>` to see the exact import:',+ },+ {+ type: 'code',+ lang: 'jsx',+ code: "import {AcmeCarousel} from '@acme/brand-integration/components/AcmeCarousel';",+ },+ {+ type: 'prose',+ text: 'For themes, see {@link generic:use-a-theme}. To build an integration of your own, see {@link namespace:authoring}.',+ },+ ],+ },+ {+ title: 'Check for problems',+ content: [+ {+ type: 'prose',+ text: 'Run `astryx doctor` to see integration issues: missing roots, invalid contributions, or a CLI version mismatch. The doctor check is the one place every issue for every package is listed.',+ },+ {+ type: 'code',+ lang: 'bash',+ code: 'astryx doctor',+ },+ ],+ },+ ],+};diff --git a/packages/cli/test/search-consumer-ranking.test.mjs b/packages/cli/test/search-consumer-ranking.test.mjsnew file mode 100644index 0000000000..14cbc3b678--- /dev/null+++ b/packages/cli/test/search-consumer-ranking.test.mjs@@ -0,0 +1,53 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Consumer queries rank consumer docs above authoring docs.+ *+ * An app builder searching "add an integration" or "use a theme" should find+ * consumer guides in the first 3 results, not the authoring reference or the+ * API function docs. Authoring queries ("create an integration", "build an+ * integration") should still rank authoring content first.+ */++import {describe, it, expect} from 'vitest';+import {search} from '../api/search/search.mjs';++// Each case: [query, expected-name-in-top-3, must-NOT-be-first]+/** @type {Array<[string, string, string?]>} */+const CONSUMER_QUERIES = [+ ['add an integration', 'use-integrations'],+ ['use an integration', 'use-integrations'],+ ['install a package', 'use-integrations'],+ ['discover integrations', 'use-integrations'],+ ['install an integration', 'use-integrations'],+ ['how to use a theme', 'use-a-theme'],+];++/** @type {Array<[string, string]>} */+const AUTHORING_QUERIES = [+ ['build an integration', 'authoring'],+ ['create an integration', 'authoring'],+];++describe('consumer queries rank consumer docs first', () => {+ for (const [query, expected] of CONSUMER_QUERIES) {+ it(`"${query}" ranks "${expected}" first`, async () => {+ const res = await search(query);+ const first = res.data.results[0]?.name;+ expect(first, `first for "${query}": ${first}`).toBe(expected);+ });+ }+});++describe('authoring queries still rank authoring content first', () => {+ for (const [query, expected] of AUTHORING_QUERIES) {+ it(`"${query}" ranks "${expected}" in the top 3`, async () => {+ const res = await search(query);+ const top3 = res.data.results.slice(0, 3).map(r => r.name);+ expect(+ top3.some(name => name.startsWith(expected)),+ `top 3 for "${query}": ${top3.join(', ')} should contain a ${expected} result`,+ ).toBe(true);+ });+ }+});