github/pelican
1
0
Fork 1
mirror of https://github.com/getpelican/pelican.git synced 2025-10-15 20:28:56 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'getpelican:master' into Chinese-translation

Browse source
This commit is contained in:
GeorgeHu 2023-11-19 20:05:28 +08:00 • committed by GitHub
commit 4da471211a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
306 changed files with 8621 additions and 6489 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/_static/pelican-logo.svg vendored
View file

@ -1 +1 @@
<?xml version="1.0" encoding="UTF-8"?><svg id="svg33" width="64" height="64" style="clip-rule:evenodd;fill-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.4142" version="1.1" viewBox="0 0 64 64" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"><g id="g864" transform="matrix(.10228 0 0 .10228 2.441 6.0098e-5)"><g id="g4" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path2" d="m210.35 607.22c-.34-2.106-.842-4.303-1.491-6.591-1.537-5.441-4.918-10.074-9.506-13.854-1.205-1.001-2.503-1.946-3.88-2.823-5.293-3.381-11.692-5.851-18.522-7.32-4.588-.99-9.367-1.525-14.139-1.593-34.662-.774-56.234.387-90.373-.911.012.023.012.046.022.068 1.56 1.264 3.154 2.471 4.782 3.643 3.573 2.584 7.297 4.952 11.155 7.127 7.184 4.04 14.845 7.342 22.859 9.801.956.295 1.912.58 2.87.842 5.6.603 10.631 1.206 14.648 3.074 1.015.455 1.959 1.001 2.835 1.639 2.87 2.106 6.057 6.124 8.152 8.936 4.497 5.999 3.551 10.928 8.88 13.887.557.308 1.182.604 1.889.866 1.696.638 4.119 1.491 5.225-.91.16-.342.283-.764.387-1.264-.446-1.434-1.981-2.675-2.905-3.29-1.638-1.07-2.287-1.719-3.47-2.937-2.186-2.243-2.333-6.056-3.871-8.708 1.935-.82 12.146-2.186 14.287-1.89 4.576.204 8.185.557 10.939 3.392 1.08.854 1.672 1.594 2.652 2.334.069.057.125.114.194.159 4.338 3.153 8.343 4.28 11.894 5.362.936.284 1.822.558 2.69.876 1.332.478 2.582 1.048 3.754 1.81 1.39.922 3.748 3.336 3.849 5.419-3.496-1.116-1.185.296-6.342-.102-2.515-.285-5.087-.456-7.671-.638-4.018-.284-8.038-.581-11.805-1.297-.627-.115-1.254-.251-1.867-.399-.479-.102-.946-.227-1.401-.353-.011.193-.021.376-.021.546-.104 3.939 2.674 5.908-3.678 13.399-.057.08-.137.159-.205.25-1.686 1.97-10.449 5.715-13.182 6.432-11.634 2.334-20.502-5.237-34.515-1.423-4.929 1.833-8.549 9.824-10.815 15.8-3.016 7.936-5.406 17.576-8.139 27.06 5.329-.797 10.53-1.936 15.585-3.427 11.167-3.279 21.651-8.185 31.168-14.445.911-1.231 1.912-2.29 2.994-3.108.284-.217.58-.422.877-.603.215-.137.956-.286 2.127-.502 10.861-1.924 58.5-8.377 61.597-42.962.319-3.494.172-7.285-.513-11.372zm-106.94 18.59c-6.375-1.924-8.003-2.243-12.055-5.385.067.33.17.695.307 1.081 10.779 6.068 22.608 10.462 35.141 12.842-3.893-9.051-8.502-7.445-23.393-8.538zm29.518-4.099c-2.779-6.738-10.313-10.575-16.813-12.464-8.721-3.12-15.061-.125-33.458-8.811.147.239.284.467.432.694 3.575 2.584 7.297 4.963 11.157 7.126 7.184 4.041 14.844 7.343 22.857 9.802 4.167.489 8.175 1.184 11.863 2.96 1.639.773 3.21 1.764 4.702 3.039-.183-.82-.434-1.605-.74-2.346z" style="fill-rule:nonzero;fill:url(#_Linear1)"/></g><g id="g8" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path6" d="m114.13 595.61c-.958-.262-1.914-.547-2.87-.842-8.014-2.459-15.675-5.761-22.859-9.801-3.858-2.175-7.582-4.543-11.155-7.127-1.628-1.172-3.222-2.379-4.782-3.643 2.14 6.603 11.634 13.57 18.078 16.313 8.218 3.495 16.381 4.303 23.588 5.1z" style="fill:#90d4d1"/></g><g id="g12" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path10" d="m94.253 608.25c-3.86-2.163-7.582-4.542-11.157-7.126 10.006 15.823 22.575 15.584 34.014 16.928-8.013-2.459-15.673-5.761-22.857-9.802z" style="fill:#90d4d1"/></g><g id="g16" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path14" d="m126.81 634.34c-12.533-2.38-24.362-6.774-35.141-12.842 1.376 3.973 6.351 10.257 12.943 11.658 2.858 1.024 2.094.762 6.967.614 7.137-.364 10.552-.592 15.608 1.469-.126-.308-.251-.604-.377-.899z" style="fill:#90d4d1"/></g><g id="g20" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path18" d="m143.27 665.76c-.081.101-.159.204-.239.318-13.844 14.093-31.179 24.69-50.59 30.393 1.492-4.132 2.824-8.468 4.076-12.839 5.329-.797 10.53-1.936 15.585-3.427 11.167-3.279 21.651-8.185 31.168-14.445z" style="fill:#90d4d1"/></g><g id="g24" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path22" d="m143.03 666.08c-6.046 8.287-9.118 24.122-12.659 33.274-5.144 13.342-12.294 22.95-27.958 24.317-3.928.351-27.582 1.24-30.11-.035.159-1.344 4.098-2.961 5.123-3.747 6.852-4.847 11.416-13.5 15.014-23.416 19.411-5.703 36.746-16.3 50.59-30.393z" style="fill:#14a0c4"/></g></g><defs id="defs31"><linearGradient id="_Linear1" x2="1" gradientTransform="matrix(138.58 0 0 138.58 72.442 628.88)" gradientUnits="userSpaceOnUse"><stop id="stop26" style="stop-color:rgb(84,196,198)" offset="0"/><stop id="stop28" style="stop-color:rgb(18,186,213)" offset="1"/></linearGradient></defs></svg>
<?xml version="1.0" encoding="UTF-8"?><svg id="svg33" width="64" height="64" style="clip-rule:evenodd;fill-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.4142" version="1.1" viewBox="0 0 64 64" xml:space="preserve" xmlns="http://www.w3.org/2000/svg"><g id="g864" transform="matrix(.10228 0 0 .10228 2.441 6.0098e-5)"><g id="g4" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path2" d="m210.35 607.22c-.34-2.106-.842-4.303-1.491-6.591-1.537-5.441-4.918-10.074-9.506-13.854-1.205-1.001-2.503-1.946-3.88-2.823-5.293-3.381-11.692-5.851-18.522-7.32-4.588-.99-9.367-1.525-14.139-1.593-34.662-.774-56.234.387-90.373-.911.012.023.012.046.022.068 1.56 1.264 3.154 2.471 4.782 3.643 3.573 2.584 7.297 4.952 11.155 7.127 7.184 4.04 14.845 7.342 22.859 9.801.956.295 1.912.58 2.87.842 5.6.603 10.631 1.206 14.648 3.074 1.015.455 1.959 1.001 2.835 1.639 2.87 2.106 6.057 6.124 8.152 8.936 4.497 5.999 3.551 10.928 8.88 13.887.557.308 1.182.604 1.889.866 1.696.638 4.119 1.491 5.225-.91.16-.342.283-.764.387-1.264-.446-1.434-1.981-2.675-2.905-3.29-1.638-1.07-2.287-1.719-3.47-2.937-2.186-2.243-2.333-6.056-3.871-8.708 1.935-.82 12.146-2.186 14.287-1.89 4.576.204 8.185.557 10.939 3.392 1.08.854 1.672 1.594 2.652 2.334.069.057.125.114.194.159 4.338 3.153 8.343 4.28 11.894 5.362.936.284 1.822.558 2.69.876 1.332.478 2.582 1.048 3.754 1.81 1.39.922 3.748 3.336 3.849 5.419-3.496-1.116-1.185.296-6.342-.102-2.515-.285-5.087-.456-7.671-.638-4.018-.284-8.038-.581-11.805-1.297-.627-.115-1.254-.251-1.867-.399-.479-.102-.946-.227-1.401-.353-.011.193-.021.376-.021.546-.104 3.939 2.674 5.908-3.678 13.399-.057.08-.137.159-.205.25-1.686 1.97-10.449 5.715-13.182 6.432-11.634 2.334-20.502-5.237-34.515-1.423-4.929 1.833-8.549 9.824-10.815 15.8-3.016 7.936-5.406 17.576-8.139 27.06 5.329-.797 10.53-1.936 15.585-3.427 11.167-3.279 21.651-8.185 31.168-14.445.911-1.231 1.912-2.29 2.994-3.108.284-.217.58-.422.877-.603.215-.137.956-.286 2.127-.502 10.861-1.924 58.5-8.377 61.597-42.962.319-3.494.172-7.285-.513-11.372zm-106.94 18.59c-6.375-1.924-8.003-2.243-12.055-5.385.067.33.17.695.307 1.081 10.779 6.068 22.608 10.462 35.141 12.842-3.893-9.051-8.502-7.445-23.393-8.538zm29.518-4.099c-2.779-6.738-10.313-10.575-16.813-12.464-8.721-3.12-15.061-.125-33.458-8.811.147.239.284.467.432.694 3.575 2.584 7.297 4.963 11.157 7.126 7.184 4.041 14.844 7.343 22.857 9.802 4.167.489 8.175 1.184 11.863 2.96 1.639.773 3.21 1.764 4.702 3.039-.183-.82-.434-1.605-.74-2.346z" style="fill-rule:nonzero;fill:url(#_Linear1)"/></g><g id="g8" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path6" d="m114.13 595.61c-.958-.262-1.914-.547-2.87-.842-8.014-2.459-15.675-5.761-22.859-9.801-3.858-2.175-7.582-4.543-11.155-7.127-1.628-1.172-3.222-2.379-4.782-3.643 2.14 6.603 11.634 13.57 18.078 16.313 8.218 3.495 16.381 4.303 23.588 5.1z" style="fill:#90d4d1"/></g><g id="g12" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path10" d="m94.253 608.25c-3.86-2.163-7.582-4.542-11.157-7.126 10.006 15.823 22.575 15.584 34.014 16.928-8.013-2.459-15.673-5.761-22.857-9.802z" style="fill:#90d4d1"/></g><g id="g16" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path14" d="m126.81 634.34c-12.533-2.38-24.362-6.774-35.141-12.842 1.376 3.973 6.351 10.257 12.943 11.658 2.858 1.024 2.094.762 6.967.614 7.137-.364 10.552-.592 15.608 1.469-.126-.308-.251-.604-.377-.899z" style="fill:#90d4d1"/></g><g id="g20" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path18" d="m143.27 665.76c-.081.101-.159.204-.239.318-13.844 14.093-31.179 24.69-50.59 30.393 1.492-4.132 2.824-8.468 4.076-12.839 5.329-.797 10.53-1.936 15.585-3.427 11.167-3.279 21.651-8.185 31.168-14.445z" style="fill:#90d4d1"/></g><g id="g24" transform="matrix(4.1667 0 0 4.1667 -301.27 -2392.2)"><path id="path22" d="m143.03 666.08c-6.046 8.287-9.118 24.122-12.659 33.274-5.144 13.342-12.294 22.95-27.958 24.317-3.928.351-27.582 1.24-30.11-.035.159-1.344 4.098-2.961 5.123-3.747 6.852-4.847 11.416-13.5 15.014-23.416 19.411-5.703 36.746-16.3 50.59-30.393z" style="fill:#14a0c4"/></g></g><defs id="defs31"><linearGradient id="_Linear1" x2="1" gradientTransform="matrix(138.58 0 0 138.58 72.442 628.88)" gradientUnits="userSpaceOnUse"><stop id="stop26" style="stop-color:rgb(84,196,198)" offset="0"/><stop id="stop28" style="stop-color:rgb(18,186,213)" offset="1"/></linearGradient></defs></svg>

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.3 KiB

After

Width:  |  Height:  |  Size: 4.3 KiB

Before After
Before After

1
docs/_static/theme_overrides.css vendored
View file

@ -9,4 +9,3 @@
.wy-table-responsive {
overflow: visible !important;
}

28
docs/changelog.rst
View file

@ -1,6 +1,34 @@
Release history
###############
4.9.1 - 2023-11-15
==================
* Ensure ``tzdata`` dependency is installed on Windows
4.9.0 - 2023-11-12
==================
* Upgrade code to new minimum supported Python version: 3.8
* Settings support for ``pathlib.Path`` `(#2758) <https://github.com/getpelican/pelican/pull/2758>`_
* Various improvements to Simple theme (`#2976 <https://github.com/getpelican/pelican/pull/2976>`_ & `#3234 <https://github.com/getpelican/pelican/pull/3234>`_)
* Use Furo as Sphinx documentation theme `(#3023) <https://github.com/getpelican/pelican/pull/3023>`_
* Default to 100 articles maximum in feeds `(#3127) <https://github.com/getpelican/pelican/pull/3127>`_
* Add ``period_archives common context`` variable `(#3148) <https://github.com/getpelican/pelican/pull/3148>`_
* Use ``watchfiles`` as the file-watching backend `(#3151) <https://github.com/getpelican/pelican/pull/3151>`_
* Add GitHub Actions workflow for GitHub Pages `(#3189) <https://github.com/getpelican/pelican/pull/3189>`_
* Allow dataclasses in settings `(#3204) <https://github.com/getpelican/pelican/pull/3204>`_
* Switch build tool to PDM instead of Setuptools/Poetry `(#3220) <https://github.com/getpelican/pelican/pull/3220>`_
* Provide a ``plugin_enabled`` Jinja test for themes `(#3235) <https://github.com/getpelican/pelican/pull/3235>`_
* Preserve connection order in Blinker `(#3238) <https://github.com/getpelican/pelican/pull/3238>`_
* Remove social icons from default ``notmyidea`` theme `(#3240) <https://github.com/getpelican/pelican/pull/3240>`_
* Remove unreliable ``WRITE_SELECTED`` feature `(#3243) <https://github.com/getpelican/pelican/pull/3243>`_
* Importer: Report broken embedded video links when importing from Tumblr `(#3177) <https://github.com/getpelican/pelican/issues/3177>`_
* Importer: Remove newline addition when iterating Photo post types `(#3178) <https://github.com/getpelican/pelican/issues/3178>`_
* Importer: Force timestamp conversion in Tumblr importer to be UTC with offset `(#3221) <https://github.com/getpelican/pelican/pull/3221>`_
* Importer: Use tempfile for intermediate HTML file for Pandoc `(#3221) <https://github.com/getpelican/pelican/pull/3221>`_
* Switch linters to Ruff `(#3223) <https://github.com/getpelican/pelican/pull/3223>`_
4.8.0 - 2022-07-11
==================

95
docs/conf.py
View file

@ -2,45 +2,58 @@ import datetime
import os
import sys
from pelican import __version__
if sys.version_info >= (3, 11):
import tomllib
else:
import tomli as tomllib
sys.path.append(os.path.abspath(os.pardir))
# -- General configuration ----------------------------------------------------
templates_path = ['_templates']
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.ifconfig',
'sphinx.ext.extlinks']
source_suffix = '.rst'
master_doc = 'index'
project = 'Pelican'
year = datetime.datetime.now().date().year
copyright = f'2010–{year}'
exclude_patterns = ['_build']
release = __version__
version = '.'.join(release.split('.')[:1])
last_stable = __version__
rst_prolog = '''
.. |last_stable| replace:: :pelican-doc:`{}`
'''.format(last_stable)
extlinks = {
'pelican-doc': ('https://docs.getpelican.com/en/latest/%s.html', '%s')
}
with open("../pyproject.toml", "rb") as f:
project_data = tomllib.load(f).get("project")
if project_data is None:
raise KeyError("project data is not found")
# -- General configuration ----------------------------------------------------
templates_path = ["_templates"]
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}"
exclude_patterns = ["_build"]
release = project_data.get("version")
version = ".".join(release.split(".")[:1])
last_stable = project_data.get("version")
rst_prolog = f"""
.. |last_stable| replace:: :pelican-doc:`{last_stable}`
.. |min_python| replace:: {project_data.get('requires-python').split(",")[0]}
"""
extlinks = {"pelican-doc": ("https://docs.getpelican.com/en/latest/%s.html", "%s")}
# -- Options for HTML output --------------------------------------------------
html_theme = 'furo'
html_title = f'<strong>{project}</strong> <i>{release}</i>'
html_static_path = ['_static']
html_theme = "furo"
html_title = f"<strong>{project}</strong> <i>{release}</i>"
html_static_path = ["_static"]
html_theme_options = {
'light_logo': 'pelican-logo.svg',
'dark_logo': 'pelican-logo.svg',
'navigation_with_keys': True,
"light_logo": "pelican-logo.svg",
"dark_logo": "pelican-logo.svg",
"navigation_with_keys": True,
}
# Output file base name for HTML help builder.
htmlhelp_basename = 'Pelicandoc'
htmlhelp_basename = "Pelicandoc"
html_use_smartypants = True
@ -56,21 +69,29 @@ html_show_sourcelink = False
def setup(app):
# overrides for wide tables in RTD theme
app.add_css_file('theme_overrides.css') # path relative to _static
app.add_css_file("theme_overrides.css") # path relative to _static
# -- Options for LaTeX output -------------------------------------------------
latex_documents = [
('index', 'Pelican.tex', 'Pelican Documentation', 'Justin Mayer',
'manual'),
("index", "Pelican.tex", "Pelican Documentation", "Justin Mayer", "manual"),
]
# -- Options for manual page output -------------------------------------------
man_pages = [
('index', 'pelican', 'pelican documentation',
['Justin Mayer'], 1),
('pelican-themes', 'pelican-themes', 'A theme manager for Pelican',
['Mickaël Raybaud'], 1),
('themes', 'pelican-theming', 'How to create themes for Pelican',
['The Pelican contributors'], 1)
("index", "pelican", "pelican documentation", ["Justin Mayer"], 1),
(
"pelican-themes",
"pelican-themes",
"A theme manager for Pelican",
["Mickaël Raybaud"],
1,
),
(
"themes",
"pelican-theming",
"How to create themes for Pelican",
["The Pelican contributors"],
1,
),
]

