https://github.com/courseorchestra/asciidoctor-open-document
Open Document converter for Asciidoctor
https://github.com/courseorchestra/asciidoctor-open-document
Last synced: 8 months ago
JSON representation
Open Document converter for Asciidoctor
- Host: GitHub
- URL: https://github.com/courseorchestra/asciidoctor-open-document
- Owner: CourseOrchestra
- License: mit
- Created: 2021-05-05T13:47:02.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-10-30T05:24:44.000Z (over 1 year ago)
- Last Synced: 2024-10-30T08:36:16.639Z (over 1 year ago)
- Language: Ruby
- Homepage:
- Size: 5.16 MB
- Stars: 24
- Watchers: 6
- Forks: 7
- Open Issues: 3
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
:toc: macro
:toclevels: 4
image::https://github.com/CourseOrchestra/asciidoctor-open-document/workflows/build/badge.svg[link=https://github.com/CourseOrchestra/asciidoctor-open-document/actions?query=workflow%3A"build"]
= Open Document converter for Asciidoctor
toc::[]
== About
//tag::about[]
Open Document converter for Asciidoctor allows to convert asciidoc documentation into fodt (plain Open Document) format. It relies on https://docs.asciidoctor.org/home/[Asciidoctor project].
Fodt file may be converted with https://www.libreoffice.org/[LibreOffice] SDK or CLI into pdf, odt, docx, doc etc.
Examples (built automatically as a part of CI routine):
* https://github.com/CourseOrchestra/asciidoctor-open-document/blob/main/test/test_cases/stew/test.adoc[source asciidoc file];
* https://courseorchestra.github.io/asciidoctor-open-document/test.fodt[fodt file] (indexes are not updated);
* https://courseorchestra.github.io/asciidoctor-open-document/test.odt[odt file];
* https://courseorchestra.github.io/asciidoctor-open-document/test.pdf[pdf file];
* https://courseorchestra.github.io/asciidoctor-open-document/test.docx[docx file] -- yes, sometimes messy, but generally not so bad and there is always a possibility to simplify conversion rules and tailor them to the needs of the exact project.
The asciidoctor-open-document converter can be extended in the following ways:
* custom fodt template. Allows to customize paragraph properties, text properties, page properties (orientation, header, footer and like), list properties, table properties. Custom fodt template can contain title page or any before/after content;
* custom slim templates;
* custom xml-content preprocessor;
* custom Open Document style setters.
//end::about[]
== Usage
//tag::usage[]
=== With docker
==== With `a-od` simplified utility
Assuming you need to convert `test.adoc` from the current directory to odt format.
----
docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od test.adoc odt
----
General syntax of `a-od` is:
----
a-od [file] [output format] [custom fodt temlate] [custom conversion library]
----
To use asciidoctor cli options add `--asciidoctor` at the end and any asciidoctor cli options. For example, to convert `foo.adoc` to pdf with revision number `v5` use:
----
a-od foo.adoc pdf --asciidoctor -a revnumber=v5
----
==== Or step by step without `a-od`
* Convert adoc to preliminary Open Document content file
+
The following steps assume that asciidoc file `test.adoc` is in the `/my-adoc` directory. As a result we want to get `test.fodt` and `test.pdf`.
+
----
docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od-pre -r asciidoctor-mathematical -r asciidoctor-diagram test.adoc -o pre.xml
----
+
Here `asciidoctor-mathematical` and `asciidoctor-diagram` extensions are used.
* Convert preliminary Open Document content file to fodt
+
----
docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od-out -c /usr/local/a-od/a-od-my/my-cp-example.rb -i pre.xml -o test.fodt
----
+
Here the custom library is used. It contains examples of custom features: positioning equation number, paragraph alignment role, code highlighting, positioning admonitions inside of the list element.
* Convert fodt to pdf, odt, docx
+
----
docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od java -jar /usr/local/a-od/lo-kts-converter.main.jar -f pdf,odt,docx -i test.fodt
----
=== As a ruby script
Conversion consists of 2 steps.
. Convert adoc to preliminary content file
. Convert preliminary content file to fodt
==== Convert adoc to preliminary content file
Conversion to preliminary content file is done by the standard `asciidoctor` command with a slim template (slim folder of a source code).
----
asciidoctor -T [path to slim] -b fodt asciidoc_file.adoc
----
There is a wrapper `a-od-pre` in docker image. Use it like a normal `asciidoctor` command. It just sets slim template and backend.
==== Convert preliminary content file to fodt
Conversion to final fodt file is done with the `asciidoctor-od.rb` script.
----
ruby [path to script]/a-od-producer.rb -i [prelimenary content file] -o [final file] -c [custom process library] -f [fodt template]
----
There is a wrapper `a-od-out` in docker image. It just runs ruby with `a-od-producer.rb`.
//end::usage[]
*More details* can be found in https://courseorchestra.github.io/asciidoctor-open-document/[Open Document converter for Asciidoctor documentation].