mirror of
https://github.com/Heretek-AI/heretek-openclaw-docs.git
synced 2026-07-01 13:18:20 -04:00
chore: Add CI/CD workflows, CODEOWNERS, and documentation templates
This commit is contained in:
John Doe
@@ -0,0 +1,165 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run ESLint
|
||||
run: npm run lint
|
||||
|
||||
- name: Run Prettier check
|
||||
run: npm run format:check
|
||||
|
||||
typecheck:
|
||||
name: Type Check
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run TypeScript
|
||||
run: npm run typecheck
|
||||
|
||||
test:
|
||||
name: Test
|
||||
runs-on: ubuntu-latest
|
||||
services:
|
||||
postgres:
|
||||
image: postgres:15
|
||||
env:
|
||||
POSTGRES_USER: test
|
||||
POSTGRES_PASSWORD: test
|
||||
POSTGRES_DB: test
|
||||
ports:
|
||||
- 5432:5432
|
||||
options: >-
|
||||
--health-cmd pg_isready
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
|
||||
redis:
|
||||
image: redis:7
|
||||
ports:
|
||||
- 6379:6379
|
||||
options: >-
|
||||
--health-cmd "redis-cli ping"
|
||||
--health-interval 10s
|
||||
--health-timeout 5s
|
||||
--health-retries 5
|
||||
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run tests
|
||||
run: npm run test
|
||||
env:
|
||||
POSTGRES_HOST: localhost
|
||||
POSTGRES_PORT: 5432
|
||||
POSTGRES_USER: test
|
||||
POSTGRES_PASSWORD: test
|
||||
POSTGRES_DB: test
|
||||
REDIS_HOST: localhost
|
||||
REDIS_PORT: 6379
|
||||
|
||||
- name: Upload coverage
|
||||
uses: codecov/codecov-action@v3
|
||||
if: always()
|
||||
with:
|
||||
files: ./coverage/coverage-final.json
|
||||
fail_ci_if_error: false
|
||||
|
||||
build:
|
||||
name: Build
|
||||
runs-on: ubuntu-latest
|
||||
needs: [lint, typecheck, test]
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build
|
||||
run: npm run build
|
||||
|
||||
- name: Upload build artifacts
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: build
|
||||
path: dist/
|
||||
retention-days: 7
|
||||
|
||||
security:
|
||||
name: Security Scan
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run npm audit
|
||||
run: npm audit --audit-level=moderate
|
||||
continue-on-error: true
|
||||
|
||||
- name: Run Snyk
|
||||
uses: snyk/actions/node@master
|
||||
continue-on-error: true
|
||||
env:
|
||||
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
|
||||
@@ -0,0 +1,173 @@
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
- '*/v*'
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
packages: write
|
||||
|
||||
jobs:
|
||||
release:
|
||||
name: Create Release
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
version: ${{ steps.get_version.outputs.version }}
|
||||
component: ${{ steps.get_version.outputs.component }}
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Get version
|
||||
id: get_version
|
||||
run: |
|
||||
TAG=${GITHUB_REF#refs/tags/}
|
||||
VERSION=${TAG##*/v}
|
||||
COMPONENT=${TAG%/*}
|
||||
if [ "$COMPONENT" = "$TAG" ]; then
|
||||
COMPONENT=""
|
||||
fi
|
||||
echo "version=$VERSION" >> $GITHUB_OUTPUT
|
||||
echo "component=$COMPONENT" >> $GITHUB_OUTPUT
|
||||
echo "Version: $VERSION"
|
||||
echo "Component: $COMPONENT"
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Build
|
||||
run: npm run build
|
||||
|
||||
- name: Generate changelog
|
||||
id: changelog
|
||||
run: |
|
||||
PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
|
||||
if [ -z "$PREVIOUS_TAG" ]; then
|
||||
CHANGELOG=$(git log --pretty=format:"- %s (%h)" HEAD)
|
||||
else
|
||||
CHANGELOG=$(git log --pretty=format:"- %s (%h)" $PREVIOUS_TAG..HEAD)
|
||||
fi
|
||||
echo "changelog<<EOF" >> $GITHUB_OUTPUT
|
||||
echo "$CHANGELOG" >> $GITHUB_OUTPUT
|
||||
echo "EOF" >> $GITHUB_OUTPUT
|
||||
|
||||
- name: Create GitHub Release
|
||||
uses: actions/create-release@v1
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
with:
|
||||
tag_name: ${{ github.ref }}
|
||||
release_name: Release ${{ steps.get_version.outputs.version }}
|
||||
body: |
|
||||
## Changes
|
||||
|
||||
${{ steps.changelog.outputs.changelog }}
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @heretek/openclaw-${{ steps.get_version.outputs.component }}@${{ steps.get_version.outputs.version }}
|
||||
```
|
||||
draft: false
|
||||
prerelease: ${{ contains(github.ref, 'beta') || contains(github.ref, 'alpha') }}
|
||||
|
||||
publish-npm:
|
||||
name: Publish to npm
|
||||
runs-on: ubuntu-latest
|
||||
needs: release
|
||||
if: ${{ !contains(needs.release.outputs.component, 'deploy') && !contains(needs.release.outputs.component, 'docs') }}
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
cache: 'npm'
|
||||
registry-url: 'https://registry.npmjs.org'
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Update version
|
||||
run: npm version ${{ needs.release.outputs.version }} --no-git-tag-version
|
||||
|
||||
- name: Build
|
||||
run: npm run build
|
||||
|
||||
- name: Publish to npm
|
||||
run: npm publish --access public
|
||||
env:
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
|
||||
- name: Create npm release notes
|
||||
run: |
|
||||
echo "Published @heretek/openclaw-${{ needs.release.outputs.component }}@${{ needs.release.outputs.version }} to npm"
|
||||
|
||||
publish-docker:
|
||||
name: Publish to Docker Hub
|
||||
runs-on: ubuntu-latest
|
||||
needs: release
|
||||
if: ${{ needs.release.outputs.component == 'core' || needs.release.outputs.component == '' }}
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Login to Docker Hub
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
username: ${{ secrets.DOCKERHUB_USERNAME }}
|
||||
password: ${{ secrets.DOCKERHUB_TOKEN }}
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: |
|
||||
heretek/openclaw:${{ needs.release.outputs.version }}
|
||||
heretek/openclaw:latest
|
||||
platforms: linux/amd64,linux/arm64
|
||||
cache-from: type=registry,ref=heretek/openclaw:buildcache
|
||||
cache-to: type=registry,ref=heretek/openclaw:buildcache,mode=max
|
||||
|
||||
notify:
|
||||
name: Notify
|
||||
runs-on: ubuntu-latest
|
||||
needs: [release, publish-npm, publish-docker]
|
||||
if: always()
|
||||
steps:
|
||||
- name: Notify Slack
|
||||
uses: slackapi/slack-github-action@v1
|
||||
if: ${{ needs.release.result == 'success' }}
|
||||
with:
|
||||
payload: |
|
||||
{
|
||||
"text": "🚀 Released: ${{ github.repository }} v${{ needs.release.outputs.version }}",
|
||||
"blocks": [
|
||||
{
|
||||
"type": "section",
|
||||
"text": {
|
||||
"type": "mrkdwn",
|
||||
"text": "🚀 *New Release*\n*${{ github.repository }}* v${{ needs.release.outputs.version }}\n${{ github.event.release.html_url }}"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
env:
|
||||
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
|
||||
+52
@@ -0,0 +1,52 @@
|
||||
# Heretek OpenClaw CODEOWNERS
|
||||
# https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners
|
||||
|
||||
# This file defines who is responsible for code reviews in this repository.
|
||||
# Each line specifies a path pattern and the users/groups responsible for it.
|
||||
|
||||
# Format:
|
||||
# <path-pattern> <owner1> <owner2> ...
|
||||
|
||||
# Default owners for the entire repository
|
||||
* @heretek/docs-team
|
||||
|
||||
# Core team has ownership of all code
|
||||
/src/ @heretek/docs-team
|
||||
|
||||
# Agent-specific ownership
|
||||
/src/agents/ @heretek/docs-team
|
||||
/src/agents/steward/ @heretek/docs-team
|
||||
/src/agents/explorer/ @heretek/docs-team
|
||||
/src/agents/sentinel/ @heretek/docs-team
|
||||
|
||||
# Skills ownership
|
||||
/src/skills/ @heretek/docs-team
|
||||
/src/skills/triad-* @heretek/docs-team
|
||||
/src/skills/memory-* @heretek/docs-team
|
||||
|
||||
# Plugin ownership
|
||||
/plugins/ @heretek/docs-team
|
||||
/plugins/consciousness/ @heretek/docs-team
|
||||
/plugins/liberation/ @heretek/docs-team
|
||||
|
||||
# Test ownership
|
||||
/tests/ @heretek/docs-team
|
||||
/tests/unit/ @heretek/docs-team
|
||||
/tests/integration/ @heretek/docs-team
|
||||
/tests/e2e/ @heretek/docs-team
|
||||
|
||||
# Configuration ownership
|
||||
/openclaw.json @heretek/docs-team
|
||||
/package.json @heretek/docs-team
|
||||
|
||||
# Documentation ownership
|
||||
/docs/ @heretek/docs-team
|
||||
/README.md @heretek/docs-team
|
||||
|
||||
# Infrastructure ownership
|
||||
/Dockerfile @heretek/docs-team
|
||||
/docker-compose.yml @heretek/docs-team
|
||||
/deploy/ @heretek/docs-team
|
||||
|
||||
# CI/CD ownership
|
||||
.github/workflows/ @heretek/docs-team
|
||||
+296
@@ -0,0 +1,296 @@
|
||||
# Contributing to Heretek OpenClaw
|
||||
|
||||
Thank you for your interest in contributing to Heretek OpenClaw! This document provides guidelines and instructions for contributing.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Making Changes](#making-changes)
|
||||
- [Pull Requests](#pull-requests)
|
||||
- [Testing](#testing)
|
||||
- [Code Style](#code-style)
|
||||
- [Commit Messages](#commit-messages)
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
- Be respectful and inclusive
|
||||
- Focus on constructive feedback
|
||||
- Welcome newcomers and help them learn
|
||||
- Keep discussions on topic
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Fork the repository** on GitHub
|
||||
2. **Clone your fork** locally
|
||||
```bash
|
||||
git clone https://github.com/your-username/heretek-openclaw-docs.git
|
||||
cd heretek-openclaw-docs
|
||||
```
|
||||
3. **Add upstream remote**
|
||||
```bash
|
||||
git remote add upstream https://github.com/heretek/heretek-openclaw-docs.git
|
||||
```
|
||||
4. **Install dependencies**
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- npm 9+
|
||||
- Git
|
||||
- Docker (for integration tests)
|
||||
|
||||
### Environment Setup
|
||||
|
||||
```bash
|
||||
# Copy environment template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit with your settings
|
||||
nano .env
|
||||
```
|
||||
|
||||
### Running Locally
|
||||
|
||||
```bash
|
||||
# Development mode
|
||||
npm run dev
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
|
||||
# Lint code
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## Making Changes
|
||||
|
||||
### Branch Naming
|
||||
|
||||
Use descriptive branch names:
|
||||
|
||||
```
|
||||
feature/add-new-skill
|
||||
fix/gateway-memory-leak
|
||||
docs/update-api-reference
|
||||
refactor/improve-error-handling
|
||||
```
|
||||
|
||||
### Making Commits
|
||||
|
||||
1. **Create a branch** from `main`
|
||||
```bash
|
||||
git checkout -b feature/your-feature
|
||||
```
|
||||
|
||||
2. **Make focused commits**
|
||||
- Each commit should do one thing
|
||||
- Write clear commit messages
|
||||
- Test before committing
|
||||
|
||||
3. **Keep your branch updated**
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
```
|
||||
|
||||
## Pull Requests
|
||||
|
||||
### Before Submitting
|
||||
|
||||
- [ ] Tests pass locally
|
||||
- [ ] Code is linted
|
||||
- [ ] Documentation is updated
|
||||
- [ ] Changes are tested
|
||||
|
||||
### PR Description
|
||||
|
||||
Use the PR template and include:
|
||||
|
||||
- **What** changes are being made
|
||||
- **Why** the changes are needed
|
||||
- **How** the changes were tested
|
||||
- **Related issues** (if any)
|
||||
|
||||
### Review Process
|
||||
|
||||
1. **Automated checks** must pass
|
||||
2. **Code review** by maintainers
|
||||
3. **Address feedback** promptly
|
||||
4. **Squash commits** if requested
|
||||
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# All tests
|
||||
npm test
|
||||
|
||||
# Unit tests only
|
||||
npm run test:unit
|
||||
|
||||
# Integration tests only
|
||||
npm run test:integration
|
||||
|
||||
# With coverage
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
### Writing Tests
|
||||
|
||||
- Write tests for new features
|
||||
- Update tests when fixing bugs
|
||||
- Aim for meaningful coverage
|
||||
- Test edge cases
|
||||
|
||||
### Test Types
|
||||
|
||||
| Type | Location | Purpose |
|
||||
|------|----------|---------|
|
||||
| Unit | `tests/unit/` | Test individual functions |
|
||||
| Integration | `tests/integration/` | Test component interactions |
|
||||
| E2E | `tests/e2e/` | Test full user flows |
|
||||
| Skills | `tests/skills/` | Test skill execution |
|
||||
|
||||
## Code Style
|
||||
|
||||
### JavaScript/TypeScript
|
||||
|
||||
- Use ESLint configuration provided
|
||||
- Prefer `const` over `let`
|
||||
- Use meaningful variable names
|
||||
- Add JSDoc comments for public APIs
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* Calculate agent health status
|
||||
* @param {Object} agent - Agent instance
|
||||
* @returns {Object} Health status
|
||||
*/
|
||||
function calculateHealth(agent) {
|
||||
const metrics = collectMetrics(agent);
|
||||
return {
|
||||
status: metrics.status,
|
||||
score: metrics.score
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Formatting
|
||||
|
||||
- Use Prettier for consistent formatting
|
||||
- 2 spaces for indentation
|
||||
- Single quotes for strings
|
||||
- Semicolons required
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
npm run format
|
||||
|
||||
# Check formatting
|
||||
npm run format:check
|
||||
```
|
||||
|
||||
## Commit Messages
|
||||
|
||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer]
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat:` New feature
|
||||
- `fix:` Bug fix
|
||||
- `docs:` Documentation changes
|
||||
- `style:` Code style changes (formatting)
|
||||
- `refactor:` Code refactoring
|
||||
- `test:` Test additions/changes
|
||||
- `chore:` Build/config changes
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
feat(agents): add historian agent for memory management
|
||||
|
||||
Implements the historian agent responsible for long-term
|
||||
memory consolidation and decision tracking.
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
```
|
||||
fix(gateway): resolve WebSocket connection timeout
|
||||
|
||||
Increased timeout from 5s to 30s for slow connections.
|
||||
|
||||
Fixes #456
|
||||
```
|
||||
|
||||
```
|
||||
docs(api): update A2A protocol documentation
|
||||
|
||||
Added examples for new message types and clarified
|
||||
error handling procedures.
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
### Writing Documentation
|
||||
|
||||
- Use clear, concise language
|
||||
- Include examples where helpful
|
||||
- Link to related documentation
|
||||
- Keep headings hierarchical
|
||||
|
||||
### Documentation Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
├── getting-started/
|
||||
├── architecture/
|
||||
├── configuration/
|
||||
├── operations/
|
||||
└── api/
|
||||
```
|
||||
|
||||
## Release Process
|
||||
|
||||
### Version Numbering
|
||||
|
||||
We use [Semantic Versioning](https://semver.org/):
|
||||
|
||||
- `MAJOR.MINOR.PATCH`
|
||||
- Breaking changes → increment MAJOR
|
||||
- New features → increment MINOR
|
||||
- Bug fixes → increment PATCH
|
||||
|
||||
### Release Checklist
|
||||
|
||||
- [ ] Update version in package.json
|
||||
- [ ] Update CHANGELOG.md
|
||||
- [ ] Create git tag
|
||||
- [ ] Publish to npm (if applicable)
|
||||
- [ ] Create GitHub release
|
||||
|
||||
## Questions?
|
||||
|
||||
- **General questions:** GitHub Discussions
|
||||
- **Bug reports:** GitHub Issues
|
||||
- **Security issues:** Email security@heretek.ai
|
||||
|
||||
---
|
||||
|
||||
Thank you for contributing to Heretek OpenClaw! 🦞
|
||||
@@ -0,0 +1,285 @@
|
||||
# Heretek OpenClaw Documentation
|
||||
|
||||
> Official documentation site for Heretek OpenClaw, built with Next.js and deployed to GitHub Pages.
|
||||
|
||||
## Overview
|
||||
|
||||
This repository contains the documentation site for Heretek OpenClaw, including:
|
||||
|
||||
- **User Guides** - Getting started, installation, configuration
|
||||
- **API Documentation** - Gateway API, A2A protocol, plugin API
|
||||
- **Operations Guides** - Runbooks, monitoring, troubleshooting
|
||||
- **Architecture** - System design, component documentation
|
||||
- **Deployment** - Cloud and on-premises deployment guides
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- npm 9+
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
git clone https://github.com/heretek/heretek-openclaw-docs.git
|
||||
cd heretek-openclaw-docs
|
||||
npm install
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
npm run dev
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Preview production build
|
||||
npm run preview
|
||||
```
|
||||
|
||||
Access the site at `http://localhost:3000`
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
heretek-openclaw-docs/
|
||||
├── src/ # Next.js source code
|
||||
│ ├── app/ # App router pages
|
||||
│ ├── components/ # Reusable components
|
||||
│ └── styles/ # Global styles
|
||||
├── content/ # Documentation content
|
||||
│ ├── api/ # API documentation
|
||||
│ ├── operations/ # Operations guides
|
||||
│ ├── configuration/ # Configuration guides
|
||||
│ └── deployment/ # Deployment guides
|
||||
├── public/ # Static assets
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## Content Organization
|
||||
|
||||
### Documentation Categories
|
||||
|
||||
| Category | Location | Description |
|
||||
|----------|----------|-------------|
|
||||
| API | `content/api/` | API reference documentation |
|
||||
| Operations | `content/operations/` | Runbooks and operational procedures |
|
||||
| Configuration | `content/configuration/` | Configuration guides and examples |
|
||||
| Deployment | `content/deployment/` | Deployment instructions |
|
||||
| Architecture | `content/architecture/` | System architecture documentation |
|
||||
| Plugins | `content/plugins/` | Plugin development guides |
|
||||
|
||||
### Content Format
|
||||
|
||||
Documentation uses Markdown with frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Gateway Architecture
|
||||
description: Overview of OpenClaw Gateway architecture
|
||||
---
|
||||
|
||||
# Gateway Architecture
|
||||
|
||||
Content goes here...
|
||||
```
|
||||
|
||||
## Adding New Documentation
|
||||
|
||||
### Create a New Page
|
||||
|
||||
1. Create a new `.mdx` file in the appropriate `content/` subdirectory
|
||||
2. Add frontmatter with title and description
|
||||
3. Write content using Markdown
|
||||
4. Add to navigation in `src/config/navigation.ts`
|
||||
|
||||
### Example
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: My New Guide
|
||||
description: How to do something with OpenClaw
|
||||
order: 5
|
||||
---
|
||||
|
||||
# My New Guide
|
||||
|
||||
## Introduction
|
||||
|
||||
This guide covers...
|
||||
|
||||
## Steps
|
||||
|
||||
1. First step
|
||||
2. Second step
|
||||
3. Third step
|
||||
|
||||
## Conclusion
|
||||
|
||||
Summary of what was covered.
|
||||
```
|
||||
|
||||
## Navigation Configuration
|
||||
|
||||
Edit `src/config/navigation.ts` to update the sidebar:
|
||||
|
||||
```typescript
|
||||
export const navigation = {
|
||||
main: [
|
||||
{
|
||||
title: 'Getting Started',
|
||||
href: '/docs/getting-started',
|
||||
},
|
||||
{
|
||||
title: 'Architecture',
|
||||
href: '/docs/architecture',
|
||||
},
|
||||
// Add new pages here
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
The documentation site includes full-text search powered by [search library]. Search indexes are built automatically during deployment.
|
||||
|
||||
## Styling
|
||||
|
||||
### Custom Components
|
||||
|
||||
Available components in `src/components/`:
|
||||
|
||||
- `<Callout>` - Highlighted information boxes
|
||||
- `<CodeBlock>` - Syntax-highlighted code
|
||||
- `<Step>` - Numbered step containers
|
||||
- `<Tabs>` - Tabbed content sections
|
||||
|
||||
### Usage Example
|
||||
|
||||
```mdx
|
||||
<Callout type="info">
|
||||
This is an important note!
|
||||
</Callout>
|
||||
|
||||
<Step number={1}>
|
||||
First, do this...
|
||||
</Step>
|
||||
|
||||
<Tabs>
|
||||
<Tab label="Docker">
|
||||
```bash
|
||||
docker compose up
|
||||
```
|
||||
</Tab>
|
||||
<Tab label="Kubernetes">
|
||||
```bash
|
||||
kubectl apply -f manifests/
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
Documentation is automatically deployed to GitHub Pages on every push to `main`:
|
||||
|
||||
1. Push changes to `main` branch
|
||||
2. GitHub Actions builds the site
|
||||
3. Deployed to `https://heretek.github.io/heretek-openclaw-docs`
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
```bash
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
# Preview locally
|
||||
npm run preview
|
||||
|
||||
# Deploy (if you have write access)
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
## CI/CD
|
||||
|
||||
The documentation site uses GitHub Actions for continuous deployment:
|
||||
|
||||
```yaml
|
||||
name: Deploy Documentation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
jobs:
|
||||
build-and-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
- run: npm install
|
||||
- run: npm run build
|
||||
- uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Writing Style
|
||||
|
||||
- Use clear, concise language
|
||||
- Include code examples where relevant
|
||||
- Link to related documentation
|
||||
- Use appropriate heading hierarchy (H1 → H2 → H3)
|
||||
|
||||
### Code Examples
|
||||
|
||||
- Use real, working code
|
||||
- Include comments for complex sections
|
||||
- Specify language for syntax highlighting
|
||||
- Test examples before publishing
|
||||
|
||||
### Images and Diagrams
|
||||
|
||||
- Store images in `public/images/`
|
||||
- Use SVG for diagrams when possible
|
||||
- Include alt text for accessibility
|
||||
- Optimize image file sizes
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Check links
|
||||
npm run check:links
|
||||
|
||||
# Validate Markdown
|
||||
npm run lint:markdown
|
||||
|
||||
# Type check
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
## Related Repositories
|
||||
|
||||
- [Core](https://github.com/heretek/heretek-openclaw-core) - Gateway and agents
|
||||
- [CLI](https://github.com/heretek/heretek-openclaw-cli) - Deployment CLI
|
||||
- [Dashboard](https://github.com/heretek/heretek-openclaw-dashboard) - Health monitoring
|
||||
- [Plugins](https://github.com/heretek/heretek-openclaw-plugins) - Plugin system
|
||||
- [Deploy](https://github.com/heretek/heretek-openclaw-deploy) - Infrastructure as Code
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues:** https://github.com/heretek/heretek-openclaw-docs/issues
|
||||
- **Discussions:** https://github.com/heretek/heretek-openclaw-docs/discussions
|
||||
|
||||
---
|
||||
|
||||
🦞 *The thought that never ends.*
|
||||
Reference in New Issue
Block a user