Patrick.Sy/website-and-documentation
1
0
Fork 0
forked from DevFW-CICD/website-and-documentation
Code Pull requests Activity

docs: consolidate root documentation to README-* structure

Browse source 
- Created README-documentor.md: comprehensive guide for content contributors
- Created README-likec4.md: architecture modeling guide (merged from README-ARCHITECTURE.md + LIKEC4-QUICKSTART.md)
- Enhanced README-developer.md:
  - Added Docker/Container Build section (from DOCKER.md)
  - Expanded Testing section (from TESTING.md)
  - Added Version Management section (from VERSIONS.md)
  - Added LikeC4 tasks reference
- Updated README.md: modernized with badges and clear structure
- Deleted redundant files:
  - DOCUMENTOR-GUIDE.md (ASCII art, redundant to README-documentor.md)
  - DOCKER.md (integrated into README-developer.md)
  - TESTING.md (integrated into README-developer.md)
  - README-ARCHITECTURE.md (merged into README-likec4.md)
  - LIKEC4-QUICKSTART.md (merged into README-likec4.md)
  - VERSIONS.md (integrated into README-developer.md)
- Added devbox shell step to local-development.md

All hands-on documentation now follows README-* naming convention.
RELEASE.md retained as process documentation (not hands-on guide).
This commit is contained in:
Stephan Lo 2025-11-07 15:48:55 +01:00
parent 9921e07e3e
commit 9e509ed265
11 changed files with 1127 additions and 644 deletions
Download patch file Download diff file Expand all files Collapse all files

191
README-developer.md
View file

