JuliaKurs23/AGENTS.md

AGENTS.md - Guidelines for Agentic Coding in JuliaKurs23

This is a Quarto-based Julia programming course book in English. The book teaches scientific computing with Julia using interactive Jupyter notebooks rendered with Quarto.

Translation Note: The book was originally written in German and has been translated to professional, concise English suitable for mathematicians. All code, LaTeX equations, and formatting have been preserved during translation. Only text descriptions and code comments were translated to English.

Project Overview

• Type: Educational book website/PDF generated from Quarto (.qmd) files
• Language: English (all content)
• Build System: Quarto with Julia Jupyter kernel
• Julia Version: 1.10
• Output: HTML website and PDF
• License: CC BY-NC-SA 4.0

---

Build Commands

Build the Book

# Build HTML website
quarto render

# Build only HTML
quarto render --to julia-color-html

# Build only PDF
quarto render --to julia-color-pdf

# Preview locally
quarto preview

Development Commands

# Render a specific chapter
quarto render chapters/first_contact.qmd

# Build with specific output directory
quarto render --output-dir _book

# Run in daemon mode (faster rebuilds)
quarto render --execute-daemon 3600

Deployment

# Deploy to web server (rsync _book/)
./deploy.sh

Testing Individual Code Blocks

Quarto executes Julia code in Jupyter notebooks. To test individual code blocks:

1. Open the .qmd file in VS Code with Julia extension
2. Use Julia REPL to execute code blocks interactively
3. Or use IJulia/Jupyter to run specific cells

# In Julia REPL, test code from a cell:
include("path/to/notebook.jl")

Julia Package Management

# Install dependencies (from Project.toml)
julia -e 'using Pkg; Pkg.instantiate()'

# Add a new package
julia -e 'using Pkg; Pkg.add("PackageName")'

---

Code Style Guidelines

General Structure (.qmd files)

• All .qmd files start with YAML front matter specifying engine: julia
• Code blocks use triple backticks with julia language identifier
• Use Quarto cell options in comments like #| option: value
• Common options: eval:, echo:, output:, error:, hide_line:

Example:

---
engine: julia
---

```{julia}
#| eval: true
#| echo: true
#| output: true
using Statistics
mean([1, 2, 3])

### Julia Code Conventions

#### Imports

```julia
# Prefer using for packages with many exports
using Statistics, LinearAlgebra, Plots

# Use import when you need specific exports or module name
import Base: convert, show

Naming Conventions

• Variables/functions: lowercase with underscores (my_variable, calculate_mean)
• Types: CamelCase (MyType, AbstractMatrix)
• Constants: ALL_UPPERCASE (MAX_ITER, PI)
• Modules: PascalCase (Statistics, LinearAlgebra)

Formatting

• Use 4 spaces for indentation (Julia default)
• Limit lines to ~92 characters when practical
• Use spaces around operators: a + b, not a+b
• No spaces before commas: f(a, b), not f(a , b)

Types

• Use explicit types when needed for performance or clarity
• Parameterize types when useful: Vector{Float64}, Dict{Symbol, Int}
• Prefer concrete types for fields in structs

Error Handling

# Use try-catch for expected errors
try
    parse(Int, user_input)
catch e
    println("Invalid input: $e")
end

# Use assertions for internal checks
@assert x >= 0 "x must be non-negative"

Quarto-Specific Guidelines

Cell Options

Use these in code block comments:

• #| eval: true/false - whether to execute
• #| echo: true/false - show source code
• #| output: true/false - show output
• #| error: true/false - show errors
• #| hide_line: true - hide this line from output
• #| fig-cap: "Caption" - figure caption

Embedding Notebooks

{{< embed notebooks/nb-types.ipynb#nb1 >}}

Conditional Content

::: {.content-visible when-format="html"}
... HTML only content
:::

::: {.content-visible when-format="pdf"}
... PDF only content
:::

---

File Organization

/
├── _quarto.yml          # Quarto configuration
├── Project.toml         # Julia dependencies
├── index.qmd            # Book index
├── chapters/            # Chapter .qmd files
├── notebooks/           # Jupyter notebooks (.ipynb)
├── css/                 # Custom styles
├── images/              # Images and logos
├── fonts/               # Custom fonts
└── _book/               # Built output (generated)

---

VS Code Settings

The project uses VS Code with:

• Julia environment: /home/hellmund/Julia/23
• LTEx for spell checking (disabled for code blocks)
• Auto-exclude: .ipynb, .md, .quarto_ipynb files

---

Important Notes

1. All content is in English - Comments, documentation, variable names in examples should be English (professional, concise, suitable for mathematicians)
2. Code comments were translated - German text and code comments were translated to English; all Julia code, LaTeX equations, and Quarto formatting were preserved
3. Code execution is cached - Use #| eval: true to execute cells
4. ansi color codes - The julia-color extension handles ANSI escape sequences in output
5. Freeze mode - Set to auto in _quarto.yml; use freeze: false to re-run all code
6. Keep intermediate files - keep-ipynb, keep-tex, keep-md are all true