Merge pull request #3189 from seanh/publish-to-ghp-using-gha

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 <https://help.github.com/categories/20/articles>`_ offer an easy
-and convenient way to publish Pelican sites. There are `two types of GitHub
-Pages <https://help.github.com/articles/user-organization-and-project-pages>`_:
-*Project Pages* and *User Pages*. Pelican sites can be published as both
-Project Pages and User Pages.
+If you use `GitHub <https://github.com/>`_ for your Pelican site you can
+publish your site to `GitHub Pages <https://pages.github.com/>`_ for free.
+Your site will be published to ``https://<username>.github.io`` if it's a user or
+organization site or to ``https://<username>.github.io/<repository>`` if it's a
+project site. It's also possible to `use a custom domain with GitHub Pages <https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site>`_.
 
-Project Pages
--------------
+There are `two ways to publish a site to GitHub Pages <https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site>`_:
+
+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,87 @@ 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 <https://github.com/getpelican/pelican/blob/master/.github/workflows/github_pages.yml>`_
+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/<username>/<repository>/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://<username>.github.io`` for a user or
+   organization site or ``https://<username>.github.io/<repository>>`` 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 <https://docs.github.com/en/actions/using-workflows/reusing-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"`` |        |               |
+|              |          | or if you have a requirements     |        |               |
+|              |          | file: ``"-r requirements.txt"``   |        |               |
++--------------+----------+-----------------------------------+--------+---------------+
+| 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
 ----------------