SpecsModelExplore
Git Project
Git Project

Work with file-based IOModel projects stored in a Git repository and edited through the IDE extension.

A Git-project is a file-based IOModel project that lives in a Git repository. Instead of being stored and versioned in the platform, its models and specifications are plain files you edit through the IDE extension (or directly), and version with Git.

Cloud project vs Git-project

Cloud projects are stored and versioned inside IOModel (with in-platform branches). A Git-project keeps content as files in your repository and uses Git for versioning. This page covers the Git-project workflow.

Expected directory layout

A Git-project is the same tree Studio uses. Full rules: File & Folder Structure.

my-project/
  project.yaml
  models.yaml
  models/
    ...
  specs/
    meta.yaml
    <group>/
      meta.yaml
      overview.mdx              # leaf: no children, no attachments
      topic/
        index.mdx               # folder: children or attachments
        _attachments/

Form follows content

Do not create a directory for every page. A leaf with no attachments stays <page>.mdx. pages: entries are one URL segment; nested folders hold their own meta.yaml. The directory is _attachments, not _assets.

project.yaml

project:
  title: My Project
  description: Architecture and specs versioned in Git
  icon: Folder
  features:
    - specs
    - model

Bring existing files into a Git-project

Arrange your files

Place existing model YAML and spec MDX into the expected layout in your repository.

Add project.yaml

Declare the title, description, icon, and enabled features.

Add navigation meta

Provide meta.yaml files so groups and pages appear in the sidebar in the intended order.

Open in the IDE extension

Load the project so the model tree and spec pages render, with live feedback as you edit.

Mapping existing content

You havePut it inResult
Architecture YAMLmodels/ + models.yamlBrowsable model tree
Markdown/MDX docsspecs/<group>/Specification pages
Object/workflow filesattachments: on the ownerTabs and handbook

Versioning

A Git-project uses Git itself for history and collaboration:

  • Commit and branch with your normal Git workflow.
  • Review changes in pull requests alongside code.
  • In-platform branches do not apply — Git is the source of versioning.

In-platform branches

Git-projects do not use IOModel’s in-platform branches. Use Git branches and pull requests for isolation and review.

Keep navigation meta.yaml files accurate. They control sidebar order and which pages are visible.

Last updated on