Course Package Format (ZIP)

Specification version: 2.0

Oceanowledge accepts two package types: course (practical lessons) and book (narrative chapters). The manifest is always named course.md.

Archive structure

course-name.zip
├── course.md
├── lessons/                 # type: course
│   └── 01-intro.md
├── chapters/                # type: book
│   └── 01-intro.md
└── assets/                  # optional PNG/SVG and other images

Manifest

---
type: course                 # course | book; defaults to course
title: "Elixir Basics"
version: "1.1"               # required MAJOR.MINOR package version
slug: elixir-basics
language: en                  # en | ru | es
level: beginner
tags: [elixir, backend]
lessons:
  - 01-intro.md
---
Description in Markdown...

Books use type: book and replace lessons: with chapters:. The matching directory and list are required; using the wrong key is a manifest error. The list order defines reading order. A published package re-upload must have a strictly greater version. Malformed versions are warnings; missing versions default to "1.1".

Course lessons

Each lesson has YAML frontmatter and all four sections: ## Theory, ## Examples, ## Checklist, and ## Questions. Questions use numbered prompts and task-list options, with exactly one [x] answer. Mermaid fences are preserved as ordinary Markdown. Relative assets/... image links are rewritten when the file exists.

Book chapters

Chapters have YAML frontmatter and free-form prose. Optional reserved sections are:

## Illustration: each ### heading defines a named figure with its first image and optional italic caption.
## Encyclopedia: each ### heading defines a glossary term and its definition.
## Questions: the same optional self-check format as course questions.
## Further Reading: Markdown content, commonly a link list.

Checklists are course-only. Book chapters may contain ordinary ##/### headings outside the reserved sections.

Validation and limits

Missing course.md, invalid type, wrong content key, missing listed files, bad content frontmatter, missing course sections, path traversal, or an archive over 50 MB/1,000 files fails the import. Unlisted content files, malformed package versions, broken image references, and questions without exactly one correct option are warnings; invalid questions are skipped.

Assets are uploaded under a versioned course path. Replacing a package replaces its content and preserves the course record while incrementing the platform’s internal course version.

Course Package Format