19
docs/contribute.rst
View file

@ -15,16 +15,16 @@ Setting up the development environment
======================================
While there are many ways to set up one's development environment, the following
instructions will utilize Pip_ and Poetry_. These tools facilitate managing
instructions will utilize Pip_ and PDM_. These tools facilitate managing
virtual environments for separate Python projects that are isolated from one
another, so you can use different packages (and package versions) for each.
Please note that Python 3.7+ is required for Pelican development.
Please note that Python |min_python| is required for Pelican development.
*(Optional)* If you prefer to `install Poetry <https://python-poetry.org/docs/master/#installation>`_ once for use with multiple projects,
*(Optional)* If you prefer to `install PDM <https://pdm.fming.dev/latest/#installation>`_ once for use with multiple projects,
you can install it via::
curl -sSL https://install.python-poetry.org | python3 -
curl -sSL https://pdm.fming.dev/install-pdm.py | python3 -
Point your web browser to the `Pelican repository`_ and tap the **Fork** button
at top-right. Then clone the source for your fork and add the upstream project
@ -35,7 +35,7 @@ as a Git remote::
cd ~/projects/pelican
git remote add upstream https://github.com/getpelican/pelican.git
While Poetry can dynamically create and manage virtual environments, we're going
While PDM can dynamically create and manage virtual environments, we're going
to manually create and activate a virtual environment::
mkdir ~/virtualenvs && cd ~/virtualenvs
@ -46,12 +46,11 @@ Install the needed dependencies and set up the project::
python -m pip install invoke
invoke setup
python -m pip install -e ~/projects/pelican
Your local environment should now be ready to go!
.. _Pip: https://pip.pypa.io/
.. _Poetry: https://python-poetry.org/
.. _PDM: https://pdm.fming.dev/latest/
.. _Pelican repository: https://github.com/getpelican/pelican
Development
@ -75,6 +74,9 @@ via::
invoke tests
(For more on Invoke, see ``invoke -l`` to list tasks, or
https://pyinvoke.org for documentation.)
In addition to running the test suite, it is important to also ensure that any
lines you changed conform to code style guidelines. You can check that via::
@ -156,8 +158,7 @@ check for code style compliance via::
If style violations are found, many of them can be addressed automatically via::
invoke black
invoke isort
invoke format
If style violations are found even after running the above auto-formatters,
you will need to make additional manual changes until ``invoke lint`` no longer

4
docs/faq.rst
View file

@ -217,10 +217,6 @@ changed. A simple solution is to make ``rsync`` use the ``--checksum`` option,
which will make it compare the file checksums in a much faster way than Pelican
would.
When only several specific output files are of interest (e.g. when working on
some specific page or the theme templates), the ``WRITE_SELECTED`` option may
help, see :ref:`writing_only_selected_content`.
How to process only a subset of all articles?
=============================================

19
docs/importer.rst
View file

@ -11,7 +11,6 @@ software to reStructuredText or Markdown. The supported import formats are:
- Blogger XML export
- Dotclear export
- Posterous API
- Tumblr API
- WordPress XML export
- RSS/Atom feed
@ -48,16 +47,15 @@ Usage
::
pelican-import [-h] [--blogger] [--dotclear] [--posterous] [--tumblr] [--wpfile] [--feed]
pelican-import [-h] [--blogger] [--dotclear] [--tumblr] [--wpfile] [--feed]
[-o OUTPUT] [-m MARKUP] [--dir-cat] [--dir-page] [--strip-raw] [--wp-custpost]
[--wp-attach] [--disable-slugs] [-e EMAIL] [-p PASSWORD] [-b BLOGNAME]
input|api_token|api_key
[--wp-attach] [--disable-slugs] [-b BLOGNAME]
input|api_key
Positional arguments
--------------------
============= ============================================================================
``input`` The input file to read
``api_token`` (Posterous only) api_token can be obtained from http://posterous.com/api/
``api_key`` (Tumblr only) api_key can be obtained from https://www.tumblr.com/oauth/apps
============= ============================================================================
@ -67,7 +65,6 @@ Optional arguments
-h, --help Show this help message and exit
--blogger Blogger XML export (default: False)
--dotclear Dotclear export (default: False)
--posterous Posterous API (default: False)
--tumblr Tumblr API (default: False)
--wpfile WordPress XML export (default: False)
--feed Feed to parse (default: False)
@ -101,10 +98,6 @@ Optional arguments
output. With this disabled, your Pelican URLs may not
be consistent with your original posts. (default:
False)
-e EMAIL, --email=EMAIL
Email used to authenticate Posterous API
-p PASSWORD, --password=PASSWORD
Password used to authenticate Posterous API
-b BLOGNAME, --blogname=BLOGNAME
Blog name used in Tumblr API
@ -120,13 +113,9 @@ For Dotclear::
$ pelican-import --dotclear -o ~/output ~/backup.txt
for Posterous::
$ pelican-import --posterous -o ~/output --email=<email_address> --password=<password> <api_token>
For Tumblr::
$ pelican-import --tumblr -o ~/output --blogname=<blogname> <api_token>
$ pelican-import --tumblr -o ~/output --blogname=<blogname> <api_key>
For WordPress::

2
docs/install.rst
View file

@ -1,7 +1,7 @@
Installing Pelican
##################
Pelican currently runs best on 3.7+; earlier versions of Python are not supported.
Pelican currently runs best on |min_python|; earlier versions of Python are not supported.
You can install Pelican via several different methods. The simplest is via Pip_::

10
docs/plugins.rst
View file

@ -94,9 +94,12 @@ which you map the signals to your plugin logic. Let's take a simple example::
your ``register`` callable or they will be garbage-collected before the
signal is emitted.
If multiple plugins connect to the same signal, there is no way to guarantee or
control in which order the plugins will be executed. This is a limitation
inherited from Blinker_, the dependency Pelican uses to implement signals.
If multiple plugins connect to the same signal, plugins will be executed in the
order they are connected. With ``PLUGINS`` setting, order will be as defined in
the setting. If you rely on auto-discovered namespace plugins, no ``PLUGINS``
setting, they will be connected in the same order they are discovered (same
order as ``pelican-plugins`` output). If you want to specify the order
explicitly, disable auto-discovery by defining ``PLUGINS`` in the desired order.
Namespace plugin structure
--------------------------
@ -341,4 +344,3 @@ custom article, using the ``article_generator_pretaxonomy`` signal::
.. _Pip: https://pip.pypa.io/
.. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314
.. _Blinker: https://pythonhosted.org/blinker/

12
docs/publish.rst
View file

@ -18,18 +18,6 @@ folder, using the default theme to produce a simple site. The default theme
consists of very simple HTML without styling and is provided so folks may use
it as a basis for creating their own themes.
When working on a single article or page, it is possible to generate only the
file that corresponds to that content. To do this, use the ``--write-selected``
argument, like so::
pelican --write-selected output/posts/my-post-title.html
Note that you must specify the path to the generated *output* file — not the
source content. To determine the output file name and location, use the
``--debug`` flag. If desired, ``--write-selected`` can take a comma-separated
list of paths or can be configured as a setting. (See:
:ref:`writing_only_selected_content`)
You can also tell Pelican to watch for your modifications, instead of manually
re-running it every time you want to see your changes. To enable this, run the
``pelican`` command with the ``-r`` or ``--autoreload`` option. On non-Windows

2
docs/quickstart.rst
View file

@ -8,7 +8,7 @@ Installation
------------
Install Pelican (and optionally Markdown if you intend to use it) on Python
3.7+ by running the following command in your preferred terminal, prefixing
|min_python| by running the following command in your preferred terminal, prefixing
with ``sudo`` if permissions warrant::
python -m pip install "pelican[markdown]"

61
docs/settings.rst
View file

@ -362,13 +362,6 @@ Basic settings
If ``True``, load unmodified content from caches.
.. data:: WRITE_SELECTED = []
If this list is not empty, **only** output files with their paths in this
list are written. Paths should be either absolute or relative to the current
Pelican working directory. For possible use cases see
:ref:`writing_only_selected_content`.
.. data:: FORMATTED_FIELDS = ['summary']
A list of metadata fields containing reST/Markdown content to be parsed and
@ -564,44 +557,47 @@ written over time.
Example usage::
YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'
YEAR_ARCHIVE_URL = 'posts/{date:%Y}/'
MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'
MONTH_ARCHIVE_URL = 'posts/{date:%Y}/{date:%b}/'
With these settings, Pelican will create an archive of all your posts for the
year at (for instance) ``posts/2011/index.html`` and an archive of all your
posts for the month at ``posts/2011/Aug/index.html``.
posts for the month at ``posts/2011/Aug/index.html``. These can be accessed
through the URLs ``posts/2011/`` and ``posts/2011/Aug/``, respectively.
.. note::
Period archives work best when the final path segment is ``index.html``.
This way a reader can remove a portion of your URL and automatically arrive
at an appropriate archive of posts, without having to specify a page name.
.. data:: YEAR_ARCHIVE_URL = ''
The URL to use for per-year archives of your posts. Used only if you have
the ``{url}`` placeholder in ``PAGINATION_PATTERNS``.
.. data:: YEAR_ARCHIVE_SAVE_AS = ''
The location to save per-year archives of your posts.
.. data:: MONTH_ARCHIVE_URL = ''
.. data:: YEAR_ARCHIVE_URL = ''
The URL to use for per-month archives of your posts. Used only if you have
the ``{url}`` placeholder in ``PAGINATION_PATTERNS``.
The URL to use for per-year archives of your posts. You should set this if
you enable per-year archives.
.. data:: MONTH_ARCHIVE_SAVE_AS = ''
The location to save per-month archives of your posts.
.. data:: DAY_ARCHIVE_URL = ''
.. data:: MONTH_ARCHIVE_URL = ''
The URL to use for per-day archives of your posts. Used only if you have the
``{url}`` placeholder in ``PAGINATION_PATTERNS``.
The URL to use for per-month archives of your posts. You should set this if
you enable per-month archives.
.. data:: DAY_ARCHIVE_SAVE_AS = ''
The location to save per-day archives of your posts.
.. data:: DAY_ARCHIVE_URL = ''
The URL to use for per-day archives of your posts. You should set this if
you enable per-day archives.
``DIRECT_TEMPLATES`` work a bit differently than noted above. Only the
``_SAVE_AS`` settings are available, but it is available for any direct
template.
@ -1001,10 +997,10 @@ the ``TAG_FEED_ATOM`` and ``TAG_FEED_RSS`` settings:
placeholder. If not set, ``TAG_FEED_RSS`` is used both for save location and
URL.
.. data:: FEED_MAX_ITEMS
.. data:: FEED_MAX_ITEMS = 100
Maximum number of items allowed in a feed. Feed item quantity is
unrestricted by default.
Maximum number of items allowed in a feed. Setting to ``None`` will cause the
feed to contains every article. 100 if not specified.
.. data:: RSS_FEED_SUMMARY_ONLY = True
@ -1228,6 +1224,12 @@ Following are example ways to specify your preferred theme::
# Specify a customized theme, via absolute path
THEME = "/home/myuser/projects/mysite/themes/mycustomtheme"
The built-in ``simple`` theme can be customized using the following settings.
.. data:: STYLESHEET_URL
The URL of the stylesheet to use.
The built-in ``notmyidea`` theme can make good use of the following settings.
Feel free to use them in your themes as well.
@ -1391,21 +1393,6 @@ modification times of the generated ``*.html`` files will always change.
Therefore, ``rsync``-based uploading may benefit from the ``--checksum``
option.
.. _writing_only_selected_content:
Writing only selected content
=============================
When only working on a single article or page, or making tweaks to your theme,
it is often desirable to generate and review your work as quickly as possible.
In such cases, generating and writing the entire site output is often
unnecessary. By specifying only the desired files as output paths in the
``WRITE_SELECTED`` list, **only** those files will be written. This list can be
also specified on the command line using the ``--write-selected`` option, which
accepts a comma-separated list of output file paths. By default this list is
empty, so all output is written. See :ref:`site_generation` for more details.
Example settings
================

80
docs/themes.rst
View file

@ -71,6 +71,8 @@ All templates will receive the variables defined in your settings file, as long
as they are in all-caps. You can access them directly.
.. _common_variables:
Common Variables
----------------
@ -92,6 +94,10 @@ dates The same list of articles, but ordered by date,
ascending.
hidden_articles The list of hidden articles
drafts The list of draft articles
period_archives A dictionary containing elements related to
time-period archives (if enabled). See the section
:ref:`Listing and Linking to Period Archives
<period_archives_variable>` for details.
authors A list of (author, articles) tuples, containing all
the authors and corresponding articles (values)
categories A list of (category, articles) tuples, containing
@ -134,6 +140,23 @@ your date according to the locale given in your settings::
.. _datetime: https://docs.python.org/3/library/datetime.html#datetime-objects
.. _strftime: https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior
Checking Loaded Plugins
-----------------------
Pelican provides a ``plugin_enabled`` Jinja test for checking if a certain plugin
is enabled. This test accepts a plugin name as a string and will return a Boolean.
Namespace plugins can be specified by full name (``pelican.plugins.plugin_name``)
or short name (``plugin_name``). The following example uses the ``webassets`` plugin
to minify CSS if the plugin is enabled and otherwise falls back to regular CSS::
{% if "webassets" is plugin_enabled %}
{% assets filters="cssmin", output="css/style.min.css", "css/style.scss" %}
<link rel="stylesheet" href="{{SITEURL}}/{{ASSET_URL}}">
{% endassets %}
{% else %}
<link rel="stylesheet" href="{{SITEURL}}/css/style.css}">
{% endif %}
index.html
----------
@ -348,6 +371,63 @@ period_archives.html template
<https://github.com/getpelican/pelican/blob/master/pelican/themes/simple/templates/period_archives.html>`_.
.. _period_archives_variable:
Listing and Linking to Period Archives
""""""""""""""""""""""""""""""""""""""
The ``period_archives`` variable can be used to generate a list of links to
the set of period archives that Pelican generates. As a :ref:`common variable
<common_variables>`, it is available for use in any template, so you
can implement such an index in a custom direct template, or in a sidebar
visible across different site pages.
``period_archives`` is a dict that may contain ``year``, ``month``, and/or
``day`` keys, depending on which ``*_ARCHIVE_SAVE_AS`` settings are enabled.
The corresponding value is a list of dicts, where each dict in turn represents
a time period (ordered according to the ``NEWEST_FIRST_ARCHIVES`` setting)
with the following keys and values:
=================== ===================================================
Key Value
=================== ===================================================
period The same tuple as described in
``period_archives.html``, e.g.
``(2023, 'June', 18)``.
period_num The same tuple as described in
``period_archives.html``, e.g. ``(2023, 6, 18)``.
url The URL to the period archive page, e.g.
``posts/2023/06/18/``. This is controlled by the
corresponding ``*_ARCHIVE_URL`` setting.
save_as The path to the save location of the period archive
page file, e.g. ``posts/2023/06/18/index.html``.
This is used internally by Pelican and is usually
not relevant to themes.
articles A list of :ref:`Article <object-article>` objects
that fall under the time period.
dates Same list as ``articles``, but ordered according
to the ``NEWEST_FIRST_ARCHIVES`` setting.
=================== ===================================================
Here is an example of how ``period_archives`` can be used in a template:
.. code-block:: html+jinja
<ul>
{% for archive in period_archives.month %}
<li>
<a href="{{ SITEURL }}/{{ archive.url }}">
{{ archive.period | reverse | join(' ') }} ({{ archive.articles|count }})
</a>
</li>
{% endfor %}
</ul>
You can change ``period_archives.month`` in the ``for`` statement to
``period_archives.year`` or ``period_archives.day`` as appropriate, depending
on the time period granularity desired.
Objects
=======

116
docs/tips.rst
View file

@ -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
----------------