Programming for Actuarial Work Working Party
This git repository hosts the markdown files that comprise the introductory guide to programming material. By rendering the markdown files (using the bookdown library in R), a collection of HTML files are created that represent the markdown files in a gitbook web friendly format. These web pages can then be hosted on github pages for public viewing.
The rendered book is viewable here
There are two main folders in this directory: /book and /markdown.
The /markdown folder contains all the R markdown files that are to be rendered into the final book output. It also includes the R script to render these files into this HTML format.
The /book folder contains all the rendered HTML output. Each markdown file has its own HTML file respectively. A supporting /libs folder is created that contains the supporting libraries required for the final gitbook output.
The markdown files are based on the usage specified in the bookdown R library. An online user guide (rendered with bookdown itself) can be found here.
Each chapter has its own R markdown file. The name of the file indicates the order of each chapter, eg 01-intro.Rmd will be placed first etc. Files that begin with an underscore are ignored during rendering. The file called index.Rmd is always placed first and is the ‘landing page’ of the final gitbook site. It is also the first parameter required for the render book function used in R.
A guide to the available markdown syntax can be found here.
After a contributor has finished editting the R markdown files, they will need to run the script in the _renderbook.R file in order to render them into the final HTML files for web viewing. The first line of this script needs to be altered to the relevant directory location, depending on where the contributor has cloned their instance of this repo.
The final rendered book can be viewed locally by opening the /book/index.html page in your browser. When editting the markdown files, this local site can be left open. To view the result of any changes made, save the updated Rmd files, run the render book script in R, and then refresh your browser.
Github has the ability to host static web pages, such as our rendered bookdown output. More information can be found here.
For each user, github offers the <username>.github.io domain as a free static web host. The content of the <username>.github.io repo is then displayed at this web address.
There are several ways to implement the static web pages. Github can render markdown files into its own template web pages (using Jekyll), and even R code can be run (using Travis) when committing changes to this repo.
However, in its simplest implementation, just rendering the R markdown files locally into the /book directory allows a user to view the book at institute-and-faculty-of-actuaries.github.io/book or institute-and-faculty-of-actuaries.github.io/book/index.html once pushed to the origin remote.
The bookdown and github pages specific workflow is therefore:
_renderbook.R script to the relevant location and run the next two lines