@ -12,7 +12,11 @@ curl -fsSL https://get.jetify.com/devbox | bash
### Setup
1. Clone the repository
2. Start devbox shell:
2. Install dependencies:
```bash
task deps:install
```
3. Start devbox shell:
```bash
devbox shell
```
@ -25,6 +29,8 @@ Devbox automatically installs all required tools:
- htmltest
- go-task
> **Note:** For content contributors, see [README-documentor.md](./README-documentor.md) for a simplified guide.
## 📚 Technology Stack
### Hugo (v0.151.0+extended)
@ -49,6 +55,22 @@ Key directories:
- `assets/scss/` - Custom styles
- `static/` - Static assets (images, etc.)
### LikeC4 (v1.43.0)
LikeC4 is used for interactive architecture diagrams:
- C4 model-based architecture visualization
- Web Components for embedding diagrams
- Real-time preview during development
Architecture models:
- `resources/edp-likec4/` - Platform architecture models
- `resources/doc-likec4/` - Documentation platform models
LikeC4 tasks available:
- `task likec4:generate` - Generate web components
- `task likec4:validate` - Validate C4 models
- `task likec4:update` - Update LikeC4 version
### Task (Taskfile)
Task is a task runner / build tool that replaces Makefiles. It uses `Taskfile.yml` for defining tasks.
@ -90,6 +112,140 @@ task deps:install # Install all dependencies
task deps:update # Update all dependencies
```
#### LikeC4
```bash
task likec4:generate # Generate web components from C4 models
task likec4:validate # Validate C4 model syntax
task likec4:update # Update LikeC4 to latest version
```
#### Build & Test OCI Image
```bash
task build:oci-image # Build Docker/OCI image
task test:oci-image # Build and test image
```
#### CI/CD
```bash
task ci # Run full CI pipeline locally
```
## 🧪 Testing
This project uses multiple automated tests for quality assurance.
### Test Configuration Files
- `.htmltest.yml` - Link checker configuration
- `.htmlvalidate.json` - HTML validation rules
- `.markdownlint.json` - Markdown linting rules
### CI/CD Integration
GitHub Actions runs these tests automatically on every push/PR via `.github/workflows/test.yml`.
### Local Development Workflow
**Before commit:**
```bash
task test:quick
```
**Before push:**
```bash
task test
```
## 🐳 Docker / Container Build
### Version Management
All tool versions are defined in `.env.versions` as the single source of truth:
```bash
NODE_VERSION=24.10.0
GO_VERSION=1.25.1
HUGO_VERSION=0.151.0
```
These versions are used in:
- `devbox.json` - Local development (manual sync required)
- `Dockerfile` - Build arguments with defaults
- `.github/workflows/ci.yaml` - CI/CD pipeline (automatic)
**Updating versions:**
1. Edit `.env.versions`
2. Manually sync `devbox.json`:
```json
{
"packages": [
"hugo@0.151.0",
"go@1.25.1",
"nodejs@24.10.0"
]
}
```
3. Rebuild: `devbox shell --refresh`
### Local Build
**Using Task (recommended):**
```bash
task build:oci-image # Build OCI image
task test:oci-image # Build and test
```
This automatically loads versions from `.env.versions` and tags with `latest` and git commit hash.
**Helper script for manual builds:**
```bash
source scripts/get-versions.sh
# Shows Docker build command with correct versions
```
**Manual build:**
```bash
docker build --network=host \
--build-arg NODE_VERSION=24.10.0 \
--build-arg GO_VERSION=1.25.1 \
--build-arg HUGO_VERSION=0.151.0 \
-t ipceicis-developerframework:latest .
```
**Test the image:**
```bash
docker run -d -p 8080:80 --name hugo-test ipceicis-developerframework:latest
curl http://localhost:8080
docker stop hugo-test && docker rm hugo-test
```
### Image Structure
- **Build Stage**: Node.js base, installs Go and Hugo
- **Runtime Stage**: nginx:alpine serves static content (~50MB)
Build process:
1. Install npm dependencies
2. Download Hugo modules
3. Build static site (`hugo --gc --minify`)
4. Copy to nginx container
### CI/CD Pipeline
`.github/workflows/ci.yaml` automatically:
1. Extracts versions from devbox environment
2. Builds multi-arch images (amd64 + arm64)
3. Pushes to container registry
**Required GitHub Secrets:**
- `PACKAGES_USER` - Registry username
- `PACKAGES_TOKEN` - Registry token/password
#### CI/CD
```bash
task ci # Run full CI pipeline locally
@ -128,16 +284,27 @@ hugo version
│ └── en/ # English content
│ ├── docs/ # Documentation
│ └── blog/ # Blog posts
├── resources/ # LikeC4 architecture models
│ ├── edp-likec4/ # Platform architecture (C4 models)
│ └── doc-likec4/ # Documentation platform architecture
├── layouts/ # Custom HTML templates
│ └── shortcodes/ # Custom shortcodes (e.g., likec4-view)
├── static/ # Static files
│ └── js/ # JavaScript (LikeC4 webcomponents)
├── assets/ # Assets (SCSS, images)
├── public/ # Generated site (not in Git)
├── resources/ # Hugo cache (not in Git)
├── hugo.toml # Hugo configuration
├── go.mod # Hugo modules (Docsy theme)
├── Taskfile.yml # Task definitions
├── package.json # NPM dependencies & scripts
└── devbox.json # Devbox configuration
├── devbox.json # Devbox configuration
├── .env.versions # Version definitions (SSOT)
├── Dockerfile # Multi-stage container build
├── README.md # Main README
├── README-developer.md # This file
├── README-documentor.md # Guide for content contributors
├── README-likec4.md # LikeC4 architecture modeling guide
└── RELEASE.md # Release process documentation
```
## 📝 Content Creation
@ -197,6 +364,18 @@ Important information
{{</* /alert */>}}
```
#### LikeC4 Architecture Diagrams
```markdown
{{</* likec4-view view="overview" project="architecture" title="System Overview" */>}}
```
Parameters:
- `view` - View ID from C4 model
- `project` - `"architecture"` or `"documentation-platform"`
- `title` - Optional custom title
See [README-documentor.md](./README-documentor.md) for detailed LikeC4 workflow.
## 🧪 Testing
See [TESTING.md](TESTING.md) for detailed testing documentation.
@ -285,9 +464,15 @@ devbox shell --refresh
- [Hugo Documentation](https://gohugo.io/documentation/)
- [Docsy Documentation](https://www.docsy.dev/docs/)
- [LikeC4 Documentation](https://likec4.dev/)
- [Taskfile Documentation](https://taskfile.dev/)
- [Devbox Documentation](https://www.jetify.com/devbox/docs/)
**Project-specific guides:**
- [README-documentor.md](./README-documentor.md) - Content contributor guide
- [TESTING.md](./TESTING.md) - Detailed testing documentation
- [DOCUMENTOR-GUIDE.md](./DOCUMENTOR-GUIDE.md) - Quick reference for documentors
## 🤝 Contributing
1. Create a feature branch