# Generating Output Documents From .md Files

Markdown can be converted to other document formats using Pandoc, a “universal document converter.” It reads many different document file types, then converts one format to another. Some file types get fussy when converted, but Markdown and Pandoc play very nicely together.

Markdown can be converted to other document formats using Pandoc, a “universal document converter.” It reads many different document file types, then converts one format to another. Some file types get fussy when converted, but Markdown and Pandoc play very nicely together.

There are several ways to access Pandoc, using either a terminal command line or one of many different file converter applications. This guide will focus on converting .md files to .html and .docx formats.


## Converting .md Files Using Terminal Command Line

This method generates both .docx and .html files.

1.  If Pandoc is not installed on your computer, go to the Pandoc installation page for instructions to download and install to your computer.
2.  Use the following Terminal commands to convert from .md to .html or .docx format. The commands are the same, except for the extension on the output file.

```
    pandoc -s /filepath/Input_Filename.md  -o /filepath/Output_Filename.html

    pandoc -s /filepath/Input_Filename.md  -o /filepath/Output_Filename.docx
```

Pandoc is fussier about rendering PDFs. First, it does not tolerate markup errors, and may refuse to convert a file. Second, you must install a pdf-engine then call it in the command. Look at the example below:

```
    pandoc -s --pdf-engine=xelatex /filepath/Input_Filename.md  -o 
    
    /filepath/Output_Filename.pdf
```

The pdf-engine defines what the format will look like. This particular PDF engine’s default layout and fonts look outdated and can be hard to read. Changing them requires some deeper coding work, which is why I do not recommend using Pandoc for creating occasional PDFs. It usually is quicker to render a file from Markdown to MS Word then save it as a PDF.


## Converting .md Files to .html

Many plain text editors have a built-in option to convert Markdown to plain HTML. If your text editor does not have this feature, a web-based Pandoc converter works well.

1. Go to the MD to HTML Converter at https://ashkanph.github.io/md-to-html/.
2. In the upper right corner, use Browse to find your local folder containing the .md file being converted.
3. Once an .md file is selected, it is converted to .html and displayed.
4. Use the Save as HTML button to write a copy of the file in .html back to the same folder as the original .md file.
5. If you open a version of the file with the .html extension in your plain text editor, you will see it now has HTML markup. You can copy/paste the code into most LMS pages. Or, you can share the file itself with others; they can open it in any web browser.


### Other Options for HTML

There are many free MD to HTML converters available. Two very good ones are [Markdown It](https://markdown-it.github.io/) and [Markdown to HTML](https://markdowntohtml.com/); both have very user-friendly interfaces, but require copy/pasting the text rather than choosing a file. 

[Dillinger](https://dillinger.io/) is a web-based editor that shows the Markdown code in a window next to either the HTML code or the styled text. Rendered Markdown can be exported as HTML, but like R Studio, Dillinger includes some extra styling information.

If you prefer to use a standalone Markdown editor, [HarooPad](http://pad.haroopress.com/) produces very clean HTML. HarooPad handles equations particularly well. 


## Converting .md Files to .docx

R Studio is very good for converting .md files to well-formatted Word documents.

1. Open R Studio, and go to the workshop files. Open one of the files you edited or created. 
2. At the top of the screen, open the pulldown menu next to __Preview__ and choose __Word document__.

<center>

![Converting Markdown to Word format](images/Preview-Word-ABLE.png){width=80%}

</center>
<br/>

3. R Studio will call Pandoc, generate a pre-formatted MS Word .docx file, then save it to the same directory where the .md file is located.
4. Click on the .docx file to open it in MS Word.

MS Word files are formatted using a standard template. To format documents a different way, create a template file with the header and text styles that you want. When newly generated documents are copy/pasted into the template file, the text will change to the styles you set. 

<br> 

## Other Resources
### File Format Converters

* HTML5 for the web:
    + [MD to HTML Converter](https://ashkanph.github.io/md-to-html/)
    + [Dillinger](https://dillinger.io/)
    + [Markdown It](https://markdown-it.github.io/)
    + [Markdown to HTML](https://markdowntohtml.com/)
* MS Word documents:
    + [Pandoc Converter](https://pandoc.org/demos.html)

### Installing R and R Studio

* [Install R](https://cloud.r-project.org/).
* [Install RStudio](https://www.rstudio.com/products/rstudio/download/).
* [Installing R and R Studio, Step by Step](https://moderndive.netlify.app/1-getting-started.html)
* [Using Markdown inside R](https://bookdown.org/yihui/rmarkdown/)