Improve examplary YAML file and correct typos (#83)

Co-authored-by: Christophe Dervieux <[email protected]>

Author: jakobarendt

README.md

@@ -2,21 +2,21 @@
 
 This repository stores [Github Actions](https://github.com/features/actions) useful for building and publishing [Quarto](https://quarto.org/) documents.
 
-1. [quarto-dev/quarto-actions/setup](https://github.com/quarto-dev/quarto-actions/tree/main/setup) - Install Quarto
-2. [quarto-dev/quarto-actions/render](https://github.com/quarto-dev/quarto-actions/tree/main/render) - Render project
-3. [quarto-dev/quarto-actions/publish](https://github.com/quarto-dev/quarto-actions/tree/main/publish) - Publish project
+1. [quarto-dev/quarto-actions/setup](./setup) - Install Quarto
+2. [quarto-dev/quarto-actions/render](./render) - Render project
+3. [quarto-dev/quarto-actions/publish](./publish) - Publish project
 
 We recommend using `v2` for your actions, and our examples all use `v2`.
 
 ## Examples
 
-In [Examples](./examples), you will find some YAML workflow files to serve as templates to be reused as a base for your project. We are also sharing some links to real example Github repositories using Quarto with Github Actions for rendering and deploying documents and projects. If you want to add your repository in the list, we welcome a PR.
+In [Examples](./examples), you will find a YAML workflow file to serve as a template to be reused as a base for your project. We are also sharing some links to real example Github repositories using Quarto with Github Actions for rendering and deploying documents and projects. If you want to add your repository in the list, we welcome a PR.
 
 ## Release Management
 
 This repository uses [GitHub's recommended release management for actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions#using-release-management-for-actions): 
 
 * GitHub releases with tags are used for updates on the actions. 
 * Semantic versioning is used, with major, minor and possibly patch release. 
-* Major versions (such as `v1`) will always point to the last minor or patch release for this major version. (when `v1.0.2` is out, `v1` will point to this update to). This means using `quarto-dev/quarto-actions/setup@v2` in your workflow file will automatically get the updated versions. Using `quarto-dev/quarto-actions/[email protected]` will pin a specific release.
+* Major versions (such as `v1`) will always point to the last minor or patch release for this major version. (when `v1.0.2` is out, `v1` will point to this update, too). This means using `quarto-dev/quarto-actions/setup@v2` in your workflow file will automatically get the updated versions. Using `quarto-dev/quarto-actions/[email protected]` will pin a specific release.
 * Major version changes (`v1` to `v2`) will often come with breaking changes, and workflows might require manual updates.

examples/example-01-basics.md

@@ -6,7 +6,7 @@ The simplest workflow using Quarto Actions uses the `setup` and `publish` action
 
 1. **Add the GitHub Actions workflow to your project**
 
-   Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to GitHub Pages (and render)" action. No further changes are needed to the action (in particular, do *not* edit the line below to add a secret to this file. This file has the same permissions as your repository, and might be publicly readable)
+   Copy [quarto-publish-example.yml](quarto-publish-example.yml) to `.github/workflows/quarto-publish.yml`. Uncomment the "Publish to GitHub Pages (and render)" action. Do *not* edit the line below to add a secret to this file. Also uncomment the minimum required access permissions; a general change in your repository's settings for GitHub actions permissions is **not needed**.
 
 2. **run `quarto publish gh-pages` locally, once**
 

examples/quarto-publish-example.yml

@@ -12,6 +12,7 @@ name: Render and Publish
 jobs:
   build-deploy:
     runs-on: ubuntu-latest
+    
     steps:
       - name: Check out repository
         uses: actions/checkout@v4

publish/README.md

@@ -5,7 +5,7 @@ Give this token a memorable name, and note the resulting string (or keep this wi
 
 2. Add Netlify auth token to your repository's secrets. Go to the repository that will be using this GHA. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use `NETLIFY_AUTH_TOKEN`, and for the "Value" field, paste the string you got from step 1.
 
-3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml) as an example).
+3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](../examples/quarto-publish-example.yml) as an example).
 
 4. Add `_publish.yml` to your repository. Quarto stores publishing metadata information in `_publish.yml`. To create this file, run `quarto publish netlify` locally once.
 
@@ -21,7 +21,7 @@ Give this token a memorable name, and note the resulting string (or keep this wi
 
 ## GitHub Pages
 
-1. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml) as an example).
+1. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](../examples/quarto-publish-example.yml) as an example).
 
 2. Head over to your repository on GitHub. Under Settings > Pages > Build and deployment, under source, ensure **Deploy from a branch** is selected. Under the branch option, select the root of the gh-pages branch.
 
@@ -34,6 +34,15 @@ Give this token a memorable name, and note the resulting string (or keep this wi
      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
+   ```
+
+5. Configure the minimum required access for the `publish` action to function (see also [quarto-publish-example.yml]()). Add these two lines below and on the same level of indentation as `runs-on:`:
+
+   ```yaml
+   permissions:
+     contents: write
    ```
 
 ## Posit Connect
@@ -42,7 +51,7 @@ Give this token a memorable name, and note the resulting string (or keep this wi
 
 2. Add Posit Connect auth token to your GitHub repository. Go to the GitHub webpage for the repository that will be using this GitHub Action. Click on "Settings". On the new page, click on "Secrets", then on the dropdown "Actions". Now, on the right-hand tab, click on the "New repository secret" button to the right of the title "Actions secrets". For the "Name" field, use `CONNECT_API_KEY`, and for the "Value" field, paste the string you got from step 1.
 
-3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](https://github.com/quarto-dev/quarto-actions/blob/main/examples/quarto-publish-example.yml) as an example).
+3. Add the GitHub Actions workflow to your project. (Use [quarto-publish-example.yml](../examples/quarto-publish-example.yml) as an example).
 
 4. Add `_publish.yml` to your repository. Quarto stores publishing metadata information in `_publish.yml`. To create this file, run `quarto publish connect` locally once.