From 29185e4ad7fbd6ec900657cc13c529e68454e8af Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 28 Aug 2023 19:21:03 +0100 Subject: [PATCH] Add GitHub Actions workflow for GitHub Pages Add a GitHub Actions workflow that users can use to publish their Pelican sites to GitHub Pages by running `pelican` on GitHub Actions, without having to run `pelican` locally and push the output directory to a branch. See: https://github.com/getpelican/pelican/discussions/3174 --- .github/workflows/github_pages.yml | 61 +++++++++++++++ docs/tips.rst | 114 ++++++++++++++++++++++++++--- 2 files changed, 164 insertions(+), 11 deletions(-) create mode 100644 .github/workflows/github_pages.yml diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml new file mode 100644 index 00000000..481dd118 --- /dev/null +++ b/.github/workflows/github_pages.yml @@ -0,0 +1,61 @@ +name: Deploy to GitHub Pages +on: + workflow_call: + inputs: + settings: + required: true + description: "The path to your Pelican settings file (`pelican`'s `--settings` option), for example: 'publishconf.py'" + type: string + requirements: + required: false + default: "pelican" + description: "The Python requirements to install, for example to enable markdown and typogrify use: 'pelican[markdown] typogrify'" + type: string + output-path: + required: false + default: "output/" + description: "Where to output the generated files (`pelican`'s `--output` option)" + type: string +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: "pages" + cancel-in-progress: false +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.11" + - name: Configure GitHub Pages + id: pages + uses: actions/configure-pages@v3 + - name: Install requirements + run: pip install ${{ inputs.requirements }} + - name: Build Pelican site + run: | + pelican \ + --settings "${{ inputs.settings }}" \ + --extra-settings SITEURL='"${{ steps.pages.outputs.base_url }}"' \ + --output "${{ inputs.output-path }}" + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: ${{ inputs.output-path }} + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 + diff --git a/docs/tips.rst b/docs/tips.rst index 8b9dda15..abd46c8a 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -34,17 +34,30 @@ settings on your AWS console. From there:: Error Document: 404.html -Publishing to GitHub -==================== +Publishing to GitHub Pages +========================== -`GitHub Pages `_ offer an easy -and convenient way to publish Pelican sites. There are `two types of GitHub -Pages `_: -*Project Pages* and *User Pages*. Pelican sites can be published as both -Project Pages and User Pages. +If you use `GitHub `_ for your Pelican site you can +publish your site to `GitHub Pages `_ for free. +Your site will be published to ``https://.github.io`` if it's a user or +organization site or to ``https://.github.io/`` if it's a +project site. It's also possible to `use a custom domain with GitHub Pages `_. -Project Pages -------------- +There are `two ways to publish a site to GitHub Pages `_: + +1. **Publishing from a branch:** run ``pelican`` locally and push the output + directory to a special branch of your GitHub repo. GitHub will then publish + the contents of this branch to your GitHub Pages site. +2. **Publishing with a custom GitHub Actions workflow:** just push the source + files of your Pelican site to your GitHub repo's default branch and have a + custom GitHub Actions workflow run ``pelican`` for you to generate the + output directory and publish it to your GitHub Pages site. This way you + don't need to run ``pelican`` locally. You can even edit your site's source + files using GitHub's web interface and any changes that you commit will be + published. + +Publishing a Project Site to GitHub Pages from a Branch +------------------------------------------------------- To publish a Pelican site as a Project Page you need to *push* the content of the ``output`` dir generated by Pelican to a repository's ``gh-pages`` branch @@ -72,8 +85,8 @@ already exist). The ``git push origin gh-pages`` command updates the remote ``tasks.py``) created by the ``pelican-quickstart`` command publishes the Pelican site as Project Pages, as described above. -User Pages ----------- +Publishing a User Site to GitHub Pages from a Branch +---------------------------------------------------- To publish a Pelican site in the form of User Pages, you need to *push* the content of the ``output`` dir generated by Pelican to the ``master`` branch of @@ -110,6 +123,85 @@ branch of your GitHub repository:: (assuming origin is set to your remote repository). +Publishing to GitHub Pages Using a Custom GitHub Actions Workflow +----------------------------------------------------------------- + +Pelican comes with a `custom workflow `_ +for publishing a Pelican site. To use it: + +1. Enable GitHub Pages in your repo: go to **Settings → Pages** and choose + **GitHub Actions** for the **Source** setting. + +2. Commit a ``.github/workflows/pelican.yml`` file to your repo with these contents: + + .. code-block:: yaml + + name: Deploy to GitHub Pages + on: + push: + branches: ["main"] + workflow_dispatch: + jobs: + deploy: + uses: "getpelican/pelican/.github/workflows/github_pages.yml@master" + permissions: + contents: "read" + pages: "write" + id-token: "write" + with: + settings: "publishconf.py" + +3. Go to the **Actions** tab in your repo + (``https://github.com///actions``) and you should see a + **Deploy to GitHub Pages** action running. + +4. Once the action completes you should see your Pelican site deployed at your + repo's GitHub Pages URL: ``https://.github.io`` for a user or + organization site or ``https://.github.io/>`` for a + project site. + +Notes: + +* You don't need to set ``SITEURL`` in your Pelican settings: the workflow will + set it for you + +* You don't need to commit your ``--output`` / ``OUTPUT_PATH`` directory + (``output/``) to git: the workflow will run ``pelican`` to build the output + directory for you on GitHub Actions + +See `GitHub's docs about reusable workflows `_ +for more information. + +A number of optional inputs can be added to the ``with:`` block when calling +the workflow: + ++--------------+----------+-----------------------------------+--------+---------------+ +| Name | Required | Description | Type | Default | ++==============+==========+===================================+========+===============+ +| settings | Yes | The path to your Pelican settings | string | | +| | | file (``pelican``'s | | | +| | | ``--settings`` option), | | | +| | | for example: ``"publishconf.py"`` | | | ++--------------+----------+-----------------------------------+--------+---------------+ +| requirements | No | The Python requirements to | string | ``"pelican"`` | +| | | install, for example to enable | | | +| | | markdown and typogrify use: | | | +| | | ``"pelican[markdown] typogrify"`` | | | ++--------------+----------+-----------------------------------+--------+---------------+ +| output-path | No | Where to output the generated | string | ``"output/"`` | +| | | files (``pelican``'s ``--output`` | | | +| | | option) | | | ++--------------+----------+-----------------------------------+--------+---------------+ + +For example: + +.. code-block:: yaml + + with: + settings: "publishconf.py" + requirements: "pelican[markdown] typogrify" + output-path: "__output__/" + Custom 404 Pages ----------------