Collaboration

Comments in Documents

When working in a team, comments are indispensable. AsciiDoc supports two types of comments that don’t appear in the output:

Single-line comments start with //:

// TODO: Revise this section
Here is the visible text.

Block comments for longer notes:

////
This entire block is a comment.
It can span multiple lines.
Ideal for detailed notes or temporarily
hidden text passages.
////

Comments are only visible in the editor – they are ignored in preview and output.

Tips for effective comments can be found in our blog article Do’s and Don’ts for Comments.

Docs-as-Code

AsciiDoc is excellent for the docs-as-code approach: documentation is treated like source code and managed with the same tools.

Advantages of this approach:

  • Versioning: Changes are traceable

  • Collaboration: Multiple authors can work in parallel

  • Reviews: Changes can be reviewed before being adopted

  • Automation: Documents can be automatically built and published

Since AsciiDoc is plain text, it can be optimally used with Git or other version control systems.

Version Control with Git

AsciiDoc files are ideal for Git:

  • Changes are traceable line by line

  • Merge conflicts are easy to resolve

  • Branches enable parallel document versions

Typical workflow:

  1. Make changes in a branch

  2. Create a pull request

  3. Review by colleagues

  4. Merge into the main branch

Write each sentence on its own line (Semantic Line Breaks). This makes diffs clearer and facilitates reviews.

Automation

adoc Studio can be fully automated – ideal for CI/CD pipelines and recurring tasks.

Command-line tool: With the CLI tool, you export documents directly from the terminal:

adocstudio export --product "Manual PDF" --output ./output/

You can download and install the command-line tool in adoc Studio  Settings …  CLI.

Shortcuts app: On Mac, you can also automate exports via the Shortcuts app. Create your own shortcuts that export your products at the push of a button – without manually opening adoc Studio.

Typical automation scenarios:

  • Nightly builds of your documentation

  • Export on every Git push

  • Batch export of all language versions

A detailed example for automation can be found in the blog article Automation with adoc Studio.

Project Dictionaries

For teams working on many different projects, adoc Studio offers project-specific dictionaries. This way you maintain consistent spelling across the team.

To add a dictionary:

  1. Enable spell checking via Edit  Spelling and Grammar  Check Spelling While Typing

  2. Click "Learn" on an unknown word

  3. Choose an existing dictionary or create a new one

The new dictionary (.adict file) appears in the sidebar. It can be versioned, transferred to other projects, and shared by the team.

adoc Studio saves projects as regular folders with AsciiDoc files. You can put these directly in a Git repository and manage them with your preferred Git client.