Understanding Site Structure

In RStudio web pages are built from the Rmarkdown (.Rmd) files. So,

index.Rmd becomes index.html
writepage.Rmd becomes writepage.html

When we use the Build button, the rmarkdown files are converted to html. Those html files become the pages of the website in the site structure.

The structure of the site is contained in the file _site.yml. It looks like this.

name: "Create a simple Rmarkdown website"
output:
  html_document:
    theme: cosmo
    #highlight: textmate
navbar:
  left:
    - text: "Home"
      href: index.html
    - text: "Next Steps"
      menu: 
        - text: "Writing Pages"
          href: writepage.html 
        - text: "Include Images"
          href: images.html
        - text: "Embed a webpage"
          href: embed.html
        - text: "Embed an infographic"
          href: info.html
    - text: "Change the Structure"   
      menu:
        - text: "Site structure"
          href: structure.html
    - text: "Publish to Github"      
      menu: 
        - text: "publish"
          href: publish.html
        - text: "submenu item"
          href: yourfile.html
output_dir: "."

The basics

The site structure starts with the name of the site. Then we have the output as html_document and a theme. For available themes see the RStudio websites section. You can also choose the text highlight option (commented out with # here).

Next comes location of the navigation bar.

The index file

All websites must have an index file. In this case the - text: provides the instruction on what to call the menu item "Home". Below that we have the reference to the html file that corresponds with home. To build a website on GitHub you must have an index file, so this goes here.

An important point here is that the indents matter. If they are slightly out the site will create an error or not display properly. Use the tab key to make sure things are properly aligned.

- text: "Home"
  href: index.html

Menus and sub menus

To create sub-menus on the navigation bar we start by giving the text that we want to see in the menu. Next we specify that this is a menu and then indent the pages that appear under the menu with text and href.

- text: "Next Steps"
      menu: 
        - text: "Writing Pages"
          href: mypage.html 
        - text: "Include Images"
          href: images.html
        - text: "Embed a webpage"
          href: embed.html
        - text: "Embed an infographic"
          href: info.html

If we want a new sub-menu we simply repeat the above with the relevant titles and links to the html files.

The most important things to remember here are:

The indents above really matter. If the site will not build it is probably because the indents of - text and href are not aligned.
The file names matter. If the markdown file is called info1 it will rended as info1.html. If you put info.html into the structure then the _site.yml will not find info1.html and that will cause a problem.

output_dir

This is set to “.” if you want to publish the site on GitHub. For other options see the Publishing Websites section of the RStudio guide.

Understanding Site Structure

Paul Oldham

30/08/2017

The basics

The index file

Menus and sub menus

output_dir