[ARTEMIS-4383] Migrate user docs to AsciiDoc

• Type: Task
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 2.31.0
• Assignee: Justin Bertram
• Reporter: Justin Bertram
• Created: 01/Aug/23 18:24
• Updated: 20/Jun/24 06:57
• Resolved: 15/Sep/23 19:08

Description

Markdown, which is currently used for user-facing documentation, is good for a lot of things. However, it's not great for the kind of complex documentation we have and our need to produce both multi-page HTML and single-page PDF output via Maven.

Markdown lacks features which would make the documentation easier to read, easier to navigate, and just look better overall.

The current tool-chain uses honkit and a tool called Calibre. Hokit is written in TypeScript and is installed via NPM. Calibre is a native tool so it must be installed via an OS-specific package manager. All this complexity makes building, releasing, uploading, etc. a pain.

AsciiDoc is relatively simple like Markdown, but it has more features for presentation and navigation not to mention Java-based Maven tooling to generate both HTML and PDF. Migrating will improve both the appearance of the documentation as well as the processes to generate and upload it.

Issue Links

• breaks: ARTEMIS-4830 Return a search bar to the HTML documentation page
• fixes: ARTEMIS-4300 Wrong links in docs
• links to: GitHub Pull Request #4573