Zum Import und Export gibt es zusätzlich beispielsweise Pandoc.
Aus MS Word ist der Asciidoc-Export vergleichsweise einfach
pandoc another.docx -f docx -t asciidoc --wrap=none --markdown-headings=atx --extract-media=images -o another.en.adocUm von Asciidoc nach Word zu exportieren legt man einen Docbook-Export als Zwischenschritt ein:
asciidoctor --backend docbook pdf.en.adoc --out-file pdf.en.docbook
pandoc --from docbook --to docx --output pdf.en.docx --highlight-style espresso .\pdf.en.docbookWie PDF-Themes kann man sich auch Word-Vorlagedateien konfigurieren, dann sähe ein Export in etwa so aus:
pandoc -o my-custom-styles.docx \
--print-default-data-file reference.docx
An extension for Asciidoctor.js to convert diagrams to images using Kroki!
When the Asciidoctor gem is installed successfully, the Asciidoctor command line interface (CLI) named asciidoctor will be available on your PATH.
AsciiDoc is a lightweight and semantic markup language primarily designed for writing technical documentation. The language can be used to produce a variety of presentation-rich output formats, all from content encoded in a concise, human-readable, plain text format.
The AsciiDoc syntax is intuitive because it builds on well-established, plain text conventions for marking up and structuring text. Someone unfamiliar with AsciiDoc can probably guess the purpose of many of its syntax elements just by looking at them. That’s because the elements of the syntax were carefully chosen to look like what they mean (a practice long employed by the tech industry).
The AsciiDoc language isn’t coupled to the output format it produces. An AsciiDoc processor can parse and comprehend an AsciiDoc source document and convert the parsed document structure into one or more output formats, such as HTML, PDF, EPUB3, man(ual) page, or DocBook. The ability to produce multiple output formats is one of the main advantages of AsciiDoc. This capability enables it to be used in static site generators, IDEs, git tools and services, CI/CD systems, and other software.
AsciiDoc bridges the gap between ease of writing and the rigorous requirements of technical authoring and publishing. AsciiDoc only requires a text editor to read or write, thereby offering a low bar to getting started.
Welcome to the Asciidoctor documentation site! Here you can find the reference material, guides, and examples to write content in AsciiDoc and publish it using Asciidoctor. This documentation will help you start your journey with AsciiDoc or dive deeper if you’re already well on your way.
Antora collects and processes content source files according to a set of hierarchical files and directories it expects to find at a content source root. This page introduces this hierarchy, the reserved directory and file names it employs, and the rules about which files get collected or ignored.
Antora employs both convention and configuration to aggregate content and generate your site. Before setting up or migrating your repositories, let’s review some key concepts that could impact how you organize your documentation projects and content files to work with Antora.
This plugin is designed to help to publish your Antora docs into Confluence. The main reason is, that we want to have a single source of truth for our documentation. We want to write our documentation in AsciiDoc and publish it to Confluence as some of our Stakeholders are using Confluence.
The captain offers the following options:
- Publish your whole Antora docs to Confluence
- Publish only selected pages/ folders, by using filters
- Control where the docs should be published by setting an
overall parent page in Confluence - Decide if you want to inform your readers that those pages are
- generated by automation by applying a banner.
In a previous article, we established that content is sovereign, which means the site generator needs to gather content from various repositories and branches. In order for the generator to identify, aggregate, and catalog content partitioned in this way, the repositories must present a consistent structure. Otherwise, the generator isn’t going to know which files represent pages or which pages should be grouped together.
Ship your documentation as fast as your product.
We provide tools and workflows that help teams coordinate documentation initiatives across products and departments.
The table below shows the full list of languages (and corresponding classes/aliases) supported by Highlight.js. Languages that list a Package below are 3rd party languages and are not bundled with the core library. You can find their repositories by following the links.
Note: The languages available will depend on how you’ve built or are included the library in your app. For example our default minified web build includes only ~40 popular languages. See Getting the Library and Importing the Library in the README for examples of how to load additional/specific languages.
This Docker image provides:
- Asciidoctor 2.0.23
- Asciidoctor Diagram 2.3.1 with ERD and Graphviz integration (supports plantuml and graphiz diagrams)
- Asciidoctor PDF 2.3.17
- Asciidoctor EPUB3 2.1.3
- Asciidoctor FB2 0.7.0
- Asciidoctor Mathematical 0.3.5
- Asciidoctor reveal.js 5.1.0
- AsciiMath
- Source highlighting using Rouge, CodeRay or Pygments
- Asciidoctor Confluence 0.0.2
- Asciidoctor Bibtex 0.9.0
- Asciidoctor Kroki 0.10.0
- Asciidoctor Reducer 1.0.2
This image uses Alpine Linux 3.20.1 as base image.
ubi8-asciidoctor
A utility image for the UBI8 image + asciidoctor.
Contains the primary used asciidoctor-pdf for generating reports.
It's base is from https://github.com/asciidoctor/docker-asciidoctor but now ubi based.
Purpose
Useful for environments where these libraries/tools are needed such as:
- local development
- CI tools that do not require specific CI tooling configuration, such as GiLab Jobs.
Published
https://quay.io/repository/redhat-cop/ubi8-asciidoctor via GitHub Workflows.
Links and discussion that helped me, docs and blogs
docToolchain is composed of two parts:
-
doctoolchain which is the toolchain used to create your documentation
-
the docToolchain shell wrapper script installed in your project which calls the toolchain
The use of this setup has the following advantages:
-
It’s easy to build your documentation within your project folder.
-
Ensures that everyone in the project uses the same docToolchain version.
-
Keeps all docToolchain technology out of your project repository.
-
Facilitates the installation of the docToolchain if not installed.
-
Makes it easier to upgrade to never versions of docToolchain.
Antora erstellt Dokumentations-Websites für Nutzer. Gemäß des Docs-as-Code-Ansatzes werden alle Inhalte in AsciiDoc-Dateien in Git-Repositories versioniert und über CI/CD publiziert.
Die Nutzer erhalten eine übersichtliche Darstellung der Dokumentation im Browser mit Navigationsleiste, Suche und Querverweisen. Sie können zwischen verschiedenen Versionen der Dokumentation hin- und herschalten, um die für sie passenden Informationen zu finden. Open-Source-Projekte wie Camel, Debezium und Couchbase nutzen diese Lösung bereits.
Entwickler und Autoren der Dokumentation bearbeiten die Inhalte wie gewohnt in ihrer IDE und versionieren die Inhalte in der Versionsverwaltung mit Git. Alle Änderungen durchlaufen die bestehenden Code-Review- und Build-Prozesse des Projekts.
Dieser Vortrag stellt die Grundlagen eines Antora-Setups vor und zeigt alle Schritte von einer Dokumentationsänderung in der IDE bis hin zur aktualisierten Dokumentations-Website mit Continuous Integration und Delivery.
- Antora - The multi-repository documentation site generator for tech writers who writing in AsciiDoc
- Antora - Documentation
There are times when you’ll want to publish your docs to Confluence, such as when you work in a team where not everyone wants to work with Git. docToolchain lets you publish your Git-based docs to Confluence alongside manually edited Confluence pages.
When you work in a restricted environment where you don’t have direct access to the internet, you might need a self-contained version of docToolchain. A version which does not need to download dependencies but already has them on board.