Document Format#
Kodemo uses a JSON document format to save and load content. To get a better understanding of how that JSON is structured, let's build out a document from the ground up.
Title & Version#
At the root of our document you'll find a document title as well as a version number. The version number refers to the Kodemo Editor version that was used to author the document.
Story#
The story
represents the main body text for a document. It is stored as HTML and supports all of the standard HTML tags for formatting.
Subjects#
The subjects are the tabs to the right of the Kodemo interface, i.e. the code/images/etc you're writing about. Each subject has a unique key that is used when linking to it from the story.
Subject Index#
The subjectIndex
is an array of subject keys in the order that we want subjects to appear to the end user. If a subject is missing from the index, it will appear last after all indexed subjects.
Subject Type & Name#
Each subject must have a type
and name
. The type can be either code
, image
, or iframe
. The subject name is used to represent this subject in the Kodemo UI.
Versions#
The content for our subjects is stored as one or more versions. Versions are used to represent multiple variants of the same content, for example code that changes in multiple steps.
Some subjects, such as images, require only one version. Others, like code, support multiple versions and will carry out unique transitions when the end user navigates between those versions.
All versions have unique keys. They contain slightly different data depending on what type of content they represent.
Version Index#
Just like subjects, versions have their own versionIndex
. This is used to control the order of appearance of versions in the interface.
Effects#
Effects are used to create a relationship between keywords in your story and your subjects. More specifically, they make a subject appear in view as you progress through the story.
Effects are inline tags with the following data attributes:
data-effect-id
[required]
A unique identifier for the effect.
data-effect-subject
[required]
ID of the subject this effect should activate.
data-effect-version
ID of the subject version to activate.
data-effect-type="invisible"
Effect are visible as inline highlights in the story. If you'd like to add an effect that isn't highlighted in the story, set this attribute to "invisible".
data-effect-payload
This is used to provide context-specific data to effects, such as which lines of code that should be highlighted or which part of an image that should be focused.