The development of documentation is conducted using the following tools:
JSON
and YAML
in text form.SVG
format.For structuring text AsciiDoc
documents and creating a unified static HTML site, Antora is used, based on .yml playbook configurations.
Necessary tools for development:
AsciiDoc
syntax support.PlantUML
syntax.AsciiDoc
documents through a web browser.IntelliJ IDEA provides several ways for local viewing of technical documentation. Here's how you can utilize these options:
You can use the built-in toolbar above the documentation development window in an open AsciiDoc (.adoc
) file. Here, you will find options for real-time documentation preview mode:
Show Editor and Preview:
Show Preview Only:
You can also use the viewing options located in the top right corner of the development window:
Built-In Preview:
View in external browser:
π‘ TIP: You can also open the desired viewing option by pressing the key combination
Alt+F2
>Preview File in...
.
These IntelliJ IDEA features allow flexible work with technical documentation, providing various viewing options to meet the needs of developers and technical writers.
You can build the overall structure of the documentation using Antora in a local environment.
π NOTE: Complete installation instructions for Antora can be found at this link.
Check if Antora is installed:
antora -v
Install Node.
To check if Node is installed and its version, execute the following command:
node --version
Install Node on Linux using the command:
nvm install --lts
See detailed instructions at this link.
π‘ TIP: Linux users are invited to share their comments and supplement important information missing in this brief guide or the complete documentation.
Install Node on macOS using the command:
nvm install --lts
View detailed instructions at this link.
π‘ TIP: macOS users are invited to share their comments and supplement important information missing in this brief guide or the complete documentation.
For installing Node on Windows, follow these steps:
Install Chocolatey:
Execute the command:
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
Install nvm:
Execute the command:
choco install -y nvm
Install Node:
Execute the command:
nvm install 16.20.2
π IMPORTANT: Specify the exact version of Node for Windows (e.g.,
16.20.2
) if you encounter an issue nvm-windows#214.π NOTE: If Node is not installed after running the
nvm install
command, try installing Node through Chocolatey using the command:choco install nodejs-lts
or
choco install nodejs
π‘ TIP: Detailed instructions can be found at this link.
Windows users are invited to share their comments and supplement important information missing in this brief guide or the complete documentation.
npm
You can install Antora globally so that the antora
command is available on your PATH
. To install Antora globally, pass the -g
option to npm i
.
npm i -g @antora/cli@3.1 @antora/site-generator@3.1
Verify the antora command is available on your PATH
by running:
antora -v
If the installation was successful, the command should report the version of the Antora CLI and site generator.
antora -v
@antora/cli: 3.1.5
@antora/site-generator: 3.1.5
π‘ TIP: See also: Installing Antora Locally.
π NOTE: Complete instructions for accessing private repositories can be found at this link.
To grant Antora access to your source repositories, follow these steps:
Open a terminal and execute the command to configure Git:
git config --global credential.helper store && \
echo -n 'Repository URL: ' && read REPLY && \
git ls-remote -h $REPLY > /dev/null
π NOTE: For
'Repository URL: '
, enter the URL of the Git repository to which you need to grant access.
Repeat these steps for each repository from your Antora playbook. In our example, it's the site.yml file.)
Use personal access tokens to grant access to repositories:
In your GitLab account, open GitLab personal access token and create a token with read_repository
scope.
To grant access to repositories, use one of the following methods:
GIT_CREDENTIALS
environment variable:
Set the environment variable with the value of the personal access token. For example:
export GIT_CREDENTIALS='https://<FirstName_LastName>:<personalAccessToken>@gitlab.example.com'
Antora will use this token for all repositories in gitlab.example.com
.
.git_credentials
file. Add lines with the necessary repositories in the following format:
https://<personalAccessToken>:@gitlab.example.com/<repository_path>
# or
https://<FirstName_LastName>:<personalAccessToken>@gitlab.example.com/<repository_path>
# or use a single token for all repositories
https://<FirstName_LastName>:<personalAccessToken>gitlab.example.com/
Generate a static HTML site from the documentation using the command:
antora site.yml
Generate a static LOCAL HTML site from the documentation using the command:
antora site-local.yml
The generated site can be viewed locally through the default browser. The output of this site will be available at the path defined in your site.yml playbook:
output:
dir: ./output/ua
To automate the documentation generation step, you can set up a Shell Script run configuration in IntelliJ IDEA:
After setting up, IntelliJ IDEA will have an additional run configuration antora-site for generating technical documentation through Antora, which can be used for the quick launch of the process.