adoc Studio | Working with adoc Studio

2.1. The User Interface

After launching adoc Studio, you see the view shown below. It displays the User Manual created with adoc Studio, which opens via Help User Manual.

The adoc Studio window is divided into three areas:

Sidebar with:
1. Project Navigator for all files and directories (keyboard shortcut: ⌘+1)
2. Section Navigator for the table of contents (keyboard shortcut: ⌘+2)
3. Search Navigator for searching across all files (keyboard shortcut: ⌘+3)
4. Issue Navigator for all warnings and error messages (keyboard shortcut: ⌘+4)
Text editor
Preview

At the top of the window is the toolbar with these functions:

Show/hide sidebar (keyboard shortcut: ⌘+0)
Create a new component (keyboard shortcut: ⇧+⌘+N)
Back and forward navigation buttons (keyboard shortcut: ⌃⌘< and ⌃⌘>)
Directory tree as a popup menu
Export the current file
Content structure as a popup menu
Optional: list of all products
Show/hide editor (with or keyboard shortcut: ⇧+⌘+E)
Show/hide preview (with or keyboard shortcut: ⇧+⌘+E) including settings

Each area can be shown or hidden individually to adapt the layout to different screen sizes. The corresponding functions are in the menus View, Editor, and Preview.

2.2. The Project Navigator

In adoc Studio, you work in a project-oriented way. A project contains the content and, if needed, associated images and other media. As the scope grows, however, maintaining an overview becomes more difficult. To improve organization, divide extensive content into smaller, thematically distinct documents. Manage these documents together with the required media within a single project.

A document refers to the content itself: the AsciiDoc text with its structure and semantic meaning. A file is the technical representation of that document on the file system. In adoc Studio, a document is stored in one or more files and can be exported to various output formats.

In adoc Studio, a document usually refers to a single file within the project. That file resides on a storage medium (such as a hard drive, SSD, or cloud) and contains the AsciiDoc text.

A document can also contain additional content, such as terms for dictionaries, AI prompts, or other project-specific data.

The file extension determines the type of document:

The primary extension .adoc identifies an AsciiDoc file.
Other supported file extensions are described in the relevant sections.

The Project Navigator displays all documents in the project in a structured, clear layout.

Creating a New Project

Create a new project with the menu bar command File New Project.

Two items appear initially in the sidebar:

A folder for media.
The file Document.adoc as the first document in the project.

Control whether the .adoc file extension is displayed in adoc Studio Settings. Open Settings also with the keyboard shortcut ⌘+,.

Sort files and folders in the Project Navigator as needed. You can nest items at any depth.

Adjust the sort order for a project entry or individual folder in the information dialog. Right-click a project entry or folder and choose Information from the context menu.

Store media and images in media folders whenever possible, even though you can place them anywhere in the project. Create additional folders as needed.

In the next step, write text into an existing document.

Using Standalone Documents

Add further documents to your project via File New, the keyboard shortcut ⌘+N, or the in the sidebar.

Each document is a self-contained unit stored in its own file.

To edit a document:

Click the document in the Project Navigator.
The editor opens the file for editing.
The preview immediately shows the content in the selected layout.

Selecting a different document opens it in the editor.

The contents of Another_Document.adoc are not automatically included in Document.adoc, and vice versa. AsciiDoc provides ways to include content from other files, for example via the include macro.

Using Composite Documents

Composite documents, unlike standalone documents, automatically combine multiple files into a single overall document.

A composite document appears in the project as a special folder with the icon. On the file system, it corresponds to a directory that contains all the included files.

Within a composite document, you can use additional folders for structuring, nested to any depth.

Click a composite document in the Project Navigator and the preview displays the complete document including all included files.

Select a folder within the composite document and the preview shows all chapters it contains as a continuous document.

In both cases, the editor remains empty because the preview uses multiple files to display the document or partial document. Click a file in the Project Navigator to edit it.

Right-click a passage in the Project Navigator and choose Show Source to open the corresponding file in the editor.

New files in composite documents are created as Chapter.adoc by default and can be renamed at any time.

Using Folders for Structure

Use folders to maintain an overview even with many files. The filter at the bottom of the Project Navigator also helps you find files quickly. Organize your projects in adoc Studio using folders the same way you do in the operating system.

