gatsby-source-guru

A Gatsby source plugin for fetching content from GetGuru knowledge base and creating pages from your cards.

Features

• 🚀 Fetch cards from GetGuru API with collection-based authentication
• 📝 Convert HTML to Markdown using Turndown for better Gatsby integration
• 🖼️ Download attachments and optimise for static hosting
• 🔗 Convert internal links between Guru cards to local page routes
• ⚡ GraphQL integration with typed nodes for queries
• 🛡️ Error handling with detailed logging and fallbacks

Installation

npm install gatsby-source-guru
# or
yarn add gatsby-source-guru

Configuration

Add the plugin to your gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: 'gatsby-source-guru',
      options: {
        // Required: Your Guru collection ID
        collectionId: 'your-collection-id',
        
        // Required: Authentication - choose one method
        
        // Option 1: Collection-based auth (recommended)
        authMode: 'collection',
        collectionToken: process.env.GURU_COLLECTION_TOKEN,
        
        // Option 2: User-based auth  
        // authMode: 'user',
        // apiUsername: process.env.GURU_API_USERNAME,
        // apiPassword: process.env.GURU_API_PASSWORD,
        // teamName: process.env.GURU_TEAM_NAME,
        
        // Optional: Download settings
        downloadAttachments: true,        // Download card attachments
        attachmentsDir: 'static/guru-attachments', // Where to save files
        
        // Optional: Content processing
        convertToMarkdown: true,          // Convert HTML to Markdown
        processInternalLinks: true,       // Convert Guru links to local routes
        
        // Optional: Debugging
        verbose: false                    // Enable detailed logging
      }
    }
  ]
}

Environment Variables

Create a .env file in your project root:

# Collection-based authentication (recommended)
GURU_COLLECTION_TOKEN=your-collection-token

# OR User-based authentication
# GURU_API_USERNAME=your-username
# GURU_API_PASSWORD=your-password
# GURU_TEAM_NAME=your-team-name

Usage

GraphQL Queries

The plugin creates GuruCard nodes that you can query:

query {
  allGuruCard {
    nodes {
      id
      title
      content          # Processed content (HTML or Markdown)
      markdownContent  # Markdown version (if enabled)
      htmlContent      # Original HTML content
      slug             # URL-friendly slug
      lastModified
      dateCreated
      owner {
        firstName
        lastName
        email
      }
      collection {
        name
        id
      }
      attachments {
        filename
        url
        localPath      # Path to downloaded file
      }
    }
  }
}

Creating Pages

Use the data in gatsby-node.js to create pages:

const path = require('path')

exports.createPages = async ({ graphql, actions, reporter }) => {
  const { createPage } = actions
  
  const result = await graphql(`
    query {
      allGuruCard {
        nodes {
          id
          slug
          title
          content
        }
      }
    }
  `)
  
  if (result.errors) {
    reporter.panicOnBuild('Error loading Guru cards', result.errors)
    return
  }
  
  const cardTemplate = path.resolve('./src/templates/card.js')
  
  result.data.allGuruCard.nodes.forEach(card => {
    createPage({
      path: `/pages/${card.slug}/`,
      component: cardTemplate,
      context: {
        id: card.id,
        title: card.title
      }
    })
  })
}

Page Template Example

Create src/templates/card.js:

import React from 'react'
import { graphql } from 'gatsby'
import Layout from '../components/layout'

const CardTemplate = ({ data }) => {
  const card = data.guruCard
  
  return (
    <Layout>
      <article>
        <header>
          <h1>{card.title}</h1>
          <p>
            By {card.owner.firstName} {card.owner.lastName} • 
            Last updated: {new Date(card.lastModified).toLocaleDateString()}
          </p>
        </header>
        
        <div dangerouslySetInnerHTML={{ __html: card.content }} />
        
        {card.attachments?.length > 0 && (
          <section>
            <h3>Attachments</h3>
            {card.attachments.map(attachment => (
              <a 
                key={attachment.filename} 
                href={attachment.localPath || attachment.url}
                download
              >
                {attachment.filename}
              </a>
            ))}
          </section>
        )}
      </article>
    </Layout>
  )
}

export const query = graphql`
  query($id: String!) {
    guruCard(id: { eq: $id }) {
      id
      title
      content
      markdownContent
      lastModified
      owner {
        firstName
        lastName
        email
      }
      attachments {
        filename
        url
        localPath
      }
    }
  }
`

export default CardTemplate

Authentication Methods

Collection-Based (Recommended)

Best for CI/CD and team environments:

1. Get your collection ID from Guru dashboard
2. Create a collection token in Guru settings
3. Use username + token authentication

User-Based

For development or personal use:

1. Use your Guru email and password
2. Less secure, not recommended for production

Content Processing

HTML to Markdown Conversion

When convertToMarkdown: true, the plugin converts HTML content to Markdown using Turndown. This provides:

• Better integration with Markdown-based Gatsby workflows
• Cleaner content for search indexing
• Easier content manipulation

Internal Link Processing

The plugin automatically converts internal Guru card links to local page routes:

<!-- Original Guru link -->
<a href="https://app.getguru.com/card/abc123/My-Card">My Card</a>

<!-- Converted to local route -->
<a href="/pages/my-card/">My Card</a>

Attachment Handling

Files are downloaded and stored locally:

• Images: Available for Gatsby image optimisation
• Documents: Served as static assets
• Public files: Direct download links maintained
• Private files: Downloaded for local serving

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | collectionId | string | required | Your Guru collection ID | | authMode | string | 'collection' | Authentication method: 'collection' or 'user' | | guruUsername | string | - | Username for collection auth | | guruToken | string | - | Token for collection auth | | guruEmail | string | - | Email for user auth | | guruPassword | string | - | Password for user auth | | downloadAttachments | boolean | true | Download card attachments | | attachmentsDir | string | 'static/guru-attachments' | Directory for downloaded files | | convertToMarkdown | boolean | true | Convert HTML to Markdown | | processInternalLinks | boolean | true | Process internal Guru links | | verbose | boolean | false | Enable detailed logging |

Troubleshooting

Authentication Issues

Error: Unauthorized (401)

• Verify your credentials in .env
• Check collection ID is correct
• Ensure token has proper permissions

Module Not Found

Cannot find module 'turndown'

• Run npm install or yarn install
• Ensure turndown is in dependencies

No Cards Found

Found 0 cards via search

• Verify collection has published cards
• Check collection permissions
• Enable verbose: true for detailed logs

Build Failures

Error building static HTML

• Check for client-side only code in templates
• Verify GraphQL queries match schema
• Use gatsby clean to clear cache

Development

Local Development

# Clone the repository
git clone https://github.com/armakuni/ak-way.git
cd ak-way/plugins/gatsby-source-guru

# Install dependencies
npm install

# Test in a Gatsby project
npm link
cd /path/to/your/gatsby-site
npm link gatsby-source-guru

Testing

# Run tests
npm test

# Test with different auth methods
GURU_USERNAME=test npm test

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions

Related

• Gatsby - Static site generator
• GetGuru - Knowledge management platform
• Turndown - HTML to Markdown converter

Built with ❤️ by Armakuni