Documentation Update Guide

Overview

This guide explains how to update documentation in the OKLABS multi-project GitBook system hosted at how.oklabs.my.id.

Documentation Structure

/data/core-stack/gitbook/
├── README.md                    # Central hub homepage
├── SUMMARY.md                   # Multi-project navigation (table of contents)
├── projects/
│   ├── providertrack/           # ProviderTrack documentation
│   │   ├── README.md            # Project overview
│   │   ├── api/                 # API documentation
│   │   │   └── outsider-api.md  # Complete API reference
│   │   ├── guides/              # Admin guides
│   │   │   └── provider-management.md
│   │   └── deployment/          # Setup guides
│   │       └── vm-setup.md
│   └── other-projects/          # Future projects
│       └── README.md            # Placeholder
└── infrastructure/              # OKLABS infrastructure docs
    └── overview.md              # System architecture

Update Methods

Method 1: Direct File Editing on VM

Step 1: Connect to VM

ssh root@core-stack

Step 2: Navigate to GitBook directory

cd /data/core-stack/gitbook

Step 3: Edit files directly

# Edit main homepage
nano README.md

# Edit ProviderTrack API docs
nano projects/providertrack/api/outsider-api.md

# Edit provider management guide
nano projects/providertrack/guides/provider-management.md

Step 4: Rebuild GitBook

docker exec gitbook gitbook build

Step 5: Restart GitBook container (if needed)

docker restart gitbook

Method 2: Upload from Local Machine

Step 1: Edit files locally Edit documentation files on your local machine using VS Code or any text editor.

Step 2: Upload via SCP

# Upload updated API documentation
scp OUTSIDER_API_COMPLETE_DOCUMENTATION.md root@core-stack:/data/core-stack/gitbook/projects/providertrack/api/outsider-api.md

# Upload provider management guide
scp PROVIDER_MANAGEMENT_GUIDE.md root@core-stack:/data/core-stack/gitbook/projects/providertrack/guides/provider-management.md

# Upload any other documentation
scp YOUR_DOCUMENTATION.md root@core-stack:/data/core-stack/gitbook/projects/providertrack/guides/

Step 3: Rebuild GitBook

ssh root@core-stack "docker exec gitbook gitbook build"

Adding New Projects

Step 1: Create Project Directory

ssh root@core-stack "mkdir -p /data/core-stack/gitbook/projects/[PROJECT_NAME]"

Step 2: Create Project Documentation

ssh root@core-stack "cat > /data/core-stack/gitbook/projects/[PROJECT_NAME]/README.md << 'EOF'
# [Project Name] Documentation

## Overview
Brief description of the project.

## Features
- Feature 1
- Feature 2
- Feature 3

## Quick Links
- [API Documentation](api/README.md)
- [Setup Guide](guides/setup.md)
- [Live System](https://[project-url].oklabs.my.id)

---
*Back to [OKLABS Documentation Hub](../../README.md)*
EOF"

Step 3: Update Table of Contents

Edit /data/core-stack/gitbook/SUMMARY.md to include the new project:

# OKLABS Documentation Hub

## Introduction
* [Welcome](README.md)

## ProviderTrack Project
* [Overview](projects/providertrack/README.md)
* [API Documentation](projects/providertrack/api/outsider-api.md)
* [Administration](projects/providertrack/guides/provider-management.md)
* [Deployment](projects/providertrack/deployment/vm-setup.md)

## [New Project Name]
* [Overview](projects/[PROJECT_NAME]/README.md)
* [Documentation](projects/[PROJECT_NAME]/docs/README.md)

## Other Projects
* [Coming Soon](projects/other-projects/README.md)

Step 4: Rebuild GitBook

ssh root@core-stack "docker exec gitbook gitbook build"

Common Update Scenarios

Updating API Documentation

For ProviderTrack API changes:

1. Edit local OUTSIDER_API_COMPLETE_DOCUMENTATION.md
2. Upload to server:

   scp OUTSIDER_API_COMPLETE_DOCUMENTATION.md root@core-stack:/data/core-stack/gitbook/projects/providertrack/api/outsider-api.md
   

3. Rebuild: ssh root@core-stack "docker exec gitbook gitbook build"

Adding New Provider Examples

To add new shipping providers (e.g., Tiki, Wahana):

1. Edit projects/providertrack/guides/provider-management.md

2. Add new sections following the existing format:

   ## Tiki Express Example
   
   ### Provider Information
   - **Name**: Tiki Express
   - **Website**: https://www.tiki.id
   - **Type**: Domestic & International Shipping
   
   ### Configuration Steps
   [Step-by-step instructions]
   

3. Upload and rebuild

Updating Infrastructure Documentation

To update system information:

1. Edit infrastructure/overview.md
2. Add new services to the table:

   | New Service | newservice.oklabs.my.id | Service description |
   

3. Upload and rebuild

Troubleshooting

GitBook Build Errors

Problem: Build fails with plugin errors Solution:

ssh root@core-stack
cd /data/core-stack/gitbook
docker exec gitbook gitbook install
docker exec gitbook gitbook build

Problem: Changes not visible after rebuild Solution:

ssh root@core-stack "docker restart gitbook"

File Permission Issues

Problem: Cannot edit files Solution:

ssh root@core-stack "chown -R root:root /data/core-stack/gitbook"
ssh root@core-stack "chmod -R 755 /data/core-stack/gitbook"

Navigation Issues

Problem: New pages not showing in navigation Solution: Ensure SUMMARY.md is updated with correct paths and rebuild

Best Practices

Documentation Standards

1. Use consistent formatting: Follow Markdown standards
2. Include navigation links: Always link back to parent pages
3. Add table of contents: For long documents, include TOC
4. Use code blocks: Format code examples properly
5. Include examples: Provide real-world examples where possible

Update Workflow

1. Test locally: Preview changes before uploading
2. Update incrementally: Make small, focused changes
3. Rebuild after changes: Always rebuild GitBook after updates
4. Verify live site: Check https://how.oklabs.my.id after updates
5. Document changes: Keep track of what was updated

File Organization

1. Group related content: Keep similar docs in same folder
2. Use descriptive names: File names should be clear and consistent
3. Maintain hierarchy: Follow the established folder structure
4. Archive old content: Move outdated docs to archive folder

Quick Commands Reference

# Connect to VM
ssh root@core-stack

# Navigate to GitBook
cd /data/core-stack/gitbook

# List current structure
find . -name "*.md" | head -20

# Edit main homepage
nano README.md

# Upload file from local
scp LOCAL_FILE.md root@core-stack:/data/core-stack/gitbook/TARGET_PATH/

# Rebuild GitBook
docker exec gitbook gitbook build

# Restart GitBook
docker restart gitbook

# Check GitBook status
docker ps | grep gitbook

# View GitBook logs
docker logs gitbook

# Check file permissions
ls -la /data/core-stack/gitbook/

Access Information

• Documentation Site: https://how.oklabs.my.id
• GitBook Container: Running on port 4000
• Local Preview: http://track.oklabs.my.id:4000 (for testing)
• Files Location: /data/core-stack/gitbook/

Support

For documentation update assistance:

• Email: ossie@somagede.com
• System Status: https://uptime.oklabs.my.id
• System Access: Requires SSH access to core-stack VM
• GitBook Version: Using yanqd0/gitbook Docker image

OKLABS Documentation Update Guide - Keep your docs current and accessible

Last Updated: August 9, 2025