DecisionsDev GitHub Pages - Gatsby Carbon Theme

This repository hosts the GitHub Pages website for the DecisionsDev organization, built with Gatsby and the IBM Carbon Design System theme.

🌐 Live Site

Once deployed, the site will be available at: https://decisionsdev.github.io/

🚀 Quick Start

Prerequisites

Node.js 18.x or higher
npm or yarn

Installation

# Clone the repository
git clone https://github.com/DecisionsDev/DecisionsDev.github.io.git
cd DecisionsDev.github.io
# Install dependencies
npm install
# Optional: authenticate GitHub API requests to avoid rate limits# PowerShell$env:GITHUB_TOKEN="your_github_token_here"# Bashexport GITHUB_TOKEN="your_github_token_here"# Start development server
npm run dev

The site will be available at http://localhost:8000

GitHub API Authentication

Several repository tooling scripts call the GitHub REST API. Unauthenticated requests are heavily rate-limited and can fail with HTTP 403 responses such as “API rate limit exceeded”.

Set GITHUB_TOKEN before running npm run build, npm run build:repos, npm run build:videos, or direct tooling like tools/build-repositories.js, tools/extract-videos.js, and tools/generate-topics-report.js.

Use a GitHub personal access token with at least public repository read access.

# PowerShell$env:GITHUB_TOKEN="your_github_token_here"
npm run build

# Bashexport GITHUB_TOKEN="your_github_token_here"
npm run build

📁 Project Structure

DecisionsDev.github.io/
├── src/
│ ├── pages/
│ │ ├── index.mdx # Homepage
│ │ ├── deployment-tools.mdx # Deployment tools page
│ │ ├── rest-api.mdx # REST API samples page
│ │ └── docker.mdx # Docker resources page
│ ├── images/ # Image assets
│ ├── components/ # React components
│ ├── data/ # Data files (repositories.json, nav-items.yaml)
│ └── gatsby-theme-carbon/ # Theme customizations
├── docs/ # Documentation files
│ ├── SETUP.md # Setup guide
│ ├── DEPLOYMENT.md # Deployment guide
│ ├── README-TOPICS-SCRIPT.md # Topics script documentation
│ ├── TOPICS_GUIDE.md # Topics guide
│ └── topics-report.md # Topics report
├── tools/ # Utility scripts
│ ├── build-repositories.js # Build repositories.json with categorization
│ ├── fetch-repos.js # Fetch repositories from GitHub
│ ├── generate-topics-report.js # Generate topics report
│ ├── add-topics-to-repos.js # Add topics to repositories
│ ├── topic-analyzer.js # Analyze repository topics
│ ├── deploy.sh # Deployment script (Linux/Mac)
│ └── deploy.bat # Deployment script (Windows)
├── gatsby-config.js # Gatsby configuration
├── package.json # Dependencies
└── README.md # This file

🛠️ Development

Available Scripts

# Start development server
npm run dev
# Fetch and categorize repositories from GitHub
npm run build:repos
# Fetch and categorize videos from GitHub
npm run build:videos
# Build for production (includes GitHub API-backed data refresh)
npm run build
# Serve production build locally
npm run serve
# Clean cache and build artifacts
npm run clean
# Deploy to GitHub Pages (production)
npm run deploy
# Deploy to preview repository (for review)
npm run deploy:preview

Adding New Pages

Create a new .mdx file in src/pages/
Add frontmatter with title and description
Write content using MDX (Markdown + React components)
The page will be automatically available at /filename

Example:

---title: My New Pagedescription: Description of the page---
<PageDescription>
Brief description of the page content.
</PageDescription>
## Content goes here
Your content using Markdown and Carbon components.

Using Carbon Components

The Gatsby Carbon theme provides many pre-built components:

<Row>
<ColumncolLg={8}>
Content in a column
</Column>
</Row>
<Buttonhref="/link">Button Text</Button>
<ResourceCardsubTitle="Card Title"href="/link"
>
![Icon](./icon.svg)
</ResourceCard>

📝 Content Organization

Project Categories

Projects are organised by product in the Decisions family.

Adding Projects

To add a new project to a category page:

Open the relevant .mdx file (e.g., src/pages/index.mdx)
Add a new section with project details
Include links to the GitHub repository
Add relevant tags and descriptions

🎨 Customization

Theme Configuration

Edit gatsby-config.js to customize:

