guidence/GettingStarted.md

In markanewman/stormdown: PhD dissertation template for Harrisburg University in R Markdown

Using stormdown to write your Ph.D. dissertation

This walkthrough guides you through the process of how to use stormdown to write your Ph.D. dissertation. It should cover everything you should need to get started from a brand-new PC. If it does not, add an issue to the backlog or submit a PR. If you have been using your PC for a while, the chances are that most of the work is already done. Feel free to skip steps you do not need (like installing R). This guidance is Windows-centric, but similar steps should run on Mac or Linux. The version numbers for the packages I use are noted. If you use a different version, YMMV.

When testing these steps, I started from a new VM in Azure. If you find something that does not work, you may need to fiddle with your install base. Assuming there is enough interest, I will put up a troubleshooting FAQ.

1. Setup the prerequisites.
   • R (3.6.3) + R Studio (1.2.5033)
   • RTools (3.5.0.4)
   • I recommend using Chocolatey, but you can use any method you like. Open a Powershell prompt in admin mode and run the below commands.

if('Unrestricted' -ne (Get-ExecutionPolicy)) { Set-ExecutionPolicy Bypass -Scope Process -Force }
iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
refreshenv
choco install r.project --version=3.6.3 -y
refreshenv
choco install r.studio --version=1.2.5033 -y
choco install rtools --version=3.5.0.4 -y

1. Open up R Studio
2. Install the R packages: rmarkdown (2.3), bookdown (0.20), tinytex (0.24), devtools (2.3.0), kableExtra (1.1.0), dplyr (1.0.0), and ggpubr (0.3.0).
   • kableExtra, rlang, dplyr, and ggpubr are only used in the sample sections. You only need them to test the inital Knit.
   • In order to pin the version of the packages, set the repo to a snapshot version.

r <- getOption('repos')
r['CRAN'] <- 'https://mran.microsoft.com/snapshot/2020-06-24'
options(repos = r)
install.packages(c('rmarkdown', 'bookdown', 'tinytex'))
install.packages(c('devtools'))
install.packages(c('kableExtra', 'dplyr', 'ggpubr'))

1. Install LaTeX. There will be a couple of popups complaining about missing DLLs, ignore those.

tinytex::install_tinytex()

1. Restart R Studio then run the following to test the LaTeX install.

tinytex:::is_tinytex()

1. Install stormdown then restart R Studio rtools won't work if there is no timezone set, so that may need done too.

if(Sys.timezone() == 'unknown') { Sys.setenv(TZ = 'GMT') }
devtools::install_github('markanewman/stormdown', upgrade = 'never')

1. Restart R Studio to refresh the template cache.
2. Create your files. File -> New File -> R Markdown... then choose 'From template', then choose 'HU-Dissertation, and enter index as the Name (see Figures 1-2 below). Note that this will currently only Knit if you name the directory index at this step. Please note: both the folder and the entry point rmd file are called index. The file name must remain index.rmd, but you may want to rename your directory to something more memorable.
   • If you are not using R Studio, the below command line should help. {r} #only if not running RStudio rmarkdown::draft('index', template = 'dissertation', package = 'stormdown', create_dir = T, edit = F)
3. Make sure your working directory is the same as the one you used to create the template. Files Tab -> Go To Folder -> More -> Set As Working Directory (see Figure 3 below).
   • If you are not using R Studio, the below command line should help. {r} #only if not running RStudio setwd("index")
4. Knit the files. The first time you knit, it will take a long time as the system automatically puls down all the LaTeX packages. Subsequent knits will be much faster.
   • If you are not using R Studio, the below command line should help. {r} #only if not running RStudio bookdown::render_book('index.rmd')
5. Enjoy.

Figure 1: Path to new templates

Figure 2: Create new template

Figure 3: Set working directory

markanewman/stormdown documentation built on Jan. 1, 2021, 9:18 a.m.