website-and-documentation/content/en/docs/documentation/quick-reference.md

---
title: "Quick Reference"
linkTitle: "Quick Reference"
weight: 60
description: >
  Cheat sheet for common documentor tasks.
---

## Common Commands

### Local Development

```bash
# Start development server (with hot reload)
task serve

# Build for production
task build

# Build for development (faster, no minification)
task build:dev

# Clean build artifacts
task clean
```

### Testing

```bash
# Quick tests (build + markdown)
task test:quick

# Full test suite
task test

# Individual tests
task test:build      # Hugo build validation
task test:markdown   # Markdown linting
task test:html       # HTML validation
task test:links      # Link checking
```

### Dependencies

```bash
# Install dependencies
task deps:install

# Update dependencies
task deps:update

# Ensure npm dependencies (auto-installs if missing)
task deps:ensure-npm
```

### Container Operations

```bash
# Build OCI/Docker image
task build:oci-image

# Build and test container
task test:oci-image
```

## File Locations

### Content

| Path | Description |
|------|-------------|
| `content/en/docs/` | Main documentation |
| `content/en/blog/` | Blog posts |
| `content/en/_index.md` | Homepage |

### Architecture Models

| Path | Description |
|------|-------------|
| `resources/edp-likec4/` | Platform architecture models |
| `resources/doc-likec4/` | Documentation platform models |

### Configuration

| File | Purpose |
|------|---------|
| `hugo.toml` | Hugo configuration |
| `config.yaml` | Docsy theme config |
| `Taskfile.yml` | Task definitions |
| `package.json` | npm dependencies and scripts |
| `.markdownlint.json` | Markdown linting rules |
| `.htmlvalidate.json` | HTML validation rules |
| `.htmltest.yml` | Link checker config |

### Build Output

| Path | Description |
|------|-------------|
| `public/` | Generated static site |
| `resources/_gen/` | Generated resources (Hugo) |
| `data/build_info.json` | Build metadata (git commit, version) |

## Markdown Frontmatter

### Standard Page

```yaml
---
title: "Page Title"
linkTitle: "Short Title"
weight: 10
description: >
  Brief description for SEO and navigation.
---
```

### Blog Post

```yaml
---
title: "Post Title"
date: 2025-01-15
author: "Your Name"
description: >
  Post summary.
---
```

## Embedding Architecture Diagrams

### Basic Embed

```markdown
{{< likec4-view view="view-name" project="project-name" >}}
```

### Parameters

- `view` (required) - The view ID from your LikeC4 model
- `project` (optional, default: "architecture") - The LikeC4 project name
- `title` (optional, default: "Architecture View: {view}") - Custom header text above the diagram

### Examples

```markdown
{{< likec4-view view="overview" project="documentation-platform" >}}
{{< likec4-view view="localDevelopment" project="documentation-platform" >}}
{{< likec4-view view="cicdPipeline" project="documentation-platform" >}}
{{< likec4-view view="otc-faas" project="architecture" title="OTC FaaS Deployment" >}}
```

## LikeC4 Commands

### Regenerate Webcomponents

After modifying `.c4` files:

```bash
task likec4:generate
```

This regenerates both:

- `static/js/likec4-webcomponent.js` (EDP architecture)
- `static/js/likec4-doc-webcomponent.js` (Documentation platform)

### Start Development Server

```bash
cd resources/doc-likec4  # or resources/edp-likec4
npm install
npm start
```

Opens LikeC4 IDE at `http://localhost:5173`

### Export Diagrams

```bash
cd resources/doc-likec4
npx likec4 export png -o ./images .
```

## Git Workflow

### Feature Branch

```bash
# Create feature branch
git checkout -b feature/your-feature

# Make changes and test
task serve
task test:quick

# Commit
git add .
git commit -m "Description of changes"

# Push
git push origin feature/your-feature

# Create pull request on GitHub
```

### Update from Main

```bash
git checkout main
git pull origin main
git checkout feature/your-feature
git rebase main
```

## Troubleshooting

### Port 1313 in use

```bash
lsof -ti:1313 | xargs kill -9
```

### Build errors

```bash
task clean
task build:dev
```

### Missing dependencies

```bash
task deps:install
```

### Hugo module issues

```bash
hugo mod clean
hugo mod get -u
hugo mod tidy
```

### LikeC4 language server

In VS Code: `Ctrl+Shift+P` → "LikeC4: restart language server"

## URLs

### Local Development

- **Documentation:** <http://localhost:1313>
- **LikeC4 IDE:** <http://localhost:5173> (when running `npm start` in likec4 folder)

### Production

Check `edgeconnectdeployment.yaml` for deployment URL or run:

```bash
kubectl get service edpdoc -n <namespace>
```

## Quick Checks Before Committing

1. ✅ `task test:quick` passes
2. ✅ Preview looks correct in browser
3. ✅ No broken links (visual check)
4. ✅ Architecture diagrams render
5. ✅ Frontmatter is correct

## Getting Help

- **Hugo docs:** <https://gohugo.io/documentation/>
- **Docsy theme:** <https://www.docsy.dev/docs/>
- **LikeC4:** <https://likec4.dev/>
- **Task:** <https://taskfile.dev/>

## View Documentation Architecture

To understand how this documentation platform works:

→ Start here: [Documentation About Documentation](../)