🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more
Socket
DemoInstallSign in
Socket

@diplodoc/algolia

Package Overview
Dependencies
Maintainers
7
Versions
5
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@diplodoc/algolia

Algolia search integration extension for Diplodoc

0.4.1
latest
npm
Version published
Maintainers
7
Created
Source

Algolia Extension for Diplodoc

This extension provides Algolia search integration for Diplodoc documentation. It enables powerful search functionality for your documentation by indexing content into Algolia and providing a seamless search experience for your users.

Features

  • Automatic indexing of documentation content
  • Multi-language support
  • Customizable search settings
  • Parallel processing for fast indexing
  • Section-based search results for precise navigation
  • Client-side search implementation

Installation

npm install @diplodoc/algolia

How Indexing Works

By default, the extension only creates local search indices in the _search directory of your output folder. These local indices are JSON files that contain the processed documentation content.

To upload these indices to Algolia, you need to either:

  • Set the index parameter to true during the build process
  • Run the dedicated index command after building the documentation

Configuration

Required Configuration

To use this extension, you need to provide Algolia credentials:

ParameterEnvironment VariableCLI OptionDescription
App IDALGOLIA_APP_ID--app-idYour Algolia application ID
API KeyALGOLIA_API_KEY--api-keyYour Algolia admin API key (for indexing)
Index NameALGOLIA_INDEX_NAME--index-nameName of the Algolia index

Optional Configuration

ParameterCLI OptionDefaultDescription
Input Path--input./Path to documentation directory
Index--indexfalseWhether to create and upload an index for search

Configuration Methods

You can configure the extension using three different methods:

  • Environment Variables

    • Set environment variables before running the CLI
    • Useful for CI/CD pipelines and secure storage of API keys
    • Example: ALGOLIA_APP_ID, ALGOLIA_API_KEY, ALGOLIA_INDEX_NAME
  • CLI Flags

    • Pass options directly to the CLI command
    • Overrides environment variables
    • Example: --app-id, --api-key, --index-name
  • Configuration File (.yfm)

    • Add configuration to your .yfm file
    • Useful for project-specific settings
    • Note: Do not store sensitive information like API keys in this file as it may be committed to version control

Example priority: CLI flags > Environment variables > Configuration file

Parameter Availability by Configuration Method

ParameterCLI FlagEnvironment Variable.yfm ConfigDescription
appId--app-idALGOLIA_APP_IDsearch.appIdAlgolia Application ID
apiKey--api-keyALGOLIA_API_KEYsearch.apiKeyAlgolia API Key for indexing
indexName--index-nameALGOLIA_INDEX_NAMEsearch.indexNameIndex name (e.g., "docs")
index--index-search.indexWhether to upload indices to Algolia (default: false)
searchKey--search-keyALGOLIA_SEARCH_KEYsearch.searchKeyClient-side API key for search (default: "search-api-key")
provider--search-providerALGOLIA_PROVIDERsearch.providerSearch provider name (default: "algolia")
api--search-apiALGOLIA_API_PATHsearch.apiPath to the client-side search API (default: "_search/api.js")
indexSettings--search.indexSettingsAlgolia index settings (searchable attributes, etc.)
querySettings--search.querySettingsAlgolia query settings (hits per page, etc.)

Usage

Basic Usage with Diplodoc CLI

The extension can be used with the Diplodoc CLI by adding it to the extensions parameter:

npx -y @diplodoc/cli -i ./input-docs -o ~/output-docs --extensions @diplodoc/algolia

Method 1: Using Environment Variables

export ALGOLIA_APP_ID="your-app-id"
export ALGOLIA_API_KEY="your-api-key"
export ALGOLIA_INDEX_NAME="your-index-name"

npx -y @diplodoc/cli -i ./input-docs -o ~/output-docs --extensions @diplodoc/algolia

Method 2: Using CLI Flags

npx -y @diplodoc/cli -i ./input-docs -o ~/output-docs \
  --extensions @diplodoc/algolia \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --index-name "your-index-name" \
  --index

Method 3: Using Configuration File (.yfm)

# .yfm file
search:
  provider: algolia
  appId: your-app-id
  # Do not include apiKey here for security reasons
  indexName: docs
  index: true

Then run:

# API key should be provided via environment variable or CLI flag
export ALGOLIA_API_KEY="your-api-key"
npx -y @diplodoc/cli -i ./input-docs -o ~/output-docs --extensions @diplodoc/algolia

Using the Index Command

The extension provides a dedicated index command for indexing documentation without rebuilding it:

npx -y @diplodoc/cli index -i ~/output-docs --extensions @diplodoc/algolia

This is useful when you want to update the search index without rebuilding the entire documentation. The index command processes the already built documentation and uploads it to Algolia.

Options for the index command:

npx -y @diplodoc/cli index -i ~/output-docs \
  --extensions @diplodoc/algolia \
  --app-id "your-app-id" \
  --api-key "your-api-key" \
  --index-name "your-index-name"

Search Configuration

Client-Side Configuration

The extension automatically generates the necessary client-side configuration for search:

<!-- This is automatically included in your documentation -->
<script src="_search/api.js"></script>

Search Settings

You can customize the search settings in your .yfm configuration file:

# .yfm file
search:
  provider: algolia
  appId: your-app-id
  indexName: docs
  index: true
  indexSettings:
    # Algolia index settings
    searchableAttributes:
      - title
      - content
      - headings
      - keywords
    attributesToHighlight:
      - title
      - content
  querySettings:
    # Algolia query settings
    hitsPerPage: 10
    attributesToRetrieve:
      - title
      - content
      - url
      - section

Resources

License

MIT

FAQs

Package last updated on 06 Jun 2025

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts