Tips & tricks for making the most of GitHub
Contents:
Host static web pages for free!
- In the repository settings, scroll down to the GitHub Pages heading.
Under source, select the default branch (e.g.
master
ormain
) and select the/docs
folder. Then click theSave
button. - Put your HTML or markdown files in
/docs
. - Your webpages will appear at
https://your-username.github.io/repo-name/filename.html
.
- Pat has a custom domain set up for the lab, so pages from repos in
the
SchlossLab
GitHub Organization appear athttp://www.schlosslab.org/repo-name
.- e.g. the mikropml documentation appears at
http://www.schlosslab.org/mikropml/, and the source files are
in the
/docs
folder ofSchlossLab/mikropml
.
- e.g. the mikropml documentation appears at
http://www.schlosslab.org/mikropml/, and the source files are
in the
- In settings, choose a theme, then plain markdown (
.md
) files will automatically be styled and rendered to HTML. GitHub stores your theme setting in/docs/_config.yml
. - Create a file called
index.md
inside/docs
, and it will appear as the landing page athttps://your-username.github.io/repo-name
. (Must first choose a theme for.md
to render properly.) - To make a personal website, the repo must be named
your-username.github.io
.- Here’s mine: https://github.com/kelly-sovacool/kelly-sovacool.github.io
- If you own a custom domain, you can use it!
- Warning: the rendered web page will be public even if your repository is private.
Currently, GitHub shows HTML files in your repository in plain text. That makes sense if you’re a web developer and need to edit HTML manually. But if you’re rendering an R Markdown document to an HTML format, chances are you would much rather view the HTML in its prettier rendered form.
When you render an R Markdown file, use the option output_dir = "docs"
if you selected the /docs
directory as your webpage source. Example:
rmarkdown::render('reports/report.Rmd', output_dir = 'docs')
- The R Markdown source is
reports/report.Rmd
. - The HTML source (rendered from R Markdown) is
docs/report.html
. - The rendered HTML appears at http://www.schlosslab.org/gh-tips/report.html.
When using the xaringan
package to make slides with R Markdown:
- Put the R Markdown file in the same directory as the output HTML.
- Knit from the document directory (select the arrow to the right of the knit button).
- Set
self-contained: true
so the HTML output files will contain everything needed to render (including images).
Example:
- R Markdown Source:
docs/slides/example-slides.Rmd
- HTML Output:
docs/slides/example-slides.html
- Rendered HTML: http://www.schlosslab.org/gh-tips/slides/example-slides.html
Do things like run unit tests, render R Markdown documents, and more ✨ automagically ✨
All you need is a GitHub repo! Every workflow is a YAML file in
.github/workflows/
, and GitHub will automatically run the jobs in the
workflow depending on rules you specify.
-
Create
.github/workfows/demo.yml
:name: GitHub Actions Demo on: [push] jobs: Explore-GitHub-Actions: runs-on: ubuntu-latest steps: - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event." - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!" - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}." - name: Check out repository code uses: actions/checkout@v2 - run: echo "💡 The ${{ github.repository }} repository has been cloned to the runner." - run: echo "🖥️ The workflow is now ready to test your code on the runner." - name: List files in the repository run: | ls ${{ github.workspace }} - run: echo "🍏 This job's status is ${{ job.status }}."
-
Add, commit, & push it to GitHub.
git add .github/workflows/demo.yml git commit -m "Create GitHub Actions demo" git push
-
Wait for the workflow to run and take a look at the results under the Actions tab.
-
When a commit is pushed to any branch.
on: push
-
When a commit is pushed to a particular branch or branches.
on: push: branches: - main - another-branch-name
-
When a commit is pushed to a Pull Request against a particular branch.
on: pull_request: branches: - main
-
When certain files are modified.
on: push: paths: - *.R - *.Rmd - *.py
-
On a schedule (a.k.a. a cron job).
on: schedule: - cron: '0 0 * * 1' # every monday at midnight
- Reformat your code on every push.
- Check that an R package still works for every OS & the last 3 R versions.
- Render package documentation on every Pull Request.
- Compile a JOSS/JOSE paper.md as a PDF and upload as an artifact.
- Render an R Markdown document every Monday at 5am.
- You can only have one workflow that pushes commits to your repo.
- Use crontab guru to make sure your cron schedule does what you think it does.
- There’s a monthly wall time limit for private repos, but there’s no limit for public repos.
- The GitHub Docs: https://docs.github.com/en/actions
- Actions for R by RStudio: https://github.com/r-lib/actions
TODO
Open an Issue or submit a Pull Request on this repository!