If you use a folder in a standalone document and select it, both the editor and the preview show nothing.
In a composite document, the preview shows all files in the selected folder.

Using Media Folders

You can place media such as images anywhere in a project: at the top level or in any subfolder. To use them in a document, provide an absolute or relative file path.

It is easier, however, to place images in a dedicated media folder. Then you only need to specify the image filename instead of the full path.

A project may contain multiple media folders. adoc Studio searches the project for media in a defined order.

Search Order for Images

The line image::photo.jpg[] instructs adoc Studio to search for the image in the following order:

adoc Studio first looks for photo.jpg in the same directory as the .adoc file.
If not found, the app searches the parent media folder.
If the image is not there either, adoc Studio checks the media folder one level higher.
This process repeats until the app reaches the root directory of the project.
If adoc Studio still cannot find the file, the editor highlights the filename in red and adds an entry to the Issue Navigator in the sidebar.

Example of an error message in the project

Images with Path Specifications

The line image::/photo.jpg[] searches for the image in the project directory where the .adocproject file is located.
The line image::/Folder/photo.jpg[] searches in the subdirectory "Folder", relative to the project directory.
The line image::../photo.jpg[] searches one level above the text file that references it.

All paths follow the same conventions as in the operating system. A path starting with / is relative to the project root directory, the folder containing your .adocproject file.

For AsciiDoc advanced users:

In adoc Studio, you can also use the imagesdir attribute. If you define a path with :imagesdir:, adoc Studio treats that value as a prefix before every image reference in the document. Further details and specific use cases are available on the AsciiDoc website.

For referencing projects, additional rules apply. Details are described in that section.

Adding a New Component

To add a new component to your project, click in the toolbar or use the keyboard shortcut ⇧+⌘+N.

The dialog adapts automatically to the current selection in the file list:

If you select a standalone document, you can create another standalone document or a composite document.
If you select a composite document or a chapter, you can add new chapters.

Regardless of the selection, you can also add new folders, media folders, or existing files.

Alternatively, drag files directly from Finder into the file list to add them to the project.

Adding Existing Files

Double-click in Finder

Open a .adoc file in Finder with a double-click in adoc Studio, provided no other application has taken over the .adoc extension. adoc Studio then shows a dialog. Select the target project or create a new one. The file is copied into the selected project without being moved from its original location.

Drag and drop from Finder

Alternatively, drag a file from Finder to the desired position in adoc Studio.

If you drop the file onto a composite document, adoc Studio automatically adds it as a chapter of that composite document.

Copy or move files in Finder

You can also copy or move files directly into the project directory in Finder.

adoc Studio automatically detects new or changed files and displays them in the project file list after a short time.

Menu bar function

You can also add files to a project via the menu bar.

Choose File New Add Files… or use the keyboard shortcut ⌥+⌘+A.

adoc Studio inserts the selected file(s) below the current selection in the file list. You can then drag them to the desired position with the mouse.

If you drag a file into a composite document, adoc Studio automatically adds it as a chapter of that composite document.

File Information

If a file is part of a composite document but should not appear in the preview or export, you can disable its inclusion:

Right-click the file in the file directory to open the context menu.

Choose Information … and adoc Studio opens the dialog shown on the right.

Deactivate the "Part of the composite document" option to remove the file from inclusion.

This lets you, for example, create to-do lists that never become part of your document.

Further information

Most files and all folders in the sidebar can be edited via the Information … menu. In addition to renaming files or folders, further options are available there.

These settings affect only the work within adoc Studio. In macOS Finder (as well as in other operating systems), all items continue to appear as regular files and folders.

2.3. Saving a Project

Save your project to any location via File Save… or the keyboard shortcut ⌘+S.

Save adoc Studio files on your device, a server, or in the cloud.

Alternatively, use a version control system such as Git or GitHub.

If you close the last project window without saving, adoc Studio reminds you.

adoc Studio automatically saves .adoc files at short intervals. Trigger a manual save at any time with the keyboard shortcut ⌘+S.

2.4. Additional Windows for a Project

Open a project in multiple windows via Window New Window. This is especially useful when working with multiple monitors. Organize preview, translation, and revision of a document in separate windows for more efficient work.

