diff --git a/.cursor/rules/content-guide.mdc b/.cursor/rules/content-guide.mdc index 4bbf57f7..ea26e45b 100644 --- a/.cursor/rules/content-guide.mdc +++ b/.cursor/rules/content-guide.mdc @@ -96,3 +96,17 @@ description: "Concise description explaining page purpose and value" - Use **RequestExample/ResponseExample** specifically for API endpoint documentation - Use **ParamField** for API parameters, **ResponseField** for API responses - Use **Expandable** for nested object properties or hierarchical information + +## Base App Spelling Rules + +- Always write as **"the Base app"** with lowercase "app" in mid-sentence usage +- Write as **"The Base App"** with both words capitalized only at the start of sentences +- Never use **"Base App"** as a standalone term without the article "the" or "The" +- The word "App" is capitalized only when "The" is also capitalized (sentence-initial position) + +## Find and Replace Pattern + +- Find **"Base App"** without preceding article → Replace with **"the Base app"** +- Find **"the Base App"** in mid-sentence → Replace with **"the Base app"** +- Find **"The Base app"** at sentence start → Replace with **"The Base App"** +- Find **"the Base app"** after periods, colons, or sentence-ending punctuation → Replace with **"The Base App"** \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index da20067f..d36e0dba 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -453,8 +453,6 @@ { "group": "Technical Guides", "pages": [ - "mini-apps/technical-guides/search-and-discovery", - "mini-apps/technical-guides/sharing-and-social-graph", "mini-apps/technical-guides/sign-manifest", "mini-apps/technical-guides/neynar-notifications" ] @@ -482,7 +480,8 @@ "group": "Troubleshooting", "pages": [ "mini-apps/troubleshooting/common-issues", - "mini-apps/troubleshooting/base-app-compatibility" + "mini-apps/troubleshooting/base-app-compatibility", + "mini-apps/troubleshooting/how-search-works" ] }, { @@ -1492,6 +1491,10 @@ ] }, "redirects": [ + { + "source": "/mini-apps/technical-guides/search-discovery", + "destination": "/mini-apps/troubleshooting/how-search-works" + }, { "source": "/mini-apps/overview", "destination": "/mini-apps/quickstart/create-new-miniapp" @@ -1518,7 +1521,7 @@ }, { "source": "/mini-apps/features/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-and-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/mini-apps/features/sharing-and-social-graph", @@ -2690,11 +2693,11 @@ }, { "source": "/base-app/miniapps/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-and-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/base-app/build-with-minikit/search-and-discovery", - "destination": "/mini-apps/technical-guides/search-and-discovery" + "destination": "/mini-apps/troubleshooting/how-search-works" }, { "source": "/base-app/miniapps/sharing-your-miniapp", diff --git a/docs/mini-apps/core-concepts/embeds-and-previews.mdx b/docs/mini-apps/core-concepts/embeds-and-previews.mdx index de98fcfe..f5c7b601 100644 --- a/docs/mini-apps/core-concepts/embeds-and-previews.mdx +++ b/docs/mini-apps/core-concepts/embeds-and-previews.mdx @@ -143,4 +143,3 @@ Splash screen background color. Must be hex color code. Defaults to manifest spl Learn how to maximize sharing, social engagement, and viral growth for your Mini App using Base's social graph features. - diff --git a/docs/mini-apps/core-concepts/manifest.mdx b/docs/mini-apps/core-concepts/manifest.mdx index 70179cda..83757957 100644 --- a/docs/mini-apps/core-concepts/manifest.mdx +++ b/docs/mini-apps/core-concepts/manifest.mdx @@ -204,11 +204,7 @@ Open Graph image. 1200×630px (1.91:1), PNG/JPG. ## Related Concepts - - - Learn how your manifest powers search indexing and category placement in the Base app discovery features. - - + Understand how your manifest creates rich embeds when your Mini App is shared in feeds and social platforms. diff --git a/docs/mini-apps/growth/optimize-onboarding.mdx b/docs/mini-apps/growth/optimize-onboarding.mdx index 8fa43b69..40cc77b4 100644 --- a/docs/mini-apps/growth/optimize-onboarding.mdx +++ b/docs/mini-apps/growth/optimize-onboarding.mdx @@ -32,7 +32,7 @@ Deliver value instantly and avoid blocking actions. - After success, prompt social actions via [SDK actions](/mini-apps/features/links) and [Sharing & Social Graph](/mini-apps/features/sharing-and-social-graph) -- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/features/search-and-discovery) +- Offer next step: save, follow, or share — optimize with [Search & Discovery](/mini-apps/troubleshooting/how-search-works) @@ -103,7 +103,7 @@ Learn how to implement them with [SDK actions](/mini-apps/features/links). - + diff --git a/docs/mini-apps/llms-full.txt b/docs/mini-apps/llms-full.txt index 4026123e..e65bc23b 100644 --- a/docs/mini-apps/llms-full.txt +++ b/docs/mini-apps/llms-full.txt @@ -49,7 +49,7 @@ export function Providers(props: { children: React.ReactNode }) { - [Manifest](https://docs.base.org/mini-apps/features/manifest.md) — Manifest - [Authentication](https://docs.base.org/mini-apps/features/Authentication.md) — Auth - [Embeds & Previews](https://docs.base.org/mini-apps/features/embeds-and-previews.md) — Embeds -- [Search & Discovery](https://docs.base.org/mini-apps/features/search-and-discovery.md) — Discovery +- [Search & Discovery](https://docs.base.org/mini-apps/technical-guides/search-discovery.md) — Discovery - [Sharing & Social Graph](https://docs.base.org/mini-apps/features/sharing-and-social-graph.md) — Sharing - [Notifications](https://docs.base.org/mini-apps/features/notifications.md) — Notifications - [Links](https://docs.base.org/mini-apps/features/links.md) — Links @@ -94,7 +94,7 @@ Source: `https://docs.base.org/mini-apps/overview.md` - Onboarding: Reduce steps; defer heavy auth until value is shown; prefill from client context. - Source: `https://docs.base.org/mini-apps/growth/optimize-onboarding.md` - Discovery: Optimize for search and featuring by following guidelines. - - Source: `https://docs.base.org/mini-apps/features/search-and-discovery.md` + - Source: `https://docs.base.org/mini-apps/technical-guides/search-discovery.md` ## Authentication Best Practices (excerpts) diff --git a/docs/mini-apps/llms.txt b/docs/mini-apps/llms.txt index 1de2d10c..39f244bc 100644 --- a/docs/mini-apps/llms.txt +++ b/docs/mini-apps/llms.txt @@ -33,7 +33,7 @@ - [Hooks: useMiniKit](https://docs.base.org/onchainkit/latest/components/minikit/hooks/useMiniKit.md) — Access frame context and client features ## Optional -- [Search & Discovery](https://docs.base.org/mini-apps/features/search-and-discovery.md) — Indexing and ranking signals in Base App +- [Search & Discovery](https://docs.base.org/mini-apps/technical-guides/search-discovery.md) — Indexing and ranking signals in Base App - [Sharing & Social Graph](https://docs.base.org/mini-apps/features/sharing-and-social-graph.md) — Viral distribution patterns diff --git a/docs/mini-apps/quickstart/build-checklist.mdx b/docs/mini-apps/quickstart/build-checklist.mdx index 264c7bce..fd227586 100644 --- a/docs/mini-apps/quickstart/build-checklist.mdx +++ b/docs/mini-apps/quickstart/build-checklist.mdx @@ -33,7 +33,7 @@ Distribution starts in the feed: compelling previews with a clear image and laun Be found across surfaces: set a primary category, share once to trigger indexing, and keep assets valid to appear in search and categories. - + ## Sharing & Social Graph diff --git a/docs/mini-apps/technical-guides/embeds-and-previews.mdx b/docs/mini-apps/technical-guides/embeds-and-previews.mdx index 1faa9908..8c7a363b 100644 --- a/docs/mini-apps/technical-guides/embeds-and-previews.mdx +++ b/docs/mini-apps/technical-guides/embeds-and-previews.mdx @@ -265,7 +265,7 @@ Set `Cache-Control` carefully: long enough for performance (300–600s), short e Continue with: -- [Search and Discovery](/mini-apps/technical-guides/search-and-discovery) +- [Search and Discovery](/mini-apps/troubleshooting/how-search-works) - [Manifest](/mini-apps/core-concepts/manifest) diff --git a/docs/mini-apps/technical-guides/search-and-discovery.mdx b/docs/mini-apps/technical-guides/search-and-discovery.mdx deleted file mode 100644 index fcb82dce..00000000 --- a/docs/mini-apps/technical-guides/search-and-discovery.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Search & Discovery -description: Learn how users discover and access Mini Apps in the Base ecosystem, including discovery surfaces, ranking systems, and optimization strategies for maximum visibility. ---- - -> **What you’ll learn** -> By the end of this guide, you’ll be able to: -> - Get your Mini App indexed in Base App search and understand how indexing works. -> - Choose the right categories and implement strategies to improve visibility across discovery surfaces. -> - Apply best practices to increase discoverability across Base App surfaces. - -## Search - -### How Search Works -Users discover Mini Apps through direct search queries in Base App. - - -search bar in base app - - -Your Mini App will only appear in search results after it has been indexed. To ensure indexing, share your Mini App at least once in Base App. Indexing typically takes ~10 minutes after the first share. - -### Managing Search Indexing - -Development Environment: add `"noindex": true` to prevent dev/staging from appearing in search. Remove or set false for production. - -**Removing from Search:** -To remove your Mini App from search results, invalidate your manifest (removes from all discovery). - - -If your Mini App does not show in search please follow the debugging guide [here](/mini-apps/troubleshooting/common-issues#1-app-discovery--indexing-issues) - - -## Discovery Surfaces - - -### Saved Apps -Personal launcher and quick access hub - - -saved apps - - -Appears here: -- User's saved Mini Apps -- Recently used applications - -Prompt users to save via the Add Frame flow at key value moments. - -### App Categories -Browsable directory organized by interest - - -app categories - - - -Choose your primaryCategory carefully as it determines where your app appears in Base App's category browsing. - - - -app categories - - - The Base app uses aggregated data (7-day rolling window) to generate dynamic category rankings. - -## Visual Specifications - -For detailed visual mapping of how metadata translates to UI elements, see the [Figma specification file](https://www.figma.com/design/4wx6s24NB0KLgprQAyMT8R/TBA-Mini-App-Specs). - -## Optimization Strategies - - - -### Category Optimization -- **Choose primaryCategory strategically** based on your target audience and competition -- **Monitor category rankings** and adjust strategy based on performance -- **Consider seasonal trends** that might affect category popularity - -### Metadata Best Practices -- **High-quality icon** (1024×1024, clear and recognizable at small sizes) -- **Compelling description** under 130 characters that clearly communicates value -- **Relevant tags** that match user search behavior -- **OG image optimized** for social sharing (1200×630) with clear visual hierarchy - -## Build for Discovery: Checklist - -- [ ] High-quality icon (1024×1024, clear at small sizes) -- [ ] Compelling description under 130 characters -- [ ] Relevant category selection for your target audience -- [ ] OG image optimized for social sharing (1200×630) -- [ ] Test metadata rendering across different clients -- [ ] Implement proper manifest files with correct categorization -- [ ] Choose relevant categories (primaryCategory) -- [ ] Create shareable moments that naturally encourage shares -- [ ] Design compelling embeds with clear CTAs -- [ ] Encourage saves for easy return access - -## Complete Implementation Guide - -For step-by-step implementation including code examples, see: -- [Manifest Configuration](/mini-apps/core-concepts/manifest) -- [Embed Implementation](/mini-apps/core-concepts/embeds-and-previews) - -Further reading: - -- [Sharing & Embeds](/mini-apps/core-concepts/embeds-and-previews) -- [Manifest](/mini-apps/core-concepts/manifest) - - - diff --git a/docs/mini-apps/troubleshooting/how-search-works.mdx b/docs/mini-apps/troubleshooting/how-search-works.mdx new file mode 100644 index 00000000..3204c3a2 --- /dev/null +++ b/docs/mini-apps/troubleshooting/how-search-works.mdx @@ -0,0 +1,80 @@ +--- +title: How Search works +description: If your Mini App isn't appearing in the Base app, this guide explains how indexing and search work so you can identify and fix the issue. +--- +Indexing is how The Base app adds your Mini App to its catalog, making it discoverable through search and browsing. +Unlike traditional app stores with manual submission, you control when indexing happens. Share your Mini App URL to the social feed, and indexing starts automatically—no review process required. + +## How indexing works + +Understanding the indexing process helps you diagnose why your Mini App may not be appearing. + + +Your manifest must be properly configured and validated for indexing to work. See [manifest documentation](/mini-apps/core-concepts/manifest) for required fields and validation. + + + + + Share your URL to the feed. + + + The Base app fetches and validates your manifest file. + + Invalid or unreachable manifests will fail indexing. + + + + Your Mini App is recorded and becomes searchable within 10 minutes. + + + + +## How search works +The Base App's search queries your Mini App's `name` field from the catalog. Both exact and partial matches appear in results. Search displays your Mini App based on information you provided in your manifest. + + +search bar in the Base app + + + +When making changes to your manifest, you will need to share your URL to reindex. + + +## Discovery surfaces + +### Category browsing +Your app appears in the category specified by `primaryCategory` in your manifest. Users browse categories to discover apps by interest. + + +app categories + + + +**Category rankings**: Rankings use 7-day engagement metrics such as shares. + + +### Saved apps +When users save your Mini App, it appears in their personal saved options for quick access. Prompt users to save at key moments. + + +saved apps + + +### Direct messages + +When users share your Mini App URL in a direct message, it displays as an interactive embed. Recipients can preview and open your app directly from the conversation, with `context.location` set to `messaging` so you can customize the experience for shared discovery. + +## Related + + + + Configure name and metadata for indexing. + + + Add required embed metadata. + + + Complete debugging guide. + + + diff --git a/docs/tone_of_voice.mdx b/docs/tone_of_voice.mdx new file mode 100644 index 00000000..589dfb7f --- /dev/null +++ b/docs/tone_of_voice.mdx @@ -0,0 +1,84 @@ + You are an expert technical documentation specialist with deep expertise in developer documentation, technical writing best practices, and the Mintlify documentation platform. Your role is to create clear, consistent, and developer-focused content that helps engineers accomplish their goals quickly and successfully. +You have mastery in: +Technical writing principles (clarity, concision, active voice) +Developer psychology and information needs +Mintlify component usage and best practices +Identifying and eliminating the curse of knowledge +Writing for both human developers and AI comprehension + + +## Voice +Professional and direct - No preamble. State facts clearly. +Active voice - Identify who does what. +❌ The data is processed by the function + ✅ The function processes data +Conversational brevity - Use "you" but cut excess words. +❌ You should configure the environment variables + ✅ Configure your environment variables +Data over description - Show metrics, not marketing. +❌ incredibly fast → ✅ completes in < 100ms + + + + + +## Structure + +**Strong verbs** - Choose precise action verbs over weak ones (is, are, occurs, happens). + +**Concise sentences** - One idea per sentence. Target 15-20 words, maximum 30. + +**Direct constructions** - Start with the subject. Eliminate "There is/There are" and filler phrases (~~at this point in time~~ → now, ~~is able to~~ → can). + +**Progressive disclosure** - Essential info first, then standard workflows, then error cases, finally advanced topics. + +## Terminology + +**Consistent** - One term per concept throughout all documentation (parameter OR argument, method OR function). + +**Precise** - Use explicit names: ❌ "the auth file" → ✅ "`authentication.js`" + +**Clear** - Define abbreviations on first use: "Application Programming Interface (API)" → then use "API" + +## Organization + +**Focused paragraphs** - One topic per paragraph with a clear topic sentence. + +**Strategic lists** - Numbered for sequential steps, bulleted for unordered items. Maintain parallel structure. + +**Clear instructions** - Start steps with imperative verbs (Install, Configure, Initialize). + +## Code + +Write complete, runnable examples with error handling, expected outputs, and realistic values (use environment variables, not placeholders). + +```javascript +const apiKey = process.env.API_KEY; + +try { + const result = calculateTotal([10, 20, 30]); + console.log(result); // Output: 60 +} catch (error) { + console.error(`Calculation failed: ${error.message}`); +} +``` + + + + +Never use: emojis, placeholder values (YOUR_API_KEY), weak verbs (is, are, occurs), "There is/There are", marketing language, mixed terminology, vague link text ("click here"), unexplained concepts, passive voice without justification. + + + +Page structure requires YAML frontmatter with title and description. Use `` for procedures, `` for platform variations, `` for multi-language examples, callouts for context (``, ``, ``), `` for images, and field components for API docs. + + + +Before output: sentences under 30 words with strong verbs and active voice, terms defined and consistent, no emojis, code examples complete with error handling, proper frontmatter and components used. + + + +**Before:** "There is a configuration file that is used for setting up the API client. The file should be located in the root directory and it needs to have the API key and endpoint URL." + +**After:** "The `config.json` file configures your API client. Place it in your project's root directory. Required fields: `apiKey` and `endpointUrl`. Missing files trigger initialization errors." + diff --git a/global-tone-voice.mdx b/global-tone-voice.mdx new file mode 100644 index 00000000..e69de29b