A Minimal Example

Suppose, you have a file that reads

file_name <- system.file("files", "minimal", "knit.Rasciidoc",
                         package = "rasciidoc")
cat(readLines(file_name), sep = "\n")

= 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
my_sum <- function(x) {
    value <- 0
    for (x_i in x) {
        value <- value + x_i 
    }
    return(value)
}
//end.rcode

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

withr::with_dir(tempdir(), {
                    file.copy(file_name, ".")
                    rasciidoc::render(basename(file_name))
})

## Warning in run_knit(file_name, knit = knit, envir = envir): Setting option knit
## to TRUE based on the file contents!

## Due to the CRAN policy of not writing "anywhere else on the file system apart from the R session's temporary directory" we work on a temporary copy of /tmp/RtmpcZokEj/knit.Rasciidoc.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/RtmpcZokEj. Set the option "write_to_disk" to TRUE (using
##  options("write_to_disk" = TRUE)
## ) to bypass this. You may want to include the above line into your ~/.Rprofile.

## processing file: /tmp/RtmpcZokEj/knit.Rasciidoc

## output file: /tmp/RtmpcZokEj/knit.asciidoc

## [1] 0

you will create an HTML file that is identical to this file 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:

file_name <- system.file("files", "simple", "knit.Rasciidoc",
                         package = "rasciidoc")
cat(readLines(file_name), sep = "\n")

= 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, code = readLines("src/sum.R")
//end.rcode


== A new section

//begin.rcode, code = readLines("src/my_sum.R")
//end.rcode
=== A subsection
//begin.rcode
print(value)
//end.rcode

//begin.rcode
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:

my_directory <- file.path(tempdir(), "simple")
dir.create(my_directory)
withr::with_dir(my_directory, {
                    file.copy(file_name, ".")
                    file.copy(file.path(dirname(file_name), "src"), ".",
                              recursive = TRUE)
})

## [1] TRUE

dir(my_directory, recursive = TRUE, full.names = TRUE)

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

you could render the file

rasciidoc::render(file.path(my_directory, basename(file_name)))

## Warning in run_knit(file_name, knit = knit, envir = envir): Setting option knit
## to TRUE based on the file contents!

## Due to the CRAN policy of not writing "anywhere else on the file system apart from the R session's temporary directory" we work on a temporary copy of /tmp/RtmpcZokEj/simple/knit.Rasciidoc.
## Thus all internal sourcing and internal links will be broken and any output is written to /tmp/RtmpcZokEj. Set the option "write_to_disk" to TRUE (using
##  options("write_to_disk" = TRUE)
## ) to bypass this. You may want to include the above line into your ~/.Rprofile.

## processing file: /tmp/RtmpcZokEj/simple/knit.Rasciidoc

## output file: /tmp/RtmpcZokEj/knit.asciidoc

## [1] 0

and create an HTML file that is identical to this file and that you could browse using browseURL(file.path(tempdir(), paste0(sub("\\..*$", "", basename(file_name)), ".html"))) from your current R session .