On Mac, hold ⌘ and click the window title to open a menu showing the path of the current project in Finder.

2.5. Referencing Projects

Referencing projects differ from standard projects, in which all files are managed within their own folder.

Standard adoc Studio projects reside in a project folder that contains the project file as well as all documents, folders, and media.

With adoc Studio, you can also create referencing projects. These reference existing files directly from their current location on the file system, without copying them into the project folder.

Create a referencing project via File New Referencing Project with the ⌥ key held down.

adoc Studio opens an empty project window.
Save the project as an .adocproject file in any location.
Drag files or folders from any location into the Project Navigator.
adoc Studio creates a reference to the original files in the project.
Edit the .adoc documents as usual; changes are saved directly in the original source folder.

2.6. The Section Navigator

The second tab in the sidebar displays the heading structure as an outline.

For composite documents, the Section Navigator shows the complete table of contents, regardless of which chapter you are currently working in. For individual documents, the navigator shows only the table of contents for that document.

To output a table of contents in the text in the preview or export, use the attribute :toc:, described here.

2.7. The Search Navigator

The tab with the magnifying glass is the Search Navigator. Use it to search for text across the entire project.

Open the context menu behind the magnifying glass to enable the replace function.

You can also configure the following settings:

Ignore case.
Ignore accents and umlauts.
In multilingual projects, restrict the search to specific languages.

This menu also lets you enable regular expressions for searching.

After a search, adoc Studio groups results by file. Click a file to open it in the editor and jump directly to the desired position.

Features

Replace found text with the practical options in adoc Studio:

Select individual results in the list (multiple selection with ⇧ held) and apply replacements only at those positions.
Select a file in the results list to apply replacements only in that file.

2.8. The Issue Navigator

The Issue Navigator detects AsciiDoc issues in the text. It does not check for grammatical or spelling errors; it identifies problems with AsciiDoc commands.

When an error occurs, adoc Studio displays the error list icon in red errorlist . Minor issues are shown as warnings in yellow.

The list is sorted by order of occurrence. Click a message to open the editor directly at the corresponding location so you can fix the error.

2.9. Writing and Navigating in the Text

Select a text file from the file list. If the insertion point is not yet blinking in the editor window, click in the middle area of the window or press ⌃+TAB.

adoc Studio is then ready to accept your text. For information about AsciiDoc, see the next chapter.

The text you enter appears immediately in the preview. For longer texts, adoc Studio automatically synchronizes the position of both windows so that the section you are writing is visible at the same height in the preview.

The vertical position of the insertion point stays synchronized with the scroll position of the preview.

Switching to the PDF preview can take more time for longer texts. Use the HTML preview instead, as it updates faster.

Customize the editor to your personal preferences, such as color settings or font size. The Editor Styles tab in Application Settings offers many design options.

Additional Navigation

Above the editor is the additional navigation bar.

It starts with the navigation arrows left and right , which work similarly to a web browser. Use them to navigate forward and backward between recently edited files.

Next to the arrows is a graphical block that shows the current file and its structure.

Reading from left to right, you can see which file you are working in.

At the far right is a small table of contents that shows the overall context of the file and its structure. Structure entries shown in gray come from other files within a composite document.

Line Numbers

A single line number appears on the right edge of the editor for orientation. For most purposes, this is sufficient for communicating about line numbers. To display all line numbers, adjust the setting in Settings.

Click a line number or use the keyboard shortcut ⌘+L to jump directly to a specific line.

Texts are also saved immediately

adoc Studio saves changes to texts immediately, just like project files. Your data is protected from loss at all times.

Insertion Point

While writing, use the keyboard to move the insertion point without taking your hands off the keyboard. adoc Studio includes all important keyboard shortcuts for text editing.

Table 1. Modifier Keys Used
`⌘`	Command key
`⌥`	Option key
`⌃`	Control key
`⇧`	Shift key
`⌤`	Enter key
`⏎`	Return key
`⌫`	Backspace key
`⌦`	Delete key (extended keyboard)

