MolViewStories CLI Tool

WarningDevelopment Status

The CLI is currently in active development. Features and commands may change.

In other sections we have described that a Story is a collection of scenes where each scene is defined by having a molecular description in MolViewSpec (and created using Javascript) and a narrative component written in markdown. Stories also have shared metadata. The structure that we have built up to create stories on the web can also be reused locally by recreating the Story in the form of a nested set of files. In this case a story would consist of a file tree that looks something like the files structure below.

The MVS CLI is a way to reuse the StoryManager class of the mol-view-stories repository and allow us to build stories form the command line.

my-story/
├── story.yaml              # Story metadata and settings
├── story.js                # Optional global JavaScript
├── assets/                 # Local molecular files (optional)
└── scenes/
    ├── scene1/
    │   ├── scene1.yaml     # Camera, timing, settings
    │   ├── scene1.md       # Narrative content (Markdown)
    │   └── scene1.js       # Visualization code
    └── scene2/
        ├── scene2.yaml
        ├── scene2.md
        └── scene2.js

MVS CLI Quick Start

The best way to get started is to build a preexisting story from our repo. We will work on creating a quarto template that will help users get started on new stories or incorporating them into existing website workflows.

# Install
git clone https://github.com/molstar/mol-view-stories.git
cd mol-view-stories/cli
deno task build

# Explore an example
./mvs watch examples/exosome

# Create your own story
./mvs create my-story --scenes-as-folders
cd my-story

# Edit your story files
nano story.yaml                    # Story configuration
nano scenes/scene1/scene1.yaml     # Scene settings
nano scenes/scene1/scene1.md       # Scene narrative
nano scenes/scene1/scene1.js       # Visualization code

# Develop with live reload
../mvs watch .

# Build for deployment
../mvs build . -o story.html

Commands

mvs create <story-name>
mvs create <story-name> --scenes-as-folders  # Folder-based (separate scene files)

# builds a scene
mvs build <folder-path> \
    -o <filename>
    --format {json|mvsx|html|mvstory}

mvs watch <folder-path> # Serve on port 8080

Story Structure

Folder-Based Format

Recommended for complex stories with multiple scenes:

my-story/
├── story.yaml              # Story metadata and settings
├── story.js                # Optional global JavaScript
├── assets/                 # Local molecular files (optional)
└── scenes/
    ├── scene1/
    │   ├── scene1.yaml     # Camera, timing, settings
    │   ├── scene1.md       # Narrative content (Markdown)
    │   └── scene1.js       # Visualization code
    └── scene2/
        ├── scene2.yaml
        ├── scene2.md
        └── scene2.js

story.yaml:

title: "My Molecular Story"
author_note: "Optional description"

settings:
  autoPlay: false
  loopStory: false
  showControls: true

scenes:
  - folder: scene1
  - folder: scene2

Inline Format

Simpler format for basic stories - all scenes defined in story.yaml:

my-story/
├── story.yaml              # All configuration and scenes
└── assets/                 # Optional assets

story.yaml with inline scenes:

title: "My Story"

scenes:
  - id: intro
    header: "Introduction"
    description: |
      # Scene content in Markdown
    javascript: |
      // Visualization code
      const structure = builder.download({...});

Configuration Reference

Story Settings

Required: title

Optional: author_note, settings (autoPlay, loopStory, showControls, backgroundColor), global_js, scene_defaults, scene_order

Scene Settings

  • header - Scene title
  • key - Unique identifier
  • camera - Position, target, FOV, mode
  • linger_duration_ms - Display duration
  • transition_duration_ms - Animation duration
  • settings - Scene-specific options

Examples

The CLI includes working examples in examples/:

Full Stories: - exosome - 5-scene structural exploration - tbp - TATA-binding protein - terms-of-entrapment - 14-scene educational story - npc-basket - Nuclear pore complex - motm-01 - Molecule of the Month

Learning Examples: - learning-simple - Minimal folder-based starter - learning-simple-inline - Inline format basics - learning-molviewspec-basics - MolViewSpec API intro - learning-mvs-features - Core features walkthrough

./mvs watch examples/exosome
./mvs build examples/tbp -o tbp.html