$ node --version
-
- GitHub
- GitLab
- Bitbucket
-
By logging in you accept
our terms of service
and privacy policy
The command line interface for Antora.
Homepage Repository npm Download
npm install @antora/cli@3.1.6
Antora is a modular, multi-repository site generator designed for creating documentation sites from content composed in AsciiDoc and processed with Asciidoctor.
Antora’s toolchain and workflow help documentation and engineering teams create, manage, collaborate on, remix, and publish documentation sites sourced from multiple versioned git repositories without needing expertise in web technologies, build automation, or system administration.
This project includes a command line interface (CLI) and a preassembled site generator pipeline so you can quickly start publishing documentation sites with Antora.
This section offers a basic tutorial for evaluating Antora. More comprehensive installation instructions are in the Antora documentation.
Antora is built on Node.js (“Node”) and is verified to work on Linux, macOS, and Windows.
To install Antora, you’ll need Node (including npm, which is bundled with Node) on your system.
You may also find the base build tools for your OS helpful (which includes git), though they’re not required.
You need Node installed on your machine to install and run Antora.
Antora follows Node’s release schedule, so we advise that you choose an active long-term support (LTS) release of Node. We recommend using Node 10. While you can use other versions of Node, Antora is only tested against active LTS releases.
To check whether you have Node installed, and which version, open a terminal and type:
$ node --version
If this command fails with an error, it means you don’t yet have Node installed. If the command doesn’t report an active Node LTS version (e.g., v10.15.0), you don’t have a suitable version of Node installed.
The best way to install Node is to use nvm (Node Version Manager). If your package manager provides Node and npm packages, and you’re familiar with using the tools installed system-wide, you may choose to go that route. However, we believe you’ll be more successful if you choose nvm.
|
Note
|
Most CI environments use nvm to manage the version of Node used in the build job. By using nvm, you align your local setup with the environment used to generate and publish your production site. |
If you’re using Linux or macOS, follow the nvm installation instructions to set up nvm on your machine.
If you’re using Windows, you can install the Windows port of nvm via the Chocolatey package manager using choco install -y nvm.
Alternatively, you can install the LTS release of Node directly using choco install -y nodejs-lts.
Once you’ve installed nvm, open a new terminal and install the latest Node LTS release using:
$ nvm install --lts
|
Important
|
If you’re using nvm for Windows, you must enter the full version of Node when running commands (e.g., nvm install 10.15.0, nvm use 10.15.0).
Run nvm list available to see a list of available Node versions.
|
To make Node 10 the default in new terminals (Linux and macOS only), type:
$ nvm alias default 10
Switch to this version of Node using the following command:
$ nvm use 10
Now that you have Node installed, you can proceed with installing Antora.
To generate a site with Antora, you need the Antora CLI and an Antora site generator pipeline.
Once these packages are installed, you use the antora command to generate your site.
We’ll begin by installing the Antora CLI using npm.
You should install this package globally so the antora command is always available on your PATH.
In your terminal, type:
$ npm install -g @antora/cli
|
Note
|
If you prefer Yarn over npm, you can choose to install Antora using yarn global add @antora/cli.
|
Verify the antora command is available on your PATH by running:
$ antora -v
If the installation worked, this command should complete successfully and report the version of the Antora CLI.
Next, install the default Antora site generator using npm (or Yarn):
$ npm install -g @antora/site-generator-default
You can opt to install the site generator inside the project containing your playbook file instead of installing it globally.
Now that the Antora CLI and default site generator are installed, you are ready to set up a playbook and generate a documentation site.
To generate a site with Antora, you need a playbook file that points to at least one content source repository and a UI bundle. Since the Antora repository is set up as an Antora documentation project, we can use that for now as your content source. Antora also provides a default UI for you to use out of the box.
First, create a new directory for your site and switch to it. Next, add a playbook file named antora-playbook.yml and populate it with the following contents:
site:
title: Antora Docs
content:
sources:
- url: https://gitlab.com/antora/antora.git
branches: master
start_path: docs
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: trueNotice we’re looking for a documentation component under the docs/ subdirectory of the master branch of the Antora git repository. We’re also using Antora’s default UI as the UI for the site. Antora will take care of assembling all this input together to produce a documentation site.
The UI bundle can be loaded from a URI or a local filesystem path. If you want to use your own UI bundle, follow the instructions in the README for the Default UI.
To generate the site, simply point the antora command at your playbook file.
In your terminal, type:
$ antora antora-playbook.yml
Antora will clone the content repository, convert the AsciiDoc pages to embeddable HTML, wrap the HTML in a page template from the UI, then assemble the pages together along with the assets into the destination folder, which defaults to build/site.
To view your site, navigate to any HTML page inside the destination folder in your browser. Using this example, look for the entry point file build/site/index.html. That file will redirect you to the start page.
If something goes wrong during generation, you’ll see an error message in the terminal.
If this message does not provide enough information to fix the problem, you can ask Antora for more context.
To tell Antora to reveal the calls leading up to the error (i.e., the stacktrace), run the antora command again, this time with the --stacktrace option:
$ antora --stacktrace antora-playbook.yml
Share this stacktrace when asking for help.
If any of your content repositories require authentication, Antora will look up the credentials in the default git credential store file or one that you specify using the --git-credentials-path CLI option.
See the private repository authentication documentation to learn more.
Antora also supports local content, which is essential for authoring. If you want to make modifications to the documentation, you’ll first need to clone the content repository (which in this example just happens to be the Antora repository):
$ git clone https://gitlab.com/antora/antora.git workspace/antora
Next, update the content source entry in the playbook to point to the local checkout instead of the remote URL:
content:
sources:
- url: ./workspace/antora
branches: master
start_path: docsNow, any changes you make to the content under the workspace/antora/docs/ folder will be visible the next time you generate the site.
A site generated by Antora is designed to be viewable with or without a web server. However, you may need to view your site through a web server to test certain features, such as indexified URLs or caching. You can use the serve package for this purpose.
Install the serve package globally using npm:
$ npm i -g serve@6.5.8
That puts a command by the same name on your PATH. Now launch the web server by pointing it at the location of the generated site:
$ serve build/site
Paste the provided URL into the location bar of your browser and you’ll be viewing your site through a local web server.
Antora is designed to help you easily write and publish your documentation. However, we can’t fully realize this goal without your feedback! We encourage you to report issues, ask questions, share ideas, or discuss other aspects of this project using the communication tools provided below.
Activity drives progress! To that end, the issue tracker is king.
The preferred means of communicating problems, ideas, and other feedback is through the project issue tracker.
Issue tracker (GitLab)
Any significant change or decision about the project must be logged there.
If you need to switch to real time input, you may be interested in visiting one of the chat rooms. We’ve set up two chat rooms for discussing Antora. Choose the one that best suits your needs.
antora/users (Gitter) — Community support for Antora users.
antora/dev (Gitter) — Discussions involving the development of Antora.
Keep in mind that the discussion logs for these rooms are archived, but there is no guarantee those logs will be saved indefinitely.
If you want to share your experience with Antora or help promote it, we encourage you to post about it on social media. When you talk about Antora on Twitter, you can mention the official account for the project:
@antoraproject (Twitter) — The official Antora account on Twitter.
You can also use the #antora hashtag to help promote the project or discover other people talking about it.
If you decide you want to get involved to help improve the project, then you’ll be interested in the information provided in the Contributing section.
If you are interested in contributing to this project, please refer to the contributing guide. In this guide, you’ll learn how to:
Thanks in advance for helping to make this project a success!
The Antora core components include a default site generator package, the packages the default site generator delegates to, and a CLI package. These packages are released together and follow semantic versioning rules (major.minor.patch). Major versions are maintained for at least 1 year after the initial public stable release. Only the latest minor release will receive patch releases.
The project roadmap provides the current development direction and schedule for Antora.
Copyright © 2017-2018 by OpenDevise Inc. and the individual contributors to Antora.
Use of this software is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0). See LICENSE to find the full license text.
Development of Antora is led and sponsored by OpenDevise.
The Tidelift Subscription provides access to a continuously curated stream of human-researched and maintainer-verified data on open source packages and their licenses, releases, vulnerabilities, and development practices.
Learn more →Something wrong with this page? Make a suggestion
Export .ABOUT file for this package
Last synced: 2024-01-02 23:49:10 UTC
Login to resync this project