Table 2. Moving in the Document
`←`	Move one character to the left
`→`	Move one character to the right
`↑`	Move one line up
`↓`	Move one line down
`⌥`+`←`	Move one word to the left
`⌥`+`→`	Move one word to the right
`⌘`+`←`	Move to the beginning of the line
`⌘`+`→`	Move to the end of the line
`⌘`+`↑`	Move to the beginning of the document
`⌘`+`↓`	Move to the end of the document

Table 3. Selecting in the Document
`⇧`+`←`	Extend selection to the left
`⇧`+`→`	Extend selection to the right
`⇧`+`↑`	Extend selection upwards
`⇧`+`↓`	Extend selection downwards
`⇧`+`⌥`+`←`	Extend selection one word to the left
`⇧`+`⌥`+`→`	Extend selection one word to the right
`⇧`+`⌘`+`↑`	Extend selection to the beginning of the document
`⇧`+`⌘`+`↓`	Extend selection to the end of the document
`⌃`+`↑`	Move line with insertion point or selection up
`⌃`+`↓`	Move line with insertion point or selection down

Table 4. Deleting in the Document
`⌘`+`⌫`	Delete current line to the left of the cursor
`⌥`+`⌫`	Delete word to the left of the cursor
`⌥`+`⌦`	Delete word to the right of the cursor

Table 5. Alternative Keyboard Shortcuts
`⌃`+`a`	Move to the beginning of the line
`⌃`+`b`	Move one character to the left
`⌃`+`d`	Delete the character to the right of the cursor
`⌃`+`e`	Move to the end of the line
`⌃`+`f`	Move one character to the right
`⌃`+`h`	Delete the character to the left of the cursor
`⌃`+`k`	Delete the rest of the line from the cursor
`⌃`+`n`	Move one line down
`⌃`+`o`	Insert a new line after the insertion point
`⌃`+`p`	Move one line up
`⌃`+`t`	Swap character at insertion point or within a selection
`⌃`+`v`	Move one page down
`⌃`+`y`	Re-insert text previously deleted with `⌃`+`k`

Another keyboard shortcut you will use often in adoc Studio is the ESC key. It opens the comprehensive set of input assistance features.

Table 6. Mouse Actions in the Document
Click and drag: select text character by character
Double-click and drag: select text word by word
Triple-click and drag: select text paragraph by paragraph

2.10. Input Assistance: adoc Coach

AsciiDoc has a very large feature set. Even experienced users can occasionally forget individual commands or macros. For this reason, adoc Studio provides intelligent input assistance.

While you write, adoc Studio continuously looks for opportunities to help. Often, a menu with completion suggestions appears after the second or third character. adoc Studio takes care not to interrupt your writing flow. Suggestions are shown only when you pause briefly. Open the input assistance menu with the ESC key whenever you need it.

Example: Embedding an Image

Start at the beginning of a line by typing pho or ima.
A short menu appears:
Navigate the list with ↓ or ↑.
Select the desired entry with ⏎.
After selecting, another menu appears:

Images are displayed directly as small previews.
Select the appropriate image and confirm again with ⏎. The image appears at full width in the preview.
Place the insertion point between the square brackets after the image name ([]) to enter image options.
First enter the image width by typing wi. A menu shows all available options that contain wi.
Navigate with the arrow keys to width= and press ⏎.
You now see:
Overwrite the placeholder text with a number (for example 200) to see the image scaling in the preview immediately.
Place the insertion point again between the square brackets after the image name ([]). It does not matter whether you insert the option before or after width. All options must be separated by a comma.
Press ESC to open the completion menu with the remaining image options.
To place the image to the right of text, use the float option. Type flo and the completion menu shows all options containing flo:
Select float=right.

Done. You have inserted an image, scaled it, and positioned it to the right of the text.

The source text looks like this:

image::adocstudio.png[width=200, float=right]

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate, velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Figure 1. The result in the preview:

adoc Coach is available for every AsciiDoc command and attribute. If you are unsure, press ESC to see all macros available at the current position.

2.11. Spell Checking

On macOS, spell checking is enabled by default in many applications. This also applies to adoc Studio. Misspelled words are immediately visible through a red underline.

You can use spell checking automatically in the background or start it manually. Choose Edit Spelling and Grammar Check Document Now or use the keyboard shortcut ⌘+Ü. adoc Studio then jumps directly to the next detected error. Right-click a marked word to see suggested corrections and accept the desired spelling with one click.