{resolve: 'gatsby-theme-carbon',options: {theme: {homepage: 'dark',// 'dark' or 'white'interior: 'g10',// 'g10', 'g90', 'g100', 'white'},},}

Styling

The Carbon theme uses IBM's design system. Custom styles can be added in:

src/gatsby-theme-carbon/styles/ - Global style overrides
Component-level styles using CSS modules

🚢 Deployment

GitHub Pages Deployment

Automatic Deployment (Recommended):

# Build and deploy to gh-pages branch
npm run deploy

Manual Deployment:

# Build the site
npm run build
# The built site is in the 'public' directory# Push the public directory to gh-pages branch

GitHub Actions (Optional)

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pageson:
push:
branches: [main]jobs:
build-and-deploy:
runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3with:
node-version: '18'
- run: npm install
- run: npm run build
- uses: peaceiris/actions-gh-pages@v3with:
github_token: ${{ secrets.GITHUB_TOKEN }}publish_dir: ./public

Enabling GitHub Pages

Go to repository Settings
Navigate to "Pages"
Select source: gh-pages branch
Save

The site will be live at https://decisionsdevelopment.github.io/

🛠️ Tools

The tools/ directory contains utility scripts for managing the repository:

Repository Management

build-repositories.js - Fetch repos from GitHub and apply categorization (creates repositories.json)
fetch-repos.js - Fetch repository data from GitHub API
topic-analyzer.js - Analyze repository topics and suggest categories

Topic Management

list-all-topics.js - List all topics used across DecisionsDev repositories
remove-topics-from-repos.js - Remove or replace topics in repositories
add-topics-to-repos.js - Automatically add structured topics to repositories
generate-topics-report.js - Generate a report of repository topics

Deployment

deploy.sh / deploy.bat - Production deployment scripts for Linux/Mac and Windows
deploy-preview.sh / deploy-preview.bat - Preview deployment scripts for private review

Using the Tools

# Build repositories.json with categorization (recommended)
npm run build:repos
# List all topics used in the organization
node tools/list-all-topics.js
node tools/list-all-topics.js --verbose # Show which repos use each topic
node tools/list-all-topics.js --pattern "product-*"# Filter by pattern# Remove topics from repositories
node tools/remove-topics-from-repos.js --topics old-topic --dry-run
node tools/remove-topics-from-repos.js --topics old-topic --apply
# Replace topics (only where they exist)
node tools/remove-topics-from-repos.js --topics old-topic --replace new-topic --dry-run
node tools/remove-topics-from-repos.js --pattern "odmdev-*" --replace odm --apply
# Generate topics report
node tools/generate-topics-report.js
# Deploy the site
./tools/deploy.sh # Linux/Mac
tools\deploy.bat # Windows

Repository Categorization

The build-repositories.js script automatically categorizes repositories based on their names and descriptions:

Products: odm, decision-intelligence, bai, cp4ba
Components: decisioncenter, ruleexecutionserver, container, ai, etc.
Types: sample, tool, tutorial, documentation, integration, etc.

The script:

Fetches all repositories from the DecisionsDev GitHub organization
Analyzes each repository using topic-analyzer.js
Adds a categories field with clean names (without prefixes)
Preserves original GitHub topics for backward compatibility
Writes the result to src/data/repositories.json

Example output structure:

{
"name": "odm-ondocker",
"description": "Deploy ODM with Docker Compose",
"topics": ["docker", "ibm-odm", "odm"],
"categories": {
"products": ["odm"],
"components": ["container"],
"types": ["sample"]
},
"url": "https://github.com/DecisionsDev/odm-ondocker"
}

📖 Documentation

The docs/ directory contains detailed documentation:

SETUP.md - Complete setup guide
DEPLOYMENT.md - Production deployment instructions
PREVIEW-DEPLOYMENT.md - Preview deployment for private review
CATEGORIZATION.md - Repository categorization system
TOPICS_GUIDE.md - Guide for repository topics
README-TOPICS-SCRIPT.md - Topics script documentation

📚 Resources

Gatsby Carbon Theme

IBM Carbon Design System

Gatsby

🤝 Contributing

Adding Content

Fork the repository
Create a feature branch
Add or update content
Test locally with npm run dev
Submit a pull request

Content Guidelines

Use clear, concise language
Include code examples where appropriate
Add links to relevant repositories
Use proper Markdown formatting
Test all links

Adding Topics to Your Repository

When contributing a new repository to DecisionsDev, please add relevant topics:

Use existing topics - Run node tools/list-all-topics.js to see all topics currently in use
Select the most relevant - Choose 3-7 topics that best describe your repository
Follow the pattern - Use lowercase, hyphenated names (e.g., decision-center, not DecisionCenter)
Common topics include:
- Products: odm, decision-intelligence, bai, cp4ba
- Technologies: docker, kubernetes, java, react, kafka
- Types: tutorial, sample, integration, rpa
- Components: decision-center, dsi, analytics

Example: For an ODM Docker tutorial, use: odm, docker, tutorial, business-rules

See TOPICS_GUIDE.md for detailed guidance.

Code Style

Follow existing file structure
Use meaningful component names
Add comments for complex logic
Keep pages focused and organized

🐛 Troubleshooting

Build Errors

# Clear cache and rebuild
npm run clean
npm install
npm run build

Port Already in Use

# Kill process on port 8000# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F
# Linux/Mac
lsof -ti:8000 | xargs kill -9

Module Not Found

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

📄 License

This website is licensed under the Apache License 2.0.

📞 Support

For issues or questions:

History

build refresh
update form odm-collective

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
src		src
tools		tools
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
_config.yml		_config.yml
gatsby-config.js		gatsby-config.js
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

DecisionsDev GitHub Pages - Gatsby Carbon Theme

🌐 Live Site

🚀 Quick Start

Prerequisites

Installation

GitHub API Authentication

📁 Project Structure

🛠️ Development

Available Scripts

Adding New Pages

Using Carbon Components

📝 Content Organization

Project Categories

Adding Projects

🎨 Customization

Theme Configuration

Styling

🚢 Deployment

GitHub Pages Deployment

GitHub Actions (Optional)

Enabling GitHub Pages

🛠️ Tools

Repository Management

Topic Management

Deployment

Using the Tools

Repository Categorization

📖 Documentation

📚 Resources

Gatsby Carbon Theme

IBM Carbon Design System

Gatsby

🤝 Contributing

Adding Content

Content Guidelines

Adding Topics to Your Repository

Code Style

🐛 Troubleshooting

Build Errors

Port Already in Use

Module Not Found

📄 License

📞 Support

History

About

Topics

Resources

Code of conduct

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages