Skip to content

Commit 68fdfd5

Browse files
Copilotgraknol
Copilot
and
graknol
authored
Add secure Algolia search integration to Docusaurus documentation (#39)
* Initial plan * Add Algolia search integration to Docusaurus Co-authored-by: graknol <[email protected]> * Use environment variables for Algolia credentials instead of hardcoded values Co-authored-by: graknol <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: graknol <[email protected]>
1 parent e874bb9 commit 68fdfd5

File tree

3 files changed

+148
-0
lines changed

3 files changed

+148
-0
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@ jobs:
4242
npm ci
4343
4444
- name: Build documentation
45+
env:
46+
ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
47+
ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}
4548
run: |
4649
cd docs
4750
npm run build

‎docs/ALGOLIA_SEARCH_SETUP.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Algolia Search Setup for Docusaurus
2+
3+
This document explains how to configure Algolia search for the Declarative SQLite documentation site.
4+
5+
## Current Status
6+
7+
The Algolia search functionality has been integrated into the Docusaurus configuration. The search interface is fully functional and appears in the top navigation bar.
8+
9+
## Configuration
10+
11+
The search configuration is located in `docusaurus.config.ts` in the `themeConfig.algolia` section:
12+
13+
```typescript
14+
algolia: {
15+
// The application ID provided by Algolia (from environment variable)
16+
appId: process.env.ALGOLIA_APP_ID!,
17+
// Public API key: it is safe to commit it (from environment variable)
18+
apiKey: process.env.ALGOLIA_API_KEY!,
19+
indexName: 'declarative_sqlite',
20+
// Optional: see doc section below
21+
contextualSearch: true,
22+
// Optional: Algolia search parameters
23+
searchParameters: {},
24+
// Optional: path for search page that enabled by default (`false` to disable it)
25+
searchPagePath: 'search',
26+
},
27+
```
28+
29+
## Setup Steps
30+
31+
To complete the Algolia search setup with your open source key:
32+
33+
### 1. Add GitHub Secrets
34+
35+
The Algolia credentials are loaded from environment variables for security. You need to add the following secrets to your GitHub repository:
36+
37+
1. Go to your GitHub repository
38+
2. Navigate to Settings → Secrets and variables → Actions
39+
3. Add the following repository secrets:
40+
- `ALGOLIA_APP_ID`: Your Algolia Application ID
41+
- `ALGOLIA_API_KEY`: Your Algolia Search API Key (public/search-only key)
42+
43+
### 2. Environment Variables for Local Development
44+
45+
For local development, create a `.env.local` file in the `docs` directory:
46+
47+
```bash
48+
# docs/.env.local
49+
ALGOLIA_APP_ID=your_actual_app_id
50+
ALGOLIA_API_KEY=your_actual_api_key
51+
```
52+
53+
**Note**: Never commit the `.env.local` file. It's already excluded by the default `.gitignore`.
54+
55+
### 3. Index Your Documentation
56+
57+
You'll need to create a search index of your documentation. There are two main approaches:
58+
59+
#### Option A: DocSearch (Recommended for Open Source)
60+
61+
If you're using Algolia's free DocSearch program:
62+
63+
1. Apply for DocSearch at https://docsearch.algolia.com/apply/
64+
2. Once approved, Algolia will provide you with the correct `appId`, `apiKey`, and `indexName`
65+
3. Algolia will automatically crawl and index your documentation
66+
67+
#### Option B: Manual Indexing
68+
69+
If you prefer to manage the indexing yourself:
70+
71+
1. Set up an Algolia index in your dashboard
72+
2. Use Algolia's crawling tools or API to index your documentation content
73+
3. Update the configuration with your custom index details
74+
75+
### 4. Test the Search
76+
77+
After setting up the secrets and environment variables:
78+
79+
1. Run `npm run start` to start the development server (with `.env.local` for local testing)
80+
2. Click the search icon in the navigation bar or use Ctrl+K (Cmd+K on Mac)
81+
3. Try searching for documentation terms like "database", "flutter", "schema", etc.
82+
83+
## Features
84+
85+
The current configuration includes:
86+
87+
- **Search Interface**: Accessible via the navigation bar search icon or Ctrl+K shortcut
88+
- **Contextual Search**: Enabled to provide more relevant results based on the current page
89+
- **Search Page**: Dedicated search results page at `/search`
90+
- **Keyboard Navigation**: Full keyboard support for search results
91+
- **Mobile Support**: Search works on mobile devices
92+
93+
## Troubleshooting
94+
95+
- **"No results" or connection errors**: Verify your `ALGOLIA_APP_ID` and `ALGOLIA_API_KEY` secrets are set correctly
96+
- **Build failures**: Ensure the environment variables are available during the build process
97+
- **Outdated results**: If using DocSearch, Algolia crawls periodically. Manual indexing gives you more control
98+
- **Search not appearing**: Check the browser console for errors related to missing environment variables
99+
100+
## Additional Configuration Options
101+
102+
You can customize the search behavior with additional options:
103+
104+
```typescript
105+
algolia: {
106+
appId: process.env.ALGOLIA_APP_ID!,
107+
apiKey: process.env.ALGOLIA_API_KEY!,
108+
indexName: 'declarative_sqlite',
109+
contextualSearch: true,
110+
searchParameters: {
111+
// Additional Algolia search parameters
112+
facetFilters: [],
113+
},
114+
searchPagePath: 'search',
115+
// Custom placeholder text
116+
placeholder: 'Search documentation...',
117+
// Disable search page
118+
searchPagePath: false,
119+
},
120+
```
121+
122+
## Security
123+
124+
The configuration now uses environment variables for sensitive data:
125+
- GitHub Secrets are used for CI/CD deployment
126+
- Local development uses `.env.local` file (never committed)
127+
- No sensitive credentials are stored in the codebase
128+
129+
For more details, see the [Docusaurus Algolia Search documentation](https://docusaurus.io/docs/search#using-algolia-docsearch).

‎docs/docusaurus.config.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,22 @@ const config: Config = {
5555
],
5656

5757
themeConfig: {
58+
// Algolia search configuration
59+
...(process.env.ALGOLIA_APP_ID && process.env.ALGOLIA_API_KEY && {
60+
algolia: {
61+
// The application ID provided by Algolia (from environment variable)
62+
appId: process.env.ALGOLIA_APP_ID,
63+
// Public API key: it is safe to commit it (from environment variable)
64+
apiKey: process.env.ALGOLIA_API_KEY,
65+
indexName: 'declarative_sqlite',
66+
// Optional: see doc section below
67+
contextualSearch: true,
68+
// Optional: Algolia search parameters
69+
searchParameters: {},
70+
// Optional: path for search page that enabled by default (`false` to disable it)
71+
searchPagePath: 'search',
72+
},
73+
}),
5874
colorMode: {
5975
defaultMode: 'dark',
6076
disableSwitch: false,

0 commit comments

Comments
 (0)