Antora vs R Markdown

Overview

Antora is a modular, multi-repository site generator designed for producing documentation sites from content composed in AsciiDoc and converted to HTML using Asciidoctor and Handlebars.

Antora provides both a toolchain and workflow to help documentation and engineering teams create, manage, collaborate on, remix, and publish documentation sites aggregated from multi-branch git repositories without needing expertise in web technologies, build automation, or system administration.

Who it's for

Tech writers, first and foremost.

If you're already using Asciidoctor, and you need help managing a large set of documentation written in AsciiDoc, Antora was designed for you. If you haven't yet tried Asciidoctor (or AsciiDoc), Antora is a great way to get started because it provides everything you need to start writing and publishing documentation today.

What it includes

Antora includes a command line interface (CLI) (command: antora), a preassembled site generator pipeline, and a default UI so you can get started quickly publishing documentation sites with Antora.

Since Antora is both modular and extensible, there are plenty of opportunities to explore to take it further once you have your first site up and running.

Availability

Antora is available as a suite of npm packages and a Docker image. Antora runs on any platform that supports Node, which includes Linux, macOS, and Windows.

Learn more

To learn more about Antora, be sure to check out the documentation, which, as you would expect, is published by Antora itself.

The rmarkdown package helps you create dynamic analysis documents that combine code, rendered output (such as figures), and prose. You bring your data, code, and ideas, and R Markdown renders your content into a polished document that can be used to:

• Do data science interactively within the RStudio IDE,

• Reproduce your analyses,

• Collaborate and share code with others, and

• Communicate your results with others.

R Markdown documents can be rendered to many output formats including HTML documents, PDFs, Word files, slideshows, and more, allowing you to focus on the content while R Markdown takes care of your presentation.

Installation

The easiest way to install the rmarkdown package is from within the RStudio IDE, but you don't need to explicitly install it or load it, as RStudio automatically does both when needed. A recent version of Pandoc (>= 1.12.3) is also required; RStudio also automatically includes this too so you do not need to download Pandoc if you plan to use rmarkdown from the RStudio IDE.

If you want to use the rmarkdown package outside of RStudio, you can install the package from CRAN as follows:

install.packages("rmarkdown")

If you want to use the development version of the rmarkdown package (either with or without RStudio), you can install the package from GitHub via the remotes package:

remotes::install_github('rstudio/rmarkdown')

If not using the RStudio IDE, you'll need to install a recent version of Pandoc (>= 1.12.3); see the Pandoc installation instructions for help.

Usage

The easiest way to make a new R Markdown document is from within RStudio. Go to File > New File > R Markdown. From the new file wizard, you may:

• Provide a document title (optional but recommended),
• Provide an author name (optional but recommended),
• Select a default output format- HTML is the recommended format for authoring, and you can switch the output format anytime (required),
• Click OK (required).

Once inside your new .Rmd file, you should see some boilerplate text that includes code chunks. Use the "Knit" button in the RStudio IDE to render the file and preview the output with a single click or use the keyboard shortcut Cmd/Ctrl + Shift + K.

You can also delete all the text below the YAML frontmatter and fill in your own .Rmd by:

• Adding code chunks (keyboard shortcut: Ctrl + Alt + I; OS X: Cmd + Option + I),
• Writing prose with Markdown formatting, and
• Running each code chunk interactively by clicking the icon within RStudio.

You can also click "Knit to HTML" again to render the full document with all code chunks. For more help getting started in R Markdown, please see the R Markdown website or use the "Get Started" links at the top of this page.

Getting help

There are two main places to get help:

1. The RStudio community is a friendly place to ask any questions about rmarkdown and the R Markdown family of packages.

2. Stack Overflow is a great source of answers to common rmarkdown questions. It is also a great place to get help, once you have created a reproducible example that illustrates your problem.