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

   Example: Create a simple view in resources/edp-likec4/views/my-view.c4:

   specification {
     element myperson
     element mysystem
   }
   
   model {
     customer = myperson 'Customer' {
       description 'End user of the platform'
     }
   
     mySystem = mysystem 'My System' {
       description 'Example system component'
     }
   
     customer -> mySystem 'uses'
   }
   
   views {
     view myCustomView {
       title "My Custom Architecture View"
   
       include customer
       include mySystem
   
       autoLayout TopBottom
     }
   }
   

3. Regenerate webcomponents:

   task likec4:generate
   

4. Embed diagrams in Markdown:

   {{</* likec4-view view="myCustomView" project="architecture" title="My Custom Architecture View" */>}}
   

   Finding available view IDs:

   • Open the .c4 files in your project directory
   • Look for view <viewId> { declarations
   • The <viewId> is what you use in the view parameter
   • Or use: grep -r "^view " resources/edp-likec4/ --include="*.c4"

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