blob: 9dc84f52d21a9537bdb943eaac43f32b4621d2e3 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
|
= Process AsciiDoc Using the CLI
////
command-line-usage.adoc
Command line usage quick start for Asciidoctor
included in the install-toolchain and user-manual documents
////
When the Asciidoctor gem is installed successfully, the Asciidoctor command line interface (CLI) named `asciidoctor` will be available on your PATH.
== Version and runtime
To confirm that the CLI is available, execute the following command in your terminal application:
$ asciidoctor --version
If this command completes successfully, information about Asciidoctor and the runtime environment will be printed to the standard output of your terminal:
[subs=attributes+]
Asciidoctor {release-version} [https://asciidoctor.org]
Runtime Environment ({ruby-description}) (lc:UTF-8 fs:UTF-8 in:UTF-8 ex:UTF-8)
The runtime environment information varies based on the version of Ruby you're using and the encoding settings of your operating system.
== Convert an AsciiDoc file
To invoke Asciidoctor from the CLI and convert an `.adoc` file, execute:
$ asciidoctor <asciidoc-file>
This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the `.html` extension.
xref:man1/asciidoctor.adoc#options[CLI Options] describes the available options and parameters for the Asciidoctor CLI.
== Help topics
The `--help` option provides self-describing documentation for the `asciidoctor` command, grouped by topic.
If you don't specify a topic, the `--help` option prints the usage statement for the `asciidoctor` command:
$ asciidoctor --help
You can generate the full documentation (i.e., man page) for the `asciidoctor` command by passing the `manpage` topic to the `--help` option.
You can pipe that output to the `man` pager to view it:
$ asciidoctor --help manpage | man -l -
You can also find the man page for the `asciidoctor` command rendered as HTML in this documentation, which you can view in a browser instead.
See xref:man1/asciidoctor.adoc[asciidoctor(1)].
You can print an AsciiDoc syntax crib sheet by passing the `syntax` topic to the `--help` option.
$ asciidoctor --help syntax
The crib sheet itself is composed in AsciiDoc.
You can convert it to HTML by piping the output back into the `asciidoctor` command.
$ asciidoctor --help syntax | asciidoctor -o syntax.html -
Navigate to the [.path]_syntax.html_ file in your browser to see what the examples in the crib sheet look like when converted to HTML.
|
