Inspired by Karl Broman`s reader on using knitr with asciidoc (https://kbroman.org/knitr_knutshell/pages/asciidoc.html), this is a wrapper to and a slight modification of knitr.

Knitting

A Minimal Example

Suppose, you have a file that reads

## = Some Title
## Your Name
## :toc2:
## :numbered:
## :data-uri:
## :duration: 120
##
## == A Section
##
## === A Subsection
##
## * A list with a https://en.wikipedia.org/wiki/Hyperlink[link].
## * Yet another entry in the list.
##
## == Code
## //begin.rcode
## a  <- c(2, 3, 4, 10) # <1>
## value <- 0 # <2>
## for (a_i in a) { # <3>
##     value <- value + a_i  # <4>
## }
## print(value) # <5>
## //end.rcode
##
##
## == A new section
##
## //begin.rcode a_plot, dev = "png", fig.cap = "A Plot"
## plot(1:10)
## //end.rcode

If you run render on this file (we use a temporary directory here)

## 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |..................                                                    |  25%
##   ordinary text without R code
##
## 
  |                                                                            
  |...................................                                   |  50%
## label: unnamed-chunk-8
## 
  |                                                                            
  |....................................................                  |  75%
##   ordinary text without R code
##
## 
  |                                                                            
  |......................................................................| 100%
## label: a_plot (with options)
## List of 2
##  $ dev    : chr "png"
##  $ fig.cap: chr "A Plot"
## [1] TRUE

you will create an HTML file that is identical to [this file](https://fvafrcu.gitlab.io/rasciidoc/inst/files/minimal/plot.html) and that you could browse using browseURL(file.path(tempdir(), paste0(sub("\\..*$", "", basename(file_name)), ".html"))) from your current R session (vignettes like this are not allowed to start external programs like browsers, so you’ll have to do it yourself).

A Simple Example

Suppose you changed your file to be less minimalistic:

## = Some Title
## Your Name
## :toc2:
## :numbered:
## :data-uri:
## :duration: 120
##
## == What is this About?
##
##
## === Some simple asciidoc
##
## * A list with a https://en.wikipedia.org/wiki/Hyperlink[link].
## * Yet another entry in the list.
##
## == Including Code
## Do not use the _include_ macro provided by asciidoc!
## //begin.rcode, label = "sum", code = readLines("src/sum.R")
## //end.rcode
##
##
## == A new section
##
## //begin.rcode, label = "my_sum", code = readLines("src/my_sum.R")
## //end.rcode
## === A subsection
## //begin.rcode, label = "value"
## print(value)
## //end.rcode
##
## //begin.rcode, label = "run my_sum"
## print(my_sum(1:3))
## //end.rcode
##
## Some inline code: Object +value+ has value +r value+.
##
##
## === Second subsection

This file obviously reads code from files in a subdirectory called "src/", so if you had that subdirectory and its files, too:

## [1] TRUE
## [1] "/tmp/RtmplyBX0c/simple/knit.Rasciidoc"
## [2] "/tmp/RtmplyBX0c/simple/src/my_sum.R"
## [3] "/tmp/RtmplyBX0c/simple/src/sum.R"

you could render the file

## 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |........                                                              |  11%
##   ordinary text without R code
##
## 
  |                                                                            
  |................                                                      |  22%
## label: sum (with options)
## List of 1
##  $ code: chr [1:6] "a  <- c(2, 3, 4, 10) # <1>" "value <- 0 # <2>" "for (a_i in a) { # <3>" "    value <- value + a_i  # <4>" ...
##
## 
  |                                                                            
  |.......................                                               |  33%
##   ordinary text without R code
##
## 
  |                                                                            
  |...............................                                       |  44%
## label: my_sum (with options)
## List of 1
##  $ code: chr [1:7] "my_sum <- function(x) {" "    value <- 0" "    for (x_i in x) {" "        value <- value + x_i" ...
##
## 
  |                                                                            
  |.......................................                               |  56%
##   ordinary text without R code
##
## 
  |                                                                            
  |...............................................                       |  67%
## label: value
## 
  |                                                                            
  |......................................................                |  78%
##   ordinary text without R code
##
## 
  |                                                                            
  |..............................................................        |  89%
## label: run my_sum
## 
  |                                                                            
  |......................................................................| 100%
##    inline R code fragments
## [1] TRUE

and create an HTML file that is identical to [this file](https://fvafrcu.gitlab.io/rasciidoc/inst/files/simple/knit.html) and that you could browse using browseURL(file.path(my_directory, paste0(sub("\\..*$", "", basename(file_name)), ".html"))) from your current R session .

Spinnig

You can also use a spinnig file for input:

## #' = Some Title
## #' Your Name
## #' :toc2:
## #' :numbered:
## #' :data-uri:
## #' :duration: 120
## #'
## #' == What is this About?
## #'
## #' //begin_no_slide
## #' This will not show up on slides.
## #' //end_no_slide
## #'
## #' === Some simple asciidoc
## #'
## #' * A list with a https://en.wikipedia.org/wiki/Hyperlink[link].
## #' * Yet another entry in the list.
## #'
## #' == Including Code
## #' Do not use the _include_ macro provided by asciidoc!
## #' Instead prefix all source statements with
## #' ----
## #' #+ code = readLines("file_to_be_sourced")
## #' #+ include = FALSE
## #' ----
## #' It est use
## #' ----
## #' #+ code = readLines("src/sum.R")
## #' #+ include = FALSE
## #' source("src/sum.R")
## #' ----
## #' to produce
## #+ code = readLines("src/sum.R")
## #+ include = FALSE
## source("src/sum.R")
## #'
## #'
## message("A message, probably different output hooks.")
## #' == A new section
## #'
## #+ code = readLines("src/my_sum.R")
## #' === A subsection
## print(value)
## #'
## print(my_sum(1:3))
## #'
## #' Inline code does not work: Object +value+ has value +r value+.
## #'

You run render on it:

## 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |......................................................................| 100%
##    inline R code fragments
## [1] TRUE

Vignettes Using rasciidoc

This vignette is built by rasciidoc's vignette engine (see https://gitlab.com/fvafrcu/rasciidoc/-/blob/master/vignettes/An_Introduction_to_rasciidoc.Rasciidoc for its input file).

Just add a

////
    %\VignetteIndexEntry{Your Vignette Entry}
    %\VignetteEngine{rasciidoc::rasciidoc}
////

block to your rasciidoc input file and add rasciidoc to the VignetteBuilder and Suggests fields of your package’s DESCRIPTION file.