Skip to main content

Integration Guides

Who This Is For: Developers, DevOps engineers, and technical leads implementing third-party integrations to enhance documentation functionality.

When to Use This Guide: You need to add search capabilities, integrate analytics tracking, connect documentation with issue trackers, set up deployment pipelines, or automate documentation workflows.

What You'll Learn: How to integrate popular services (Algolia, GitHub, Slack, Google Analytics), configure OAuth and API authentication, implement webhooks, and automate documentation publishing and notifications.

Overview​

Modern documentation platforms thrive on integrations. Whether you're adding powerful search with Algolia, tracking user behavior with analytics, syncing content from GitHub, or automating deployments to Netlify, this guide provides practical, working examples for the most valuable integrations.

Real-World Scenario: Your documentation site has grown to 500+ pages, and users struggle to find information. You want to implement Algolia search, track which pages users visit most with Google Analytics, automatically notify your Slack channel when docs are updated, and deploy changes to production via GitHub Actions. This guide walks you through implementing each integration with real code examples and configuration files.

Quick Start​

Integration Prerequisites​

  • API credentials for services
  • Basic understanding of REST APIs
  • Node.js and npm installed
  • Git for version control

Available Integrations​

Content Management​

  • GitHub/GitLab integration
  • Confluence synchronization
  • Jira ticket linking
  • Slack notifications

Search & Analytics​

  • Algolia search
  • Google Analytics
  • Mixpanel
  • Hotjar

Deployment & Hosting​

  • Netlify
  • Vercel
  • GitHub Pages
  • AWS S3 + CloudFront

GitHub Integration​

Set Up GitHub Authentication​

1. Create GitHub App​

  1. Go to GitHub Settings → Developer settings
  2. Click "New GitHub App"
  3. Fill in application details
  4. Set webhook URL (optional)
  5. Generate client secret

2. Configure Environment Variables​

# .env
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
GITHUB_REPO_OWNER=your-username
GITHUB_REPO_NAME=your-repo

3. Install GitHub Plugin​

npm install @docusaurus/plugin-github

4. Update Configuration​

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-github',
      {
        owner: process.env.GITHUB_REPO_OWNER,
        repo: process.env.GITHUB_REPO_NAME,
      },
    ],
  ],
};

GitHub Actions CI/CD​

Deploy on Push​

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Algolia Search Integration​

Set Up Algolia​

1. Create Algolia Account​

  • Sign up at algolia.com
  • Create new application
  • Get API keys

2. Install Algolia Plugin​

npm install @easyops-cn/docusaurus-search-local
// docusaurus.config.js
themes: [
  [
    require.resolve("@easyops-cn/docusaurus-search-local"),
    {
      hashed: true,
      language: ["en"],
      docsRouteBasePath: '/docs',
      blogRouteBasePath: '/blog',
    },
  ],
],

Index Content​

# Run Algolia crawler
docker run -it --env-file=.env -e "CONFIG=$(cat algolia-config.json | jq -r tostring)" algolia/docsearch-scraper

Google Analytics Integration​

Set Up GA4​

1. Create GA4 Property​

  1. Go to Google Analytics
  2. Create new GA4 property
  3. Get Measurement ID (G-XXXXXXXXXX)

2. Install Plugin​

npm install @docusaurus/plugin-google-gtag

3. Configure​

// docusaurus.config.js
plugins: [
  [
    '@docusaurus/plugin-google-gtag',
    {
      trackingID: 'G-XXXXXXXXXX',
      anonymizeIP: true,
    },
  ],
],

Custom Event Tracking​

// Track custom events
import { trackEvent } from '@docusaurus/useGlobalData';

function trackDownload() {
  gtag('event', 'download', {
    event_category: 'documentation',
    event_label: 'user_guide_pdf',
  });
}

Slack Integration​

Webhook Setup​

1. Create Slack Webhook​

  1. Go to your Slack workspace
  2. Navigate to Apps → Incoming Webhooks
  3. Add to channel
  4. Copy webhook URL

2. Configure Notifications​

// notify-slack.js
const fetch = require('node-fetch');

async function notifySlack(message) {
  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: message }),
  });
}

// Usage
notifySlack(' New documentation published!');

3. Automate with GitHub Actions​

