metalsmith-algolia

A metalsmith plugin for indexing content on Algolia

This plugin allows you to index your content in Algolia search engine on metalsmith building process.

If this plugin doesn't fit your needs, please don't hesitate to ask for feature requests.

Installation

npm install --save metalsmith-algolia

Usage

Javascript API

The exemple bellow show the minimum code required to index your content. (node: metalsmith-markdown is not required)

const metalsmith = require('metalsmith');
const markdown = require('metalsmith-markdown');
const algolia = require('metalsmith-algolia');

metalsmith(__dirname)
  .source('./src')
  .use(markdown())
  .use(algolia({
    projectId: '<algolia-project-id>',
    privateKey: '<algolia-private-key>',
    index: '<algolia-index>'
  }))
  .build();

please, use command line arguments or environement variables to store your algolia private key

Templates metadata

Here is an exemple with a fake markdown template ./src/mypage.md

---
title: My awesome static page !
description: This is a exemple page
algolia: true
---
# My awesome static page !
content exemple

Indexed document

By default, metadata (string/boolean/integers) and contents will be sent to Algolia for all files with algolia: true metadata
With this exemple, the generated document will look like:

{
  "title": "My awesome static page !",
  "description": "This is a exemple page",
  "contents": "<h1>My awesome static page !\n<p>content exemple</p>"
}

Customize indexed documents

If you need to cleanup your contents, compute additional fields, or remove metadata from indexing, you can use the fileParser option to plugin constructor to give a custom callback to generate your own documents:

const metalsmith = require('metalsmith');
const markdown = require('metalsmith-markdown');
const algolia = require('metalsmith-algolia');
const cheerio = require('cheerio');

function customFileParser(file, metadata) {
  let documents = [];
  let $ = cheerio.load(metadata.contents.toString());

  // add as many as documents as you need
  documents.push({
    title: metadata.title,
    contents: $('p').text();
  })

  return documents;
}

metalsmith(__dirname)
  .source('./src')
  .use(markdown())
  .use(algolia({
    projectId: '<algolia-project-id>',
    privateKey: '<algolia-private-key>',
    index: '<algolia-index>',
    fileParser: customFileParser
  }))
  .build();

This time, the generated document will look like:

{
  "title": "My awesome static page !",
  "contents": "content exemple"
}

Options reference

name	default	description
`projectId`		(required) Algolia project identifier
`privateKey`		(required) Algolia private key
`index`		(required)* Algolia index
`clearIndex`	false	Clear Algolia index before indexing new documents
`fileParser`	null	Function reference to a custom handler for building documents
`pattern`	*/	Glob pattern to match input files against. Can be an array or a single string

hint: metalsmith-algolia use debug

Todolist

Add tests/linter
Add travis configuration
Try bulk operations (without fail fast)

stafyniaksacha/metalsmith-algolia