Home

The published site of the ChRIS documentation is hosted at: https://mfonn.github.io/CHRIS_docs/

CONVERTING MARKDOWN TO ADOC

Markdown is a plain text formatting syntax aimed at making writing for the internet easier. The philosophy behind Markdown is that plain text documents should be readable without tags complicating them, however there should still be ways to add text modifiers like lists, headings, italics and the like. AsciiDoc is a lightweight markup language that is used as a tool for generating software documentation. One of its advantage over markdown is the ability to leverage directives

AsciiDoc is a lightweight markup language that is used as a popular tool for generating any type of software documentation. The AsciiDoc syntax is readable, concise, comprehensive, extensible, and extremely intuitive. One of the core advantages of using AsciiDoc is the ability to leverage include directives. Since this is a native feature of AsciiDoc, writers and developers alike can single-source content much like a React component. Rather than updating the same content in multiple places, writers simply have a source file that is included where necessary, and changes cascade to all locations.

The ChRIS documentation is written using markdown, in other to convert to asciidoc:

• Install asciidoctor, Asciidoctor is a Ruby-based text processor for parsing asciidoc into a document model and converting it to output format such as html.

sudo apt-get install -y asciidoctor

• Install Kramdown

  • Install kramdown sudo gem install kramdown-asciidoc
  • Convert the markdown file to adoc using the syntax: kramdoc --format=GFM \ --output=FILENAME.adoc \ --wrap=ventilate \ FILENAME.md

  To open the page on your local host using

  • Clone the repository, antora branch using git clone -b antora <link to repository>
  • cd into the repository
  • Install Antora and required packages node -e "fs.writeFileSync('package.json', '{}')" && npm i -D -E @antora/cli@3.0 @antora/site-generator@3.0
  • confirm the following files are present: -antora-playbook.yml -antora.yml
  • Run npx antora --fetch antora-playbook.yml
  • It should say, "Site generation completed"
  • Open the link generated in your browser

FOR MULTIPLE REPOSITORIES (STEPS I USED TO CREATE MULTIPLE REPOSITORIES)

• clone the repository locally
• install asciidoc
• changed markdown to adoc
• install antora
• create antora-playbook.yml file
• create antora.yml file
• create modules/root/pages
• remember to change adoc names from readme
• remember to change version name to repository name
• push to main page
• add the new url to the main documentation page