Merge branch 'main' into fix_3173

.coveragerc

@@ -1,2 +1,4 @@
 [report]
-omit = pelican/tests/*
+omit =
+       pelican/tests/*
+       pelican/signals.py

.git-blame-ignore-revs

@@ -15,3 +15,5 @@ db241feaa445375dc05e189e69287000ffe5fa8e
 7577dd7603f7cb3a09922d1edb65b6eafb6e2ac7
 # Indent Jinja templates, HTML, CSS, and JS via DjHTML
 4af40e80772a58eac8969360e5caeb99e3e26e78
+# Ruff UP031: Use F-string format specifiers instead of percent format
+30bde3823f50b9ba8ac5996c1c46bb72031aa6b8

.github/CODEOWNERS

@@ -0,0 +1 @@
+.github/workflows/github_pages.yml @seanh

.github/ISSUE_TEMPLATE/---bug-report.md

@@ -17,11 +17,15 @@ assignees: ''
 
 <!-- Checked checkbox should look like this: [x] -->
 - [ ] I have read the [Filing Issues](https://docs.getpelican.com/en/latest/contribute.html#filing-issues) and subsequent “How to Get Help” sections of the documentation.
+- [ ] I can reproduce this problem with stock/default settings file, theme, and sample content (as described in above “How to Get Help” sections of the documentation).
 - [ ] I have searched the [issues](https://github.com/getpelican/pelican/issues?q=is%3Aissue) (including closed ones) and believe that this is not a duplicate.
 
 <!--
-  Once the above boxes are checked, if you are able to fill in the following list
-  with your information, it would be very helpful for maintainers.
+  If you cannot reproduce the problem with stock/default settings file, theme, and sample content,
+  please close this tab and ask your question in the Discussions area instead:
+  <https://github.com/getpelican/pelican/discussions>
+  Otherwise, once the above boxes are checked, please fill out the following list
+  of information, which would be very helpful for maintainers.
 -->
 
 - **OS version and name**: <!-- Replace with version + name -->

.github/ISSUE_TEMPLATE/---everything-else.md

@@ -8,7 +8,11 @@ assignees: ''
 ---
 
 <!--
-  Describe your question/issue here. This space is meant to be used for general questions
+  Instead of a new issue, please consider submitting your question to:
+  <https://github.com/getpelican/pelican/discussions>
+  If for some reason you believe that your question warrants a new issue
+  instead of a discussion thread, describe your question/issue here.
+  This space is meant to be used for general questions
   that are not bugs, feature requests, or documentation issues.
   Before you submit this, let’s make sure of a few things.
   Please make sure the following boxes are ticked if they are correct.
@@ -18,6 +22,7 @@ assignees: ''
 <!-- Checked checkbox should look like this: [x] -->
 - [ ] I have searched the [issues](https://github.com/getpelican/pelican/issues?q=is%3Aissue) (including closed ones) and believe that this is not a duplicate.
 - [ ] I have searched the [documentation](https://docs.getpelican.com/) and believe that my question is not covered.
+- [ ] I have carefully read the [How to Get Help](https://docs.getpelican.com/en/latest/contribute.html#how-to-get-help) section of the documentation.
 
 ## Issue
 <!-- Now feel free to write your issue, but please be descriptive! Thanks again 🙌 ❤️ -->

.github/ISSUE_TEMPLATE/config.yml

@@ -1,6 +1,6 @@
 ---
 # Ref: https://help.github.com/en/github/building-a-strong-community/configuring-issue-templates-for-your-repository#configuring-the-template-chooser
-blank_issues_enabled: true
+blank_issues_enabled: false
 contact_links:
 - name: '💬 Pelican IRC Channel'
   url: https://web.libera.chat/?#pelican

.github/dependabot.yml

@@ -0,0 +1,14 @@
+# See https://docs.github.com/en/free-pro-team@latest/
+#  github/administering-a-repository/enabling-and-disabling-version-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/github_pages.yml

@@ -1,4 +1,4 @@
-# Workflow for publishing to GitHub Pages. **NO OFFICIAL SUPPORT PROVIDED.**
+# Workflow for building the site and (optionally) publishing it to GitHub Pages.
 name: Deploy to GitHub Pages
 on:
   workflow_call:
@@ -17,44 +17,83 @@ on:
         default: "output/"
         description: "Where to output the generated files (`pelican`'s `--output` option)"
         type: string
+      theme:
+        required: false
+        default: ""
+        description: "The GitHub repo URL of a custom theme to use, for example: 'https://github.com/seanh/sidecar.git'"
+        type: string
+      python:
+        required: false
+        default: "3.12"
+        description: "The version of Python to use, for example: '3.12' (to use the most recent version of Python 3.12, this is faster) or '3.12.1' (to use an exact version, slower)"
+        type: string
+      siteurl:
+        required: false
+        default: ""
+        description: "The base URL of your web site (Pelican's SITEURL setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases."
+        type: string
+      feed_domain:
+        required: false
+        default: ""
+        description: "The domain to be prepended to feed URLs (Pelican's FEED_DOMAIN setting). If not passed this will default to the URL of your GitHub Pages site, which is correct in most cases."
+        type: string
+      deploy:
+        required: false
+        default: true
+        description: "Whether to deploy the site. If true then build the site and deploy it. If false then just test that the site builds successfully but don't deploy anything."
+        type: boolean
 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@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: ${{ inputs.python }}
+      - name: Checkout theme
+        if: ${{ inputs.theme }}
+        run: git clone '${{ inputs.theme }}' .theme
       - name: Configure GitHub Pages
         id: pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
       - name: Install requirements
         run: pip install ${{ inputs.requirements }}
       - name: Build Pelican site
+        shell: python
         run: |
-          pelican \
-            --settings "${{ inputs.settings }}" \
-            --extra-settings SITEURL='"${{ steps.pages.outputs.base_url }}"' \
-            --output "${{ inputs.output-path }}"
+          import subprocess
+
+          cmd = "pelican"
+          cmd += " --settings ${{ inputs.settings }}"
+          cmd += " --extra-settings"
+          cmd += """ SITEURL='"${{ inputs.siteurl || steps.pages.outputs.base_url }}"'"""
+          cmd += """ FEED_DOMAIN='"${{ inputs.feed_domain || steps.pages.outputs.base_url }}"'"""
+          cmd += " --output ${{ inputs.output-path }}"
+
+          if "${{ inputs.theme }}":
+              cmd += " --theme-path .theme"
+
+          subprocess.run(cmd, shell=True, check=True)
       - name: Fix permissions
         run: |
           chmod -c -R +rX "${{ inputs.output-path }}" | while read line; do
             echo "::warning title=Invalid file permissions automatically fixed::$line"
           done
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
+        uses: actions/upload-pages-artifact@v3
         with:
           path: ${{ inputs.output-path }}
   deploy:
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+    if: ${{ inputs.deploy }}
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
@@ -63,4 +102,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -110,7 +110,7 @@ jobs:
     environment: Deployment
     needs: [test, lint, docs, build]
     runs-on: ubuntu-latest
-    if: github.ref=='refs/heads/master' && github.event_name!='pull_request' && github.repository == 'getpelican/pelican'
+    if: github.ref=='refs/heads/main' && github.event_name!='pull_request' && github.repository == 'getpelican/pelican'
 
     permissions:
       contents: write

.gitignore

@@ -4,7 +4,7 @@
 *.pyc
 .DS_Store
 docs/_build
-docs/fr/_build
+docs/*/_build
 build
 dist
 tags
