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
This will convert all existing documentation into html files and put these into the
docs subdirectory of your mizer directory. In detail:
All .Rmd files in the
vignettes subdirectory (and its subdirectories, if any) will produce html files of the same name in
All .Rd documentation files in
man will produce html files of the same name in
NEWS file will be converted to
The README.md file will be converted to
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.
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.
docs/reference/index.html is created according to the reference: section in the
_pkgdown_yml file, with a similar syntax as the article: section.
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
To rebuild the reference pages after changing the roxygen code doc you can run
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
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.
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.
It is easy to embed videos into a webpage by putting an iframe into the Rmarkdown 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.