Docs: Workflow & Style

- Updated author and date
- Fixed code errors in callout implementation
- Corrected the workflow file path
- Updated gitHub actions workflow: added the permissions section (bug PR #49, fixed at PR #52) and updated the action version (a newer version is availabile from PR #54)
- Clarified the instructions for configuring the repository before publishing
- Included alternative methods using the "Render" button or "Render on Save" option in RStudio, with a screenshot (added to assets)
- Added a reference link

.github/workflows/quarto-publish-example.yaml

@@ -0,0 +1,90 @@
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches: 
+      - main
+
+name: Render and Publish
+
+# you need these permissions to publish to GitHub pages
+permissions: 
+    contents: write
+    pages: write
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Publish to GitHub Pages (and render)
+        uses: quarto-dev/quarto-actions/publish@v2
+        with:
+          target: gh-pages
+          path: docs/_site
+          tinytex: true 
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # To install LaTeX to build PDF book 
+
+          # uncomment below and fill to pin a version
+          # version: SPECIFIC-QUARTO-VERSION-HERE
+
+      # add software dependencies here and any libraries
+
+      # From https://github.com/actions/setup-python
+      # - name: Setup Python
+      #   uses: actions/setup-python@v3
+
+      # From https://github.com/r-lib/actions/tree/v2-branch/setup-r
+      # - name: Setup R
+      #   uses: r-lib/actions/setup-r@v2
+
+      # From https://github.com/julia-actions/setup-julia
+      # - name: Setup Julia
+      #   uses: julia-actions/setup-julia@v1
+
+      # See more at https://github.com/quarto-dev/quarto-actions/blob/main/examples/example-03-dependencies.md
+
+      # To publish to Netlify, RStudio Connect, or GitHub Pages, uncomment
+      # the appropriate block below
+
+      # - name: Publish to Netlify (and render)
+      #   uses: quarto-dev/quarto-actions/publish@v2
+      #   with:
+      #     target: netlify
+      #     NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+
+      # - name: Publish to RStudio Connect (and render)
+      #   uses: quarto-dev/quarto-actions/publish@v2
+      #   with:
+      #     target: connect
+      #     CONNECT_SERVER: enter-the-server-url-here
+      #     CONNECT_API_KEY: ${{ secrets.CONNECT_API_KEY }} 
+
+      # NOTE: If Publishing to GitHub Pages, set the permissions correctly (see top of this yaml)
+      # - name: Publish to GitHub Pages (and render) 
+      #   uses: quarto-dev/quarto-actions/publish@v2
+      #   with:
+      #     target: gh-pages
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions
+
+      # - name: Publish to confluence
+      #   uses: quarto-dev/quarto-actions/publish@v2
+      #   with:
+      #     target: confluence
+      #   env: 
+      #     CONFLUENCE_USER_EMAIL: ${{ secrets.CONFLUENCE_USER_EMAIL }}
+      #     CONFLUENCE_AUTH_TOKEN: ${{ secrets.CONFLUENCE_AUTH_TOKEN }}
+      #     CONFLUENCE_DOMAIN: ${{ secrets.CONFLUENCE_DOMAIN }}
+
+      # Add comment to trigger yaml Action
+

docs/tutorials/github.qmd

@@ -1,8 +1,8 @@
 ---
 title: NHSE GitHub
 subtitle: "Version Control & Project Management"
-author: "Craig Robert Shenton"
-date: "2023-01-22"
+author: "Craig Robert Shenton / updated by: Chaeyoon Kim"
+date: "2024-07-01"
 categories: [Git, GitHub, NHS England]
 image: "../assets/logos/GitHub-logo.png"
 ---
@@ -24,7 +24,7 @@ Private repos are not visable for all members. To allow others to see private re
 
 :::
 
-::: {.callout-info}
+::: {.callout-tip}
 ## Moving GitHub Repositories to NHSE Organisation
 1. Ensure you're a member of the NHSE GitHub Organisation. If not, follow the instructions provided above to request access.
 2. Navigate to the settings of your repository and find the "Transfer" option in the Danger Zone.
@@ -45,7 +45,7 @@ Private repos are not visable for all members. To allow others to see private re
 
 Note that the [GitHub desktop app](https://desktop.github.com/) is available on Modern Desktop (see `Company Portal > Apps`) and can be installed on UDAL VMs. The tool greatly improves the Git experience and makes managing multiple software projects much easier.
 
-![](../assets/figures/github-desktop.png)
+![GitHub Desktop screenshot](../assets/figures/github-desktop.png)
 
 ## Resources
 
@@ -62,7 +62,7 @@ Publish a Quarto website project to your GitHub pages using GitHub actions.
 
 ### Add the GitHub Actions workflow to your project
 
-Copy [quarto-publish.yml](https://github.com/craig-shenton/nhs-r-reporting/blob/main/_assets/actions/quarto-publish-example.yml) to the folder `.github/workflows/quarto-publish.yml`.
+Copy [quarto-publish.yml](https://github.com/nhsengland/nhs-r-reporting/blob/main/.github/workflows/quarto-publish-example.yaml) to the folder `.github/workflows/quarto-publish-example.yaml`.
 
 ```yaml
 on:
@@ -73,12 +73,17 @@ on:
 
 name: Render and Publish
 
+# you need these permissions to publish to GitHub pages
+permissions: 
+    contents: write
+    pages: write
+
 jobs:
   build-deploy:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-latest    
     steps:
       - name: Check out repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
@@ -87,8 +92,10 @@ jobs:
         uses: quarto-dev/quarto-actions/publish@v2
         with:
           target: gh-pages
+          path: docs/_site
+          tinytex: true 
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
 ::: {.callout-note}
@@ -111,12 +118,16 @@ Do *not* edit the `GITHUB_TOKEN` to add a personal secret to this file. This fil
 
 ### Configure the repository before publishing
 
-Quarto needs to configure the repository for publishing through GitHub Actions. To do this, run `quarto publish gh-pages` locally once.
+Quarto needs to configure the repository for publishing through GitHub Actions. To do this, run `quarto publish gh-pages` locally once. Make sure you're running the command from within the working directory of your Quarto project in RStudio. You can verify the working directory by checking the top left corner of the R console window. If necessary, use the setwd() function in R or find the menu `Session > Set Working Directory > Choose Directory` to change the working directory to your project location.
+
+You can also use the *Render* button, or check the *Render on Save* option on the editor toolbar:
+
+![RStudio editor toolbar](../assets/figures/rstudio-editor-toolbar.png)
 
 ### Commit and push the workflow
 
 Now, add and commit the workflow file you have just created, and push the result to GitHub. This should trigger a new action from GitHub that will automatically render and publish your website through GitHub pages.
 
 ::: {.callout-note}
-Note that GitHub Pages uses a `gh-pages` branch in your repository, which will be automatically created if one doesn't exist.
+Note that GitHub Pages uses a `gh-pages` branch in your repository, which will be automatically created if one doesn't exist. Read more: [Publishing - GitHub Pages](https://quarto.org/docs/publishing/github-pages.html)
 :::