Based on the Minimal Mistakes Jekyll theme under and MIT license.
See full config. The following are the most important places where you need to make changes (see comments in these files also):
_config.yml
to update site metadata
_data/navigation.yml
to add more tabs to the top navigation: title and url (relative to site url)# main links in _data/navigation.yml
main:
- title: "Instructions"
url: /
- title: "Compute an E-value"
url: /evalue/
- title: "More resources"
url: /resources/
Open the site.Rproj
file in RStudio IDE. Open Rmd files you’d like to edit. Click render. Jekyll will ignore Rmd, and will deploy html based on the md files.
Adding a new page under http://evalue-calculator.com/path/dir/
:
path/dir
index.Rmd
into the folder (see below for what goes into the header)This is the part that goes into the Rmd header of the file path/dir/index.Rmd
:
---
title: Add your title here
layout: archive
output:
md_document:
variant: gfm
preserve_yaml: true
---
Keeping the layout
and output
is important, so that it will show up as expected after Jekyll renders the pages.
Note: if images are included as part of the Rmd, those will be placed relative to the index.Rmd
file and need to be added to git.
See this cheat sheet for markdown formatting.
Here is how you can add Shiny apps that are already deployed. (See Shiny app deployment below.)
Create new folder in the root, e.g. app
and add app/index.md
file with the following content: change the app url
---
layout: app
app_url: https://shiny-app1.heroku.com/
---
This will indicate to the Jekyll template to use the app
layout (which puts the iframe around the app URL). The app_url
is the link that will show up in the iframe.
If the website is served over https, the iframe needs to be https as well.
GitHub pages use Jekyll, so no additional steps are required. Commit changes and it is done. Make sure you go to the Settings tab of the repo and set GitHub pages deployment from the root folder of the master/main branch.
Set up a www subdomain: http://www.evalue-calculator.com/
following this guide.
www.evalue-calculator.com
to the Custom Domain field and click Savewww
or the required subdomainmayamathur.github.io
To edit the outer framework exclusive of the Shiny app iframe itself (e.g., the Resources tab), just edit and knit the relevant .Rmd file, commit as normal (with no special message), and push. Remember you need to knit the .Rmd file or else the changes will not be reflected in the .md file, which is what the website ultimately uses.
assests/css/main.scss
._sass/minimal-mistakes/_variables.scss
(not tested)._sass/minimal_mistakes/_archive.scss
.Note: We are using the “archive” layout (_sass/minimal_mistakes/_archive.scss
), so if you want to change a parameter that is normally in _page.scss
, you should change it in _archive.scss
instead.
The shiny apps live inside the _shinyapps
folder (Jekyll ignores directories that begin with underscore, thus we don’t need to worry about publishing the source code as part of the website).
The apps can be placed inside this folder, e.g.
_shinyapps/evalue
_shinyapps/app2
The structure inside the app folders can be identical:
_shinyapps/evalue/app/global.R
: the global script_shinyapps/evalue/app/ui.R
: the UI_shinyapps/evalue/app/server.R
: the server function_shinyapps/evalue/Dockerfile
: see comments inside the file and prompts for where to edit._shinyapps/evalue/renv.lock
: run renv::init()
and/or renv::snapshot()
to capture dependencies in the renv.lock
file.Edit the .R
files as needed, add other scripts and data objects inside the app
folder (this is copied into the Docker image).
This workflow works with public and private repositories.
shiny-example
, if available, this will create the app at https://shiny-example.herokuapp.com/) to the app and create the app.HEROKU_EMAIL
: your Heroku email that you use to log inHEROKU_API_KEY
: your Heroku api key, you can find it under your personal settings, click on reveal and copySee the .github/workflows/deploy.yml
file for additional options (see also comments in the yaml file):
appdir
variable to e.g. _shinyapps/evalue
, this is the directory the script will use to find the Shiny files relative to the Dockerfile in the root of this directoryThe plan is to add multiple Shiny apps in the same GitHub repo, thus we need a mechanism that only deploys one app at a time. The solution is to make the GitHub action jobs conditional on certain words in the commit message. E.g. it only deploys if the message contains deploy evalue
.
When you add a new app, the Heroku email and API key will remain the same. You will have to add a new job to the deploy.yml
file, specify the trigger words, app directory, and app name.
Once the app is deployed, you can add a page and navigation entry for the new app as desired above.
Install jekyll (one time setup inside the directory): skip steps as appropriate, e.g. if you have Ruby installed etc (ruby -v
should return Ruby version). See more about Ruby and Jekyll installation here.
This will install jekyll to evalue_website/vendor
. Important: To avoid errors in bundle install
, the entire file path to ruby (which will be in evalue_website/vendor
) needs to not have spaces in the directory names. Change them to underscores before the installation.
# Install Command Line Tools
xcode-select --install
# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Ruby
brew install ruby
# Add the brew ruby path to your shell configuration:
PATH="`ruby -e 'puts Gem.user_dir'`/bin:$PATH"
# Install Jekyll
gem install --user-install bundler jekyll
# Install gems (dependencies) for the template
bundle install
When you edit your files and want to check locally how the site looks, first make sure you are in the top-level directory evalue_website
(where the jekyll files live) and then use this:
bundle exec jekyll serve
This will build the site that you can check at http://127.0.0.1:4000
in your browser. When you change the source it render the changes but you have to click refresh in the browser to see the changes. Stop the server with Ctrl+C in the command line.
bundle exec jekyll serve
fails with the error Configuration file: none
, you are probably not in the top-level directory evalue_website
.