docs(dev): add Taskfile and developer documentation

- Add Taskfile.yml with common development tasks
- Add go-task to devbox dependencies
- Create comprehensive README-developer.md covering:
  - Devbox setup and usage
  - Hugo and Docsy basics
  - Task commands reference
  - Development workflow
  - Content creation guide
  - Testing procedures
  - Troubleshooting tips
This commit is contained in:
Stephan Lo 2025-10-23 14:13:31 +02:00
parent 08a0e8863f
commit 3eaa574a26
4 changed files with 448 additions and 4 deletions

311
README-developer.md Normal file
View file

@ -0,0 +1,311 @@
# Developer Guide - IPCEI-CIS Developer Framework
## 🚀 Quick Start
### Prerequisites
Install [Devbox](https://www.jetify.com/devbox/):
```bash
curl -fsSL https://get.jetify.com/devbox | bash
```
### Setup
1. Clone the repository
2. Start devbox shell:
```bash
devbox shell
```
Devbox automatically installs all required tools:
- Hugo (v0.151.0+extended)
- Go (v1.25.1)
- Node.js (v24.10.0)
- Dart Sass
- htmltest
- go-task
## 📚 Technology Stack
### Hugo (v0.151.0+extended)
Hugo is a fast static site generator. This project uses Hugo in extended mode with:
- **Docsy Theme** (v0.12.0) - Documentation theme with responsive design
- **Bootstrap 5.3.8** - UI framework
- **PostCSS** - CSS processing
### Docsy Theme
Docsy is a Hugo theme optimized for technical documentation:
- Multi-language support
- Search functionality
- Navigation menu system
- Code syntax highlighting
- Responsive design
Key directories:
- `content/en/` - English content (Markdown files)
- `layouts/` - Custom layout overrides
- `assets/scss/` - Custom styles
- `static/` - Static assets (images, etc.)
### Task (Taskfile)
Task is a task runner / build tool that replaces Makefiles. It uses `Taskfile.yml` for defining tasks.
## 🛠️ Development Workflow
### Using Task (Recommended)
View all available tasks:
```bash
task
# or
task --list
```
Common tasks:
#### Development
```bash
task serve # Start Hugo dev server (http://localhost:1313)
task build # Build production site
task build:dev # Build development site
task clean # Clean build artifacts
```
#### Testing
```bash
task test # Run all tests
task test:quick # Run quick tests (without link checking)
task test:build # Test if Hugo builds successfully
task test:markdown # Lint Markdown files
task test:html # Validate HTML output
task test:links # Check all links (internal & external)
```
#### Dependencies
```bash
task deps:install # Install all dependencies
task deps:update # Update all dependencies
```
#### CI/CD
```bash
task ci # Run full CI pipeline locally
```
### Using NPM Scripts (Alternative)
If you prefer NPM:
```bash
npm test # All tests
npm run test:quick # Quick tests
npm run test:build # Build test
npm run test:markdown # Markdown linting
npm run test:html # HTML validation
npm run test:links # Link checking
```
### Using Hugo Directly
```bash
# Development server
hugo server
# Production build
hugo --gc --minify
# Check version
hugo version
```
## 📁 Project Structure
```
.
├── content/ # Content files (Markdown)
│ └── en/ # English content
│ ├── docs/ # Documentation
│ └── blog/ # Blog posts
├── layouts/ # Custom HTML templates
├── static/ # Static files
├── 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
```
## 📝 Content Creation
### Creating New Pages
```bash
# Using Hugo
hugo new docs/concepts/my-page.md
hugo new blog/my-post.md
# Or create manually in content/en/
```
### Front Matter
Every content file needs front matter:
```yaml
---
title: "My Page Title"
description: "Page description"
date: 2025-10-23
weight: 10 # Order in navigation
---
Your content here...
```
### Using Docsy Shortcodes
Docsy provides helpful shortcodes:
#### Tabbed Panes
```markdown
{{</* tabpane */>}}
{{</* tab "Tab 1" */>}}
Content for tab 1
{{</* /tab */>}}
{{</* tab "Tab 2" */>}}
Content for tab 2
{{</* /tab */>}}
{{</* /tabpane */>}}
```
#### Code Blocks
```markdown
{{</* code lang="yaml" */>}}
key: value
{{</* /code */>}}
```
#### Alerts
```markdown
{{</* alert title="Note" */>}}
Important information
{{</* /alert */>}}
```
## 🧪 Testing
See [TESTING.md](TESTING.md) for detailed testing documentation.
Quick reference:
- `task test` - Run all tests before committing
- `task test:quick` - Fast checks during development
- Tests run automatically on GitHub Actions for PRs
## 🔧 Configuration
### Hugo Configuration (`hugo.toml`)
Main settings:
- `baseURL` - Site URL
- `title` - Site title
- `defaultContentLanguage` - Default language
- Module imports (Docsy theme)
### Docsy Configuration
Docsy-specific settings in `hugo.toml`:
```toml
[params]
github_repo = "your-repo"
github_branch = "main"
```
### Devbox Configuration (`devbox.json`)
Defines all development tools and their versions.
Update tools:
```bash
devbox update # Update all packages
task deps:update # Update all dependencies (devbox + npm + hugo modules)
```
## 🎨 Styling
Custom styles in `assets/scss/_variables_project.scss`:
```scss
// Override Bootstrap/Docsy variables
$primary: #your-color;
```
Hugo will process SCSS automatically with PostCSS and Autoprefixer.
## 🌐 Multi-Language Support
Add new language:
1. Create `content/<lang>/` directory
2. Add language config in `hugo.toml`:
```toml
[languages.<lang>]
languageName = "Language Name"
weight = 2
```
## 🐛 Troubleshooting
### "Module not found" errors
```bash
hugo mod get -u
hugo mod tidy
```
### PostCSS errors
```bash
npm install
```
### Build errors
```bash
task clean
task build
```
### Devbox issues
```bash
devbox update
devbox shell --refresh
```
## 📚 Resources
- [Hugo Documentation](https://gohugo.io/documentation/)
- [Docsy Documentation](https://www.docsy.dev/docs/)
- [Taskfile Documentation](https://taskfile.dev/)
- [Devbox Documentation](https://www.jetify.com/devbox/docs/)
## 🤝 Contributing
1. Create a feature branch
2. Make your changes
3. Run tests: `task test`
4. Commit with semantic messages:
- `feat(scope): add new feature`
- `fix(scope): fix bug`
- `docs(scope): update documentation`
- `test(scope): add tests`
- `chore(scope): maintenance`
5. Push and create pull request
## 📦 Deployment
Build for production:
```bash
task build
```
Output will be in `public/` directory, ready for deployment.