@@ -17,4 +17,13 @@ samples/output
 *.pem
 *.lock
 .pdm-python
+.vale
 .venv
+**/LC_MESSAGES/*.mo
+
+# direnv
+.envrc
+
+# IDE cruft
+.idea
+.vscode

.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 # See https://pre-commit.com/hooks.html for info on hooks
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: check-ast
@@ -16,14 +16,14 @@ repos:
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # ruff version should match the one in pyproject.toml
-    rev: v0.4.6
+    rev: v0.7.2
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
 
   - repo: https://github.com/rtts/djhtml
-    rev: '3.0.6'
+    rev: '3.0.7'
     hooks:
       - id: djhtml
       - id: djcss

.vale.ini

@@ -0,0 +1,10 @@
+StylesPath = .vale/styles
+
+Vocab = Pelican
+
+MinAlertLevel = suggestion
+
+Packages = proselint, alex
+
+[*]
+BasedOnStyles = Vale, proselint, alex

CONTRIBUTING.rst

@@ -24,7 +24,7 @@ Before you ask for help, please make sure you do the following:
 
 3. Try reproducing the issue in a clean environment, ensuring you are using:
 
-* latest Pelican release (or an up-to-date Git clone of Pelican master)
+* latest Pelican release (or an up-to-date Git clone of Pelican ``main`` branch)
 * latest releases of libraries used by Pelican
 * no plugins or only those related to the issue
 
@@ -87,7 +87,7 @@ Using Git and GitHub
 --------------------
 
 * `Create a new branch`_ specific to your change (as opposed to making
-  your commits in the master branch).
+  your commits in the ``main`` branch).
 * **Don't put multiple unrelated fixes/features in the same branch / pull request.**
   For example, if you're working on a new feature and find a bugfix that
   doesn't *require* your new feature, **make a new distinct branch and pull

README.rst

@@ -64,8 +64,8 @@ Why the name “Pelican”?
 .. _`Pelican's internals`: https://docs.getpelican.com/en/latest/internals.html
 .. _`hosted on GitHub`: https://github.com/getpelican/pelican
 
-.. |build-status| image:: https://img.shields.io/github/actions/workflow/status/getpelican/pelican/main.yml?branch=master
-   :target: https://github.com/getpelican/pelican/actions/workflows/main.yml?query=branch%3Amaster
+.. |build-status| image:: https://img.shields.io/github/actions/workflow/status/getpelican/pelican/main.yml?branch=main
+   :target: https://github.com/getpelican/pelican/actions/workflows/main.yml?query=branch%3Amain
    :alt: GitHub Actions CI: continuous integration status
 .. |pypi-version| image:: https://img.shields.io/pypi/v/pelican.svg
    :target: https://pypi.org/project/pelican/

docs/changelog.rst

@@ -1,6 +1,26 @@
 Release history
 ###############
 
+4.10.1 - 2024-09-28
+===================
+
+- Fix error when running ``pelican -r -l``
+- Fix symlink handling in ``pelican-themes``
+
+4.10.0 - 2024-09-16
+===================
+
+- Add setting to specify summary via paragraph count
+- Add new status to skip generation of a post
+- Add setting to append ``ref`` parameter to links in feeds
+- Configure logging handler via ``--log-handler`` CLI option
+- Resolve intra-site links in summaries
+- Warn when files are not processed due to disabled readers
+- Add Medium post importer
+- Improve GitHub Pages workflow
+- Improve code test coverage
+- Translate documentation into Simplified Chinese
+
 4.9.1 - 2023-11-15
 ==================
 

docs/conf.py

@@ -19,17 +19,19 @@
 
 # -- General configuration ----------------------------------------------------
 templates_path = ["_templates"]
+locale_dirs = ["locale/"]
+gettext_compact = False
+gettext_uuid = True
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.ifconfig",
     "sphinx.ext.extlinks",
     "sphinxext.opengraph",
 ]
 source_suffix = ".rst"
 master_doc = "index"
 project = project_data.get("name").upper()
 year = datetime.datetime.now().date().year
-copyright = f"2010–{year}"
+copyright = f"2010–{year}"  # noqa: RUF001
 exclude_patterns = ["_build"]
 release = project_data.get("version")
 version = ".".join(release.split(".")[:1])

docs/content.rst

@@ -89,7 +89,7 @@ contains a list of reserved metadata keywords:
 ``summary``     Brief description of content for index pages
 ``lang``        Content language ID (``en``, ``fr``, etc.)
 ``translation`` If content is a translation of another (``true`` or ``false``)
-``status``      Content status: ``draft``, ``hidden``, or ``published``
+``status``      Content status: ``draft``, ``hidden``, ``skip``, or ``published``
 ``template``    Name of template to use to generate content (without extension)
 ``save_as``     Save content to this relative file path
 ``url``         URL to use for this article/page
@@ -162,7 +162,10 @@ author you can use ``author`` field.
 
 If you do not explicitly specify summary metadata for a given post, the
 ``SUMMARY_MAX_LENGTH`` setting can be used to specify how many words from the
-beginning of an article are used as the summary.
+beginning of an article are used as the summary. You can also use an article's
+first N paragraphs as its summary using the ``SUMMARY_MAX_PARAGRAPHS`` setting.
+If both settings are in use, the specified number of paragraphs will
+be used but may be truncated to respect the specified maximum length.
 
 You can also extract any metadata from the filename through a regular
 expression to be set in the ``FILENAME_METADATA`` setting. All named groups
@@ -630,6 +633,13 @@ attribute. Hidden posts will be output to ``ARTICLE_SAVE_AS`` as expected, but
 are not included by default in tag, category, and author indexes, nor in the
 main article feed. This has the effect of creating an "unlisted" post.
 
+Skip Posts
+==========
+
+Posts marked with ``skip`` status are ignored entirely. They are not processed
+nor output to the ``ARTICLE_SAVE_AS`` path. Such posts will similarly not be
+included in indexes or feeds.
+
 .. _W3C ISO 8601: https://www.w3.org/TR/NOTE-datetime
 .. _AsciiDoc: https://asciidoc.org
 .. _Pelican Plugins: https://github.com/pelican-plugins