A documentation plugin that provides contextual learning journeys directly within the Grafana interface.
The Grafana Learning Journeys Plugin transforms how users interact with documentation by providing:
- 🎯 Context-Aware Recommendations - suggestions based on current Grafana context (page, data sources, dashboard state)
- 📚 Interactive Learning Journeys - Step-by-step guided experiences with progress tracking and milestone navigation
- 🗂️ Tabbed Interface - Browser-like multi-tab experience for simultaneous documentation access
- 🔌 Extensible Architecture - Decoupled design allowing easy integration with different content sources
- 📱 Responsive Design - Optimized for sidebar integration with adaptive layouts
- 🚀 Auto-Launch Tutorials - Automatically open specific tutorials on Grafana startup for demo scenarios
For a comprehensive overview of the plugin's architecture, design patterns, and system organization, see ARCHITECTURE.md.
Clone the repository:
git clone https://github.com/grafana/docs-plugin.gitThen build the plugin:
cd docs-plugin
npm install
npm run buildSpin up the development server:
Note we are currently using main until the next release of Grafana.
npm run serverAccess the plugin in Grafana at http://localhost:3000
This plugin follows a modular, well-documented architecture. Each major component has detailed documentation:
- Source Overview - Complete source code organization and patterns
- Component Architecture - UI component organization and relationships
- App Component - Root application setup and scene integration
- App Configuration - Admin settings and plugin configuration
- Documentation Panel - Main docs functionality and tabbed interface
- Pages & Routing - Scene-based routing and navigation
- Utilities & Hooks - Business logic, data fetching, and React hooks
- Styling System - CSS-in-JS organization and theming
- Constants & Configuration - Centralized configuration and selectors
- Image Assets - Plugin logos and visual assets
- Node.js 18+ and npm
- Grafana 11.0.0 or later
- Git
- Docker (for development environment)
# Clone the repository
git clone https://github.com/grafana/grafana-docs-plugin.git
cd grafana-docs-plugin
# Install dependencies
npm install
# Build the plugin
npm run build
# Start development environment with Grafana
GRAFANA_IMAGE=jayclifford349/grafana-oss GRAFANA_VERSION=docs npm run serverThe plugin includes a complete development setup:
# Development build with watch mode
npm run dev
# Run tests
npm run test
# Lint code
npm run lint
# Type checking
npm run typecheck
# Build for production
npm run buildFor a comprehensive understanding of the project structure, see:
- Source Organization - Complete overview of the
/srcdirectory - Component Structure - UI components and their relationships
- Business Logic - Hooks, utilities, and data fetching
- Styling System - CSS-in-JS organization and theming
- ⚛️ React - UI framework with hooks and context
- 🎭 Grafana Scenes - Scene-based architecture for complex UIs
- 📘 TypeScript - Full type safety and IntelliSense
- 💅 Emotion - CSS-in-JS with theme integration
- 🎨 Grafana UI - Consistent component library
- 🔗 Extension Points - Grafana plugin integration system
// Configure external recommendation service
export const RECOMMENDER_SERVICE_URL = 'http://localhost:8080';
// Custom documentation endpoints
const customEndpoints = {
apiUrl: 'https://docs.company.com/api',
apiKey: 'your-secret-key'
};For detailed configuration options, see the App Configuration README.
For detailed API documentation, see:
- Documentation Panel API - Main panel functionality
- Utilities API - Business logic and data fetching hooks
- Configuration API - Plugin configuration
// Debug content fetching
console.log('Fetching strategies attempted:', strategies);
console.log('Final content result:', content);
// Check network connectivity
fetch(url).then(response => console.log('Direct access:', response.status));// Verify service connectivity
const healthCheck = await fetch(`${RECOMMENDER_SERVICE_URL}/health`);
console.log('Recommender service status:', healthCheck.status);
// Debug context payload
console.log('Context sent to recommender:', payload);// Clear all caches manually
clearLearningJourneyCache();
localStorage.clear();
window.location.reload();# Analyze bundle composition
npm run build:analyze
# Check for duplicate dependencies
npm run dedupe// Implement progressive loading
const preloadNextMilestone = async (content: LearningJourneyContent) => {
const nextUrl = getNextMilestoneUrl(content);
if (nextUrl) {
// Pre-fetch in background
fetchLearningJourneyContent(nextUrl);
}
};For more troubleshooting information, see the component-specific documentation linked above.
// Add to console for detailed logging
localStorage.setItem('docs-plugin-debug', 'true');
// Monitor scene state changes
console.log('Scene state:', sceneObject.state);// Monitor all fetch requests
const originalFetch = window.fetch;
window.fetch = (...args) => {
console.log('Fetch request:', args);
return originalFetch(...args);
};- TypeScript: Strict mode enabled
- React: Functional components with hooks
- Styling: Emotion CSS-in-JS with Grafana theme
- Testing: Jest + React Testing Library
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Test your changes thoroughly
- Commit with conventional commit messages
- Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
# 1. Set up development environment
npm install
npm run dev
# 2. Make changes and test
npm run test
npm run typecheck
npm run lint
# 3. Build and verify
npm run build
npm run server # Test in Grafana
# 4. Submit changes
git add .
git commit -m "feat: add custom content source support"
git push origin feature/custom-contentThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.