The markbind-action workflow should not always force push

[dcshzj]

Is your request related to a problem?

Currently, the markbind-action workflow force-pushes to the gh-pages branch every time it is executed.

It would be ideal to allow the user to determine if they wish to force push to the gh-pages branch or to retain the history of the gh-pages branch. It may be useful in some cases where the user wishes to see the changes in the output HTML as a Git diff.

Describe the solution you'd like

An additional configuration setting can be added to modify the behaviour of the workflow. As force-pushing is irreversible, the default behaviour should be to retain the history, but allow the user to set this configuration setting to enable force-pushing.

[raysonkoh]

@dcshzj Thanks for the issue submission!

A related issue might be #1432 , where the goal is to have a markbind deploy --ci command that deploys to various CI environments (including Github Actions). Using this approach, the commit history in the gh-pages branch will be retained. This is currently being worked on in PR #1460.

Once the basic functions of markbind deploy --ci is ready I think it would replace the function of markbind-action. @ang-zeyu please correct me if I'm wrong 😅.

[ang-zeyu]

Once the basic functions of markbind deploy --ci is ready I think it would replace the function of markbind-action. @ang-zeyu please correct me if I'm wrong 😅.

Hmm we could also extend markbind-action with #1009 in the future to support some sort of "auto-archive on release" workflow, until then, it would really only do what markbind deploy --ci does.

"auto-archive on release"

Once this is done we could also adapt the implementation there to use the same markbind deploy --ci approach as well

ps: the markbind-action PR hasn't been merged in yet #1426 actually, though it seems to have been published. I've marked it as pre-release.

You could manually chain markbind build and something like https://github.com/marketplace/actions/deploy-to-github-pages in the meantime to get around this

[tlylt]

I think having a force-push (or rather, keep-history) option is definitely useful.
Perhaps something similar to the crazy-max/ghaction-github-pages@v2 that is being used in the RepoSense workflow file to deploy their documentation with GitHub Pages.

    - name: Install MarkBind CLI
      run: npm i -g markbind-cli

    - name: Build MarkBind website
      run: cd docs && markbind build --baseUrl /RepoSense

    - name: Deploy to GitHub Pages
      if: success()
      uses: crazy-max/ghaction-github-pages@v2
      with:
        target_branch: gh-pages
        build_dir: docs/_site
        keep_history: true
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

perhaps if we can settle the following two points:

• specify MarkBind version
• a keep-history option

it might be good enough to highlight its usage in our documentation.
The auto-archive on release feature could be an improvement over the baseline version.