You can also add a word that appears incorrectly spelled to the system-wide dictionary. It then becomes available in all apps on your Mac.

In technical or specialized documentation, you often use terms that do not belong in the system-wide dictionary. adoc Studio provides project-specific dictionaries for this purpose.

These are saved directly in the project as .adict files. They are alphabetically sorted text files that you can edit manually if needed.

Create as many custom dictionaries as you need in each project. Manage them directly in the text via the context menu by right-clicking.

2.12. Translating Documents

Publish documents in multiple languages. The Pro version of adoc Studio supports you with translation and language management.

Preparation

First, define the languages required for the project.

Open File Project Settings… (⌘+;), or right-click a file in the Project Navigator and choose Add Language Document Languages….

In the dialog, add the desired document languages with .

Usage

Assign a language to a file by choosing Add Language a language in the context menu.

The Project Navigator then shows the language version as a sub-entry in the file tree. Expand the arrow to display the assigned language. Add further languages via Add Language another language. The context menu only offers languages that are defined in the project and not yet assigned to the file.

You can also select languages directly in the toolbar.

The toolbar shows from left to right:

Project and folder structure (e.g., Manual and Publish)
Active file in the editor (e.g., products)
Active language (e.g., English)
Current insertion point position in the document (e.g., Products)

Technical Background

When you assign the first language to a file, adoc Studio transfers the existing content into that language version. Choose the source language of your document as the first language. Additional languages are added as empty language versions.

In Finder, all language versions receive an extended naming convention. adoc Studio adds a language code before the file extension:

Manual.adoc — original document
- Manual.de.adoc — German version
- Manual.en.adoc — English version

In adoc Studio, language versions are always displayed as a file tree.

Language assignment applies to all project content, not just .adoc files. Use different media for each language as appropriate.

If no translation exists, adoc Studio uses the available file for all languages.

adoc Studio uses standardized locale codes. Mark regional variants with a hyphen, for example en-HK. All language codes appear in the list of document languages.

Output

For exports and products, select the language in which adoc Studio should generate the output.

Practical Translation Workflow

Complete the translation in three steps:

Start File Export For Translation….
In the dialog, select the languages to hand off to a translator or agency.
Import the completed translations via File Import Translation….

Involve your translation team directly. Since version 4, the Community version already supports two languages.

2.13. Writing Tools with Artificial Intelligence

Artificial intelligence produces varying results. Review and evaluate all content carefully. Do not rely on AI results without verification. adoc Studio has no influence over the results generated.

In the editor context menu, the Pro version of adoc Studio provides integrated AI functions.

The functions use one of the following providers:

ChatGPT by OpenAI
Claude by Anthropic
Gemini by Google

Apple Intelligence writing tools are not used.

Context for the AI

The context of a project is not always apparent to an AI. Often, special information and instructions need to be provided that the individual functions then take into account.

Create a context file via File New Component…. In the dialog, select the last entry AI Writing Tools Context. This creates a text file with the extension .adocai in the project. In this file, store all information you want to pass to the AI as a basis for the AI functions.

AI Functions

Select your preferred provider and model in adoc Studio Settings…. Enter the required API key once. If it is missing, adoc Studio requests it automatically on first use.

The following tools are then available:

Friendly

The AI rewrites your selected text in a positive, approachable tone.

Objective

The AI renders your text clearly, neutrally, and professionally.

Concise

The AI gets your text to the point and removes unnecessary content.

Proofread

The AI checks selected text for errors and marks detected issues in blue. Accept or reject suggestions via the context menu, as with spell checking.

Table

The AI structures suitable content automatically as a table.

List

The AI converts suitable content into a clear list.

Key Points

The AI reduces longer texts to their central statements.

Summary

The AI creates a short and understandable summary.

Translate

The AI translates your selected text into the languages you have set for the project under Languages. These target languages are available for selection directly in the context menu.

Custom Prompt

Submit a custom request to the AI via the input field. Then specify how adoc Studio uses the result:

replace the selected passage,
insert it after the selection,
copy it to the clipboard,
highlight differences, or
create a new file.

While the AI processes your request and inserts text, adoc Studio temporarily locks the current file for manual input.

