[RFC] GitHub actions

[tlienart]

I have tested the steps below but would like to check with others to ensure it works for all. Also if you do it on a test repo, it would be great if you could add me as collaborator so that I can try to trigger an update (without having set up the secrets myself) and check that that works too (sorry I'm still a bit new to this Github actions business).

Thanks a lot!

(cross ref: #379)

Below I assume you already have a local folder that works with Franklin.

Project website

This is for a repo username/repo which will lead to the page username.github.io/repo/.

1 Generate a key

In your terminal

ssh-keygen -N "" -f franklin

This will create two files franklin and franklin.pub.

2 Github settings

1. go to github.com/username/repo/settings/keys
2. click on Add deploy key and name it FRANKLIN (it doesn't matter)
3. copy the content of the franklin.pub file created earlier, one way to do so in your terminal:
   • cat franklin.pub and copy the result without whitespaces
   • on mac, cat franklin.pub | pbcopy copies the content directly to your clipboard
4. paste that in the appropriate box of the deploy key page on github
5. go to github.com/username/repo/settings/secrets
6. click on Add a new secret and name it DEPLOY_KEY (it does matter)
7. copy the content of the franklin file created earlier and paste it in the box

You can now remove the two files created:

rm franklin
rm franklin.pub

3 Deploy action

Edit your .github/workflows/deploy.yml file (or create one if you don't have one already) to the following:

name: Build and Deploy
on:
  push:
    # NOTE: For a **project** site (username.github.io/project/), push things
    # to the **master** branch and make sure to set the line below to
    # `- master`; also, at the end of the file, change to `BRANCH: gh-pages`
    # For a **personal** site (username.github.io/), push things to a **dev**
    # branch  and make sure to set the line  below to `- dev` this is because
    # for user pages GitHub pages **requires** the deployment to be on the
    # master branch; also, at the end of the file, change to `BRANCH: master`
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v2
      with:
        persist-credentials: false
    - name: Install SSH Client
      uses: webfactory/ssh-agent@v0.2.0
      with:
        ssh-private-key: ${{ secrets.DEPLOY_KEY }}
    # Python is necessary for pre-rendering steps as well as to install
    # matplotlib which is necessary if you intend to use PyPlot. If you do
    # not, then you can remove the `run: pip install matplotlib` line.
    - name: Install python
      uses: actions/setup-python@v1
      with:
        python-version: '3.x'
    - run: pip install matplotlib # if you use PyPlot this is needed
    - name: Install Julia
      uses: julia-actions/setup-julia@v1
      with:
        version: 1.3.0
    # This ensures that NodeJS and Franklin are loaded then it installs
    # highlight.js which is needed for the prerendering step.
    # Then the environment is activated and instantiated to install all
    # Julia packages which may be required to successfully build your site.
    # NOTE: the last line should be `optimize()`, you may want to give it
    # specific arguments, see the documentation or ?optimize in the REPL.
    - run: julia -e '
            using Pkg; Pkg.add(["NodeJS", "Franklin"]);
            using NodeJS; run(`$(npm_cmd()) install highlight.js`);
            using Franklin;
            Pkg.activate("."); Pkg.instantiate();
            optimize()'
    - name: Build and Deploy
      uses: JamesIves/github-pages-deploy-action@releases/v3
      with:
        SSH: true
        # Set this to `BRANCH: gh-pages` for a **project** page and  to
        # `BRANCH: master` for a **personal** page
        BRANCH: gh-pages
        FOLDER: __site

you can also edit your .gitignore and add __site/ to it.

Now push all this (on master). Your site should appear in a couple of minutes.

Personal website

This is for a repo username/username.github.io which will lead to the page username.github.io/.

The steps (1) and (2) are the same as for the project pages.

(2b) Setting up the branches

For a personal page, your source files must be on a dev branch, the master branch is only used for deployment. To do this:

git checkout -b dev
git add -A && git commit -am "moving files" && git push -u origin dev
git checkout master

Clear everything apart from the .git folder, either manually or for instance with rm -r !(.git) and push that cleared branch.

git add -A && git commit -am "cleaning  up" && git push

Then get back to the dev branch and use only that one.

git checkout  dev

3 Deploy action

Edit your .github/workflows/deploy.yml file (or create one if you don't have one already) to the following; there are two differences:

1. trigger on push to dev
2. deploy to master

name: Build and Deploy
on:
  push:
    # NOTE: For a **project** site (username.github.io/project/), push things
    # to the **master** branch and make sure to set the line below to
    # `- master`; also, at the end of the file, change to `BRANCH: gh-pages`
    # For a **personal** site (username.github.io/), push things to a **dev**
    # branch  and make sure to set the line  below to `- dev` this is because
    # for user pages GitHub pages **requires** the deployment to be on the
    # master branch; also, at the end of the file, change to `BRANCH: master`
    branches:
      - dev
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v2
      with:
        persist-credentials: false
    - name: Install SSH Client
      uses: webfactory/ssh-agent@v0.2.0
      with:
        ssh-private-key: ${{ secrets.DEPLOY_KEY }}
    # Python is necessary for pre-rendering steps as well as to install
    # matplotlib which is necessary if you intend to use PyPlot. If you do
    # not, then you can remove the `run: pip install matplotlib` line.
    - name: Install python
      uses: actions/setup-python@v1
      with:
        python-version: '3.x'
    - run: pip install matplotlib # if you use PyPlot this is needed
    - name: Install Julia
      uses: julia-actions/setup-julia@v1
      with:
        version: 1.3.0
    # This ensures that NodeJS and Franklin are loaded then it installs
    # highlight.js which is needed for the prerendering step.
    # Then the environment is activated and instantiated to install all
    # Julia packages which may be required to successfully build your site.
    # NOTE: the last line should be `optimize()`, you may want to give it
    # specific arguments, see the documentation or ?optimize in the REPL.
    - run: julia -e '
            using Pkg; Pkg.add(["NodeJS", "Franklin"]);
            using NodeJS; run(`$(npm_cmd()) install highlight.js`);
            using Franklin;
            Pkg.activate("."); Pkg.instantiate();
            optimize()'
    - name: Build and Deploy
      uses: JamesIves/github-pages-deploy-action@releases/v3
      with:
        SSH: true
        # Set this to `BRANCH: gh-pages` for a **project** page and  to
        # `BRANCH: master` for a **personal** page
        BRANCH: master
        FOLDER: __site

you can also edit your .gitignore and add __site/ to it.

Now push all this (on dev). Your site should appear in a couple of minutes.

Finally

It's helpful to change the default branch for the repo on Github by doing: Settings > Branches, pick dev and Update.

Feedback

Let me know if it works for you, if you think some steps can be simplified / better explained etc.

Thanks!

Edit: notes to self:

• lunr hook is missing, basically it should not be optimize the last step but rather something like publish (maybe named deploy) without the git operations.
• removed node-setup since NodeJS.jl installs its own version (thanks to Eric Hanson)

[tlienart]

Ok I've now gotten a bit of feedback and done a fair bit of testing on my side with different github accounts, this seems to work fine so I'll push it to the Franklin templates & will release all this soon.

[movvam]

Do these steps work with themes? I followed the project site steps and here is what I see as compared to locally with serve()

https://movvam.github.io/Notepad/

localhost

Any ideas what I've done wrong?

[tlienart]

Did you add @def prepath = "Notepad" in your config.md ? (I'm almost sure that's the issue, basically it's because your root is not movvam.github.io but actually movvam.github.io/Notepad to specify this you need to set prepath in your config.

Edit: I really need to put the content of the post here in the docs & clarify this prepath thing 🙈

Edit: :+1: for "Big Boi Movva"

[movvam]

Did you add @def prepath = "Notepad" in your config.md ?

This fixed it, thanks!

Edit: 👍 for "Big Boi Movva"

😂that's the result of a chrome extension I made that changes "mani" to "big boi" (It's fun until you're printing out an essay and it says Big Boi on the paper)

[tlienart]

Instructions now updated thanks to @kescobo see https://franklinjl.org/workflow/deploy/ ; will close this now.