New section on previews using GH Actions + update outdated deployment workflows

README.md

@@ -82,6 +82,7 @@ Some examples of websites using Franklin (_if you're using Franklin with a publi
 * [@abhishalya's website](https://abhishalya.github.io) using a custom minimalistic theme ([repo](https://github.com/abhishalya/abhishalya.github.io))
 * [JuliaCon's website](https://juliacon.org) using Franklin and Bootstrap ([repo](https://github.com/JuliaCon/www.juliacon.org))
 * [JuliaGPU's website](https://juliagpu.org) using Franklin and a custom template ([repo](https://github.com/JuliaGPU/juliagpu.org))
+* [FluxML's website](https://fluxml.ai) was migrated from jekyll (including the blogs and tutorials) ([repo](https://github.com/FluxML/fluxml.github.io))
 
 
 ## Getting started

docs/workflow/deploy.md

@@ -33,7 +33,7 @@ Your site should now be live, with the index page appearing at `http://my.exampl
 Start by creating an empty GitHub repository
 
 @@tlist
-* for a personal (or org) website the repository **must** be named `username.github.io` (or `orgname.github.io`) see also [the Github pages docs](https://pages.github.com/),
+* for a personal (or org) website the repository **must** be named `username.github.io` (or `orgname.github.io`) see also [the Github pages docs](https://pages.github.com/).
 * for a project website the repo can be named anything you want, let's say `myWebsite`.
 @@
 
@@ -102,6 +102,18 @@ You might want to customise the GitHub action for instance:
 For all such operations, modify the file `.github/workflows/deploy.yml` in your site folder.
 It should be fairly straightforward to see how to extend it but if you get stuck, ask on the **#franklin** slack channel.
 
+### Migrating to the new GitHub Pages infrastructure
+
+GitHub Pages has a whole new revamped infrastructure and workflow that does not require maintaining
+an extra `gh-pages` branch. The `gh-pages`/`gh-previews` would still be required if you have PR previews
+on for your project  (more about this in the "Previewing Pull Requests" section below). Read more
+about how you can migrate your current infrastructure to the new format -
+
+@@tlist
+- [github pages official docs](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll)
+- [new workflow examples](https://github.com/actions/starter-workflows/tree/main/pages)
+@@
+
 ### Troubleshooting
 
 If something failed, that you can't debug, ask on the **#franklin** slack channel explaining what's the issue and we'll try to help you out.
@@ -146,7 +158,7 @@ That's it!
 
 ## Previewing Pull Requests
 
-You can easily visualize the effect of a pull request on your website without having to serve it locally by using Netlify.
+You can easily visualize the effect of a pull request on your website without having to serve it locally by using GitHub Pages or Netlify.
 To do this you need to change a couple of things.
 Assuming that you use Github Actions to deploy your website, you need to change your `deploy.yml` file to make builds from PRs.
 First change:
@@ -171,6 +183,16 @@ on:
 This means that each time a PR will be opened, a "preview" website will be generated and updated by the GitHub action.
 
 Then we need to properly set up a local folder for each website generated by a PR.
+
+### Netlify
+
+Netlify can be used to deploy PR previews if you want to store the previews
+and the original rendered website in different git branches. We use a separate
+platform for previews, as GitHub allows you to deploy only one git branch at a time.
+
+Have a look at the next (GitHub Pages) sub-section if you want to deploy both
+the previews and the website on GitHub Pages.
+
 After the `Checkout` action add the following:
 
 ```yml
@@ -188,39 +210,110 @@ Finally, we want to deploy the main website and the PR preview on different bran
 ```yml
 - name: Deploy (preview)
   if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name # if this build is a PR build and the PR is NOT from a fork
-  uses: JamesIves/github-pages-deploy-action@releases/v3
+  uses: JamesIves/github-pages-deploy-action@releases/v4
   with:
-      BRANCH: gh-preview # The branch where the PRs previews are stored
-      FOLDER: __site
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      TARGET_FOLDER: "previews/PR${{ github.event.number }}" # The website preview is going to be stored in a subfolder
+      branch: gh-preview # The branch where the PRs previews are stored
+      folder: __site
+      token: ${{ secrets.GITHUB_TOKEN }}
+      target-folder: "previews/PR${{ github.event.number }}" # The website preview is going to be stored in a subfolder
 - name: Deploy (main)
   if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
-  uses: JamesIves/github-pages-deploy-action@releases/v3
+  uses: JamesIves/github-pages-deploy-action@releases/v4
   with:
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      BRANCH: gh-pages # Replace here the branch where your website is deployed
-      FOLDER: __site
+      token: ${{ secrets.GITHUB_TOKEN }}
+      branch: gh-pages # Replace here the branch where your website is deployed
+      folder: __site
 ```
 
 Now to avoid problems with the subfolder structure of our website we need to make a small change to our `config.md` file.
 Change the following lines
-```julia
-@def prepath     = "myprepath" # This is possibly "" for your case
-@def website_url = "mywebsite.github.io"
+```markdown
++++
+prepath     = "myprepath" # This is possibly "" for your case
+website_url = "mywebsite.github.io"
++++
 ```
 to
-```julia
-@def prepath     = get(ENV, "PREVIEW_FRANKLIN_PREPATH", "myprepath") # In the third argument put the prepath you normally use
-@def website_url = get(ENV, "PREVIEW_FRANKLIN_WEBSITE_URL", "mywebsite.github.io") # Just put the website name
+```markdown
++++
+prepath     = get(ENV, "PREVIEW_FRANKLIN_PREPATH", "myprepath") # In the third argument put the prepath you normally use
+website_url = get(ENV, "PREVIEW_FRANKLIN_WEBSITE_URL", "mywebsite.github.io") # Just put the website name
++++
 ```
 
 Now for the final step, you will need to visualize the obtained previews.
-Since Github only allow you to deploy one branch, you will need an alternative like Netlify.
 Create an account on [Netlify.com](https://www.netlify.com/), add your repository and chose the `gh-preview` branch without any additional settings.
 Set your Netlify website to be `{netlify name}.netlify.app`.
 
 Once everything is set up you will be able to visualize your PR preview on `{netlify name}.netlify.app/previews/PR{number of your PR}`.
+
+### GitHub Pages
+
+GitHub pages can also be used to deploy PR previews, but you will need to store the
+previews and the original rendered website in a single git branch. The previews will
+be stored in a sub-folder inside your generated website; hence, make sure this
+folder's name (the folder where previews are stored) does not conflict with an
+existing folder in your website.
+
+In the workflows below, we use a folder named "previews" to store the PR previews.
+
+After the `Checkout` action add the following:
+
+```yml
+- name: Fix URLs for PR preview deployment (pull request previews)
+  if: github.event_name == 'pull_request'
+  run: | # "previews" below is the folder name where your PR previews are stored
+    echo "PREVIEW_FRANKLIN_WEBSITE_URL=https://{github username}.github.io/previews/PR${{ github.event.number }}/" >> $GITHUB_ENV
+    echo "PREVIEW_FRANKLIN_PREPATH=previews/PR${{ github.event.number }}" >> $GITHUB_ENV
+```
+where `{github username}` is your GitHub username.
+The first line keeps track of the URL where the preview will be available.
+the second line only keeps track of the "prepath" of that preview URL so that it can be passed to Franklin.
+
+Finally, we want to deploy the main website and the PR preview on the same branch (but different folders):
+```yml
+- name: Deploy (preview)
+  if: github.event_name == 'pull_request' && github.repository == github.event.pull_request.head.repo.full_name # if this build is a PR build and the PR is NOT from a fork
+  uses: JamesIves/github-pages-deploy-action@releases/v4
+  with:
+      branch: gh-pages # The branch where your website is deployed
+      folder: __site
+      token: ${{ secrets.GITHUB_TOKEN }}
+      target-folder: "previews/PR${{ github.event.number }}" # The website preview is going to be stored in the previews subfolder
+- name: Deploy (main)
+  if: github.event_name == 'push' && github.ref == 'refs/heads/dev'
+  uses: JamesIves/github-pages-deploy-action@releases/v3
+  with:
+      token: ${{ secrets.GITHUB_TOKEN }}
+      branch: gh-pages # Replace here the branch where your website is deployed
+      folder: __site
+      clean-exclude: |  # This makes sure that the previews are not wiped out during regular builds 
+        previews/*
+```
+
+Now to avoid problems with the subfolder structure of our website we need to make a small change to our `config.md` file.
+Change the following lines
+
+```markdown
++++
+prepath     = "myprepath" # This is possibly "" for your case
+website_url = "mywebsite.github.io"
++++
+```
+to
+```markdown
++++
+prepath     = get(ENV, "PREVIEW_FRANKLIN_PREPATH", "myprepath") # In the third argument put the prepath you normally use
+website_url = get(ENV, "PREVIEW_FRANKLIN_WEBSITE_URL", "mywebsite.github.io") # Just put the website name
++++
+```
+
+Once everything is set up you will be able to visualize your PR preview on `{github username}.github.io/previews/PR{number of your PR}`.
+
+For a live demo of PR previews deployed using GitHub Pages, have a look at [FluxML's website](https://fluxml.ai) ([repo](https://github.com/FluxML/fluxml.github.io))!
+
+### PR Comments
+
 You can make things easier for your contributors to access it by adding a comment with a link to your PR automatically.
 To do this add the following Github action (create a `pr_comment.yml` file in `.github/workflows/`):
 ```yml

docs/workflow/index.md

@@ -200,7 +200,9 @@ See `?publish` for more information.
 In any case, before deploying, if you're working on a _project website_ i.e. a website whose root URL will look like `username.gitlab.io/project/` then you should add the following line in your `config.md` file:
 
 ```markdown
-@def prepath = "project"
++++
+prepath = "project"
++++
 ```
 
 the `publish` function will then ensure that all links are fixed before deploying your website.