/
Documentation

Team Workflow

Learn how to collaborate on documentation with your team using the CLI and Git.

Onboard a new team member

When someone new joins — say Jim just started on the DundlerOS project — the setup takes a couple of minutes:

  1. Clone the repository:
   git clone https://github.com/your-org/your-project.git
   cd your-project
  1. Log in:
   meldoc auth login
  1. Pull the latest documentation:
   meldoc pull

That’s it. The committed meldoc.config.yml already points at the right workspace and project, so Jim can start editing .meldoc.md files right away — no meldoc init needed.

Keep in mind: Each team member authenticates with their own account via meldoc auth login — credentials are personal and shouldn’t be shared. For CI/CD pipelines, use an Integration Tokens instead, and store it as a secret. See Environment Variables for where the CLI reads tokens from.

The daily rhythm

Start of the day — take both the code and the documentation:

git pull
meldoc pull

During the day — edit .meldoc.md files as you work on the code, while the context is still fresh.

End of the day — check what changed, publish, and commit:

meldoc scan
meldoc push

git add docs/
git commit -m "docs: Update order endpoints"
git push

Work with pull requests

Documentation changes go through the same review process as code.

  1. Create a branch:
   git checkout -b docs/update-order-endpoints

  1. Edit your documentation files.

  2. Validate the structure:

   meldoc validate
  1. Commit and push the branch:
   git add docs/
   git commit -m "docs: Update order endpoints with pagination"
   git push origin docs/update-order-endpoints

  1. Open a pull request and get it reviewed.

  2. After merge, publish to Meldoc:

   git checkout main
   git pull
   meldoc push

Tip: Set up CI/CD Integration to publish automatically when changes merge to main — no manual meldoc push needed.

Organize documentation

A consistent file structure helps the team navigate the project:

project/
├── docs/
│   ├── getting-started.meldoc.md
│   ├── api/
│   │   ├── index.meldoc.md
│   │   └── order-endpoints.meldoc.md
│   └── warehouse/
│       ├── index.meldoc.md
│       └── inventory-sync.meldoc.md
├── src/
└── meldoc.config.yml

Run meldoc organize to automatically restructure files based on parent-child relationships defined in frontmatter.

Handle conflicts

When multiple people edit the same document, conflicts can occur during sync. Meldoc uses three-way merge by default to combine non-overlapping changes automatically:

meldoc pull

To decide each conflict yourself, pull in interactive mode:

meldoc pull --resolve ask

When a conflict comes up, choose:

  • o or ours — keep your version
  • t or theirs — take the server version
  • m or merge — merge the non-overlapping changes

Or settle every conflict the same way up front:

meldoc pull --resolve theirs   # always take the server version
meldoc pull --resolve ours     # always keep the local version
meldoc pull --resolve merge    # automatic merge (the default)

For details on resolution modes and conflict markers, see Conflict Resolution.

Team habits

  • Tell the team before a large documentation change, and agree on the structure in advance rather than after the fact.
  • Review anything substantial through a pull request.
  • Pull before you start, push in small batches, and resolve conflicts quickly instead of letting local changes pile up.
  • Keep the documentation in the same repository as the code, and commit documentation changes together with the code they describe.

What’s next?

CI/CD Integration — Publish docs automatically from CI/CD pipelines.

Conflict Resolution — Handle sync conflicts in detail.

Workflow — Daily push, pull, and sync workflows.