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
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.
Ship your documentation as fast as your product.
We provide tools and workflows that help teams coordinate documentation initiatives across products and departments.
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
The open internet is a great place to code, but sometimes you are sitting behind a great firewall in a corporate environment. Your are not allowed to just pull the hottest stuff from the internet, but have to go through an internal binary artifact repository like nexus or artifactory.
-- Ralf D. Müller, Groovy enthusiast, arc42 contributor, docToolchain maintainer
The primary goal of this project is to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation produced by Swagger. The result is intended to be an up-to-date, easy-to-read, on- and offline user guide, comparable to GitHub’s API documentation. The output of Swagger2Markup can be used as an alternative to swagger-ui and can be served as static content.
NOTE: The Swagger Specification has been donated to to the Open API Initiative (OAI) and has been renamed to the OpenAPI Specification.
Swagger2Markup converts a Swagger JSON or YAML file into several AsciiDoc or GitHub Flavored Markdown documents which can be combined with hand-written documentation. The Swagger source file can be located locally or remotely via HTTP. Swagger2Markup supports the Swagger 1.2 and 2.0 specification. Internally it uses the official swagger-parser and my markup-document-builder.
You can use Swagger2Markup to convert your contract-first Swagger YAML file into a human-readable format and combine it with hand-written documentation. As an alternative, you can choose the code-first approach and use Swagger2Markup together with Swagger JAX-RS, springfox or spring-restdocs. If you are Gradle or Maven user, you can also use the Swagger2Markup Gradle Plugin or Swagger2markup Maven Plugin.
AsciiDoc is preferable to Markdown as it has more features. AsciiDoc is a text document format for writing documentation, articles, books, ebooks, slideshows, web pages and blogs. AsciiDoc files can be converted to HTML, PDF and EPUB. AsciiDoc is much better suited for describing public APIs than JavaDoc or Annotations.
You can generate your HTML5, PDF and EPUB documentation via asciidoctorj or even better via the asciidoctor-gradle-plugin or asciidoctor-maven-plugin.
The project requires at least JDK 8.
PlantUML is a component that allows you to quickly write:
-
Sequence diagram
@startuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response Alice -> Bob: Another authentication Request Alice <-- Bob: Another authentication Response @enduml
-
Usecase diagram
-
Class diagram
-
Object diagram
-
Activity diagram (here is the legacy syntax)
-
Component diagram
-
Deployment diagram
-
State diagram
-
Timing diagram
GitHub - plantuml/plantuml: Generate diagrams from textual description
Official Javadoc Documentation: Overview (plantuml 1.2024.7beta2 API)
If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Pandoc can convert documents in markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, OPML, Emacs Org-Mode, Txt2Tags, Microsoft Word docx, EPUB, or Haddock markup to
HTML formats: XHTML, HTML5, and HTML slide shows using Slidy, reveal.js, Slideous, S5, or DZSlides.
Word processor formats: Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML
Ebooks: EPUB version 2 or 3, FictionBook2
Documentation formats: DocBook, GNU TexInfo, Groff man pages, Haddock markup
Page layout formats: InDesign ICML
Outline formats: OPML
TeX formats: LaTeX, ConTeXt, LaTeX Beamer slides
PDF via LaTeX
Lightweight markup formats: Markdown, reStructuredText, AsciiDoc, MediaWiki markup, DokuWiki markup, Emacs Org-Mode, Textile
Custom formats: custom writers can be written in lua.
A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more.
AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content. AsciiDoc content can be composed using a text editor, managed in a version control system, and published to multiple output formats.
Create awesome docs the easy way!
docToolchain is a collection of scripts that makes it easy to create and maintain powerful technical documentation. Built on best-of-breed open source technologies, we deliver the best docs toolchain so you don’t have to.
Eine großangelegte Umfrage zu Open Source zeigt, dass unvollständige oder verwirrende Dokumentation zu den Hauptproblemen freier Software zählt [1]. Das gilt neben Anwendungsdokumentation insbesondere auch für technische Dokumentation, etwa von Softwarearchitektur. Diese Aussage können wir sicherlich verallgemeinern: schlechte Dokumentation von Software erschwert Änderung, Support und letztlich auch Nutzung. Wir möchten hier auf technische Dokumentation von Software abzielen, also beispielsweise Entwicklungs-, Architektur- und Betriebsdokumentation. Das Thema Anwendungsdokumentation klammern wir bewusst aus.
Unserer Erfahrung nach behindern eine ganze Reihe von Faktoren die Erstellung und kontinuierliche Pflege technischer Dokumentation:
- Ungeeignete Werkzeuge, die ursprünglich nicht für die Erstellung und Pflege solcher Dokumentation gedacht waren.
- Geringe Motivation seitens der Entwicklungsteams, oftmals verstärkt durch die oben genannten Defizite der entsprechenden Werkzeuge.
- Unklare Vorstellung über Struktur, Form und Inhalt von Dokumentation: Entwicklungsteams haben keine klare Vorstellung davon, was und wie sie dokumentieren sollen.
- Schlechte Vorlagen ("Templates") für Dokumentation.
Der Verlag Open Source Press hat zum 31.12.2015 den Betrieb eingestellt und sämtliche Rechte an den veröffentlichten Texten an die Autoren zurückübertragen. Wir haben uns entschieden, den vollen Text des Buches sowie die AsciiDoc-Quellen unter einer CreativeCommons-Lizenz frei zugänglich zu machen. Alternativ zu der Online-HTML-Version gibt es eine PDF- und EPUB-Version.
Außerdem haben wir die Quellmaterialien der Foliensätze, die wir die vergangenen Jahre für firmeninterne Schulung benutzt haben, auch unter einer CC-Lizenz veröffentlicht. Zusammen mit dem Buch stellen sie eine umfassende Materialsammlung zum Erlernen und Lehren von Git dar.
Fragen, Kritik, Anmerkungen? – Wir freuen uns über E-Mails an kontakt@gitbu.ch!
The multi-repository documentation site generator for tech writers who love writing in AsciiDoc.
AsciiDoc is a lightweight markup language for authoring notes, articles, documentation, books, web pages, slide decks and man pages in plain text. This guide is a quick reference for the common AsciiDoc document and text formatting markup