Skip to contents

mkdocs_workflow

Source: vignettes/mkdocs_workflow.Rmd
mkdocs_workflow.Rmd

Allow GitHUb pages in your repository

Getting MkDocs

For this, I followed the instructions over here. I got already python on my machine and I’m a Linux user, so I’m using Ubuntu 20.04

Given that I had already python I just installed MkDocs:

pip install mkdocs

Then I validated that the installation was succesful:

$ mkdocs --version
mkdocs, version 1.2.2 from /home/your_username/.local/lib/python3.8/site-packages/mkdocs (Python 3.8)

Done! I got MkDocs on my computer.

Getting Matherial theme

I don’t like the default theme that comes with MkDocs, so I changed to Matherial.

To install this theme, you will need to run in the terminal:

$ pip3 install mkdocs-material

Working on your notes

Now we are all set. We can start creating our Rmarkdown documents:

Create as many Rmd documents as you need. Each document will be a “section” on your final website.

Each of the titles and subtitles in your document will be sections inside the specific page.

Also, use relative paths. This will make everything less error prone.

Now, because we are going to use the package docmaker we need to follow a structure:

  • All your Rmd files should be in the root of your project.
  • Your data, images, pdfs files can be saved inside folders.
  • Don’t use docs folder. This is a special folder designated to save the files needed to build the web page. docmaker package will be in charge of the use of this folder, so you don’t have to worry about it.

Deploy and publish your notes with docmaker

So far, we have our notes. But we are still lacking the part of publishing in our web page the notes. There are several steps to do this manually but after many times repeating everything I decided to create a small R package to automatize this steps. This package is called dockmaer

You can install the package with:

devtools::install_github("ronnyhdez/docmaker")

Now, on your console you can load the package:

Configure repo with docmaker

Before building and deploying our notes, we need to do some configuration steps in our repository. docmaker can take care of this with the function:

build_repo(github_page_url = "https://ronnyhdez.github.io/test_docmaker/",
           site_author = "Ronny A. Hernández Mora")

We can get the URL of our repository in the settings > page on GitHub. After we enabled this in a step before, there should appear the URL designated by GitHub for our web site.

The site_author should be our name.

This function will do the following:

  • Create a yml file
  • Add to the .gitignore the site folder
  • Create a docs folder

Build and deploy notes

Because this is our first time, all of our notes (three in the example) are not existing as md documents nor even built or deploy with mkdocs.

docmaker have a function to take all the .Rmd files existing in our project root and do all the steps needed to deploy this ones:

make_all_docs(deploy = TRUE)

This function will do the following:

  • Render all our Rmd files to md
  • Move the outputs (including images) to the docs folder
  • If we are using a README.Rmd file this will be ignore
  • Build the mkdocs
  • If deploy is set to TRUE it will deploy the notes.
  • Create an specifi branch for the pages deployment: gh-deploy

Now, given that we are using a new branch to be deployed, we need to go back to GitHub pages and make a small change: change the branch selected to be build from main to gh-pages

After some seconds (or a few minutes), we should be able to see our site alive!

More detailed steps

I have created a blog post with more detailed steps if you get confused with the steps setting on your GitHub pages in here