# .github/workflows/notify-slack.yml
- name: Notify Slack
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    text: 'Documentation build completed'
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}

Jira Integration​

1. Install Jira Plugin​

npm install docusaurus-plugin-jira-link

2. Configure​

// docusaurus.config.js
plugins: [
  [
    'docusaurus-plugin-jira-link',
    {
      jiraBaseUrl: 'https://your-domain.atlassian.net',
      projectKeys: ['DOC', 'TECH'],
    },
  ],
],

3. Use in Markdown​

See issue DOC-123 for more details.
This feature resolves TECH-456.

Netlify Deployment​

Setup Netlify​

1. Connect Repository​

  1. Log in to Netlify
  2. Click "New site from Git"
  3. Select repository
  4. Configure build settings

2. Build Configuration​

# netlify.toml
[build]
  command = "npm run build"
  publish = "build"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[build.environment]
  NODE_VERSION = "18"

3. Environment Variables​

# Set in Netlify dashboard
ALGOLIA_API_KEY=xxxxx
GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

Deploy Preview​

# netlify.toml
[context.deploy-preview]
  command = "npm run build"

[context.branch-deploy]
  command = "npm run build"

Vercel Deployment​

Setup Vercel​

1. Install Vercel CLI​

npm install -g vercel

2. Deploy​

vercel --prod

3. Configuration​

{
  "buildCommand": "npm run build",
  "outputDirectory": "build",
  "installCommand": "npm install",
  "framework": "docusaurus",
  "env": {
    "NODE_VERSION": "18"
  }
}

API Integration Examples​

REST API Integration​

Fetch Data from API​

// src/components/ApiData.js
import React, { useEffect, useState } from 'react';

export default function ApiData() {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch('https://api.example.com/docs')
      .then(res => res.json())
      .then(data => setData(data));
  }, []);

  return <div>{data && JSON.stringify(data)}</div>;
}

GraphQL Integration​

// src/utils/graphql.js
import { GraphQLClient } from 'graphql-request';

const client = new GraphQLClient('https://api.example.com/graphql');

export async function fetchDocs() {
  const query = `{
    docs {
      title
      content
    }
  }`;
  
  return await client.request(query);
}

Monitoring & Error Tracking​

Sentry Integration​

1. Install Sentry​

npm install @sentry/react @sentry/tracing

2. Initialize​

// src/theme/Root.js
import React from 'react';
import * as Sentry from '@sentry/react';

Sentry.init({
  dsn: 'YOUR_SENTRY_DSN',
  integrations: [new Sentry.BrowserTracing()],
  tracesSampleRate: 1.0,
});

export default function Root({children}) {
  return <>{children}</>;
}

Testing Integrations​

Integration Tests​

// tests/integration.test.js
describe('GitHub Integration', () => {
  it('should fetch repository data', async () => {
    const data = await fetchGitHubRepo();
    expect(data).toHaveProperty('name');
  });
});

describe('Search Integration', () => {
  it('should return search results', async () => {
    const results = await searchDocs('api');
    expect(results.length).toBeGreaterThan(0);
  });
});

Troubleshooting​

Common Issues​

API Rate Limits​

// Implement retry logic
async function fetchWithRetry(url, retries = 3) {
  try {
    return await fetch(url);
  } catch (error) {
    if (retries > 0) {
      await new Promise(r => setTimeout(r, 1000));
      return fetchWithRetry(url, retries - 1);
    }
    throw error;
  }
}

CORS Issues​

// docusaurus.config.js
plugins: [
  [
    '@docusaurus/plugin-client-redirects',
    {
      createRedirects(existingPath) {
        // Add CORS headers
      },
    },
  ],
],

Authentication Errors​

  • Verify API keys
  • Check token expiration
  • Review permission scopes

Best Practices​

Security​

  • Store secrets in environment variables
  • Use API key rotation
  • Implement rate limiting
  • Validate webhook signatures

Performance​

  • Cache API responses
  • Use CDN for assets
  • Lazy load integrations
  • Monitor bundle size

Maintenance​

  • Keep dependencies updated
  • Monitor integration health
  • Document integration changes
  • Test after updates

Support​

Need help with integrations?

Next Steps​

Last updated on

Was this page helpful?