欢迎来到 Asciidoctor 文档站点! 在这里你可以找到用 AsciiDoc 编写并使用 Asciidoctor 发布的参考资料、指南、示例。 本文档将帮助您开始您的 AsciiDoc 之旅，或者在您已在的道路上继续深入研究。
AsciiDoc 语言文档主要是关于您为编写文档而输入的源代码。 当您写完并想发布您的 AsciiDoc 文档时，您会需要一个 AsciiDoc 处理器。 这就是 Asciidoctor 适合的场景。
Asciidoctor 是 AsciiDoc 的核心处理器。 It reads the AsciiDoc source, parses it into a document model, and converts it to a publishable format such as HTML using a converter. Asciidoctor has both a CLI and an API that you can use to invoke a built-in converter (HTML, DocBook, man page) or an add-on converter. Asciidoctor enriches the HTML it produces from AsciiDoc by applying a default stylesheet, adding stylistic icons, and syntax highlighting source blocks.
There are three variants of the core Asciidoctor processor that all share the same code base. With few exceptions, these variants all provide the full Asciidoctor experience. From these three implementations extend a host of extensions, build tool integrations, and tooling plugins in the Asciidoctor community and beyond. Choose the one that best suits the language platform you’re using.
- Asciidoctor Ruby
-
The original code base enables you to run Asciidoctor using any Ruby implementation, including C Ruby, JRuby, and TruffleRuby. JRuby and TruffleRuby allow you to use Asciidoctor on a JVM.
- Asciidoctor.js JavaScript
-
Transpiles Asciidoctor into JavaScript so you can run it in the browser or a Node.js application. It provides a CLI as well as a porcelain API for methods in the Asciidoctor document model and even enables you to write Asciidoctor extensions in JavaScript.
- AsciidoctorJ Java/JVM
-
A Java library that encapsulates the use of JRuby to load and run Asciidoctor on the JVM. It provides a CLI as well as native Java API wrappers for all of the Asciidoctor APIs and even enables you to write Asciidoctor extensions in Java.
- Build automation
-
Convert your content from AsciiDoc automatically when you run your build. Encapsulate assets, configuration profiles, and extensions for your publishing process in your build scripts. Even extract and convert AsciiDoc inside Javadoc comments or include snippets from your test suite.
-
Maven tools
-
Asciidoclet (for Javadoc)
-
- Extensions
-
Author HTML slide presentations in AsciiDoc without having to wrestle with the clutter of HTML or add diagrams to the output file that are generated from plain text markup inside your AsciiDoc document using extensions. The possiblities are boundless!
-
reveal.js converter
-
Diagram extension
-
- Site generation
-
Want to build a documentation site like this one? Write the content for the site in AsciiDoc. A static site generator delegates to an AsciiDoc processor to convert the AsciiDoc files to embedded HTML, then applies a template to that HTML to generate pages for the site.
- Essential reference
-
Keep this essential reference material for writing and publishing content with AsciiDoc and Asciidoctor close at hand.
-
AsciiDoc syntax quick reference
-
Document attributes
-
CLI reference
-
API reference
-
On any page, you can press kbd:[s] or kbd:[Ctrl,/] to focus the search box. Enter one or more terms (i.e., a query) to search the documentation. Alternately, you can press kbd:[Ctrl,<] to restore the previous search. As you type your query, the search results will be displayed in a panel immediately below the search box. You can browse the list of search results and navigate to a result using either the mouse or the keyboard.
To navigate to a result in the current tab using the mouse, hover over it with the mouse cursor and click on it using the left mouse button. If you want to keep the search results open while you’re looking for the best result, you can open the result in a new tab. To open a result in a new tab, either hold down kbd:[Ctrl] when you click the result, or right click on it and select "Open link in new tab". To clear the search, click anywhere outside of the panel of search results.
To navigate to a result using the keyboard, first use the up and down arrow keys to choose a result. This action will highlight the current result with a light blue selection box. You can then press kbd:[Enter] when the result is highlighted to navigate to that result in the current tab. To open a result in a new tab, press kbd:[Ctrl,Enter] instead. To clear the search, press kbd:[Esc].
The search will look for results using fuzzy matching.
That means it will locate pages with words or phrases that are close to what you entered, but not exactly.
This strategy helps bridge the gap between your terminology or phrasing with that used in the documentation.
If you want to look for an exact match, enclose the query in double quotes (e.g., "the details of the syntax").
You can also quote individual terms to disable the typo tolerance (e.g., "toc" position).
This strategy helps you to find exactly what you’re looking for with no false positives.
However, it will yield less results.
Another way to narrow the results is to prefix one or more terms with - (e.g., -document).
Adding this prefix will exclude results that contain that term.
By default, the search looks for results across the whole documentation site. If you want to limit the scope of the search to the documentation for the version of the project you’re currently looking at, tick the "In this project" checkbox. You can toggle this checkbox when the search results are open to compare the results for the whole site with those for the current project version.