2.14. Application Settings

Use Settings to adapt adoc Studio to your workflow.

General

Open Settings via adoc Studio Settings… or the keyboard shortcut ⌘+,.

Configure core editor functions in the General tab.

Line Numbers: Choose whether the editor displays all line numbers or only the current line.
Section Folding: Show or hide the triangles for collapsing and expanding sections.
Show File Extensions: Choose whether the Project Navigator displays all file extensions. If the option is disabled, only the selected file shows its extension.

Line Width: Set the maximum number of characters per line. If the editor window is narrower, adoc Studio wraps the line automatically.
Section Indentation: Set the left offset for headings. Choose a value between 0 and 6. Body text remains left-aligned; the = characters extend correspondingly to the left.
Tab Width: Set how many characters a tab spans (1 to 100). Values between 3 and 5 have proven effective.

Indent With: Choose whether adoc Studio uses tabs or spaces for indentation.

File Access

macOS and iOS protect files through the sandbox principle. Each app operates in its own isolated area.

If adoc Studio needs to access project files outside this sandbox, it requires your permission.

All approved folders appear in the list on this tab. Manage entries with + and -.

When you open a new project, adoc Studio automatically requests the required permission.

Grant access to a parent folder to avoid repeated permission requests.

Editor Styles

Configure the appearance of the editor here.

Select a style on the left.
Many styles support light mode ○ and dark mode ●.
In the middle list, adjust font, size, and other attributes. Start with "General".

If your system switches automatically between light and dark mode, adoc Studio remembers the last selected style for each mode.

Product Styles

Open adoc Studio Settings… or use ⌘+, and switch to the Product Styles tab.

In adoc Studio, content and design are separate. Design is applied through product styles based on CSS. Use them to style HTML, PDF files, and websites.

Left: list of all available styles.
Right: preview of the selected style.
Below: selection of example content (left) and output format (right).

Installing Custom Product Styles

Product styles use the extension .adocstyle. Install a style by:

Double-clicking it in Finder.
Dragging the file into the style list.
Clicking + below the list.

Installed product styles are not automatically part of a project. When moving to a new computer, also transfer the style files you use.

Setting a Product Style as Default

Right-click a style and select it as the default.

adoc Studio uses this style automatically for:

New projects (set as default).
Exports.
New products.

Removing Product Styles

Right-click a style and choose Delete.

Creating Custom Product Styles

To create or edit a custom product style, you need CSS knowledge.

Create a new style based on an existing one:

Select the product style to use as a basis.
Open the context menu via or by right-clicking the style and choose Duplicate.
adoc Studio creates the new style as a separate entry at the top of the list.
Double-click the name of the new style to rename it.

Editing a Style

Edit a product style with a text editor.

Suitable text editors include Apple TextEdit in "Plain Text" mode or BBEdit. Any editor that saves CSS content in Unicode format (UTF-8) works.

Proceed as follows:

Select the desired product style.
Open the context menu via or right-click and choose Edit in.
Select your preferred editor.
adoc Studio opens the product style in the chosen application.
Make the desired adjustments (see details).

Keep adoc Studio open and activate the edited style in the preview. Your changes in the external editor are immediately applied and saved.

2. adoc Studio

2.1. The User Interface

2.2. The Project Navigator

Creating a New Project

Using Standalone Documents

Using Composite Documents

Using Folders for Structure

Using Media Folders

Adding a New Component

Adding Existing Files

File Information

2.3. Saving a Project

2.4. Additional Windows for a Project

2.5. Referencing Projects

2.6. The Section Navigator

2.7. The Search Navigator

Features

2.8. The Issue Navigator

2.9. Writing and Navigating in the Text

Additional Navigation

Line Numbers

Insertion Point

2.10. Input Assistance: adoc Coach

Example: Embedding an Image

2.11. Spell Checking

2.12. Translating Documents

Preparation

Usage

Technical Background

Output

Practical Translation Workflow

2.13. Writing Tools with Artificial Intelligence

Context for the AI

AI Functions

2.14. Application Settings

General

File Access

Editor Styles

Product Styles

Installing Custom Product Styles

Setting a Product Style as Default

Removing Product Styles

Creating Custom Product Styles

Editing a Style