Cloudflare AI Search Integration

This document guides you through integrating and using Semantic Search and the conversational assistant (Ask AI) on the TanaFlows theme using Cloudflare AI Search.

1. About Cloudflare AI Search

Cloudflare AI Search is a next-generation AI-powered search solution combining two core technologies:

1. Semantic Search: Unlike traditional keyword search which matches character sequences precisely, semantic search understands user intent and query context to deliver the most accurate results, even without exact keyword matches.
2. RAG Chat (Retrieval-Augmented Generation): The Ask AI assistant uses indexed articles from your website as search context for a Large Language Model (LLM). This allows it to reply directly to user questions with verified sources linked from your own site.

2. Integrated Features on the TanaFlows Theme

TanaFlows is fully optimized to support Cloudflare AI Search out of the box:

• Semantic Search Modal: Clicking the magnifying glass icon on the header or 404 pages opens a modern search popup where users can type natural questions.
• Ask AI Assistant (Sliding Drawer): Clicking the “Ask AI” button on the header slides a conversational chat panel from the right. The chat history is collapsed by default on desktops to keep the interface minimal and clean.
• Theme Synchronization (Dark/Light Mode): Both Web Components automatically adjust their styles to match the active light or dark mode setting of the site.
• Automated Recommendations (Error 404 & Related Posts):
  • 404 Pages: Automatically suggests relevant articles based on the broken URL/keyword using the Cloudflare AI Search API.
  • Related Posts: Suggests smart related posts at the bottom of each reading page based on semantic context rather than simple public tags.

3. Detailed Setup Instructions on Cloudflare

Here is a step-by-step guide to setting up and activating Cloudflare AI Search (including both the search input box and the Ask AI assistant) on the Cloudflare Dashboard:

Step 1: Create and Configure the Instance on Cloudflare

1. Log in to your Cloudflare Dashboard account.
2. Navigate to AI Search in the left-hand navigation menu and select Instances.
3. Click Create Instance (if you haven’t already) and name your search engine.
4. In the Data Sources section, add your website’s data source by entering your Ghost sitemap link (e.g., https://your-domain.com/sitemap.xml) and click Run Crawl/Index to allow Cloudflare to synchronize your articles.

Step 2: Activate Public Endpoint & Permissions (Important)

To allow the theme source code to query Cloudflare directly without getting a 401 or 403 error, you need to unlock the public endpoint:

1. Go to the AI Search Instance you just configured, select the Settings tab -> Public Endpoint.
2. Toggle on Enable Public Endpoint.
3. Endpoint Permissions (Important): Ensure that you check both of the following options:
   • Enable Search (Allows performing searches)
   • Enable Chat or Chat/Completions (Allows conversational chat - used for the Ask AI button).
4. Configure Model for Ask AI:
   • Under Chat settings, choose a Large Language Model (LLM) that supports conversational flows. Cloudflare recommends using instruct models such as: @cf/meta/llama-3-8b-instruct.
5. Configure Allowed Origins (CORS - Prevent localhost/domain blocking):
   • If you are testing on your local machine, add http://localhost:2368 and http://127.0.0.1:2368 to the Allowed Origins list.
   • For production, enter your actual website domain (e.g., https://your-domain.com).
   • Tip: You can enter * to grant access to all origins if you want to perform quick testing.

Step 3: Retrieve the Endpoint URL

After saving the Public Endpoint configuration, Cloudflare will provide you with a public API path formatted like:

https://a36c95f2-f156-4d52-bd1b-aa5ead5841d3.search.ai.cloudflare.com/search

(Copy this entire URL path)

4. Activation in Ghost Admin

1. Log in to your website admin dashboard: Ghost Admin > Settings > Design > Site design.
2. Find the customization section for the TanaFlows theme.
3. In the Custom Search setting, switch the option from Native Search to AI Search by Cloudflare.
4. In the Search Endpoint URL field, paste the API path you copied in Step 3 (the URL path containing /search at the end).
5. Click Save in the top right corner to save your changes.

At this point, your entire search system will automatically switch to the Cloudflare AI configuration, and the Ask AI button will appear in the Header.

5. Troubleshooting & Usage Notes