Deploying to github User and Organization pages using Actions

[lasarojc]

I would like to offer an action to publish to gh-pages User and Organization, to complement what is in mkdocs-material/docs/publishing-your-site.md. The following action is probably more convoluted than it needs to be, but is a working example. It builds when you push to the source branch and pushes the built site to the master branch, which GH will copy to ghpages and publish.

name: ci
on:
  push:
    branches:
      - source
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: setup python
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
        persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal token
        fetch-depth: 0 # otherwise, you will failed to push refs to dest repo

    - name: install material
      run: |
           pip install mkdocs-material
           pip install python-markdown-math

    - name: Checkout ref branch
      uses: actions/checkout@v2
      with:
         ref: source
         path: source-branch

    - name: Checkout master branch
      uses: actions/checkout@v2
      with:
         ref: master
         path: master-branch

    - name: Create local changes and commit
      run: |
           cd source-branch
           mkdocs build -d ../master-branch
           cd ../master-branch
           git config --local user.email "github-actions@github.com"
           git config --local user.name "github-actions"
           git add -A
           git commit -m "Add changes"
           git push

Improvements welcome.

Caveat: it does not support the draw-io-exporter plugin :(

[squidfunk]

Thanks for providing the action! Could you elaborate on this example?

1. What is different from the GitHub Action that is listed in the docs?
2. Are there other requirements for publishing to GitHub Pages from organizations?

[lasarojc]

Sure. There is a good explanation of the two kinds of gh projects, i.e., projects and user/organizations here: https://www.mkdocs.org/user-guide/deploying-your-docs/ In essence, in projects, you can save the sources to master but push the built site to the gh-pages branch, which is what the already listed action does. In user/org, you need to push the built site to the master branch instead. But, now that you made me really think about it, I guess we could just use the original action but extended with --remote-branch master option Lásaro

…

On Thu, Feb 11, 2021 at 9:28 AM Martin Donath ***@***.***> wrote: Thanks for providing the action! Could you elaborate on this example? 1. What is different from the GitHub Action that is listed in the docs? 2. Are there other requirements for publishing to GitHub Pages from organizations? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2287 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAUPZ4WCRENHYE5RTXFC533S6PEPBANCNFSM4XN3XD2A> .

[lasarojc]

Indeed, I just tested it and it works fine. But, hey, at least I've learned a bit about github actions! Lásaro

…

On Thu, Feb 11, 2021 at 9:51 AM Lasaro Camargos ***@***.***> wrote: Sure. There is a good explanation of the two kinds of gh projects, i.e., projects and user/organizations here: https://www.mkdocs.org/user-guide/deploying-your-docs/ In essence, in projects, you can save the sources to master but push the built site to the gh-pages branch, which is what the already listed action does. In user/org, you need to push the built site to the master branch instead. But, now that you made me really think about it, I guess we could just use the original action but extended with --remote-branch master option Lásaro On Thu, Feb 11, 2021 at 9:28 AM Martin Donath ***@***.***> wrote: > Thanks for providing the action! Could you elaborate on this example? > > 1. What is different from the GitHub Action that is listed in the > docs? > 2. Are there other requirements for publishing to GitHub Pages from > organizations? > > — > You are receiving this because you authored the thread. > Reply to this email directly, view it on GitHub > <#2287 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AAUPZ4WCRENHYE5RTXFC533S6PEPBANCNFSM4XN3XD2A> > . >

[squidfunk]

Great. I'd refer to the MkDocs documentation for deploying GitHub actions to user/org pages. We cannot list all possible targets on the "publishing your site" page, as keeping it concise is of great importance. However, as you shared a recipe, users can come back to this discussion and get started quickly 😊

[lasarojc]

Yes, I agree. Lásaro

…

On Thu, Feb 11, 2021 at 10:18 AM Martin Donath ***@***.***> wrote: Great. I'd refer to the MkDocs documentation for deploying GitHub actions to user/org pages. We cannot list all possible targets on the "publishing your site" page, as keeping it concise is of great importance. However, as you shared a recipe, users can come back to this discussion and get started quickly 😊 — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2287 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAUPZ4W4PTVD5Z27R4DVHCTS6PKK7ANCNFSM4XN3XD2A> .