1. Introduction

This document accompanies you on the direct path to working with adoc Studio. It explains the structure of the app, introduces the commands and provides many tips for a deeper introduction to the documentation with adoc Studio.

In addition, the source code of this documentation gives you an example of how to set up a project in adoc Studio. The user manual can be called up in adoc Studio via the main menu Help  User manual.

Notation in this document

You will find some notes in the text that will give you special help.

Additional notes are displayed as a note.
Whenever there is an opportunity for a special hint, you will receive a tip.
The bell appears to alert you to special features.
Whenever you need to take special care before performing an action, this warning will appear.
Attention, here we try to draw your attention to existing dangers, damage or consequences.
more

  • External links are appended with an arrow .

  • Links within the document are normally underlined hyperlinks.

  • Keys and buttons appear as: Yes

  • Menu commands are shown as File  Export  Products.

  • Keyboard shortcuts look like this: ^+⌘+E.

  • There are references to an operating element in the app and corresponding inputs.

1.1. What is adoc Studio?

adocstudio

With adoc Studio, you can create technical documentation efficiently and effortlessly. The app supports you in creating extensive and structured documents. Once started, the cursor blinks in the editor, and every word you write instantly appears in the preview on the right. This intuitive workflow ensures high productivity. Whether on the Mac, iPad, or iPhone, you always have a consistent and user-friendly view.

adoc Studio uses an integrated writing environment based on the markup language AsciiDoc and produces documents in HTML, PDF formats and Websites.

Markup Language

Most people are familiar with Microsoft Word or another text editor. In contrast, markup languages like Markdown have become increasingly popular in recent years. These do not present the result like Microsoft Word or Apple Pages in a print-like preview. Instead, they need to be translated, which requires varying amounts of effort.

AsciiDoc

adoc Studio is based on AsciiDoc, a well-established markup language. The decision by the Eclipse Foundation to standardize the scope of AsciiDoc ensures a future-proof choice. We chose AsciiDoc because it is easy for beginners to learn and offers an extensive set of commands for professionals.

Integrated Writing Environment

An efficient and user-friendly working environment requires a program that integrates all necessary functions. With adoc Studio, you can write texts, organize them in projects, use a preview for initial checks, and export the finished documents either individually or as entire products.

adoc Studio offers extensive customization options. You can customize the appearance of the editor and choose an output style. We provide some styles and regularly release more on our website.

With adoc Studio, you can fully concentrate on the structure and content of your documents. You can emphasize important statements and make highlighted points. Additionally, the app supports the use of emojis 🙂

1.2. New Features in adoc Studio

In this document, you will occasionally find labels like v3 and v4 as indicators of new attributes, features, or macros. Below is an overview of the latest versions in reverse order.

adoc Studio 4 from [Date] February 2026

  • adoc Studio is now offered in a free version and a Pro version.

  • All subscribers of v3 automatically receive the Pro version.

The free version includes all the features needed to create documentation in HTML:

  • The program interface with the division into project management, editor, and preview.

  • Full integration of the adoc Coach to easily learn AsciiDoc.

  • The preview shows HTML and PDF.

  • Export is done in HTML.

In the paid version, the following new features are added with the update:

adoc Studio 3 from April 23, 2025

  • SF Symbols for icon macros

  • Pro Adjusting image resolutions & reducing file sizes

  • Pro Project dictionaries for your team

  • Pro Command-line tool for automation

  • Pro Apple Shortcuts for automation

  • Drag & drop functions

  • Sorting project files

  • Setting default styles

  • Integration into existing HTML pages

adoc Studio 2 from January 30, 2025

  • AsciiDoc callouts

  • Anchors on inline elements

  • Subtitles for HTML & PDF exports

  • Support for AsciiDoc bibliographies

  • Icon macros including syntax completion

  • New product styles: Manual & Light

adoc Studio 1 from June 12, 2024

  • First public version

1.3. What is a Markup Language?

Historically, the term markup originates from typography. In the art of printing, it referred to highlighting parts of text through different font variations such as

  • italic and bold typefaces,

  • small caps,

  • uppercase letters (ALL CAPS),

  • letter spacing,

  • underlining, or

  • coloring the text, as well as using different font sizes and styles.

