website-and-documentation/content/en/docs/documentation/local-development.md

title	linkTitle	weight	description
Local Development	Local Development	20	Set up your local environment and learn the documentor workflow.

Prerequisites

Before you start, ensure you have:

• Devbox or the following tools installed:
  • Hugo Extended (latest version)
  • Node.js (v24+)
  • Go (for htmltest)
  • Git

Installation

1. Clone the repository:

   git clone <repository-url>
   cd ipceicis-developerframework
   

2. Install dependencies:

   task deps:install
   

Local Development Workflow

{{< likec4-view view="localDevelopment" project="documentation-platform" >}}

Starting the Development Server

The easiest way to work locally is to start the Hugo development server:

task serve

This will:

• Generate build information (git commit, version)
• Start Hugo server on http://localhost:1313
• Enable hot reload - changes appear instantly in the browser

Content Structure

content/
└── en/                      # English content
    ├── _index.md           # Homepage
    ├── blog/               # Blog posts
    └── docs/               # Documentation
        ├── architecture/   # Architecture docs
        ├── decisions/      # ADRs
        └── v1/            # Version-specific docs

Creating Content

1. Add a new documentation page:

   # Create a new markdown file
   vim content/en/docs/your-topic/_index.md
   

2. Add frontmatter:

   ---
   title: "Your Topic"
   linkTitle: "Your Topic"
   weight: 10
   description: >
     Brief description of your topic.
   ---
   

3. Write your content in Markdown

4. Preview changes - they appear immediately if task serve is running

Creating Architecture Diagrams

Architecture diagrams are created with LikeC4:

1. Navigate to the appropriate LikeC4 project:

   • resources/edp-likec4/ - Platform architecture
   • resources/doc-likec4/ - Documentation platform architecture

2. Edit or create .c4 files with your model

3. Regenerate webcomponents:

   task likec4:generate
   

4. Embed diagrams in Markdown:

   {{< likec4-view view="localDevelopment" title="Local Development Workflow" >}}
   

   Available views:

   • overview - Complete system overview
   • localDevelopment - Documentor workflow
   • cicdPipeline - CI/CD process
   • deploymentFlow - Edge deployment
   • fullWorkflow - End-to-end workflow
   • testingCapabilities - Testing overview

Available Tasks

View all available tasks:

task --list

Common Development Tasks

Task	Description
task serve	Start development server with hot reload
task build	Build production-ready site
task build:dev	Build development version
task clean	Remove build artifacts
task test	Run all tests
task test:quick	Run tests without link checking

Quick Testing

Before committing, run quick tests:

task test:quick

This validates:

• Hugo build succeeds
• Markdown syntax is correct

For comprehensive testing, including link checking:

task test

Tips for Documentors

1. Write in present tense - "The system processes..." not "The system will process..."
2. Use code blocks with syntax highlighting
3. Include diagrams for complex concepts
4. Test locally before pushing
5. Keep it concise - readers appreciate brevity
6. Update regularly - stale docs are worse than no docs

Troubleshooting

Port 1313 already in use

# Find and kill the process
lsof -ti:1313 | xargs kill -9

Build errors

# Clean and rebuild
task clean
task build:dev

Missing dependencies

# Reinstall all dependencies
task deps:install

Next Steps

Now that you can develop locally, learn about:

• Testing processes
• CI/CD pipeline