This repo and GitHub Action was based on the tutorial by Openscapes quarto-website-tutorial by Julia Lowndes and Stefanie Butland.
+ + + +Edit the qmd or md files in the content folder. qmd files can include code (R, Python, Julia) and lots of Quarto markdown bells and whistles (like call-outs, cross-references, auto-citations and much more).
Each page should start with
+---
+title: your title
+---and the first header will be the 2nd level, so ##. Note, there are situations where you leave off
---
+title: your title
+---and start the qmd file with a level header #, but if using the default title yaml (in the --- fence) is a good habit since it makes it easy for Quarto convert your qmd file to other formats (like into a presentation).
_quarto.ymlYou can have code (R, Python or Julia) in your qmd file. You will need to have these installed on your local computer, but presumably you do already if you are adding code to your qmd files.
+x <- c(5, 15, 25, 35, 45, 55)
+y <- c(5, 20, 14, 32, 22, 38)
+lm(x ~ y)
+Call:
+lm(formula = x ~ y)
+
+Coefficients:
+(Intercept) y
+ 1.056 1.326 You will need to change the GitHub Action in .github/workflows to install these and any needed packages in order for GitHub to be able to render your webpage. The GitHub Action install R since I used that in code.qmd. If you use Python or Julia instead, then you will need to update the GitHub Action to install those.
If getting the GitHub Action to work is too much hassle (and that definitely happens), you can alway render locally and publish to the gh-pages branch. If you do this, make sure to delete or rename the GitHub Action to something like
render-and-publish.old_ymlso GitHub does not keep trying to run it. Nothing bad will happen if you don’t do this, but if you are not using the action (because it keeps failing), then you don’t need GitHub to run it.
+To render locally and push up to the gh-pages branch, open a terminal window and then cd to the directory with the Quarto project. Type this in the terminal:
quarto render gh-pagesQuarto allow many bells and whistles to make nice output. Read the documentation here Quarto documentation.
+Looking at other people’s Quarto code is a great way to figure out how to do stuff. Most will have a link to a GitHub repo where you can see the raw code. Look for a link to edit page or see source code. This will usually be on the right. Or look for the GitHub icon somewhere.
+documentation directory.To get your Quarto webpage to show up with the url
+yourname.github.io/yourrepoyou have a few steps.
+The GitHub Action will automatically recreate your website when you push to GitHub after you do the initial gh-pages set-up
gh-pagesThe first time you publish to gh-pages, you need to do so locally.
cd to your repo directory. Here is what that cd command looks like for me. You command will look different because your local repo will be somewhere else on your computer.cd ~/Documents/GitHub/NOAA-quarto-simplegh-pages. In the terminal typequarto publish gh-pagesThis is going to render your webpage and then push the _site contents to the gh-pages branch.
gh-pages?In some cases, you don’t want your website on the gh-pages branch. For example, if you are creating releases and you want the website pages archived in that release, then you won’t want your website pages on the gh-pages branch.
Here are the changes you need to make if you to avoid gh-pages branch.
_quarto.yml add the following:project:
+ type: website
+ output-dir: docsmain branch and the docs directory.docs is not listed in .gitignorequarto publish from the terminalquarto publish gh-pages. You’ll need to push to the main branch yourself (in the GitHub Action)on:
+ push:
+ branches: main
+
+name: Render and Publish
+
+jobs:
+ build-deploy:
+ runs-on: ubuntu-latest
+ env:
+ GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@v2
+
+ - name: Set up R (needed for Rmd)
+ uses: r-lib/actions/setup-r@v2
+
+ - name: Install packages (needed for Rmd)
+ run: Rscript -e 'install.packages(c("rmarkdown", "knitr", "jsonlite"))'
+
+ - name: Set up Quarto
+ uses: quarto-dev/quarto-actions/setup@v2
+ with:
+ # To install LaTeX to build PDF book
+ # tinytex: true
+ # uncomment below and fill to pin a version
+ # version: 0.9.600
+
+ - name: Render Quarto Project
+ uses: quarto-dev/quarto-actions/render@v2
+ with:
+ to: html
+
+ - name: Set up Git
+ run: |
+ git config --local user.email "actions@github.com"
+ git config --local user.name "GitHub Actions"
+
+ - name: Commit all changes and push
+ run: |
+ git add -A && git commit -m 'Build site' || echo "No changes to commit"
+ git push origin || echo "No changes to commit"The repo includes a GitHub Action that will render (build) the website automatically when you make changes to the files. It will be pushed to the gh-pages branch.
But when you are developing your content, you will want to render it locally.
+Have you updated RStudio since about August 2022? No? Then update to a newer version of RStudio. In general, you want to keep RStudio updated and it is required to have a recent version to use Quarto.
+First, clone the repo onto your local computer. How? You can click File > New Project and then select “Version Control”. Paste in the url of the repository. That will clone the repo on to your local computer. When you make changes, you will need to push those up.
+RStudio will recognize that this is a Quarto project by the presence of the _quarto.yml file and will see the “Build” tab. Click the “Render website” button to render to the _site folder.
Previewing: You can either click index.html in the _site folder and specify “preview in browser” or set up RStudio to preview to the viewer panel. To do the latter, go to Tools > Global Options > R Markdown. Then select “Show output preview in: Viewer panel”.
You can include R Markdown files in your project.
+This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see http://rmarkdown.rstudio.com.
+When you click the Knit button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:
+summary(cars) speed dist
+ Min. : 4.0 Min. : 2.00
+ 1st Qu.:12.0 1st Qu.: 26.00
+ Median :15.0 Median : 36.00
+ Mean :15.4 Mean : 42.98
+ 3rd Qu.:19.0 3rd Qu.: 56.00
+ Max. :25.0 Max. :120.00 You can also embed plots, for example:
+
Note that the echo = FALSE parameter was added to the code chunk to prevent printing of the R code that generated the plot.
A simple Quarto webpage with a book layout
+This is a template for a simple Quarto website that looks like a “book”. This is a common format for documentation. It includes a GitHub Action that will build the website automatically when you make changes to the files. The NOAA palette and fonts has been added to theme.scss. The webpage will be on the gh-pages branch. Serving the website files from this branch is a common way to keep all the website files from cluttering your main branch.
The GitHub Action installs R so you can have R code in your qmd or Rmd files. Note, you do not need to make changes to your Rmd files unless your need Quarto features like cross-references.
+Click the green “use template” button to make a repository with this content. Make sure to make your repo public (since GitHub Pages doesn’t work on private repos unless you have a paid account) and check box to include all the branches (so that you get the gh-pages branch). 
Turn on GitHub Pages under Settings > Pages . You will set pages to be made from the gh-pages branch and root directory. 
Turn on GitHub Actions under Settings > Actions > General 
Edit the repo description and Readme to add a link to the webpage. When you edit the description, you will see the link url in the url box or you can click on the Actions tab or the Settings > Pages page to find the url.
^Y;6d
zt5{am8&slrmZ)@9)&te@Mzn7ne@jH^6YF^%+J$nZ@QvF@)f4d$Mu{kHiGokD=fkot
zc-f)ZG>MqkV+N)>0$Z(%XJc-Gy%laOBuMt%cEZ)+PvHM!dt%?|=ds@VSe+r{tNyjo
zgF@pm!l?ne7o1u)8#UjqnNU4}xiC5z`6*I|mTVqZ`4nBvw!Ai7NA{P6IiGCdTyQR&
zpyMf0%%RG&dgRf{I@PexZC|_bM^abHGqp}<=^oEtb^F+u|KrZg6|cMHUeOrQ{Ez|B
z8|bk$dC`Otx{Z`DZuv<t>Oq`{wpxx?vv*rF7706W
zCG?u|Jq0gue+c#gyfI+UCP;VMW7B5+K|1>*=mJMTq0&_2{MQZjJMuT#41Al__)(@V
zPqC}xxGgIk^2=A1f>J4