Stack Overflow
Stack Overflow

Questions tagged [asciidoc]

AsciiDoc is a lightweight markup format similar to Markdown, but it was designed for technical writing with programmatic capabilities as well as semantic structure.

AsciiDoc is a document format for writing technical articles, books, ebooks, slideshows, web pages, man pages, and blogs. AsciiDoc files can be rendered in many formats including HTML, PDF, EPUB, and man page.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (handled by templates) can be customized and extended by the user. The format is very similar to the popular Markdown markup, but AsciiDoc additionally incorporates programmatic capabilities and semantic structure. Functionality such as variable substitution, conditional flow, and file inclusion make AsciiDoc dynamic, more like coding. Semantic elements like admonitions, examples, definition lists, and sidebars enable structured writing like a mature technical-writing format.

Originally designed as a lighter, writer-friendlier version of the XML-based DocBook format, AsciiDoc is supported by two distinct toolchain families: the original, Python-sourced variant, as well as newer, Ruby-based tools from an organization called Asciidoctor. The newer suite honors the original syntax almost completely but remains active extending the language and its tooling.

AsciiDoc is free software. The Python-sourced edition is licensed under the terms of the GNU General Public License version 2 (GPLv2). The Ruby-sourced edition is licensed under The MIT License.

471 questions
4
votes
1 answer

Using Sphinx to create context-sensitive help files in HTML

I am currently using AsciiDoc for documenting my software projects because it supports PDF and HTML help generation. I am currently running it through Cygwin so that the a2x toolchain functions properly. This works well for me but is a pain to setup…
Bluebill
  • 147
  • 2
  • 11
4
votes
2 answers

Process Asciidoc with Gradle task

I want to convert some AsciiDoc .adoc file into HTML and use Gradle for that. I am new to Gradle. I have found https://github.com/asciidoctor/asciidoctor-gradle-plugin and below is build.gradle that is about to do that, but with my level of Gradle I…
Paul Verest
  • 60,022
  • 51
  • 208
  • 332
4
votes
2 answers

Valid Asciidoc to convert to Manpage (with a2x)

I want to write the manpage for my CLI-script with Asciidoc and convert it with a2x --doctype manpage --format manpage MYMANPAGE.ASCIIDOC I could not find any Asciidoc example out there which can successfully be converted to a manpage with this…
Wolkenarchitekt
  • 20,170
  • 29
  • 111
  • 174
3
votes
1 answer

Asciidoc: How can I format text in a user defined attribute?

When writing H~2~O in the text of an asciidoc document, it is rendered "H subscript(2) O", However trying to define an attribute: :water: H~2~O and refer to the attribute in the text as {water} it is replaced by the verbatim definition of :water: or…
PolarBear2015
  • 745
  • 6
  • 14
3
votes
1 answer

Asciidoc long chapter titles in the header area overlaps the company logo

My problem is the representation of long {chapter-title} in the header area. The long chapter titles overlaps the company logo. It would be great if I could define a short version for the header area. I'm using the asciidoctor-maven-plugin version…
The 5th column mouse
  • 710
  • 1
  • 4
  • 11
3
votes
0 answers

Antora playbook execution crashes when having multiple source repositories

I use Antora 2.3 since sometime now and I had to introduce more source repositories into my playbook.yaml file as the documentation-site grew. Currently, I have 50-60 Git repos, each of size around 15 MB, mentioned in the playbook. Afterwards, my…
Kal_331
  • 31
  • 3
3
votes
1 answer

How can I include a swagger/openapi yaml file into doctoolchain and get a swagger-like output without using a confluence plugin?

I've tried using https://doctoolchain.github.io/docToolchain/ to create an HTML or PDF doc that includes a swagger/openapi yaml file. It looks like the only output for this is into confluence which also requires an additional confluence plugin. Is…
Neil Hart
  • 31
  • 1
3
votes
2 answers

Embed asciidoc in Azure DevOps wiki

Does anyone have a solution how to embed asciidoc/generated HTML into the Azure DevOps Wiki? As a first way just for watch (integrate HTML from asciidoc in the wiki for other users). I also have problems to access a committed html file to the wiki…
twooBeers
  • 186
  • 2
  • 11
3
votes
2 answers

Docker Image created by Google JIB did not include asciidoc of spring rest docs

I use Spring Rest Docs and JIB When i do ./gradlew build and java -jar /some/build/libs/app.jar. I can get api documents generated by spring rest docs at example.com/docs/asciidocname.html. but docker image with ./gradlew jib does not contain this…
labyu
  • 43
  • 5
3
votes
2 answers

How to escape double plus plus sign "++" in Asciidoctor Asciidoc?

For example, if I write: Notepad++ is *great*, I like Notepad++ it treats ++something++ as an escape construct which ignores the * bold and produces:

Notepad is *great*, I like Notepad

instead of the desired:

Notepad++ is…

Ciro Santilli OurBigBook.com
  • 347,512
  • 102
  • 1,199
  • 985
3
votes
2 answers

No such snippet is present in configuration warning

I'm doing documentation using Spring rest auto docs and AsciiDoc. Below is my error message Error Message Section snippet 'auto-method-path' is configured to be included in the section but no such snippet is present in configuration Section snippet…
Rui Fernandes
  • 51
  • 7
3
votes
1 answer

Better way to include content as-is with AsciiDoc include directive

Context I am making a script that dynamically inserts include directives in code blocks on an AsciiDoc file and then generates a PDF out of that. A generated AsciiDoc file could look like this: = Title [source,java] --- include::foo.java[] --- I…
HerCerM
  • 145
  • 2
  • 9
3
votes
1 answer

AsciiDoc: How to embed youtube videos in github-flavored asciidoc?

I'm writing documentation using the asciidoc markup language and pushing it to a github repo. Github renders asciidoc files (*.adoc) automatically but does for (me) unknown reasons not want to accept my embedding of a youtube video. I've tried the…
Matthias Kubisch
  • 33
  • 3
3
votes
1 answer

Unable to set font size with asciidoctor-pdf

I'm unable to set a font size (or style) for my .adoc files when transformed in PDF with asciidoctor-pdf. According to the docs, I can specify it as follows: base: font_size: 8 line_height_length: 10 So I've put it at the top of my .adoc file.…
Carla
  • 3,064
  • 8
  • 36
  • 65
3
votes
1 answer

ASCIIDOC: adding link to index.html to all documents for quick navigation

I am generating HTML documentation with Gradle org.asciidoctor.convert plugin and I want to add easy accessible link to main index document to each generated page. From index.adoc I point to individual pages, like: == Troubleshooting *…
gavenkoa
  • 45,285
  • 19
  • 251
  • 303
1 2 3
…
31 32