Environment Handling

For the best results after conversion :

1. Avoid using framebox or any other latex command to wrap the \includegraphics{} . This might interfere with the packages ability to properly read the path and copy the relevant image properly.
2. Try to keep the actual content of the caption without any LaTeX markup (normal text), as it is not reflected in HTML properly.

In newer versions of texor package, a new option is available to convert figures into Rmarkdown style code chunks to include figures there. If the option fig_in_r is set TRUE, a custom Lua Filter will transform the image structure.

For example :

\begin{figure}
  \includegraphics{image/sample.png}
  \caption{This is a sample caption}
  \labeL{fig:image-1}
\end{figure}

will be converted to

```{r , echo=FALSE , fig.cap="This is a sample caption", fig.alt="graphic without alt text",
 fig.show='hold', fig.align="center", out.width="100%"}
knitr::include_graphics(c("image/sample.png"))
```

if the option fig_in_r is set FALSE, a simple markdown figure would be generated

![Figure 1: This is a sample caption](image/sample.png){width="100%"
alt="graphic without alt text"}

Notes

1. Default handling of the texor package is to generate R markdown style code chunks to include images using knitr::include_graphics(c(file_path)). This mechanism was added using a unique Lua filter ¹ which can also handle multiple images in a single figure environment as well. The Lua filter is open source and available under MIT License here.
2. If you set the option fig_in_r = FALSE in rnw_to_rmd() or latex_to_web() functions, you can revert back to simple markdown figures which has the following syntax ![caption](file_path){#identifier ..}.
3. Some authors used to add verbatim environments inside figure environments to be able to add captions. To maintain parity, the texor package transforms the block into a raw HTML block so as to enable such out of the box use of figure environment in markdown.
4. In case you set fig_in_r = FALSE, the captions added to the figures will be appended with figure numbering which would also be reflected in the references to the figures throughout the document as well. If you want to add or change the position of the position of the figures exercise caution.
5. To add to accessibility, we have added a default alt-text to every figure which is meant to motivate the author to replace it with a better alt-text rather than repeating the caption as alt-text. However in case of bulk conversions the alt-text is a reasonable placeholder compared to no alt-text at all.

Notes

1. The table data is parsed and converted into a csv file using this Lua filter which is open source and available under MIT License.
2. The tables will be converted to kable() tables by default, unless some complex LaTeX table is identified, beyond which the package will fallback to simpler markdown tables.
3. Provision for wide tables is provided which can span across multiple tables within the document.
4. Although some support for including CodeBlocks inside of tables exists, it is not the best and can have unintended side effects.
5. Markdown tables have their captions appended with table numbering, reflected in the references as well. This is static for the document, which will require modifications if you want to add/ re-position the tables in the converted article.

Supported RJ-article (LaTeX) code environment:

Sweave code chunks

With updates to the texor package we were able to add support for Sweave articles which included retaining the code chunks with parameters. This functionality is not found natively in LaTeX, hence unsupported in pandoc as well. To add this feature, we designed a custom pandoc reader in Lua, which uses LPEG expressions to separate out the code chunks from the Sweave document, while retaining the parameters and code.

<<test>>=
1+1
rnorm(30)
@

The above Sweave code block would be converted to

```{r test}
1+1
rnorm(30)
```

Similarly inline code express in Sweave defined by \Sexpr{'0.6'} will be transformed to ` r '0.6'`

Notes

1. Any special markup (like font-size, font-style) bought by any of these code environments will be lost.
2. The retained text will have syntax highlighting (for R by default, if you want to change the syntax highlighting, change the language in the markdown source code formed).

Equation Numbering

In bookdown, you do not get automatic numbering of un-labelled equations. This can be tricky to deal with if we want to have the equation numbering matching with the one in LaTeX. To circumvent this issue we first transform the equation labels both in the equations and references, to maintain support with the specifications prescribed in bookdown. Then we transform the labels from LaTeX label in equations from \label{..} to (\#eq:..) and references from \ref{..} to \@ref(eq:..) which ensures compatibility. Next for equations without labels and no \nonumber commands, we automatically assign and add a equation label like (\#eq:autonumber..) where the equation number is the last character.

To enable this you need to set the option autonumber_eq as TRUE while converting the documents.

Notes

1. Some functionality like bibliography/footnotes might be lost in litedown as of now as it is an experimental package.
2. bookdown option includes an header file with custom JavaScript to incorporate section numbering and normal equation numbering (i.e. eq 1,2,3,.. instead of 1.1,1.2,2.1,3.1,..), this will be included when autonumber_sec is set to TRUE.
3. bookdown option will set the math_mode to katex by default unless autonumber_eq option is set to TRUE, where the math_mode is mathjax.
4. Ultimately you can modify the generated R markdown however you want for the desired format.