It also included manually marking corresponding places in the manuscript (from [Wikipedia](https://de.wikipedia.org/wiki/Schriftauszeichnung) ). These techniques were adapted to the computer era and software, leading to the development of modern markup languages.

You may have heard of the language Markdown or the „phrase“ “the text is written in Markdown.” You’re on the right track. On one hand, plain text is presented, meaning letters without formatting. On the other hand, there are marks that highlight the text specifically: indicating what is a heading, what is bold, italic, or a link, and so on.

There are numerous markup languages that are not to be confused with word processing programs like Microsoft Word. The three best-known representatives of markup languages include:

  • HTML, the language of the internet, is very widespread but often considered cumbersome.

  • TeX or LaTeX, the popular typesetting system is rarely encountered in business and is considered difficult to learn.

  • Markdown is very easy to use but too simple, as it lacks many features needed for technical documentation. A detailed comparison of Markdown and AsciiDoc offers further insights.

Due to the disadvantages of the above languages, the decision was made to use AsciiDoc as the markup language. At ProjectWizards, all manuals and public documents have been created in this format since 2007.

AsciiDoc is a mature, lightweight, and semantic markup language mainly developed for creating technical documentation. It is ideally suited for all structured texts. The impressive number of over 10 million downloads (source: Asciidoctor History) assumes that help is always available. This recognition is owed to Asciidoctor, the first parser for AsciiDoc texts.

A parser is a program that analyzes text data, breaks it down into structured components, and checks it for syntactic correctness to enable further processing.

1.4. Considering Word, Pages, or Google Docs

When choosing between adoc Studio and a WYSIWYG word processing programs like Microsoft Word, Apple Pages, or Google Docs, several reasons come into play:

The abbreviation WYSIWYG has been widely used since the 90s and stands for "What you see is what you get" in its full form. This describes the output of documents being exactly as they appear on the screen. In other words: What you see is what you get.

  1. Separation of Content and Presentation: Text-based markup languages enable a clear separation of content and presentation. This ensures consistent formatting across various documents. And it makes it easier to uniformly adjust the appearance of documents. A document written in a markup language can be opened on any computer without special software.

  2. Portability: Text-based markup languages are universal and cross-platform. They can be opened and edited on any device and operating system. Word files can already look very different on different computers.

  3. Version Control: Markup languages are compatible with version control systems like Git, making it easier to collaborate and track changes in large documents. Although Word has introduced an XML format, many administrators are still reluctant to check these files into a Git repository.

  4. Reusability: A document created in a markup language can be converted into various formats, such as HTML for a website, PDF for printing, EPUB for e-books, etc. The results in Word are often very different.

  5. Adaptability: Text-based markup languages offer a very high level of adaptability. They allow for the customization of the appearance and behavior of documents in ways that are often not possible with standard word processing programs.

  6. Automation: Automated scripts and tools can be used to generate, process, and manipulate documents in text-based markup languages. This can save time and reduce errors in large documents.

  7. Stability and Longevity: Text-based markup languages are generally stable and durable, unlike proprietary file formats that can change over time.

1.5. Installation

You can download adoc Studio from the respective App Store for your Mac or your iPad or iPhone. If you are reading this text in adoc Studio now, it’s already done. Congratulations!

System Requirements

The minimum system requirements for adoc Studio are:

  • On the Mac: macOS 13 (Ventura)

  • On the iPad: iPadOS 16

  • On the iPhone: iOS 16

1.6. Trial Phase & Licensing

A subscription grants you access to both versions of adoc Studio, for the Mac and iOS, including iPad and iPhone. The trial starts upon the first launch of adoc Studio.

During the free 14-day trial, you have access to all features. After the trial period, you can choose between a monthly or annual subscription, with the annual subscription offering a price advantage. If you decide not to subscribe, you can still view adoc Studio projects, but editing within the app will no longer be possible.

All text files are saved in plain text format (UTF-8 encoded). This ensures your data security during the trial phase. If necessary, the files can be further edited in any editor, such as [BBEdit](https://www.barebones.com/products/bbedit/), and processed with other processors, like [Asciidoctor](https://asciidoctor.org). This is, however, intended only for the unlikely case that adoc Studio does not meet your expectations.