Skip to contents

Editing the Mizer Website

Source: vignettes/editing_website.Rmd
editing_website.Rmd

Website built from package documentation

The mizer website at [https://sizespectrum.org/mizer/] is created programmatically from the documentation included in the mizer GitHub repository. Thus to edit the website just means editing this documentation. The website creation is performed by a slight modification of the pkgdown package. You can trigger a build in your local repository by issuing the commands

devtools::install_github("gustavdelius/pkgdown", ref = "mizer")
pkgdown::build_site()

This will convert all existing documentation into html files and put these into the docs subdirectory of your mizer directory. In detail:

  1. All .Rmd files in the vignettes subdirectory (and its subdirectories, if any) will produce html files of the same name in docs/articles.

  2. All .Rd documentation files in man will produce html files of the same name in docs/reference.

  3. The NEWS file will be converted to docs/news/index.html

  4. The README.md file will be converted to docs/index.html.

Then the package will use the information in the _pkgdown.yml file to create a navbar and index pages. The navbar is configured with

navbar:
  title: "mizer"
  left:
    - icon: fa-home fa-lg
      href: index.html
    - text: "Get Started"
      href: articles/mizer.html
    - text: "Articles"
      href: articles/index.html
    - text: "Reference"
      href: reference/index.html
    - text: "Publications"
      href: articles/publications.html
    - text: "News"
      href: news/index.html
  right:
    - icon: fa-github fa-lg
      href: https://github.com/sizespectrum/mizer

This is quite self-explanatory, specifying the order of the navbar entries, their text and link destination, and whether they are on the left or right side. It is clearly easy to add additional navbar entries. It would be possible to also include drop-down items in navbar. See the pkgdown documentation for more details.

The file docs/articles/index.html is created according to the article: section in the _pkgdown_yml file. At an early stage it looked as follows:

articles:
- title: User Guides
  contents:
  - model_description
- title: Developer Guides
  contents:
  - developer_vignette
  - mathematical_details

By now it has more entries to link to more vignettes. It is not necessary to use this index file. The menu entry could just as well point to a more elaborate file created from an .Rmd file in the vignette subdirectory, which might become useful in the future.

The file docs/reference/index.html is created according to the reference: section in the _pkgdown_yml file, with a similar syntax as the article: section.

Changing page content

At the top of every page on the website, except the homepage, there is a link to the page source. So it is easy to know which file to edit to make changes to a page. If you want to rebuild the website after making a change to a single page you may not want to re-build everything. You can rebuild just a single vignette. For example to rebuild this page after editing the vignette vignette/editing_website.Rmd you can call

pkgdown::build_article("editing_website")

To rebuild the reference pages after changing the roxygen code doc you can run

pkgdown::build_reference()

To change the homepage you edit index.md. This file is very similar to README.md that is used on the mizer homepage on GitHub, but can contain extra content like embedded videos that the GitHub homepage does not support. After changes to index.md you can update your local copy of the website with

pkgdown::build_home()

Of course these changes will affect only your local copy of the website. To get those changes reflected on the online site you will need to make a pull request for your changed files against the master branch of the upstream repository.

GitHub pages

The website is hosted with GitHubPages. In the settings pages of the mizer repository on GitHub the source is set to “master branch/docs folder”. This means that only the master branch controls the website.

The search bar on the website is powered by Docsearch from Algolia. This is a free service for open-source projects. The set-up is explained in the pkgdown documentation.

Embedding videos

It is easy to embed videos into a webpage by putting an iframe into the R Markdown source file. For example putting the line

<iframe width="560" height="315" src="https://www.youtube.com/embed/0RlXqLbFbWc" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

into the source of this page produced the following embedded video:

The GitHub site itself (as opposed to GitHub Pages) does not support embedded videos.