Import Format

Reference for the markdown file formats used by andamio course import and andamio course export.

You don't have to write these files by hand. Coach, Andamio's course-authoring tool (an Agent Skill, also on npm as @andamio/coach), compiles a finished module into this exact structure with its /compile skill, ready to hand to andamio course import. This page documents the format Coach produces, and that the CLI expects, for when you need to inspect or edit it directly.

Directory Structure

module-folder/
├── outline.md          # Required — module metadata and SLTs
├── introduction.md     # Optional — shown before lessons
├── lesson-1.md         # Optional — content for SLT 1
├── lesson-2.md         # Optional — content for SLT 2
├── lesson-N.md         # Optional — content for SLT N
├── assignment.md       # Optional — module assignment
└── assets/             # Optional — images
    ├── screenshot.png
    └── .image-manifest.json

outline.md (Required)

Used in the CLI: course import parses it to read the module code and SLTs, and compute-hash reads it to derive the on-chain credential hash.

andamio course import ./compiled/my-course/101 --course-id <course-id>
andamio course credential compute-hash --file ./compiled/my-course/101/outline.md

Defines the module metadata and Student Learning Targets. Each SLT becomes a lesson slot.

---
title: Introduction to Cardano
code: intro-cardano
---

## SLTs

1. Understand blockchain fundamentals
2. Set up a Cardano wallet
3. Execute your first transaction

Rules:

• YAML frontmatter must include title and code
• The code field is the unique module identifier — can be numeric (101) or a slug (intro-cardano)
• No # H1 heading in this file — the title comes from YAML frontmatter
• SLT heading must be exactly ## SLTs or ## SLT (case-insensitive)
• Each numbered or bulleted item becomes one SLT
• SLT text is used exactly as written — preserve any "I can" prefix
• If code matches an existing module, content will be updated (upsert)

lesson-N.md (Optional)

Used in the CLI: course export writes one lesson-N.md per SLT; you edit locally, then course import sends the content back.

andamio course export <course-id> 101        # writes lesson-1.md, lesson-2.md, ...
vim compiled/my-course/101/lesson-1.md
andamio course import ./compiled/my-course/101 --course-id <course-id>

Content for each lesson, where N corresponds to the SLT index (1-indexed). File lesson-1.md maps to the first SLT, lesson-2.md to the second, etc.

# Understanding Blockchain

A blockchain is a distributed ledger...

## Key Concepts

- Decentralization
- Immutability
- Consensus mechanisms

Rules:

• The # H1 heading becomes the lesson title in the app
• Everything after the H1 becomes the lesson content
• If no H1 is present, the lesson imports with a blank title
• Supports standard markdown: headings, lists, code blocks, blockquotes, emphasis, links, images

introduction.md (Optional)

Used in the CLI: picked up automatically by course import if present in the module folder. Its content stays editable at any module status, even after SLTs are locked.

andamio course import ./compiled/my-course/101 --course-id <course-id>

Module introduction shown before lessons. Great for context, prerequisites, or learning objectives.

# Welcome to Cardano Development

This module covers the fundamentals
of building on the Cardano blockchain.

## Prerequisites

- Basic programming knowledge
- Curiosity about Web3

Rules:

• # H1 heading becomes the introduction title
• Rest of content becomes the introduction body

assignment.md (Optional)

Used in the CLI: picked up automatically by course import if present. Like the introduction, assignment content remains editable at any module status.

andamio course import ./compiled/my-course/101 --course-id <course-id>

Module assignment content. This is the task students complete to demonstrate mastery.

# Module Assignment

## Task

Create a simple Cardano wallet and
document the process.

## Deliverables

1. Screenshot of wallet setup
2. Your wallet address
3. Brief reflection (200 words)

Rules:

• # H1 heading becomes the assignment title
• Use ## Task and ## Deliverables sections for consistent structure
• Additional sections like ## Notes are allowed

Images

Used in the CLI: on course import, new images in assets/ are uploaded to the CDN; on course export, images are downloaded to assets/ and an .image-manifest.json is written mapping filenames to their CDN URLs.

andamio course import ./compiled/my-course/101 --course-id <course-id>   # uploads new images in assets/
andamio course export <course-id> 101                                    # downloads images + writes .image-manifest.json

Place images in an assets/ subdirectory and reference them with relative paths.

Referencing Images

![Wallet Setup](assets/screenshot-wallet.png)

![Diagram](./assets/diagram-1.png)

Both assets/image.png and ./assets/image.png work.

Supported Formats

.png, .jpg, .jpeg, .gif, .webp, .svg (max 5MB per image)

What Happens on Import

1. New images are uploaded to the CDN
2. Local paths are replaced with hosted URLs
3. An .image-manifest.json file is written mapping filenames to CDN URLs

Image Manifest

The .image-manifest.json file preserves CDN URLs across import/export cycles:

{
  "screenshot-wallet.png": "https://storage.googleapis.com/andamio-storage/abc123.png",
  "diagram-1.png": "https://storage.googleapis.com/andamio-storage/def456.png"
}

On subsequent imports, images in the manifest are not re-uploaded. On export, images are downloaded from their CDN URLs and the manifest is recreated.

Best Practices

• Use lowercase filenames without spaces: wallet-setup.png not Wallet Setup.png
• Name screenshots to match lesson flow: 1.1-connect-wallet-01.png, 1.1-connect-wallet-02.png
• Remove unused images and their manifest entries before importing

Common Mistakes