weeheavy/pelican-theme
1
0
Fork 0
forked from github/pelican
Code Pull requests Activity

chore: remove obsolete code from repo

Browse source
This commit is contained in:
Oliver Ladner 2024-12-13 15:09:18 +01:00
commit eeaffe79e1
104 changed files with 0 additions and 18691 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.coveragerc
View file

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

19
.git-blame-ignore-revs
View file

@ -1,19 +0,0 @@
# .git-blame-ignore-revs
# Apply code style to project via: ruff format .
cabdb26cee66e1173cf16cb31d3fe5f9fa4392e7
# Upgrade code base for Python 3.8 and above
ecd598f293161a52564aa6e8dfdcc8284dc93970
# Apply Ruff and pyupgrade to Jinja templates
db241feaa445375dc05e189e69287000ffe5fa8e
# Change pre-commit to run ruff and ruff-format with fixes
6d8597addb17d5fa3027ead91427939e8e4e89ec
# Upgrade Ruff from 0.1.x to 0.4.x
0bd02c00c078fe041b65fbf4eab13601bb42676d
# Apply more Ruff checks to code
9d30c5608a58d202b1c02d55651e6ac746bfb173
# Apply yet more Ruff checks to code
7577dd7603f7cb3a09922d1edb65b6eafb6e2ac7
# Indent Jinja templates, HTML, CSS, and JS via DjHTML
4af40e80772a58eac8969360e5caeb99e3e26e78
# Ruff UP031: Use F-string format specifiers instead of percent format
30bde3823f50b9ba8ac5996c1c46bb72031aa6b8

11
.gitattributes vendored
View file

@ -1,11 +0,0 @@
# Auto detect text files and perform LF normalization
* text=auto
# Improve accuracy of GitHub's Linguist-powered language statistics
pelican/tests/content/* linguist-vendored
pelican/tests/output/* linguist-vendored
pelican/tests/theme_overrides/* linguist-vendored
pelican/themes/notmyidea/templates/*.html linguist-language=Jinja
pelican/themes/simple/templates/*.html linguist-language=Jinja
samples/* linguist-vendored
*.html linguist-vendored

1
.github/CODEOWNERS vendored
View file

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

5
.github/FUNDING.yml vendored
View file

@ -1,5 +0,0 @@
---
github: justinmayer
custom: https://donate.getpelican.com
liberapay: pelican

40
.github/ISSUE_TEMPLATE/---bug-report.md vendored
View file

@ -1,40 +0,0 @@
---
name: "\U0001F41E Bug Report"
about: Did you find a bug?
title: ''
labels: bug
assignees: ''
---
<!--
Hi there! Thank you for discovering and submitting an issue.
Before you submit this, let’s make sure of a few things.
Please make sure the following boxes are ticked if they are correct.
If not, please try and fulfill them first.
-->
<!-- 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 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.
-->
- **OS version and name**: <!-- Replace with version + name -->
- **Python version**: <!-- Replace with version -->
- **Pelican version**: <!-- Replace with version -->
- **Link to theme**: <!-- Replace with link to the theme you are using -->
- **Links to plugins**: <!-- Replace with list of links to plugins you are using -->
- **Link to your site**: <!-- If available, replace with link to your site -->
- **Link to your source**: <!-- If available, replace with link to relevant source repository -->
- **Link to a [Gist](https://gist.github.com/) with the contents of your settings file**: <!-- If your source is not accessible, put Gist link here -->
## Issue
<!--
Now feel free to write your issue. Please avoid vague phrases like “[…] doesn’t work”.
Be descriptive! Thanks again 🙌 ❤️
-->

22
.github/ISSUE_TEMPLATE/---documentation.md vendored
View file

@ -1,22 +0,0 @@
---
name: "\U0001F4DA Documentation"
about: Did you find errors, problems, or anything unclear in the docs (https://docs.getpelican.com/)?
title: ''
labels: docs
assignees: ''
---
<!--
Hi there! Thank you for discovering and submitting an issue with our documentation.
Before you submit this, let’s make sure of a few things.
Please make sure the following boxes are ticked if they are correct.
If not, please try and fulfill them first.
-->
<!-- 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.
## Issue
<!-- Now feel free to write your issue, but please be descriptive! Thanks again 🙌 ❤️ -->

24
.github/ISSUE_TEMPLATE/---enhancement-request.md vendored
View file

@ -1,24 +0,0 @@
---
name: "\U0001F381 Feature Request"
about: Do you have ideas for new features and improvements?
title: ''
labels: enhancement
assignees: ''
---
<!--
Hi there! Thank you for wanting to make Pelican better.
Before you submit this, let’s make sure of a few things.
Please make sure the following boxes are ticked if they are correct.
If not, please try and fulfill them first. The last one is optional but encouraged.
-->
<!-- 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 am willing to lend a hand to help implement this feature. <!-- optional but encouraged -->
## Feature Request
<!-- Now feel free to write your idea for improvement. Thanks again 🙌 ❤️ -->

23
.github/ISSUE_TEMPLATE/---everything-else.md vendored
View file

@ -1,23 +0,0 @@
---
name: "\U0001F5C3 Everything Else"
about: Do you have a question/issue that does not fall into any of the other categories?
title: ''
labels: question
assignees: ''
---
<!--
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.
If not, please try and fulfill them first.
-->
<!-- 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.
## Issue
<!-- Now feel free to write your issue, but please be descriptive! Thanks again 🙌 ❤️ -->

8
.github/ISSUE_TEMPLATE/config.yml vendored
View file

@ -1,8 +0,0 @@
---
# 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
contact_links:
- name: '💬 Pelican IRC Channel'
url: https://web.libera.chat/?#pelican
about: |
Chat with the community, ask questions, and learn about best practices.

14
.github/dependabot.yml vendored
View file

@ -1,14 +0,0 @@
# 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"

12
.github/pull_request_template.md vendored
View file

@ -1,12 +0,0 @@
# Pull Request Checklist
Resolves: #issue-number-here <!-- Only if related issue *already* exists — otherwise remove this line -->
<!-- This is just a reminder about the most common mistakes. Please make sure that you tick all *appropriate* boxes. Also, please read our [contribution guide](https://docs.getpelican.com/en/latest/contribute.html#contributing-code) at least once — it will save you unnecessary review cycles! -->
- [ ] Ensured **tests pass** and (if applicable) updated functional test output
- [ ] Conformed to **code style guidelines** by running appropriate linting tools
- [ ] Added **tests** for changed code
- [ ] Updated **documentation** for changed code
<!-- If you have *any* questions to *any* of the points above, just **submit and ask**! This checklist is here to *help* you, not to deter you from contributing! -->

31
.github/stale.yml vendored
View file

@ -1,31 +0,0 @@
# Configuration for probot-stale - https://github.com/probot/stale
# Number of days of inactivity before an Issue or Pull Request becomes stale
daysUntilStale: 60
# Number of days of inactivity before an Issue or Pull Request with the stale label is closed.
daysUntilClose: 30
# Set to true to ignore issues in a project (defaults to false)
exemptProjects: true
# Set to true to ignore issues in a milestone (defaults to false)
exemptMilestones: true
# Set to true to ignore issues with an assignee (defaults to false)
exemptAssignees: true
# Label to use when marking as stale
staleLabel: stale
# Comment to post when marking as stale. Set to `false` to disable
markComment: >
This issue has been automatically marked as stale because it has not had
recent activity. It will be closed if no further activity occurs. Thank you
for your participation and understanding.
# Limit the number of actions per hour, from 1-30. Default is 30
limitPerRun: 1
# Limit to only `issues` or `pulls`
only: issues

99
.github/workflows/github_pages.yml vendored
View file

@ -1,99 +0,0 @@
# Workflow for publishing to GitHub Pages.
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' or if you have a requirements file use: '-r requirements.txt'"
type: string
output-path:
required: false
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
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@v5
with:
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@v5
- name: Install requirements
run: pip install ${{ inputs.requirements }}
- name: Build Pelican site
shell: python
run: |
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@v3
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@v4

148
.github/workflows/main.yml vendored
View file

@ -1,148 +0,0 @@
name: build
on: [push, pull_request]
env:
# color output for pytest and tox
PYTEST_ADDOPTS: "--color=yes"
PY_COLORS: 1
jobs:
test:
name: Test - ${{ matrix.python }} - ${{ matrix.os }}
runs-on: ${{ matrix.os }}-latest
strategy:
matrix:
os: [ubuntu, macos, windows]
python: ["3.10", "3.11", "3.12"]
include:
- os: ubuntu
python: "3.8"
- os: ubuntu
python: "3.9"
steps:
- uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
cache: "pip"
cache-dependency-path: "**/requirements/*"
- name: Install locale (Linux)
if: startsWith(runner.os, 'Linux')
run: sudo locale-gen fr_FR.UTF-8 tr_TR.UTF-8
- name: Install pandoc
uses: r-lib/actions/setup-pandoc@v2
with:
pandoc-version: "2.9.2"
- name: Install tox
run: python -m pip install -U pip tox
- name: Info
run: |
echo "===== PYTHON ====="
python --version
echo "===== PANDOC ====="
pandoc --version | head -2
- name: Run tests
run: tox -e py${{ matrix.python }}
lint:
name: Lint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pdm-project/setup-pdm@v4
with:
python-version: "3.11"
cache: true
cache-dependency-path: ./pyproject.toml
- name: Install dependencies
run: |
pdm install --no-default --dev
- name: Run linters
run: pdm lint --diff
- name: Run pre-commit checks on all files
uses: pre-commit/action@v3.0.1
build:
name: Test build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pdm-project/setup-pdm@v4
with:
python-version: "3.11"
cache: true
cache-dependency-path: ./pyproject.toml
- name: Install dependencies
run: pdm install --dev
- name: Build package
run: pdm build
- name: Test build
run: pdm run pytest --check-build=dist pelican/tests/build_test
docs:
name: Build docs
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
cache: "pip"
cache-dependency-path: "**/requirements/*"
- name: Install tox
run: python -m pip install -U pip tox
- name: Check
run: tox -e docs
- name: cache the docs for inspection
uses: actions/upload-artifact@v4
with:
name: docs
path: docs/_build/html/
deploy:
name: Deploy
environment: Deployment
needs: [test, lint, docs, build]
runs-on: ubuntu-latest
if: github.ref=='refs/heads/main' && github.event_name!='pull_request' && github.repository == 'getpelican/pelican'
permissions:
contents: write
id-token: write
steps:
- uses: actions/checkout@v4
with:
token: ${{ secrets.GH_TOKEN }}
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Check release
id: check_release
run: |
python -m pip install --upgrade pip
python -m pip install autopub[github]
autopub check
- name: Publish
if: ${{ steps.check_release.outputs.autopub_release=='true' }}
env:
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
run: |
autopub prepare
autopub commit
autopub build
autopub githubrelease
- name: Upload package to PyPI
if: ${{ steps.check_release.outputs.autopub_release=='true' }}
uses: pypa/gh-action-pypi-publish@release/v1

24
.mailmap
View file

@ -1,24 +0,0 @@
Alexis Métaireau <alexis@notmyidea.org>
Alexis Métaireau <alexis@notmyidea.org> <alexis, notmyidea, org>
Alexis Métaireau <alexis@notmyidea.org> <ametaireau@gmail.com>
Axel Haustant <noirbizarre@gmail.com> <axel.haustant.ext@mappy.com>
Axel Haustant <noirbizarre@gmail.com> <axel.haustant@valtech.fr>
Dave Mankoff <mankyd@gmail.com>
Feth Arezki <feth@tuttu.info>
Guillaume <guillaume@lame.homelinux.com>
Guillaume <guillaume@lame.homelinux.com> <guillaume@mint.(none)>
Guillaume B <guitreize@gmail.com>
Guillermo López <guilan70@hotmail.com>
Guillermo López <guilan70@hotmail.com> <guillermo.lopez@outlook.com>
Jomel Imperio <jimperio@gmail.com>
Justin Mayer <entrop@gmail.com>
Justin Mayer <entrop@gmail.com> <entroP@gmail.com>
Marco Milanesi <kpanic@gnufunk.org> <marcom@openquake.org>
Massimo Santini <santini@dsi.unimi.it> <santini@spillane.docenti.dsi.unimi.it>
Rémy HUBSCHER <hubscher.remy@gmail.com> <remy.hubscher@ionyse.com>
Simon Conseil <contact@saimon.org>
Simon Liedtke <liedtke.simon@googlemail.com>
Skami18 <skami@skami-laptop.dyndns.org>
Stuart Colville <muffinresearchlabs@gmail.com> <muffinresearch@gmail.com>
Stéphane Bunel <stephane@lutetium.(none)>
tBunnyMan <WagThatTail@Me.com>

30
.pre-commit-config.yaml
View file

@ -1,30 +0,0 @@
---
# 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
hooks:
- id: check-added-large-files
- id: check-ast
- id: check-toml
- id: check-yaml
- id: debug-statements
- id: detect-private-key
- id: end-of-file-fixer
- id: forbid-new-submodules
- id: trailing-whitespace
- repo: https://github.com/astral-sh/ruff-pre-commit
# ruff version should match the one in pyproject.toml
rev: v0.4.10
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
- id: ruff-format
- repo: https://github.com/rtts/djhtml
rev: '3.0.6'
hooks:
- id: djhtml
- id: djcss
- id: djjs

28
.readthedocs.yaml
View file

@ -1,28 +0,0 @@
---
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the OS, Python version, and any other needed tools
build:
os: ubuntu-22.04
tools:
python: "3.10"
# Build HTML & PDF formats
formats:
- htmlzip
- pdf
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
# Version of Python and requirements required to build the docs
python:
install:
- requirements: requirements/developer.pip
- method: pip
path: .

10
.vale.ini
View file

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

139
CONTRIBUTING.rst
View file

@ -1,139 +0,0 @@
Filing issues
=============
* Before you submit a new issue, try `asking for help`_ first.
* If determined to create a new issue, first search `Pelican Discussions`_
and `existing issues`_ (open and closed) to see if your question has already
been answered previously.
.. _`asking for help`: `How to get help`_
.. _`Pelican Discussions`: https://github.com/getpelican/pelican/discussions
.. _`existing issues`: https://github.com/getpelican/pelican/issues
How to get help
===============
Before you ask for help, please make sure you do the following:
1. Read the documentation_ thoroughly. If in a hurry, at least use the search
field that is provided at top-left on the documentation_ pages. Make sure
you read the docs for the Pelican version you are using.
2. Use a search engine (e.g., DuckDuckGo, Google) to search for a solution to
your problem. Someone may have already found a solution, perhaps in the
form of a ':pelican-doc:`plugins` or a specific combination of settings.
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 ``main`` branch)
* latest releases of libraries used by Pelican
* no plugins or only those related to the issue
**NOTE:** The most common sources of problems are anomalies in (1) themes, (2)
plugins, (3) settings files, and (4) ``make``/``invoke`` automation wrappers.
If you can't reproduce your problem when using the following steps to generate
your site, then the problem is almost certainly with one of the above-listed
elements (and not Pelican itself)::
cd ~/projects/your-site
git clone https://github.com/getpelican/pelican ~/projects/pelican
pelican content -s ~/projects/pelican/samples/pelican.conf.py -t ~/projects/pelican/pelican/themes/notmyidea
If you can generate your site without problems using the steps above, then your
problem is unlikely to be caused by Pelican itself, and therefore please
consider reaching out to the maintainers of the plugins/theme you are using
instead of raising the topic with the Pelican core community.
If despite the above efforts you still cannot resolve your problem, be sure to
include in your inquiry the following information, preferably in the form of
links to content uploaded to a `paste service`_, GitHub repository, or other
publicly-accessible location:
* Describe what version of Pelican you are running (output of ``pelican --version``
or the HEAD commit hash if you cloned the repo) and how exactly you installed
it (the full command you used, e.g. ``python -m pip install pelican``).
* If you are looking for a way to get some end result, prepare a detailed
description of what the end result should look like (preferably in the form of
an image or a mock-up page) and explain in detail what you have done so far to
achieve it.
* If you are trying to solve some issue, prepare a detailed description of how
to reproduce the problem. If the issue cannot be easily reproduced, it cannot
be debugged by developers or volunteers. Describe only the **minimum steps**
necessary to reproduce it (no extra plugins, etc.).
* Upload your settings file or any other custom code that would enable people to
reproduce the problem or to see what you have already tried to achieve the
desired end result.
* Upload detailed and **complete** output logs and backtraces (remember to add
the ``--debug`` flag: ``pelican --debug content [...]``)
.. _documentation: https://docs.getpelican.com/
.. _`paste service`: https://dpaste.com
Once the above preparation is ready, you can post your query as a new thread in
`Pelican Discussions`_. Remember to include all the information you prepared.
Contributing code
=================
Before you submit a contribution, please ask whether it is desired so that you
don't spend a lot of time working on something that would be rejected for a
known reason. Consider also whether your new feature might be better suited as
a ':pelican-doc:`plugins` — you can `ask for help`_ to make that determination.
Also, if you intend to submit a pull request to address something for which there
is no existing issue, there is no need to create a new issue and then immediately
submit a pull request that closes it. You can submit the pull request by itself.
Using Git and GitHub
--------------------
* `Create a new branch`_ specific to your change (as opposed to making
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
request** for the bugfix. Similarly, any proposed changes to code style
formatting should be in a completely separate pull request.
* Add a ``RELEASE.md`` file in the root of the project that contains the
release type (major, minor, patch) and a summary of the changes that will be
used as the release changelog entry. For example::
Release type: minor
Reload browser window upon changes to content, settings, or theme
* Check for unnecessary whitespace via ``git diff --check`` before committing.
* First line of your commit message should start with present-tense verb, be 50
characters or less, and include the relevant issue number(s) if applicable.
*Example:* ``Ensure proper PLUGIN_PATH behavior. Refs #428.`` If the commit
*completely fixes* an existing bug report, please use ``Fixes #585`` or ``Fix
#585`` syntax (so the relevant issue is automatically closed upon PR merge).
* After the first line of the commit message, add a blank line and then a more
detailed explanation (when relevant).
* `Squash your commits`_ to eliminate merge commits and ensure a clean and
readable commit history.
* After you have issued a pull request, the continuous integration (CI) system
will run the test suite on all supported Python versions and check for code style
compliance. If any of these checks fail, you should fix them. (If tests fail
on the CI system but seem to pass locally, ensure that local test runs aren't
skipping any tests.)
Contribution quality standards
------------------------------
* Adhere to the project's code style standards. See: `Development Environment`_
* Ensure your code is compatible with the `officially-supported Python releases`_.
* Add docs and tests for your changes. Undocumented and untested features will
not be accepted.
* :pelican-doc:`Run all the tests <contribute>` **on all versions of Python
supported by Pelican** to ensure nothing was accidentally broken.
Check out our `Git Tips`_ page or `ask for help`_ if you
need assistance or have any questions about these guidelines.
.. _`plugin`: https://docs.getpelican.com/en/latest/plugins.html
.. _`Create a new branch`: https://github.com/getpelican/pelican/wiki/Git-Tips#making-your-changes
.. _`Squash your commits`: https://github.com/getpelican/pelican/wiki/Git-Tips#squashing-commits
.. _`Git Tips`: https://github.com/getpelican/pelican/wiki/Git-Tips
.. _`ask for help`: `How to get help`_
.. _`Development Environment`: https://docs.getpelican.com/en/latest/contribute.html#setting-up-the-development-environment
.. _`officially-supported Python releases`: https://devguide.python.org/versions/#versions

661
LICENSE
View file

@ -1,661 +0,0 @@
GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://www.fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU Affero General Public License is a free, copyleft license for
software and other kinds of works, specifically designed to ensure
cooperation with the community in the case of network server software.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
our General Public Licenses are intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
Developers that use our General Public Licenses protect your rights
with two steps: (1) assert copyright on the software, and (2) offer
you this License which gives you legal permission to copy, distribute
and/or modify the software.
A secondary benefit of defending all users' freedom is that
improvements made in alternate versions of the program, if they
receive widespread use, become available for other developers to
incorporate. Many developers of free software are heartened and
encouraged by the resulting cooperation. However, in the case of
software used on network servers, this result may fail to come about.
The GNU General Public License permits making a modified version and
letting the public access it on a server without ever releasing its
source code to the public.
The GNU Affero General Public License is designed specifically to
ensure that, in such cases, the modified source code becomes available
to the community. It requires the operator of a network server to
provide the source code of the modified version running there to the
users of that server. Therefore, public use of a modified version, on
a publicly accessible server, gives the public access to the source
code of the modified version.
An older license, called the Affero General Public License and
published by Affero, was designed to accomplish similar goals. This is
a different license, not a version of the Affero GPL, but Affero has
released a new version of the Affero GPL which permits relicensing under
this license.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU Affero General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Remote Network Interaction; Use with the GNU General Public License.
Notwithstanding any other provision of this License, if you modify the
Program, your modified version must prominently offer all users
interacting with it remotely through a computer network (if your version
supports such interaction) an opportunity to receive the Corresponding
Source of your version by providing access to the Corresponding Source
from a network server at no charge, through some standard or customary
means of facilitating copying of software. This Corresponding Source
shall include the Corresponding Source for any work covered by version 3
of the GNU General Public License that is incorporated pursuant to the
following paragraph.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the work with which it is combined will remain governed by version
3 of the GNU General Public License.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU Affero General Public License from time to time. Such new versions
will be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU Affero General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU Affero General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU Affero General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If your software can interact with users remotely through a computer
network, you should also make sure that it provides a way for users to
get its source. For example, if your program is a web application, its
interface could display a "Source" link that leads users to an archive
of the code. There are many ways you could offer source, and different
solutions will be better for different programs; see section 13 for the
specific requirements.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU AGPL, see
<https://www.gnu.org/licenses/>.

78
README.rst
View file

@ -1,78 +0,0 @@
Pelican |build-status| |pypi-version| |downloads| |repology|
============================================================
Pelican is a static site generator, written in Python_, that allows you to create
web sites by composing text files in formats such as Markdown, reStructuredText, and HTML.
With Pelican, you can create web sites without worrying about databases or server-side programming.
Pelican generates static sites that can be served via any web server or hosting service.
You can perform the following functions with Pelican:
* Compose content in Markdown_ or reStructuredText_ using your editor of choice
* Simple command-line tool (re)generates HTML, CSS, and JS from your source content
* Easy to interface with version control systems and web hooks
* Completely static output is simple to host anywhere
Features
--------
Pelican’s feature highlights include:
* Chronological content (e.g., articles, blog posts) as well as static pages
* Integration with external services
* Site themes (created using Jinja2_ templates)
* Publication of articles in multiple languages
* Generation of Atom and RSS feeds
* Code syntax highlighting via Pygments_
* Import existing content from WordPress, Dotclear, or RSS feeds
* Fast rebuild times due to content caching and selective output writing
* Extensible via a rich plugin ecosystem: `Pelican Plugins`_
Check out the `Pelican documentation`_ for further information.
How to get help, contribute, or provide feedback
------------------------------------------------
See our `contribution submission and feedback guidelines <CONTRIBUTING.rst>`_.
Source code
-----------
Pelican’s source code is `hosted on GitHub`_. For information on how it works,
have a look at `Pelican's internals`_.
Why the name “Pelican”?
-----------------------
“Pelican” is an anagram of *calepin*, which means “notebook” in French.
.. Links
.. _Python: https://www.python.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Markdown: https://daringfireball.net/projects/markdown/
.. _Jinja2: https://palletsprojects.com/p/jinja/
.. _Pygments: https://pygments.org/
.. _`Pelican Plugins`: https://github.com/pelican-plugins
.. _`Pelican documentation`: https://docs.getpelican.com/
.. _`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=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/
:alt: PyPI: the Python Package Index
.. |downloads| image:: https://img.shields.io/pypi/dm/pelican.svg
:target: https://pypi.org/project/pelican/
:alt: Monthly Downloads from PyPI
.. |repology| image:: https://repology.org/badge/tiny-repos/pelican.svg
:target: https://repology.org/project/pelican/versions
:alt: Repology: the packaging hub

178
THANKS
View file

@ -1,178 +0,0 @@
Pelican is a project led by Justin Mayer <https://justinmayer.com/>
and originally created by Alexis Métaireau <https://blog.notmyidea.org/>, but
there are a large number of people that have contributed or implemented key
features over time. We do our best to keep this list up-to-date, but you can
also have a look at the nice contributor graphs produced by GitHub:
https://github.com/getpelican/pelican/graphs/contributors
If you want to contribute, check the documentation section about how to do so:
<https://docs.getpelican.com/en/latest/contribute.html>
Aaron Kavlie
Abhishek L
Albrecht Mühlenschulte
Aldiantoro Nugroho
Alen Mujezinovic
Alessandro Martin
Alexander Artemenko
Alexandre RODIERE
Alexis Daboville
Alexis Métaireau
Allan Whatmough
Andrea Crotti
Andrew Laski
Andrew Spiers
Arnaud BOS
asselinpaul
Axel Haustant
Ben Rosser (TC01)
Ben Sturmfels
Benoît HERVIER
Bernhard Scheirle
Borgar
Brandon W Maister
Brendan Wholihan
Brian C. Lane
Brian Hsu
Brian St. Pierre
Bruno Binet
BunnyMan
Chenguang Wang
Chris Elston
Chris McDonald (Wraithan)
Chris Streeter
Christophe Chauvet
Clint Howarth
Colin Dunklau
Dafydd Crosby
Dana Woodman
Dave King
Dave Mankoff
David Beitey
David Marble
Deniz Turgut (Avaris)
derdon
Dirkjan Ochtman
Dirk Makowski
draftcode
Edward Delaporte
Emily Strickland
epatters
Eric Case
Erik Hetzner
FELD Boris
Feth Arezki
Florian Jacob
Florian Preinstorfer
Félix Delval
Frederik Ring
Freeculture
George V. Reilly
Guillaume
Guillaume B
Guillermo López
guillermooo
Ian Cordasco
Igor Kalnitsky
Irfan Ahmad
Iuri de Silvio
Ivan Dyedov
James King
James Rowe
Jason K. Moore
jawher
Jered Boxman
Jerome
Jiachen Yang
Jochen Breuer
joe di castro
John Kristensen
John Mastro
Jökull Sólberg Auðunsson
Jomel Imperio
Jonas Borges
Joseph Reagle
Joshua Adelman
Julian Berman
Justin Mayer
Kevin Deldycke
Kevin Yap
Kyle Fuller
Laureline Guerin
Leonard Huang
Leonardo Giordani
Leroy Jiang
Lucas Cimon
Marcel Hellkamp
Marco Milanesi
Marcus Fredriksson
Mario Rodas
Mark Caudill
Martin Brochhaus
Massimo Santini
Matt Bowcock
Matt Layman
Meir Kriheli
Michael Guntsche
Michael Reneer
Michael Yanovich
Mike Yumatov
Mikhail Korobov
Mirek Długosz
m-r-r
mviera
Nam Nguyen
NianQing Yao
Nico Di Rocco
Nicolas Duhamel
Nicolas Perriault
Nicolas Steinmetz
Paolo Melchiorre
Paul Asselin
Pavel Puchkin
Perry Roper
Peter Desmet
Peter Sabaini
Petr Viktorin
Philippe Pepiot
Rachid Belaid
Randall Degges
Ranjhith Kalisamy
Remi Rampin
Rémy HUBSCHER
renhbo
Richard Duivenvoorde
Rogdham
Romain Porte
Roman Skvazh
Ronny Pfannschmidt
Rory McCann
Rıdvan Örsvuran
saghul
sam
Samrat Man Singh
Simon Conseil
Simon Liedtke
Skami18
solsTiCe d'Hiver
Steve Schwarz
Stéphane Bunel
Stéphane Raimbault
Stuart Colville
Talha Mansoor
Tarek Ziade
Thanos Lefteris
Thomas Thurman
Tobias
Tom Adler
Tomi Pieviläinen
Trae Blain
Tristan Miller
Tshepang Lekhonkhobe
Valentin-Costel Hăloiu
Vlad Niculae
William Light
William Minchin
Wladislaw Merezhko
W. Trevor King
Zoresvit

130
docs/Makefile
View file

@ -1,130 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Raclette.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Raclette.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Raclette"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Raclette"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
make -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

BIN
docs/_static/overall.png vendored
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 4.9 KiB

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

@ -1 +0,0 @@
<?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

Before

Width:  |  Height:  |  Size: 4.3 KiB

BIN
docs/_static/theme-basic.zip vendored
View file

Binary file not shown.

11
docs/_static/theme_overrides.css vendored
View file

@ -1,11 +0,0 @@
/* override table width restrictions */
.wy-table-responsive table td, .wy-table-responsive table th {
/* !important prevents the common CSS stylesheets from
overriding this as on RTD they are loaded after this stylesheet */
white-space: normal !important;
}
.wy-table-responsive {
overflow: visible !important;
}

BIN
docs/_static/uml.jpg vendored
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 65 KiB

201
docs/_templates/page.html vendored
View file

@ -1,201 +0,0 @@
{% extends "base.html" %}
{% block body -%}
{{ super() }}
{% include "partials/icons.html" %}
<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
<label class="overlay sidebar-overlay" for="__navigation">
<div class="visually-hidden">Hide navigation sidebar</div>
</label>
<label class="overlay toc-overlay" for="__toc">
<div class="visually-hidden">Hide table of contents sidebar</div>
</label>
{% if theme_announcement -%}
<div class="announcement">
<aside class="announcement-content">
{% block announcement %} {{ theme_announcement }} {% endblock announcement %}
</aside>
</div>
{%- endif %}
<div class="page">
<header class="mobile-header">
<div class="header-left">
<label class="nav-overlay-icon" for="__navigation">
<div class="visually-hidden">Toggle site navigation sidebar</div>
<i class="icon"><svg><use href="#svg-menu"></use></svg></i>
</label>
</div>
<div class="header-center">
<a href="{{ pathto(master_doc) }}"><div class="brand">{{ docstitle if docstitle else project }}</div></a>
</div>
<div class="header-right">
<div class="theme-toggle-container theme-toggle-header">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-header-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
</header>
<aside class="sidebar-drawer">
<div class="sidebar-container">
{% block left_sidebar %}
<div class="sidebar-sticky">
{%- for sidebar_section in sidebars %}
{%- include sidebar_section %}
{%- endfor %}
</div>
{% endblock left_sidebar %}
</div>
</aside>
<div class="main">
<div class="content">
<div class="article-container">
<a href="#" class="back-to-top muted-link">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
</svg>
<span>{% trans %}Back to top{% endtrans %}</span>
</a>
<div class="content-icon-container">
{% if theme_top_of_page_button == "edit" -%}
{%- include "components/edit-this-page.html" with context -%}
{%- elif theme_top_of_page_button != None -%}
{{ warning("Got an unsupported value for 'top_of_page_button'") }}
{%- endif -%}
{#- Theme toggle -#}
<div class="theme-toggle-container theme-toggle-content">
<button class="theme-toggle">
<div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
<svg class="theme-icon-when-auto"><use href="#svg-sun-half"></use></svg>
<svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
<svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
</button>
</div>
<label class="toc-overlay-icon toc-content-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
<div class="visually-hidden">Toggle table of contents sidebar</div>
<i class="icon"><svg><use href="#svg-toc"></use></svg></i>
</label>
</div>
<article role="main">
{% block content %}{{ body }}{% endblock %}
</article>
</div>
<footer>
{% block footer %}
<div class="related-pages">
{% if next -%}
<a class="next-page" href="{{ next.link }}">
<div class="page-info">
<div class="context">
<span>{{ _("Next") }}</span>
</div>
<div class="title">{{ next.title }}</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
{%- endif %}
{% if prev -%}
<a class="prev-page" href="{{ prev.link }}">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>{{ _("Previous") }}</span>
</div>
{% if prev.link == pathto(master_doc) %}
<div class="title">{{ _("Home") }}</div>
{% else %}
<div class="title">{{ prev.title }}</div>
{% endif %}
</div>
</a>
{%- endif %}
</div>
<div class="bottom-of-page">
<div class="left-details">
{%- if show_copyright %}
<div class="copyright">
{%- if hasdoc('copyright') %}
{% trans path=pathto('copyright'), copyright=copyright|e -%}
<a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
{%- endtrans %}
{%- else %}
{% trans copyright=copyright|e -%}
Copyright &#169; {{ copyright }}, <a href="https://justinmayer.com">Justin Mayer</a>, Alexis Metaireau, and contributors
{%- endtrans %}
{%- endif %}
</div>
{%- endif %}
{%- if last_updated -%}
<div class="last-updated">
{% trans last_updated=last_updated|e -%}
Last updated on {{ last_updated }}
{%- endtrans -%}
</div>
{%- endif %}
</div>
<div class="right-details">
{% if theme_footer_icons or READTHEDOCS -%}
<div class="icons">
{% if theme_footer_icons -%}
{% for icon_dict in theme_footer_icons -%}
<a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
{{- icon_dict.html -}}
</a>
{% endfor %}
{%- else -%}
{#- Show Read the Docs project -#}
{%- if READTHEDOCS and slug -%}
<a class="muted-link" href="https://readthedocs.org/projects/{{ slug }}" aria-label="On Read the Docs">
<svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
<path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z" />
</svg>
</a>
{%- endif -%}
{#- Show GitHub repository home -#}
{%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%}
<a class="muted-link" href="https://github.com/{{ github_user }}/{{ github_repo }}" aria-label="On GitHub">
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
<path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
</svg>
</a>
{%- endif -%}
{%- endif %}
</div>
{%- endif %}
</div>
</div>
{% endblock footer %}
</footer>
</div>
<aside class="toc-drawer{% if furo_hide_toc %} no-toc{% endif %}">
{% block right_sidebar %}
{% if not furo_hide_toc %}
<div class="toc-sticky toc-scroll">
<div class="toc-title-container">
<span class="toc-title">
{{ _("On this page") }}
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
{{ toc }}
</div>
</div>
</div>
{% endif %}
{% endblock right_sidebar %}
</aside>
</div>
</div>
{%- endblock %}

555
docs/changelog.rst
View file

@ -1,555 +0,0 @@
Release history
###############
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
==================
* 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
==================
* Use JSON values for extra settings in Invoke tasks template `(#2994) <https://github.com/getpelican/pelican/pull/2994>`_
* Add content tag for links, which can help with things like Twitter social cards `(#3001) <https://github.com/getpelican/pelican/pull/3001>`_
* Improve word count behavior when generating summary `(#3002) <https://github.com/getpelican/pelican/pull/3002>`_
4.7.2 - 2022-02-09
==================
* Fix incorrect parsing of parameters specified via `-e` / `--extra-settings` option flags `(#2938) <https://github.com/getpelican/pelican/pull/2938>`_
* Add ``categories.html`` template to default theme `(#2973) <https://github.com/getpelican/pelican/pull/2973>`_
* Document how to use plugins to inject content `(#2922) <https://github.com/getpelican/pelican/pull/2922>`_
4.7.1 - 2021-10-12
==================
* Extend rich logging to server component `(#2927) <https://github.com/getpelican/pelican/pull/2927>`_
* Fix an issue where metadata flagged to be discarded was being cached `(#2926) <https://github.com/getpelican/pelican/pull/2926>`_
* Adjust suffix in server to allow redirection when needed `(#2931) <https://github.com/getpelican/pelican/pull/2931>`_
* Add MIME types for web fonts `(#2929) <https://github.com/getpelican/pelican/pull/2929>`_
* Distribute sample data used to run tests `(#2935) <https://github.com/getpelican/pelican/pull/2935>`_
* Add Python 3.10 to test matrix
4.7.0 - 2021-10-01
==================
* Improve default theme rendering on mobile and other small screen devices `(#2914) <https://github.com/getpelican/pelican/pull/2914>`_
* Add support for hidden articles `(#2866) <https://github.com/getpelican/pelican/pull/2866>`_
* Improve word count behavior when generating summary CJK & other locales `(#2864) <https://github.com/getpelican/pelican/pull/2864>`_
* Add progress spinner during generation `(#2869) <https://github.com/getpelican/pelican/pull/2869>`_
and richer logging `(#2897) <https://github.com/getpelican/pelican/pull/2897>`_, both via `Rich <https://github.com/willmcgugan/rich>`_
* Invoke tasks ``serve`` and ``livereload`` now auto-open a web browser pointing to the locally-served web site `(#2764) <https://github.com/getpelican/pelican/pull/2764>`_
* Support some date format codes used by ISO dates `(#2902) <https://github.com/getpelican/pelican/pull/2902>`_
* Document how to add a new writer `(#2901) <https://github.com/getpelican/pelican/pull/2901>`_
4.6.0 - 2021-03-23
==================
* Add new URL pattern to ``PAGINATION_PATTERNS`` for the last page in the list `(#1401) <https://github.com/getpelican/pelican/issues/1401>`_
* Speed up ``livereload`` Invoke task via caching `(#2847) <https://github.com/getpelican/pelican/pull/2847>`_
* Ignore ``None`` return value from ``get_generators`` signal `(#2850) <https://github.com/getpelican/pelican/pull/2850>`_
* Relax dependency minimum versions and remove upper bounds
4.5.4 - 2021-01-04
==================
Replace plugin definitions in settings with string representations after registering, so they can be cached correctly `(#2828) <https://github.com/getpelican/pelican/issues/2828>`_.
4.5.3 - 2020-12-01
==================
Fix a mistake made in PR #2821
4.5.2 - 2020-11-22
==================
Improve logging of generators and writer loaders
4.5.1 - 2020-11-02
==================
* Refactor intra-site link discovery in order to match more permissively `(#2646) <https://github.com/getpelican/pelican/issues/2646>`_
* Fix plugins running twice in auto-reload mode `(#2817) <https://github.com/getpelican/pelican/issues/2817>`_
* Add notice to use ``from pelican import signals`` instead of ``import pelican.signals`` `(#2805) <https://github.com/getpelican/pelican/issues/2805>`_
4.5.0 - 2020-08-20
==================
* Add namespace plugin support; list plugins via ``pelican-plugins`` command
* Override settings via ``-e`` / ``--extra-settings`` CLI option flags
* Add settings for custom Jinja globals and tests
* Customize article summary ellipsis via ``SUMMARY_END_SUFFIX`` setting
* Customize Typogrify dash handling via new ``TYPOGRIFY_DASHES`` setting
* Support Unicode when generating slugs
* Support Asciidoc ``.adoc`` file generation in Pelican importer
* Improve user experience when ``pelican --listen`` web server is quit
* Improve Invoke tasks template
* Include tests in source distributions
* Switch CI from Travis to GitHub Actions
* Remove support for Python 2.7
4.2.0 - 2019-10-17
==================
* Support inline SVGs; don't treat titles in SVGs as HTML titles
* Add category to feeds (in addition to tags)
* Improve content metadata field docs
* Add docs for including other Markdown/reST files in content
4.1.3 - 2019-10-09
==================
* Fix quick-start docs regarding ``pelican --listen``
* Set default listen address to 127.0.0.1
* Add extra/optional Markdown dependency to setup.py
* Use correct SSH port syntax for rsync in tasks.py
* Place all deprecated settings handling together
* Add related project URLs for display on PyPI
* Skip some tests on Windows that can't pass due to filesystem differences
4.1.2 - 2019-09-23
==================
Fix pelican.settings.load_source to avoid caching issues - PR #2621
4.1.1 - 2019-08-23
==================
* Add AutoPub to auto-publish releases on PR merge
* Add CSS classes for reStructuredText figures
* Pass ``argv`` to Pelican ``main`` entrypoint
* Set default content status to a blank string rather than ``None``
4.1.0 - 2019-07-14
==================
* Live browser reload upon changed files (provided via Invoke task)
* Add ``pyproject.toml``, managed by Poetry
* Support for invoking ``python -m pelican``
* Add relative source path attribute to content
* Allow directories in ``EXTRA_PATH_METADATA``
* Add ``all_articles`` variable to period pages (for recent posts functionality)
* Improve debug mode output
* Remove blank or duplicate summaries from Atom feed
* Fix bugs in pagination, pelican-import, pelican-quickstart, and feed importer
4.0.1 (2018-11-30)
==================
* Refactor ``pelican.server`` logging
* Fix bug in which all static files were processed as "draft"
* Bug fixes for Invoke/Makefile automation, Importer, and other miscellanea
If upgrading from 3.7.x or earlier, please note that slug-related settings in
4.0+ use ``{slug}`` and/or ``{lang}`` rather than ``%s``. If ``%s``-style
settings are encountered, Pelican will emit a warning and fall back to the
default setting. Some user-submitted themes might try to format setting values
but fail upon site build with a ``TypeError``. In such cases, the theme needs
to be updated. For example, instead of ``TAG_FEED_ATOM|format(tag.slug)``, use
``TAG_FEED_ATOM.format(slug=tag.slug)``
4.0.0 (2018-11-13)
==================
* Replace ``develop_server.sh`` script with ``pelican --listen``
* Improved copy/link behavior for large static files (e.g., videos)
* New ``{static}`` syntax to link to static content; content linked to by
``{static}`` and ``{attach}`` is automatically copied over even if not in
``STATIC_PATHS``
* Pages can now have ``draft`` status
* Show current settings via new ``--print-settings`` flag
* All settings for slugs now use ``{slug}`` and/or ``{lang}`` rather than
``%s``. If ``%s``-style settings are encountered, Pelican will emit a warning
and fallback to the default setting.
* New signals: ``feed_generated`` and ``page_generated_write_page``
* Replace Fabric with Invoke and ``fabfile.py`` template with ``tasks.py``
* Replace ``PAGINATED_DIRECT_TEMPLATES`` by ``PAGINATED_TEMPLATES``, extending
control over pagination to all templates and making page size variable
* Replace ``SLUG_SUBSTITUTIONS`` (and friends) by ``SLUG_REGEX_SUBSTITUTIONS``
for more finegrained control
* ``'{base_name}'`` value in ``PAGINATION_PATTERNS`` setting no longer strips
``'bar'`` from ``'foo/bar.html'`` (unless ``'bar' == 'index'``).
* ``ARTICLE_ORDER_BY`` and ``PAGE_ORDER_BY`` now also affect 1) category, tag
and author pages 2) feeds 3) draft and hidden articles and pages
* New ``ARTICLE_TRANSLATION_ID`` and ``PAGE_TRANSLATION_ID`` settings to
specify metadata attributes used to identify/disable translations
* Make the HTML reader parse multiple occurrences of metadata tags as a list
* New Blogger XML backup importer
* Wordpress importer now updates file links to point to local copies if the
files were downloaded with ``--wp-attach``.
* Importer no longer inserts extra newlines, to prevent breaking of HTML
attributes.
* Pelican server now prioritises ``foo.html`` and ``foo/index.html`` over
``foo/`` when resolving ``foo``.
3.7.1 (2017-01-10)
==================
* Fix locale issues in Quickstart script
* Specify encoding for README and CHANGELOG in setup.py
3.7.0 (2016-12-12)
==================
* Atom feeds output ``<content>`` in addition to ``<summary>``
* Atom feeds use ``<published>`` for the original publication date and
``<updated>`` for modifications
* Simplify Atom feed ID generation and support URL fragments
* Produce category feeds with category-specific titles
* RSS feeds now default to summary instead of full content;
set ``RSS_FEED_SUMMARY_ONLY = False`` to revert to previous behavior
* Replace ``MD_EXTENSIONS`` with ``MARKDOWN`` setting
* Replace ``JINJA_EXTENSIONS`` with more-robust ``JINJA_ENVIRONMENT`` setting
* Improve summary truncation logic to handle special characters and tags that
span multiple lines, using HTML parser instead of regular expressions
* Include summary when looking for intra-site link substitutions
* Link to authors and index via ``{author}name`` and ``{index}`` syntax
* Override widget names via ``LINKS_WIDGET_NAME`` and ``SOCIAL_WIDGET_NAME``
* Add ``INDEX_SAVE_AS`` option to override default ``index.html`` value
* Remove ``PAGES`` context variable for themes in favor of ``pages``
* ``SLUG_SUBSTITUTIONS`` now accepts 3-tuple elements, allowing URL slugs to
contain non-alphanumeric characters
* Tag and category slugs can be controlled with greater precision using the
``TAG_SUBSTITUTIONS`` and ``CATEGORY_SUBSTITUTIONS`` settings
* Author slugs can be controlled with greater precision using the
``AUTHOR_SUBSTITUTIONS`` setting
* ``DEFAULT_DATE`` can be defined as a string
* Use ``mtime`` instead of ``ctime`` when ``DEFAULT_DATE = 'fs'``
* Add ``--fatal=errors|warnings`` option for use with continuous integration
* When using generator-level caching, ensure previously-cached files are
processed instead of just new files.
* Add Python and Pelican version information to debug output
* Improve compatibility with Python 3.5
* Comply with and enforce PEP8 guidelines
* Replace tables in settings documentation with ``data::`` directives
3.6.3 (2015-08-14)
==================
* Fix permissions issue in release tarball
3.6.2 (2015-08-01)
==================
* Fix installation errors related to Unicode in tests
* Don't show pagination in ``notmyidea`` theme if there's only one page
* Make hidden pages available in context
* Improve URLWrapper comparison
3.6.0 (2015-06-15)
==================
* Disable caching by default in order to prevent potential confusion
* Improve caching behavior, replacing ``pickle`` with ``cpickle``
* Allow Markdown or reST content in metadata fields other than ``summary``
* Support semicolon-separated author/tag lists
* Improve flexibility of article sorting
* Add ``--relative-urls`` argument
* Support devserver listening on addresses other than localhost
* Unify HTTP server handlers to ``pelican.server`` throughout
* Handle intra-site links to draft posts
* Move ``tag_cloud`` from core to plugin
* Load default theme's external resources via HTTPS
* Import drafts from WordPress XML
* Improve support for Windows users
* Enhance logging and test suite
* Clean up and refactor codebase
* New signals: ``all_generators_finalized`` and ``page_writer_finalized``
3.5.0 (2014-11-04)
==================
* Introduce ``ARTICLE_ORDER_BY`` and ``PAGE_ORDER_BY`` settings to control the
order of articles and pages.
* Include time zone information in dates rendered in templates.
* Expose the reader name in the metadata for articles and pages.
* Add the ability to store static files along with content in the same
directory as articles and pages using ``{attach}`` in the path.
* Prevent Pelican from raising an exception when there are duplicate pieces of
metadata in a Markdown file.
* Introduce the ``TYPOGRIFY_IGNORE_TAGS`` setting to add HTML tags to be
ignored by Typogrify.
* Add the ability to use ``-`` in date formats to strip leading zeros. For
example, ``%-d/%-m/%y`` will now result in the date ``9/8/12``.
* Ensure feed generation is correctly disabled during quickstart configuration.
* Fix ``PAGE_EXCLUDES`` and ``ARTICLE_EXCLUDES`` from incorrectly matching
sub-directories.
* Introduce ``STATIC_EXCLUDE`` setting to add static file excludes.
* Fix an issue when using ``PAGINATION_PATTERNS`` while ``RELATIVE_URLS``
is enabled.
* Fix feed generation causing links to use the wrong language for month
names when using other locales.
* Fix an issue where the authors list in the simple template wasn't correctly
formatted.
* Fix an issue when parsing non-string URLs from settings.
* Improve consistency of debug and warning messages.
3.4.0 (2014-07-01)
==================
* Speed up content generation via new caching mechanism
* Add selective post generation (instead of always building entire site)
* Many documentation improvements, including switching to prettier RtD theme
* Add support for multiple content and plugin paths
* Add ``:modified:`` metadata field to complement ``:date:``.
Used to specify the last date and time an article was updated independently
from the date and time it was published.
* Add support for multiple authors via new ``:authors:`` metadata field
* Watch for changes in static directories when in auto-regeneration mode
* Add filters to limit log output when desired
* Add language support to drafts
* Add ``SLUGIFY_SOURCE`` setting to control how post slugs are generated
* Fix many issues relating to locale and encoding
* Apply Typogrify filter to post summary
* Preserve file metadata (e.g. time stamps) when copying static files to output
* Move AsciiDoc support from Pelican core into separate plugin
* Produce inline links instead of reference-style links when importing content
* Improve handling of ``IGNORE_FILES`` setting behavior
* Properly escape symbol characters in tag names (e.g., ``C++``)
* Minor tweaks for Python 3.4 compatibility
* Add several new signals
3.3.0 (2013-09-24)
==================
* Drop Python 3.2 support in favor of Python 3.3
* Add ``Fabfile`` so Fabric can be used for workflow automation instead of Make
* ``OUTPUT_RETENTION`` setting can be used to preserve metadata (e.g., VCS
data such as ``.hg`` and ``.git``) from being removed from output directory
* Tumblr import
* Improve logic and consistency when cleaning output folder
* Improve documentation versioning and release automation
* Improve pagination flexibility
* Rename signals for better consistency (some plugins may need to be updated)
* Move metadata extraction from generators to readers; metadata extraction no
longer article-specific
* Deprecate ``FILES_TO_COPY`` in favor of ``STATIC_PATHS`` and
``EXTRA_PATH_METADATA``
* Summaries in Markdown posts no longer include footnotes
* Remove unnecessary whitespace in output via ``lstrip_blocks`` Jinja parameter
* Move PDF generation from core to plugin
* Replace ``MARKUP`` setting with ``READERS``
* Add warning if img tag is missing ``alt`` attribute
* Add support for ``{}`` in relative links syntax, besides ``||``
* Add support for ``{tag}`` and ``{category}`` relative links
* Add a ``content_written`` signal
3.2.1 and 3.2.2
===============
* Facilitate inclusion in FreeBSD Ports Collection
3.2 (2013-04-24)
================
* Support for Python 3!
* Override page save-to location from meta-data (enables using a static page as
the site's home page, for example)
* Time period archives (per-year, per-month, and per-day archives of posts)
* Posterous blog import
* Improve WordPress blog import
* Migrate plugins to separate repository
* Improve HTML parser
* Provide ability to show or hide categories from menu using
``DISPLAY_CATEGORIES_ON_MENU`` option
* Auto-regeneration can be told to ignore files via ``IGNORE_FILES`` setting
* Improve post-generation feedback to user
* For multilingual posts, use meta-data to designate which is the original
and which is the translation
* Add ``.mdown`` to list of supported Markdown file extensions
* Document-relative URL generation (``RELATIVE_URLS``) is now off by default
3.1 (2012-12-04)
================
* Importer now stores slugs within files by default. This can be disabled with
the ``--disable-slugs`` option.
* Improve handling of links to intra-site resources
* Ensure WordPress import adds paragraphs for all types of line endings
in post content
* Decode HTML entities within WordPress post titles on import
* Improve appearance of LinkedIn icon in default theme
* Add GitHub and Google+ social icons support in default theme
* Optimize social icons
* Add ``FEED_ALL_ATOM`` and ``FEED_ALL_RSS`` to generate feeds containing all
posts regardless of their language
* Split ``TRANSLATION_FEED`` into ``TRANSLATION_FEED_ATOM`` and
``TRANSLATION_FEED_RSS``
* Different feeds can now be enabled/disabled individually
* Allow for blank author: if ``AUTHOR`` setting is not set, author won't
default to ``${USER}`` anymore, and a post won't contain any author
information if the post author is empty
* Move LESS and Webassets support from Pelican core to plugin
* The ``DEFAULT_DATE`` setting now defaults to ``None``, which means that
articles won't be generated unless date metadata is specified
* Add ``FILENAME_METADATA`` setting to support metadata extraction from
filename
* Add ``gzip_cache`` plugin to compress common text files into a ``.gz``
file within the same directory as the original file, preventing the server
(e.g. Nginx) from having to compress files during an HTTP call
* Add support for AsciiDoc-formatted content
* Add ``USE_FOLDER_AS_CATEGORY`` setting so that feature can be toggled on/off
* Support arbitrary Jinja template files
* Restore basic functional tests
* New signals: ``generator_init``, ``get_generators``, and
``article_generate_preread``
3.0 (2012-08-08)
================
* Refactored the way URLs are handled
* Improved the English documentation
* Fixed packaging using ``setuptools`` entrypoints
* Added ``typogrify`` support
* Added a way to disable feed generation
* Added support for ``DIRECT_TEMPLATES``
* Allow multiple extensions for content files
* Added LESS support
* Improved the import script
* Added functional tests
* Rsync support in the generated Makefile
* Improved feed support (easily pluggable with Feedburner for instance)
* Added support for ``abbr`` in reST
* Fixed a bunch of bugs :-)
2.8 (2012-02-28)
==================
* Dotclear importer
* Allow the usage of Markdown extensions
* Themes are now easily extensible
* Don't output pagination information if there is only one page
* Add a page per author, with all their articles
* Improved the test suite
* Made the themes easier to extend
* Removed Skribit support
* Added a ``pelican-quickstart`` script
* Fixed timezone-related issues
* Added some scripts for Windows support
* Date can be specified in seconds
* Never fail when generating posts (skip and continue)
* Allow the use of future dates
* Support having different timezones per language
* Enhanced the documentation
2.7 (2011-06-11)
==================
* Use ``logging`` rather than echoing to stdout
* Support custom Jinja filters
* Compatibility with Python 2.5
* Added a theme manager
* Packaged for Debian
* Added draft support
2.6 (2011-03-08)
==================
* Changes in the output directory structure
* Makes templates easier to work with / create
* Added RSS support (was Atom-only)
* Added tag support for the feeds
* Enhance the documentation
* Added another theme (brownstone)
* Added translations
* Added a way to use cleaner URLs with a rewrite url module (or equivalent)
* Added a tag cloud
* Added an autoreloading feature: the blog is automatically regenerated each
time a modification is detected
* Translate the documentation into French
* Import a blog from an RSS feed
* Pagination support
* Added Skribit support
2.5 (2010-11-20)
==================
* Import from WordPress
* Added some new themes (martyalchin / wide-notmyidea)
* First bug report!
* Linkedin support
* Added a FAQ
* Google Analytics support
* Twitter support
* Use relative URLs, not static ones
2.4 (2010-11-06)
================
* Minor themes changes
* Add Disqus support (so we have comments)
* Another code refactoring
* Added config settings about pages
* Blog entries can also be generated in PDF
2.3 (2010-10-31)
================
* Markdown support
2.2 (2010-10-30)
================
* Prettify output
* Manages static pages as well
2.1 (2010-10-30)
================
* Make notmyidea the default theme
2.0 (2010-10-30)
================
* Refactoring to be more extensible
* Change into the setting variables
1.2 (2010-09-28)
================
* Added a debug option
* Added per-category feeds
* Use filesystem to get dates if no metadata is provided
* Add Pygments support
1.1 (2010-08-19)
================
* First working version

99
docs/conf.py
View file

@ -1,99 +0,0 @@
import datetime
import os
import sys
if sys.version_info >= (3, 11):
import tomllib
else:
import tomli as tomllib
sys.path.append(os.path.abspath(os.pardir))
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"]
locale_dirs = ["locale/"]
gettext_compact = False
gettext_uuid = True
extensions = [
"sphinx.ext.autodoc",
"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}" # noqa: RUF001
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_options = {
"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"
html_use_smartypants = True
# If false, no module index is generated.
html_use_modindex = False
# If false, no index is generated.
html_use_index = False
# If true, links to the reST sources are added to the pages.
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
# -- Options for LaTeX output -------------------------------------------------
latex_documents = [
("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,
),
]

652
docs/content.rst
View file

@ -1,652 +0,0 @@
Writing content
###############
Articles and pages
==================
Pelican considers "articles" to be chronological content, such as posts on a
blog, and thus associated with a date.
The idea behind "pages" is that they are usually not temporal in nature and are
used for content that does not change very often (e.g., "About" or "Contact"
pages).
You can find sample content in the repository at ``samples/content/``.
.. _internal_metadata:
File metadata
=============
Pelican tries to be smart enough to get the information it needs from the
file system (for instance, about the category of your articles), but some
information you need to provide in the form of metadata inside your files.
If you are writing your content in reStructuredText format, you can provide
this metadata in text files via the following syntax (give your file the
``.rst`` extension)::
My super title
##############
:date: 2010-10-03 10:20
:modified: 2010-10-04 18:40
:tags: thats, awesome
:category: yeah
:slug: my-super-post
:authors: Alexis Metaireau, Conan Doyle
:summary: Short version for index and feeds
Author and tag lists may be semicolon-separated instead, which allows
you to write authors and tags containing commas::
:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan
Pelican implements an extension to reStructuredText to enable support for the
``abbr`` HTML tag. To use it, write something like this in your post::
This will be turned into :abbr:`HTML (HyperText Markup Language)`.
You can also use Markdown syntax (with a file ending in ``.md``, ``.markdown``,
``.mkd``, or ``.mdown``). Markdown generation requires that you first
explicitly install the Python-Markdown_ package, which can be done via ``pip
install Markdown``.
Pelican also supports `Markdown Extensions`_, which might have to be installed
separately if they are not included in the default ``Markdown`` package and can
be configured and loaded via the ``MARKDOWN`` setting.
Metadata syntax for Markdown posts should follow this pattern::
Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds
This is the content of my super blog post.
You can also have your own metadata keys (so long as they don't conflict with
reserved metadata keywords) for use in your templates. The following table
contains a list of reserved metadata keywords:
=============== ===============================================================
Metadata Description
=============== ===============================================================
``title`` Title of the article or page
``date`` Publication date (e.g., ``YYYY-MM-DD HH:SS``)
``modified`` Modification date (e.g., ``YYYY-MM-DD HH:SS``)
``tags`` Content tags, separated by commas
``keywords`` Content keywords, separated by commas (HTML content only)
``category`` Content category (one only — not multiple)
``slug`` Identifier used in URLs and translations
``author`` Content author, when there is only one
``authors`` Content authors, when there are multiple
``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``, ``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
=============== ===============================================================
Readers for additional formats (such as AsciiDoc_) are available via plugins,
which you can find via the `Pelican Plugins`_ collection as well as the legacy
`pelican-plugins`_ repository.
Pelican can also process HTML files ending in ``.html`` and ``.htm``. Pelican
interprets the HTML in a very straightforward manner, reading metadata from
``meta`` tags, the title from the ``title`` tag, and the body out from the
``body`` tag::
<html>
<head>
<title>My super title</title>
<meta name="tags" content="thats, awesome" />
<meta name="date" content="2012-07-09 22:28" />
<meta name="modified" content="2012-07-10 20:14" />
<meta name="category" content="yeah" />
<meta name="authors" content="Alexis Métaireau, Conan Doyle" />
<meta name="summary" content="Short version for index and feeds" />
</head>
<body>
This is the content of my super blog post.
</body>
</html>
With HTML, there is one simple exception to the standard metadata: tags can be
specified either via the ``tags`` metadata, as is standard in Pelican, or via
the ``keywords`` metadata, as is standard in HTML. The two can be used
interchangeably.
Note that, aside from the title, none of this content metadata is mandatory:
if the date is not specified and ``DEFAULT_DATE`` is set to ``'fs'``, Pelican
will rely on the file's "mtime" timestamp, and the category can be determined
by the directory in which the file resides. For example, a file located at
``python/foobar/myfoobar.rst`` will have a category of ``foobar``. If you would
like to organize your files in other ways where the name of the subfolder would
not be a good category name, you can set the setting ``USE_FOLDER_AS_CATEGORY``
to ``False``. When parsing dates given in the page metadata, Pelican supports
the W3C's `suggested subset ISO 8601`__.
So the title is the only required metadata. If that bothers you, worry not.
Instead of manually specifying a title in your metadata each time, you can use
the source content file name as the title. For example, a Markdown source file
named ``Publishing via Pelican.md`` would automatically be assigned a title of
*Publishing via Pelican*. If you would prefer this behavior, add the following
line to your settings file::
FILENAME_METADATA = '(?P<title>.*)'
.. note::
When experimenting with different settings (especially the metadata
ones) caching may interfere and the changes may not be visible. In
such cases disable caching with ``LOAD_CONTENT_CACHE = False`` or
use the ``--ignore-cache`` command-line switch.
__ `W3C ISO 8601`_
``modified`` should be last time you updated the article, and defaults to
``date`` if not specified. Besides you can show ``modified`` in the templates,
feed entries in feed readers will be updated automatically when you set
``modified`` to the current date after you modified your article.
``authors`` is a comma-separated list of article authors. If there's only one
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. 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
that are matched will be set in the metadata object. The default value for the
``FILENAME_METADATA`` setting will only extract the date from the filename. For
example, if you would like to extract both the date and the slug, you could set
something like: ``'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'``
Please note that the metadata available inside your files takes precedence over
the metadata extracted from the filename.
Pages
=====
If you create a folder named ``pages`` inside the content folder, all the
files in it will be used to generate static pages, such as **About** or
**Contact** pages. (See example filesystem layout below.)
You can use the ``DISPLAY_PAGES_ON_MENU`` setting to control whether all those
pages are displayed in the primary navigation menu. (Default is ``True``.)
If you want to exclude any pages from being linked to or listed in the menu,
then add a ``status: hidden`` attribute to its metadata. This is useful for
things like making error pages that fit the generated theme of your site.
Static content
==============
Static files are files other than articles and pages that are copied to the
output folder as-is, without processing. You can control which static files
are copied over with the ``STATIC_PATHS`` setting of the project's
``pelicanconf.py`` file. Pelican's default configuration includes the
``images`` directory for this, but others must be added manually. In addition,
static files that are explicitly linked to are included (see below).
.. note::
In the default configuration, all files with a valid content file suffix
(``.html``, ``.rst``, ``.md``, ...) get processed by the article and page
generators *before* the static generator. This is avoided by altering the
``*_EXCLUDE`` settings appropriately.
Mixed content in the same directory
-----------------------------------
Starting with Pelican 3.5, static files can safely share a source directory
with page source files, without exposing the page sources in the generated
site. Any such directory must be added to both ``STATIC_PATHS`` and
``PAGE_PATHS`` (or ``STATIC_PATHS`` and ``ARTICLE_PATHS``). Pelican will
identify and process the page source files normally, and copy the remaining
files as if they lived in a separate directory reserved for static files.
Note: Placing static and content source files together in the same source
directory does not guarantee that they will end up in the same place in the
generated site. The easiest way to do this is by using the ``{attach}`` link
syntax (described below). Alternatively, the ``STATIC_SAVE_AS``,
``PAGE_SAVE_AS``, and ``ARTICLE_SAVE_AS`` settings (and the corresponding
``*_URL`` settings) can be configured to place files of different types
together, just as they could in earlier versions of Pelican.
.. _ref-linking-to-internal-content:
Linking to internal content
===========================
From Pelican 3.1 onwards, it is now possible to specify intra-site links to
files in the *source content* hierarchy instead of files in the *generated*
hierarchy. This makes it easier to link from the current post to other content
that may be sitting alongside that post (instead of having to determine where
the other content will be placed after site generation).
To link to internal content (files in the ``content`` directory), use the
following syntax for the link target: ``{filename}path/to/file``.
Note: forward slashes, ``/``,
are the required path separator in the ``{filename}`` directive
on all operating systems, including Windows.
For example, a Pelican project might be structured like this::
website/
├── content
│   ├── category/
│   │   └── article1.rst
│   ├── article2.md
│ └── pages
│      └── about.md
└── pelican.conf.py
In this example, ``article1.rst`` could look like this::
The first article
#################
:date: 2012-12-01 10:02
See below intra-site link examples in reStructuredText format.
`a link relative to the current file <{filename}../article2.md>`_
`a link relative to the content root <{filename}/article2.md>`_
and ``article2.md``::
Title: The second article
Date: 2012-12-01 10:02
See below intra-site link examples in Markdown format.
[a link relative to the current file]({filename}category/article1.rst)
[a link relative to the content root]({filename}/category/article1.rst)
Linking to static files
-----------------------
You can link to static content using ``{static}path/to/file``. Files linked to
with this syntax will automatically be copied to the output directory, even if
the source directories containing them are not included in the ``STATIC_PATHS``
setting of the project's ``pelicanconf.py`` file.
For example, a project's content directory might be structured like this::
content
├── images
│   └── han.jpg
├── pdfs
│   └── menu.pdf
└── pages
   └── test.md
``test.md`` would include::
![Alt Text]({static}/images/han.jpg)
[Our Menu]({static}/pdfs/menu.pdf)
Site generation would then copy ``han.jpg`` to ``output/images/han.jpg``,
``menu.pdf`` to ``output/pdfs/menu.pdf``, and write the appropriate links
in ``test.md``.
If you use ``{static}`` to link to an article or a page, this will be turned
into a link to its source code.
Attaching static files
----------------------
Starting with Pelican 3.5, static files can be "attached" to a page or article
using this syntax for the link target: ``{attach}path/to/file``. This works
like the ``{static}`` syntax, but also relocates the static file into the
linking document's output directory. If the static file originates from a
subdirectory beneath the linking document's source, that relationship will be
preserved on output. Otherwise, it will become a sibling of the linking
document.
This only works for linking to static files.
For example, a project's content directory might be structured like this::
content
├── blog
│   ├── icons
│   │   └── icon.png
│   ├── photo.jpg
│   └── testpost.md
└── downloads
└── archive.zip
``pelicanconf.py`` would include::
PATH = 'content'
ARTICLE_PATHS = ['blog']
ARTICLE_SAVE_AS = '{date:%Y}/{slug}.html'
ARTICLE_URL = '{date:%Y}/{slug}.html'
``testpost.md`` would include::
Title: Test Post
Category: test
Date: 2014-10-31
![Icon]({attach}icons/icon.png)
![Photo]({attach}photo.jpg)
[Downloadable File]({attach}/downloads/archive.zip)
Site generation would then produce an output directory structured like this::
output
└── 2014
├── archive.zip
├── icons
│   └── icon.png
├── photo.jpg
└── test-post.html
Notice that all the files linked using ``{attach}`` ended up in or beneath
the article's output directory.
If a static file is linked multiple times, the relocating feature of
``{attach}`` will only work in the first of those links to be processed.
After the first link, Pelican will treat ``{attach}`` like ``{static}``.
This avoids breaking the already-processed links.
**Be careful when linking to a file from multiple documents:**
Since the first link to a file finalizes its location and Pelican does
not define the order in which documents are processed, using ``{attach}`` on a
file linked by multiple documents can cause its location to change from one
site build to the next. (Whether this happens in practice will depend on the
operating system, file system, version of Pelican, and documents being added,
modified, or removed from the project.) Any external sites linking to the
file's old location might then find their links broken. **It is therefore
advisable to use {attach} only if you use it in all links to a file, and only
if the linking documents share a single directory.** Under these conditions,
the file's output location will not change in future builds. In cases where
these precautions are not possible, consider using ``{static}`` links instead
of ``{attach}``, and letting the file's location be determined by the project's
``STATIC_SAVE_AS`` and ``STATIC_URL`` settings. (Per-file ``save_as`` and
``url`` overrides can still be set in ``EXTRA_PATH_METADATA``.)
.. note::
When using ``{attach}``, any parent directory in ``*_URL`` / ``*_SAVE_AS``
settings should match each other. See also: :ref:`url-settings`
Linking to authors, categories, index and tags
----------------------------------------------
You can link to authors, categories, index and tags using the ``{author}name``,
``{category}foobar``, ``{index}`` and ``{tag}tagname`` syntax.
Deprecated internal link syntax
-------------------------------
To remain compatible with earlier versions, Pelican still supports vertical
bars (``||``) in addition to curly braces (``{}``) for internal links. For
example: ``|filename|an_article.rst``, ``|tag|tagname``, ``|category|foobar``.
The syntax was changed from ``||`` to ``{}`` to avoid collision with Markdown
extensions or reST directives. Similarly, Pelican also still supports linking
to static content with ``{filename}``. The syntax was changed to ``{static}``
to allow linking to both generated articles and pages and their static sources.
Support for the old syntax may eventually be removed.
Including other files
---------------------
Both Markdown and reStructuredText syntaxes provide mechanisms for this.
Following below are some examples for **reStructuredText** using `the include directive`_:
.. code-block:: rst
.. include:: file.rst
Include a fragment of a file delimited by two identifiers, highlighted as C++ (slicing based on line numbers is also possible):
.. code-block:: rst
.. include:: main.cpp
:code: c++
:start-after: // begin
:end-before: // end
Include a raw HTML file (or an inline SVG) and put it directly into the output without any processing:
.. code-block:: rst
.. raw:: html
:file: table.html
For **Markdown**, one must rely on an extension. For example, using the `mdx_include plugin`_:
.. code-block:: none
```html
{! template.html !}
```
Importing an existing site
==========================
It is possible to import your site from several other blogging sites
(like WordPress, Tumblr, ..) using a simple script. See :ref:`import`.
Translations
============
It is possible to translate articles. To do so, you need to add a ``lang`` meta
attribute to your articles/pages and set a ``DEFAULT_LANG`` setting (which is
English [en] by default). With those settings in place, only articles with the
default language will be listed, and each article will be accompanied by a list
of available translations for that article.
.. note::
This core Pelican functionality does not create sub-sites
(e.g. ``example.com/de``) with translated templates for each
language. For such advanced functionality the `i18n_subsites
plugin`_ can be used.
By default, Pelican uses the article's URL "slug" to determine if two or more
articles are translations of one another. (This can be changed with the
``ARTICLE_TRANSLATION_ID`` setting.) The slug can be set manually in the file's
metadata; if not set explicitly, Pelican will auto-generate the slug from the
title of the article.
Here is an example of two articles, one in English and the other in French.
The English article::
Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
That's true, foobar is still alive!
And the French version::
Foobar n'est pas mort !
#######################
:slug: foobar-is-not-dead
:lang: fr
Oui oui, foobar est toujours vivant !
Post content quality notwithstanding, you can see that only item in common
between the two articles is the slug, which is functioning here as an
identifier. If you'd rather not explicitly define the slug this way, you must
then instead ensure that the translated article titles are identical, since the
slug will be auto-generated from the article title.
If you do not want the original version of one specific article to be detected
by the ``DEFAULT_LANG`` setting, use the ``translation`` metadata to specify
which posts are translations::
Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
:translation: true
That's true, foobar is still alive!
.. _internal_pygments_options:
Syntax highlighting
===================
Pelican can provide colorized syntax highlighting for your code blocks.
To do so, you must use the following conventions inside your content files.
For reStructuredText, use the ``code-block`` directive to specify the type
of code to be highlighted (in these examples, we'll use ``python``)::
.. code-block:: python
print("Pelican is a static site generator.")
For Markdown, which utilizes the `CodeHilite extension`_ to provide syntax
highlighting, include the language identifier just above the code block,
indenting both the identifier and the code::
There are two ways to specify the identifier:
:::python
print("The triple-colon syntax will *not* show line numbers.")
To display line numbers, use a path-less shebang instead of colons:
#!python
print("The path-less shebang syntax *will* show line numbers.")
The specified identifier (e.g. ``python``, ``ruby``) should be one that
appears on the `list of available lexers <https://pygments.org/docs/lexers/>`_.
When using reStructuredText the following options are available in the
`code-block` directive:
============= ============ =========================================
Option Valid values Description
============= ============ =========================================
anchorlinenos N/A If present, wrap line numbers in ``<a>`` tags.
classprefix string String to prepend to token class names
hl_lines numbers List of lines to be highlighted, where
line numbers to highlight are separated
by a space. This is similar to
``emphasize-lines`` in Sphinx, but it
does not support a range of line numbers
separated by a hyphen, or comma-separated
line numbers.
lineanchors string Wrap each line in an anchor using this
string and -linenumber.
linenos string If present or set to "table", output line
numbers in a table; if set to
"inline", output them inline. "none" means
do not output the line numbers for this
table.
linenospecial number If set, every nth line will be given the
'special' CSS class.
linenostart number Line number for the first line.
linenostep number Print every nth line number.
lineseparator string String to print between lines of code,
'\n' by default.
linespans string Wrap each line in a span using this and
-linenumber.
nobackground N/A If set, do not output background color for
the wrapping element
nowrap N/A If set, do not wrap the tokens at all.
tagsfile string ctags file to use for name definitions.
tagurlformat string format for the ctag links.
============= ============ =========================================
Note that, depending on the version, your Pygments module might not have
all of these options available. Refer to the *HtmlFormatter* section of the
`Pygments documentation <https://pygments.org/docs/formatters/>`_ for more
details on each of the options.
For example, the following code block enables line numbers, starting at 153,
and prefixes the Pygments CSS classes with *pgcss* to make the names
more unique and avoid possible CSS conflicts::
.. code-block:: identifier
:classprefix: pgcss
:linenos: table
:linenostart: 153
<indented code block goes here>
It is also possible to specify the ``PYGMENTS_RST_OPTIONS`` variable in your
Pelican settings file to include options that will be automatically applied to
every code block.
For example, if you want to have line numbers displayed for every code block
and a CSS prefix, you would set this variable to::
PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'}
If specified, settings for individual code blocks will override the defaults in
your settings file.
Publishing drafts
=================
If you want to publish an article or a page as a draft (for friends to review
before publishing, for example), you can add a ``Status: draft`` attribute to
its metadata. That article will then be output to the ``drafts`` folder and not
listed on the index page nor on any category or tag page.
If your articles should be automatically published as a draft (to not
accidentally publish an article before it is finished), include the status in
the ``DEFAULT_METADATA``::
DEFAULT_METADATA = {
'status': 'draft',
}
To publish a post when the default status is ``draft``, update the post's
metadata to include ``Status: published``.
Hidden Posts
============
Like pages, posts can also be marked as ``hidden`` with the ``Status: hidden``
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
.. _pelican-plugins: https://github.com/getpelican/pelican-plugins
.. _Python-Markdown: https://github.com/Python-Markdown/markdown
.. _Markdown Extensions: https://python-markdown.github.io/extensions/
.. _CodeHilite extension: https://python-markdown.github.io/extensions/code_hilite/#syntax
.. _i18n_subsites plugin: https://github.com/getpelican/pelican-plugins/tree/master/i18n_subsites
.. _the include directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#include
.. _mdx_include plugin: https://github.com/neurobin/mdx_include

293
docs/contribute.rst
View file

@ -1,293 +0,0 @@
Contributing and feedback guidelines
####################################
There are many ways to contribute to Pelican. You can improve the
documentation, add missing features, and fix bugs (or just report them). You
can also help out by reviewing and commenting on
`existing issues <https://github.com/getpelican/pelican/issues>`_.
Don't hesitate to fork Pelican and submit an issue or pull request on GitHub.
When doing so, please consider the following guidelines.
.. include:: ../CONTRIBUTING.rst
Setting up the development environment
======================================
While there are many ways to set up one's development environment, the following
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 |min_python| is required for Pelican development.
*(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://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
as a Git remote::
mkdir ~/projects
git clone https://github.com/YOUR_USERNAME/pelican.git ~/projects/pelican
cd ~/projects/pelican
git remote add upstream https://github.com/getpelican/pelican.git
While PDM can dynamically create and manage virtual environments, we're going
to manually create and activate a virtual environment::
mkdir ~/virtualenvs && cd ~/virtualenvs
python3 -m venv pelican
source ~/virtualenvs/pelican/*/activate
Install the needed dependencies and set up the project::
python -m pip install invoke
invoke setup
Your local environment should now be ready to go!
.. _Pip: https://pip.pypa.io/
.. _PDM: https://pdm.fming.dev/latest/
.. _Pelican repository: https://github.com/getpelican/pelican
Development
===========
Once Pelican has been set up for local development, create a topic branch for
your bug fix or feature::
git checkout -b name-of-your-bugfix-or-feature
Now you can make changes to Pelican, its documentation, and/or other aspects of
the project.
Setting up ``git blame`` (optional)
-----------------------------------
``git blame`` annotates lines in a file with information about the pull request
that last modified it. Sweeping shallow changes (like formatting) can make that
information less useful, so we keep a list of such changes to be ignored. Run the
following command to set this up in your repository, adding ``--global`` if you
want this setting to apply to all repositories::
git config blame.ignoreRevsFile .git-blame-ignore-revs
As noted in a `useful article`_ about ``git blame``, there are other related
settings you may find to be beneficial::
# Add `?` to any lines that have had a commit skipped using --ignore-rev
git config --global blame.markIgnoredLines true
# Add `*` to any lines that were added in a skipped commit and can not be attributed
git config --global blame.markUnblamableLines true
.. _useful article: https://www.michaelheap.com/git-ignore-rev/
Running the test suite
----------------------
Each time you make changes to Pelican, there are two things to do regarding
tests: check that the existing tests pass, and add tests for any new features
or bug fixes. The tests are located in ``pelican/tests``, and you can run them
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::
invoke lint
If code style violations are found in lines you changed, correct those lines
and re-run the above lint command until they have all been fixed. You do not
need to address style violations, if any, for code lines you did not touch.
After making your changes and running the tests, you may see a test failure
mentioning that "some generated files differ from the expected functional tests
output." If you have made changes that affect the HTML output generated by
Pelican, and the changes to that output are expected and deemed correct given
the nature of your changes, then you should update the output used by the
functional tests. To do so, **make sure you have both** ``en_EN.utf8`` **and**
``fr_FR.utf8`` **locales installed**, and then run the following command::
invoke update-functional-tests
You may also find that some tests are skipped because some dependency (e.g.,
Pandoc) is not installed. This does not automatically mean that these tests
have passed; you should at least verify that any skipped tests are not affected
by your changes.
You should run the test suite under each of the supported versions of Python.
This is best done by creating a separate Python environment for each version.
Tox_ is a useful tool to automate running tests inside ``virtualenv``
environments.
.. _Tox: https://tox.readthedocs.io/en/latest/
Running a code coverage report
------------------------------
Code is more likely to stay robust if it is tested. Coverage_ is a library that
measures how much of the code is tested. To run it::
invoke coverage
This will show overall coverage, coverage per file, and even line-by-line coverage.
There is also an HTML report available::
open htmlcov/index.html
.. _Coverage: https://github.com/nedbat/coveragepy
Building the docs
-----------------
If you make changes to the documentation, you should build and inspect your
changes before committing them::
invoke docserve
Open http://localhost:8000 in your browser to review the documentation. While
the above task is running, any changes you make and save to the documentation
should automatically appear in the browser, as it live-reloads when it detects
changes to the documentation source files.
Plugin development
------------------
To create a *new* Pelican plugin, please refer to the `plugin template`_
repository for detailed instructions.
If you want to contribute to an *existing* Pelican plugin, follow the steps
above to set up Pelican for local development, and then create a directory to
store cloned plugin repositories::
mkdir -p ~/projects/pelican-plugins
Assuming you wanted to contribute to the Simple Footnotes plugin, you would
first browse to the `Simple Footnotes`_ repository on GitHub and tap the **Fork**
button at top-right. Then clone the source for your fork and add the upstream
project as a Git remote::
git clone https://github.com/YOUR_USERNAME/simple-footnotes.git ~/projects/pelican-plugins/simple-footnotes
cd ~/projects/pelican-plugins/simple-footnotes
git remote add upstream https://github.com/pelican-plugins/simple-footnotes.git
Install the needed dependencies and set up the project::
invoke setup
Create a topic branch for your plugin bug fix or feature::
git checkout -b name-of-your-bugfix-or-feature
After writing new tests for your plugin changes, run the plugin test suite and
check for code style compliance via::
invoke tests
invoke lint
If style violations are found, many of them can be addressed automatically via::
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
reports any code style violations.
.. _plugin template: https://github.com/getpelican/cookiecutter-pelican-plugin
.. _Simple Footnotes: https://github.com/pelican-plugins/simple-footnotes
Submitting your changes
-----------------------
Assuming linting validation and tests pass, add a ``RELEASE.md`` file in the root
of the project that contains the release type (major, minor, patch) and a
summary of the changes that will be used as the release changelog entry.
For example::
Release type: patch
Fix browser reloading upon changes to content, settings, or theme
Commit your changes and push your topic branch::
git add .
git commit -m "Your detailed description of your changes"
git push origin name-of-your-bugfix-or-feature
Finally, browse to your repository fork on GitHub and submit a pull request.
Logging tips
============
Try to use logging with appropriate levels.
For logging messages that are not repeated, use the usual Python way::
# at top of file
import logging
logger = logging.getLogger(__name__)
# when needed
logger.warning("A warning with %s formatting", arg_to_be_formatted)
Do not format log messages yourself. Use ``%s`` formatting in messages and pass
arguments to logger. This is important, because the Pelican logger will
preprocess some arguments, such as exceptions.
Limiting extraneous log messages
--------------------------------
If the log message can occur several times, you may want to limit the log to
prevent flooding. In order to do that, use the ``extra`` keyword argument for
the logging message in the following format::
logger.warning("A warning with %s formatting", arg_to_be_formatted,
extra={'limit_msg': 'A generic message for too many warnings'})
Optionally, you can also set ``'limit_args'`` as a tuple of arguments in
``extra`` dict if your generic message needs formatting.
Limit is set to ``5``, i.e, first four logs with the same ``'limit_msg'`` are
outputted normally but the fifth one will be logged using ``'limit_msg'`` (and
``'limit_args'`` if present). After the fifth, corresponding log messages will
be ignored.
For example, if you want to log missing resources, use the following code::
for resource in resources:
if resource.is_missing:
logger.warning(
'The resource %s is missing', resource.name,
extra={'limit_msg': 'Other resources were missing'})
The log messages will be displayed as follows::
WARNING: The resource prettiest_cat.jpg is missing
WARNING: The resource best_cat_ever.jpg is missing
WARNING: The resource cutest_cat.jpg is missing
WARNING: The resource lolcat.jpg is missing
WARNING: Other resources were missing
Outputting traceback in the logs
--------------------------------
If you're logging inside an ``except`` block, you may want to provide the
traceback information as well. You can do that by setting ``exc_info`` keyword
argument to ``True`` during logging. However, doing so by default can be
undesired because tracebacks are long and can be confusing to regular users.
Try to limit them to ``--debug`` mode like the following::
try:
some_action()
except Exception as e:
logger.error('Exception occurred: %s', e,
exc_info=settings.get('DEBUG', False))

285
docs/faq.rst
View file

@ -1,285 +0,0 @@
Frequently Asked Questions (FAQ)
################################
Here are some frequently asked questions about Pelican.
What's the best way to communicate a problem, question, or suggestion?
======================================================================
Please read our :doc:`feedback guidelines <contribute>`.
How can I help?
===============
There are several ways to help out. First, you can communicate any Pelican
suggestions or problems you might have via `Pelican Discussions
<https://github.com/getpelican/pelican/discussions>`_. Please first check the
existing list of discussions and issues (both open and closed) in order to
avoid submitting topics that have already been covered before.
If you want to contribute, please fork `the Git repository
<https://github.com/getpelican/pelican/>`_, create a new feature branch, make
your changes, and issue a pull request. Someone will review your changes as
soon as possible. Please refer to the :doc:`How to Contribute <contribute>`
section for more details.
You can also contribute by creating themes and improving the documentation.
Is the Pelican settings file mandatory?
=======================================
Configuration files are optional and are just an easy way to configure Pelican.
For basic operations, it's possible to specify options while invoking Pelican
via the command line. See ``pelican --help`` for more information.
Changes to the settings file take no effect
===========================================
When experimenting with different settings (especially the metadata ones)
caching may interfere and the changes may not be visible. In such cases, ensure
that caching is disabled via ``LOAD_CONTENT_CACHE = False`` or use the
``--ignore-cache`` command-line switch.
I'm creating my own theme. How do I use Pygments for syntax highlighting?
=========================================================================
Pygments adds some classes to the generated content. These classes are used by
themes to style code syntax highlighting via CSS. Specifically, you can
customize the appearance of your syntax highlighting via the ``.highlight pre``
class in your theme's CSS file. To see how various styles can be used to render
Django code, for example, use the style selector drop-down at top-right on the
`Pygments project demo site <https://pygments.org/demo/>`_.
You can use the following example commands to generate a starting CSS file from
a Pygments built-in style (in this case, "monokai") and then copy the generated
CSS file to your new theme::
pygmentize -S monokai -f html -a .highlight > pygment.css
cp pygment.css path/to/theme/static/css/
Don't forget to import your ``pygment.css`` file from your main CSS file.
How do I create my own theme?
=============================
Please refer to :ref:`theming-pelican`.
I want to use Markdown, but I got an error.
===========================================
If you try to generate Markdown content without first installing the Markdown
library, you may see a message that says ``No valid files found in content``.
Markdown is not a hard dependency for Pelican, so if you have content in
Markdown format, you will need to explicitly install the Markdown library. You
can do so by typing the following command, prepending ``sudo`` if permissions
require it::
python -m pip install markdown
Can I use arbitrary metadata in my templates?
=============================================
Yes. For example, to include a modified date in a Markdown post, one could
include the following at the top of the article::
Modified: 2012-08-08
For reStructuredText, this metadata should of course be prefixed with a colon::
:Modified: 2012-08-08
This metadata can then be accessed in templates such as ``article.html`` via::
{% if article.modified %}
Last modified: {{ article.modified }}
{% endif %}
If you want to include metadata in templates outside the article context (e.g.,
``base.html``), the ``if`` statement should instead be::
{% if article and article.modified %}
How do I make my output folder structure identical to my content hierarchy?
===========================================================================
Try these settings::
USE_FOLDER_AS_CATEGORY = False
PATH_METADATA = "(?P<path_no_ext>.*)\..*"
ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = "{path_no_ext}.html"
How do I assign custom templates on a per-page basis?
=====================================================
It's as simple as adding an extra line of metadata to any page or article that
you want to have its own template. For example, this is how it would be handled
for content in reST format::
:template: template_name
For content in Markdown format::
Template: template_name
Then just make sure your theme contains the relevant template file (e.g.
``template_name.html``).
How can I override the generated URL of a specific page or article?
===================================================================
Include ``url`` and ``save_as`` metadata in any pages or articles that you want
to override the generated URL. Here is an example page in reST format::
Override url/save_as page
#########################
:url: override/url/
:save_as: override/url/index.html
With this metadata, the page will be written to ``override/url/index.html``
and Pelican will use the URL ``override/url/`` to link to this page.
How can I use a static page as my home page?
============================================
The override feature mentioned above can be used to specify a static page as
your home page. The following Markdown example could be stored in
``content/pages/home.md``::
Title: Welcome to My Site
URL:
save_as: index.html
Thank you for visiting. Welcome!
If the original blog index is still wanted, it can then be saved in a
different location by setting ``INDEX_SAVE_AS = 'blog_index.html'`` for
the ``'index'`` direct template.
What if I want to disable feed generation?
==========================================
To disable feed generation, all feed settings should be set to ``None``. All
but three feed settings already default to ``None``, so if you want to disable
all feed generation, you only need to specify the following settings::
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None
The word ``None`` should not be surrounded by quotes. Please note that ``None``
and ``''`` are not the same thing.
I'm getting a warning about feeds generated without SITEURL being set properly
==============================================================================
`RSS and Atom feeds require all URL links to be absolute
<https://validator.w3.org/feed/docs/rss2.html#comments>`_. In order to properly
generate links in Pelican you will need to set ``SITEURL`` to the full path of
your site.
Feeds are still generated when this warning is displayed, but links within may
be malformed and thus the feed may not validate.
Can I force Atom feeds to show only summaries instead of article content?
=========================================================================
Instead of having to open a separate browser window to read articles, the
overwhelming majority of folks who use feed readers prefer to read content
within the feed reader itself. Mainly for that reason, Pelican does not support
restricting Atom feeds to only contain summaries. Unlike Atom feeds, the RSS
feed specification does not include a separate ``content`` field, so by default
Pelican publishes RSS feeds that only contain summaries (but can optionally be
set to instead publish full content RSS feeds). So the default feed generation
behavior provides users with a choice: subscribe to Atom feeds for full content
or to RSS feeds for just the summaries.
Is Pelican only suitable for blogs?
===================================
No. Pelican can be easily configured to create and maintain any type of static
site. This may require a little customization of your theme and Pelican
configuration. For example, if you are building a launch site for your product
and do not need tags on your site, you could remove the relevant HTML code from
your theme. You can also disable generation of tag-related pages via::
TAGS_SAVE_AS = ''
TAG_SAVE_AS = ''
Why does Pelican always write all HTML files even with content caching enabled?
===============================================================================
In order to reliably determine whether the HTML output is different before
writing it, a large part of the generation environment including the template
contexts, imported plugins, etc. would have to be saved and compared, at least
in the form of a hash (which would require special handling of unhashable
types), because of all the possible combinations of plugins, pagination, etc.
which may change in many different ways. This would require a lot more
processing time and memory and storage space. Simply writing the files each
time is a lot faster and a lot more reliable.
However, this means that the modification time of the files changes every time,
so a ``rsync`` based upload will transfer them even if their content hasn't
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.
How to process only a subset of all articles?
=============================================
It is often useful to process only e.g. 10 articles for debugging purposes.
This can be achieved by explicitly specifying only the filenames of those
articles in ``ARTICLE_PATHS``. A list of such filenames could be found using a
command similar to ``cd content; find -name '*.md' | head -n 10``.
My tag cloud is missing/broken since I upgraded Pelican
=======================================================
In an ongoing effort to streamline Pelican, tag cloud generation has been
moved out of Pelican core and into a separate `plugin
<https://github.com/pelican-plugins/tag-cloud>`_. See the :ref:`plugins`
documentation for further information about the Pelican plugin system.
Since I upgraded Pelican my pages are no longer rendered
========================================================
Pages were available to themes as lowercase ``pages`` and uppercase ``PAGES``.
To bring this inline with the :ref:`templates-variables` section, ``PAGES`` has
been removed. This is quickly resolved by updating your theme to iterate over
``pages`` instead of ``PAGES``. Just replace::
{% for pg in PAGES %}
with something like::
{% for pg in pages %}
How can I stop Pelican from trying to parse my static files as content?
=======================================================================
Pelican's article and page generators run before it's static generator. That
means if you use a setup similar to the default configuration, where a static
source directory is defined inside a ``*_PATHS`` setting, all files that have a
valid content file ending (``.html``, ``.rst``, ``.md``, ...) will be treated
as articles or pages before they get treated as static files.
To circumvent this issue either use the appropriate ``*_EXCLUDES`` setting or
disable the offending reader via ``READERS`` if you don't need it.
Why is [arbitrary Markdown syntax] not supported?
=================================================
Pelican does not directly handle Markdown processing and instead delegates that
task to the Python-Markdown_ project, the core of which purposefully follows
the original Markdown syntax rules and not the myriad Markdown "flavors" that
have subsequently propagated. That said, Python-Markdown_ is quite modular, and
the syntax you are looking for may be provided by one of the many available
`Markdown Extensions`_. Alternatively, some folks have created Pelican plugins
that support Markdown variants, so that may be your best choice if there is a
particular variant you want to use when writing your content.
.. _Python-Markdown: https://github.com/Python-Markdown/markdown
.. _Markdown Extensions: https://python-markdown.github.io/extensions/

156
docs/importer.rst
View file

@ -1,156 +0,0 @@
.. _import:
Importing an existing site
##########################
Description
===========
``pelican-import`` is a command-line tool for converting articles from other
software to reStructuredText or Markdown. The supported import formats are:
- Blogger XML export
- Dotclear export
- Medium export
- Tumblr API
- WordPress XML export
- RSS/Atom feed
The conversion from HTML to reStructuredText or Markdown relies on `Pandoc`_.
For Dotclear, if the source posts are written with Markdown syntax, they will
not be converted (as Pelican also supports Markdown).
.. note::
Unlike Pelican, Wordpress supports multiple categories per article. These
are imported as a comma-separated string. You have to resolve these
manually, or use a plugin such as `More Categories`_ that enables multiple
categories per article.
.. note::
Imported pages may contain links to images that still point to the original site.
So you might want to download those images into your local content and manually
re-link them from the relevant pages of your site.
Dependencies
============
``pelican-import`` has some dependencies not required by the rest of Pelican:
- *BeautifulSoup4* and *lxml*, for WordPress and Dotclear import. Can be
installed like any other Python package (``pip install BeautifulSoup4
lxml``).
- *Feedparser*, for feed import (``pip install feedparser``).
- *Pandoc*, see the `Pandoc site`_ for installation instructions on your
operating system.
.. _Pandoc: https://pandoc.org/
.. _Pandoc site: https://pandoc.org/installing.html
Usage
=====
::
pelican-import [-h] [--blogger] [--dotclear] [--tumblr] [--wpfile] [--feed]
[-o OUTPUT] [-m MARKUP] [--dir-cat] [--dir-page] [--strip-raw] [--wp-custpost]
[--wp-attach] [--disable-slugs] [-b BLOGNAME]
input|api_key
Positional arguments
--------------------
============= ============================================================================
``input`` The input file to read
``api_key`` (Tumblr only) api_key can be obtained from https://www.tumblr.com/oauth/apps
============= ============================================================================
Optional arguments
------------------
-h, --help Show this help message and exit
--blogger Blogger XML export (default: False)
--dotclear Dotclear export (default: False)
--medium Medium export (default: False)
--tumblr Tumblr API (default: False)
--wpfile WordPress XML export (default: False)
--feed Feed to parse (default: False)
-o OUTPUT, --output OUTPUT
Output path (default: content)
-m MARKUP, --markup MARKUP
Output markup format: ``rst``, ``markdown``, or ``asciidoc``
(default: ``rst``)
--dir-cat Put files in directories with categories name
(default: False)
--dir-page Put files recognised as pages in "pages/" sub-
directory (blogger and wordpress import only)
(default: False)
--filter-author Import only post from the specified author
--strip-raw Strip raw HTML code that can't be converted to markup
such as flash embeds or iframes (default: False)
--wp-custpost Put wordpress custom post types in directories. If
used with --dir-cat option directories will be created
as "/post_type/category/" (wordpress import only)
--wp-attach Download files uploaded to wordpress as attachments.
Files will be added to posts as a list in the post
header and links to the files within the post will be
updated. All files will be downloaded, even if they
aren't associated with a post. Files will be downloaded
with their original path inside the output directory,
e.g. "output/wp-uploads/date/postname/file.jpg".
(wordpress import only) (requires an internet
connection)
--disable-slugs Disable storing slugs from imported posts within
output. With this disabled, your Pelican URLs may not
be consistent with your original posts. (default:
False)
-b BLOGNAME, --blogname=BLOGNAME
Blog name used in Tumblr API
Examples
========
For Blogger::
$ pelican-import --blogger -o ~/output ~/posts.xml
For Dotclear::
$ pelican-import --dotclear -o ~/output ~/backup.txt
For Medium::
$ pelican-import --medium -o ~/output ~/medium-export/posts/
The Medium export is a zip file. Unzip it, and point this tool to the
"posts" subdirectory. For more information on how to export, see
https://help.medium.com/hc/en-us/articles/115004745787-Export-your-account-data.
For Tumblr::
$ pelican-import --tumblr -o ~/output --blogname=<blogname> <api_key>
For WordPress::
$ pelican-import --wpfile -o ~/output ~/posts.xml
For Medium (an example of using an RSS feed):
$ python -m pip install feedparser
$ pelican-import --feed https://medium.com/feed/@username
.. note::
The RSS feed may only return the most recent posts — not all of them.
Tests
=====
To test the module, one can use sample files:
- for WordPress: https://www.wpbeginner.com/wp-themes/how-to-add-dummy-content-for-theme-development-in-wordpress/
- for Dotclear: http://media.dotaddict.org/tda/downloads/lorem-backup.txt
.. _More Categories: https://github.com/pelican-plugins/more-categories

74
docs/index.rst
View file

@ -1,74 +0,0 @@
Pelican |release|
=================
Pelican is a static site generator, written in Python_. Highlights include:
* Write your content directly with your editor of choice in reStructuredText_
or Markdown_ formats
* Includes a simple CLI tool to (re)generate your site
* Easy to interface with distributed version control systems and web hooks
* Completely static output is easy to host anywhere
Ready to get started? Check out the :doc:`Quickstart<quickstart>` guide.
Features
--------
Pelican’s feature highlights include:
* Articles (e.g., blog posts) and pages (e.g., "About", "Projects", "Contact")
* Integration with external services
* Site themes (created using Jinja2_ templates)
* Publication of articles in multiple languages
* Generation of Atom and RSS feeds
* Code syntax highlighting
* Import existing content from WordPress, Dotclear, or RSS feeds
* Fast rebuild times thanks to content caching and selective output writing
* Extensible via a rich plugin ecosystem: `Pelican Plugins`_
Why the name "Pelican"?
-----------------------
"Pelican" is an anagram for *calepin*, which means "notebook" in French. ;)
Source code
-----------
You can access the source code at: https://github.com/getpelican/pelican
How to get help, contribute, or provide feedback
------------------------------------------------
See our :doc:`feedback and contribution submission guidelines <contribute>`.
Documentation
-------------
.. toctree::
:maxdepth: 2
quickstart
install
content
publish
settings
plugins
themes
pelican-themes
importer
faq
tips
contribute
internals
report
changelog
.. Links
.. _Python: https://www.python.org/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Markdown: https://daringfireball.net/projects/markdown/
.. _Jinja2: https://palletsprojects.com/p/jinja/
.. _`Pelican documentation`: https://docs.getpelican.com/latest/
.. _`Pelican's internals`: https://docs.getpelican.com/en/latest/internals.html
.. _`Pelican Plugins`: https://github.com/pelican-plugins

122
docs/install.rst
View file

@ -1,122 +0,0 @@
Installing Pelican
##################
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_::
python -m pip install pelican
Or, if you plan on using Markdown::
python -m pip install "pelican[markdown]"
(Keep in mind that some operating systems will require you to prefix the above
command with ``sudo`` in order to install Pelican system-wide.)
While the above is the simplest method, the recommended approach is to create a
virtual environment for Pelican via virtualenv_ before installing Pelican.
Assuming you have virtualenv_ installed, you can then open a new terminal
session and create a new virtual environment for Pelican::
virtualenv ~/virtualenvs/pelican
cd ~/virtualenvs/pelican
source bin/activate
Once the virtual environment has been created and activated, Pelican can be
installed via ``python -m pip install pelican`` as noted above. Alternatively, if you
have the project source, you can install Pelican using the distutils method::
cd path-to-Pelican-source
python setup.py install
If you have Git installed and prefer to install the latest bleeding-edge
version of Pelican rather than a stable release, use the following command::
python -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"
Once Pelican is installed, you can run ``pelican --help`` to see basic usage
options. For more detail, refer to the :doc:`Publish<publish>` section.
Optional packages
-----------------
If you plan on using `Markdown <https://pypi.org/project/Markdown/>`_ as a
markup format, you can install Pelican with Markdown support::
python -m pip install "pelican[markdown]"
Typographical enhancements can be enabled in your settings file, but first the
requisite `Typogrify <https://pypi.org/project/typogrify/>`_ library must be
installed::
python -m pip install typogrify
Dependencies
------------
When Pelican is installed, the following dependent Python packages should be
automatically installed without any action on your part:
* `feedgenerator <https://pypi.org/project/feedgenerator/>`_, to generate the
Atom feeds
* `jinja2 <https://pypi.org/project/Jinja2/>`_, for templating support
* `pygments <https://pypi.org/project/Pygments/>`_, for syntax highlighting
* `docutils <https://pypi.org/project/docutils/>`_, for supporting
reStructuredText as an input format
* `blinker <https://pypi.org/project/blinker/>`_, an object-to-object and
broadcast signaling system
* `unidecode <https://pypi.org/project/Unidecode/>`_, for ASCII
transliterations of Unicode text
utilities
* `MarkupSafe <https://pypi.org/project/MarkupSafe/>`_, for a markup-safe
string implementation
* `python-dateutil <https://pypi.org/project/python-dateutil/>`_, to read
the date metadata
Upgrading
---------
If you installed a stable Pelican release via Pip_ and wish to upgrade to
the latest stable release, you can do so by adding ``--upgrade``::
python -m pip install --upgrade pelican
If you installed Pelican via distutils or the bleeding-edge method, simply
perform the same step to install the most recent version.
Kickstart your site
-------------------
Once Pelican has been installed, you can create a skeleton project via the
``pelican-quickstart`` command, which begins by asking some questions about
your site::
pelican-quickstart
If run inside an activated virtual environment, ``pelican-quickstart`` will
look for an associated project path inside ``$VIRTUAL_ENV/.project``. If that
file exists and contains a valid directory path, the new Pelican project will
be saved at that location. Otherwise, the default is the current working
directory. To set the new project path on initial invocation, use:
``pelican-quickstart --path /your/desired/directory``
Once you finish answering all the questions, your project will consist of the
following hierarchy (except for *pages* — shown in parentheses below — which
you can optionally add yourself if you plan to create non-chronological
content)::
yourproject/
├── content
│ └── (pages)
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py # Main settings file
└── publishconf.py # Settings to use when ready to publish
The next step is to begin to adding content to the *content* folder that has
been created for you.
.. _Pip: https://pip.pypa.io/
.. _virtualenv: https://virtualenv.pypa.io/en/latest/

98
docs/internals.rst
View file

@ -1,98 +0,0 @@
Pelican internals
#################
This section describe how Pelican works internally. As you'll see, it's quite
simple, but a bit of documentation doesn't hurt. :)
You can also find in the :doc:`report` section an excerpt of a report the
original author wrote with some software design information.
.. _report: :doc:`report`
Overall structure
=================
What Pelican does is take a list of files and process them into some sort of
output. Usually, the input files are reStructuredText and Markdown files, and
the output is a blog, but both input and output can be anything you want.
The logic is separated into different classes and concepts:
* **Writers** are responsible for writing files: .html files, RSS feeds, and so
on. Since those operations are commonly used, the object is created once and
then passed to the generators.
* **Readers** are used to read from various formats (HTML, Markdown and
reStructuredText for now, but the system is extensible). Given a file, they
return metadata (author, tags, category, etc.) and content (HTML-formatted).
* **Generators** generate the different outputs. For instance, Pelican comes
with ``ArticlesGenerator`` and ``PageGenerator``. Given a configuration, they
can do whatever they want. Most of the time, it's generating files from
inputs.
* Pelican also uses templates, so it's easy to write your own theme. The
syntax is `Jinja2 <https://palletsprojects.com/p/jinja/>`_ and is very easy to learn, so
don't hesitate to jump in and build your own theme.
How to implement a new reader?
==============================
Is there an awesome markup language you want to add to Pelican? Well, the only
thing you have to do is to create a class with a ``read`` method that returns
HTML content and some metadata.
Take a look at the Markdown reader::
from pelican.readers import BaseReader
from pelican.utils import pelican_open
from markdown import Markdown
class MarkdownReader(BaseReader):
enabled = True
def read(self, source_path):
"""Parse content and metadata of markdown files"""
with pelican_open(source_path) as text:
md_extensions = {'markdown.extensions.meta': {},
'markdown.extensions.codehilite': {}}
md = Markdown(extensions=md_extensions.keys(),
extension_configs=md_extensions)
content = md.convert(text)
metadata = {}
for name, value in md.Meta.items():
name = name.lower()
meta = self.process_metadata(name, value[0])
metadata[name] = meta
return content, metadata
Simple, isn't it?
If your new reader requires additional Python dependencies, then you should
wrap their ``import`` statements in a ``try...except`` block. Then inside the
reader's class, set the ``enabled`` class attribute to mark import success or
failure. This makes it possible for users to continue using their favourite
markup method without needing to install modules for formats they don't use.
How to implement a new generator?
=================================
Generators have two important methods. You're not forced to create both; only
the existing ones will be called.
* ``generate_context``, that is called first, for all the generators.
Do whatever you have to do, and update the global context if needed. This
context is shared between all generators, and will be passed to the
templates. For instance, the ``PageGenerator`` ``generate_context`` method
finds all the pages, transforms them into objects, and populates the context
with them. Be careful *not* to output anything using this context at this
stage, as it is likely to change by the effect of other generators.
* ``generate_output`` is then called. And guess what is it made for? Oh,
generating the output. :) It's here that you may want to look at the context
and call the methods of the ``writer`` object that is passed as the first
argument of this function. In the ``PageGenerator`` example, this method will
look at all the pages recorded in the global context and output a file on the
disk (using the writer method ``write_file``) for each page encountered.

1669
docs/locale/zh_CN/LC_MESSAGES/changelog.po
View file

File diff suppressed because it is too large Load diff

1074
docs/locale/zh_CN/LC_MESSAGES/content.po
View file

File diff suppressed because it is too large Load diff

731
docs/locale/zh_CN/LC_MESSAGES/contribute.po
View file

@ -1,731 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-25 20:36+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../contribute.rst:2 e8f9694c47aa44e7944dae800ee528f3
msgid "Contributing and feedback guidelines"
msgstr "项目贡献与意见反馈"
#: ../../contribute.rst:4 784f37182e78474b960306a5a794ae16
msgid ""
"There are many ways to contribute to Pelican. You can improve the "
"documentation, add missing features, and fix bugs (or just report them). "
"You can also help out by reviewing and commenting on `existing issues "
"<https://github.com/getpelican/pelican/issues>`_."
msgstr ""
"有很多渠道可以参与到贡献项目中来，例如帮助改进文档、添加缺失的特性、修复与报告bug。"
"可以从查看 `已有 issues <https://github.com/getpelican/pelican/issues>`_ 开始。"
#: ../../contribute.rst:9 e17c3ff0fa71469cbe22cb4ad2640ad8
msgid ""
"Don't hesitate to fork Pelican and submit an issue or pull request on "
"GitHub. When doing so, please consider the following guidelines."
msgstr ""
"随时随地都可以fork Pelican或是在GitHub上提交issue或PR。"
#: ../../../CONTRIBUTING.rst:2 f8bc69070fab4dd7be34e1cc6a42cc02
msgid "Filing issues"
msgstr "提出issue"
#: ../../../CONTRIBUTING.rst:4 fe98a059b9c24fcc92358f2c4505174d
msgid "Before you submit a new issue, try `asking for help`_ first."
msgstr "在你提交一个新的issue之前，可以先尝试 `请求他人帮助`_ 。"
#: ../../../CONTRIBUTING.rst:5 e9fff7c354614ae28db994c0fcc121c0
msgid ""
"If determined to create a new issue, first search `Pelican Discussions`_ "
"and `existing issues`_ (open and closed) to see if your question has "
"already been answered previously."
msgstr ""
"当你决定要提出新的issue时，先在 `Pelican的讨论版`_ 和 `已有issues`_ 中搜索一下，"
"（开放关闭的issue都搜一下），来看看你的问题是不是有人之前已经提出过。"
#: ../../../CONTRIBUTING.rst:14 84cb74beed564f31810674cacf5c1f97
msgid "How to get help"
msgstr "如何获取帮助"
#: ../../../CONTRIBUTING.rst:16 0557a84947c14606be4fd0565247d85d
msgid "Before you ask for help, please make sure you do the following:"
msgstr "在寻求帮助之前，请先尝试如下步骤："
#: ../../../CONTRIBUTING.rst:18 6d59a3356e734dd196ec8a0739556b4c
msgid ""
"Read the documentation_ thoroughly. If in a hurry, at least use the "
"search field that is provided at top-left on the documentation_ pages. "
"Make sure you read the docs for the Pelican version you are using."
msgstr ""
"完整阅读 documentation_ 。如果你很急，至少先在 documentation_ 左上角的搜索栏"
"中尝试搜索。确保你阅读的文档和使用的Pelican版本相匹配。"
#: ../../../CONTRIBUTING.rst:21 4b33299936404cf98a66b672fad0e38f
msgid ""
"Use a search engine (e.g., DuckDuckGo, Google) to search for a solution "
"to your problem. Someone may have already found a solution, perhaps in "
"the form of a ':pelican-doc:`plugins` or a specific combination of "
"settings."
msgstr ""
"使用搜索引擎（例如 DuckDuckGo、Google）搜索遇到问题的解决方案。互联网上可能"
"已经有人遇到过相同的问题，解决方法可能包括使用某些 :pelican-doc:`plugins` 或配置"
"一系列的设置选项。"
#: ../../../CONTRIBUTING.rst:25 b48195d9ef674566b89aabc38139c301
msgid "Try reproducing the issue in a clean environment, ensuring you are using:"
msgstr "尝试在一个尽可能简单的环境中重现问题，并确保以下几点："
#: ../../../CONTRIBUTING.rst:27 685d2888d2c94ea9a752ec433f8b9f1f
msgid ""
"latest Pelican release (or an up-to-date Git clone of Pelican ``main`` "
"branch)"
msgstr "使用最新版本的Pelican（或是用Git克隆Pelican的main分支）"
#: ../../../CONTRIBUTING.rst:28 910a372d95d8448492eafc66eccd1ccf
msgid "latest releases of libraries used by Pelican"
msgstr "将Pelican使用的库升级到最新版本"
#: ../../../CONTRIBUTING.rst:29 c44f4dc6b05d4be29eccc889f042702c
msgid "no plugins or only those related to the issue"
msgstr "此环境中没有使用插件或是只使用和问题相关的插件"
#: ../../../CONTRIBUTING.rst:31 3abdf6131cf4412a8205b634a6651b01
msgid ""
"**NOTE:** The most common sources of problems are anomalies in (1) "
"themes, (2) plugins, (3) settings files, and (4) ``make``/``invoke`` "
"automation wrappers. If you can't reproduce your problem when using the "
"following steps to generate your site, then the problem is almost "
"certainly with one of the above-listed elements (and not Pelican "
"itself)::"
msgstr ""
"**注意：** 最常见的问题基本上都产生于主题、插件、设置文件和自动化工具 "
"``make``/``invoke`` 中。如果按照下述步骤生成站点后无法复现之前的问题，那么"
"几乎可以肯定问题出在这四个地方，而不在Pelican本身："
#: ../../../CONTRIBUTING.rst:41 f2331ea165ac4a3c8e70bf98c995f0e8
msgid ""
"If you can generate your site without problems using the steps above, "
"then your problem is unlikely to be caused by Pelican itself, and "
"therefore please consider reaching out to the maintainers of the "
"plugins/theme you are using instead of raising the topic with the Pelican"
" core community."
msgstr ""
"如果按照上述步骤能够正常生成站点，那么你的问题不太可能是由Pelican本身导致的，"
"请考虑联系对应插件/主题的维护者，而不是在Pelican内核的社区中提出问题。"
#: ../../../CONTRIBUTING.rst:46 d83b0036d4894f3ebc73e657a203d11a
msgid ""
"If despite the above efforts you still cannot resolve your problem, be "
"sure to include in your inquiry the following information, preferably in "
"the form of links to content uploaded to a `paste service`_, GitHub "
"repository, or other publicly-accessible location:"
msgstr ""
"经过上面这些努力，若您仍无法解决问题，确保你的提问中包括如下信息，可以以 "
"`paste service`_ 链接、GitHub仓库，或者其他可公开获取的形式提供："
#: ../../../CONTRIBUTING.rst:51 4281f931e9064336b267bd67a35134e9
msgid ""
"Describe what version of Pelican you are running (output of ``pelican "
"--version`` or the HEAD commit hash if you cloned the repo) and how "
"exactly you installed it (the full command you used, e.g. ``python -m pip"
" install pelican``)."
msgstr ""
"描述正在运行的Pelican版本信息（可以通过 ``pelican --version`` 命令得到，如果"
"clone的源仓库则可以查看HEAD commit的哈希值），以及你是如何安装Pelican的"
"（要包括使用到的命令，例如 ``python -m pip install pelican``）"
#: ../../../CONTRIBUTING.rst:54 b1303c98bca840efb895aceb16789eb9
msgid ""
"If you are looking for a way to get some end result, prepare a detailed "
"description of what the end result should look like (preferably in the "
"form of an image or a mock-up page) and explain in detail what you have "
"done so far to achieve it."
msgstr ""
"如果你希望产生某种特定的最终结果，请详细描述此最终结果是什么样的（最好以图片或者"
"伪页面的形式），，并且细致讲述你做了哪些尝试。"
#: ../../../CONTRIBUTING.rst:58 8fe972c4685140d5bd1c37f4635f6f09
msgid ""
"If you are trying to solve some issue, prepare a detailed description of "
"how to reproduce the problem. If the issue cannot be easily reproduced, "
"it cannot be debugged by developers or volunteers. Describe only the "
"**minimum steps** necessary to reproduce it (no extra plugins, etc.)."
msgstr ""
"如果你在尝试解决某些问题，请详细描述如何复现此问题。如果问题很难被复现，其他开发者和志愿者就很难进行调试。"
"尽量只写出复现该问题的 **最少步骤** （无额外插件）。"
#: ../../../CONTRIBUTING.rst:62 1f3874f308e64281b910dc716180ebcf
msgid ""
"Upload your settings file or any other custom code that would enable "
"people to reproduce the problem or to see what you have already tried to "
"achieve the desired end result."
msgstr ""
"上传你的配置文件以及所有自定义过的代码，这可以使得大家能够重现问题或者看到你已经"
"做出的尝试。"
#: ../../../CONTRIBUTING.rst:65 1fdc6c63f1b141c7a35233607ec0d922
msgid ""
"Upload detailed and **complete** output logs and backtraces (remember to "
"add the ``--debug`` flag: ``pelican --debug content [...]``)"
msgstr ""
"上传详细 **完整** 的输出日志以及backtraces信息（记得在执行pelican命令时加上 "
"``--debug`` 标记： ``pelican --debug content [...]`` ）"
#: ../../../CONTRIBUTING.rst:71 8741dba5da1a4990ae9c30531d05dc19
msgid ""
"Once the above preparation is ready, you can post your query as a new "
"thread in `Pelican Discussions`_. Remember to include all the information"
" you prepared."
msgstr ""
"一旦做好了上述准备，就可以在 `Pelican Discussions`_ 中发起你的问题了。记得在请求"
"中附上收集好的信息。"
#: ../../../CONTRIBUTING.rst:75 b34a3031f5d1427e92a9d1969d7b5274
msgid "Contributing code"
msgstr "贡献代码"
#: ../../../CONTRIBUTING.rst:77 e29672c736554ebbbd6efd441af19df7
msgid ""
"Before you submit a contribution, please ask whether it is desired so "
"that you don't spend a lot of time working on something that would be "
"rejected for a known reason. Consider also whether your new feature might"
" be better suited as a ':pelican-doc:`plugins` — you can `ask for help`_"
" to make that determination."
msgstr ""
"在提交代码修改前，请先询问是否需要此修改，以免你做的工作因为已知原因而被拒绝。"
"想想要添加的新特性是否更适合以 :pelican-doc:`插件` 形式完成。可以通过 "
"`如何获取帮助`_ 来帮助你作出决定。"
#: ../../../CONTRIBUTING.rst:82 e263c09fb6e5471eb0c2c3e97994322d
msgid ""
"Also, if you intend to submit a pull request to address something for "
"which there is no existing issue, there is no need to create a new issue "
"and then immediately submit a pull request that closes it. You can submit"
" the pull request by itself."
msgstr ""
"另外，如果你的PR是为了解决一个目前没有在issue中出现过的问题，那么就没有必要先创建"
"一个新的issue，而是可以直接提起PR。"
#: ../../../CONTRIBUTING.rst:87 9b08ef3e5fe4474e9306e4bfe9662fff
msgid "Using Git and GitHub"
msgstr "使用Git与GitHub"
#: ../../../CONTRIBUTING.rst:89 7ad95f82b7d04c0ca97bb958d2425e27
msgid ""
"`Create a new branch`_ specific to your change (as opposed to making your"
" commits in the ``main`` branch)."
msgstr ""
"`创建一个新的分支`_ 来标记你做的修改（而不是直接在主分支中提交）。"
#: ../../../CONTRIBUTING.rst:91 8a31c5d7ae4045cdbf2aa67e79be3f9c
msgid ""
"**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 request** for the bugfix. Similarly, any proposed changes"
" to code style formatting should be in a completely separate pull "
"request."
msgstr ""
"**不要把多个无关联的修复/特性修改放在同一个分支/拉去请求中。** 如果当你在做新特性的时候"
"发现了一个bug可以修复，但修复这个bug *不需要用到* 这个新特性， **那么请另外创建"
"一个分支并拉取请求。** 类似的，任何对代码风格的格式化都应该在单独的请求中拉取。"
#: ../../../CONTRIBUTING.rst:96 ef2e10f7ec5e4fbbb0f977dd09b7be49
msgid ""
"Add a ``RELEASE.md`` file in the root of the project that contains the "
"release type (major, minor, patch) and a summary of the changes that will"
" be used as the release changelog entry. For example::"
msgstr ""
"在项目根目录下添加 ``RELEASE.md`` 文件，在其中包含release的类型（主要、次要、补丁），"
"以及对项目改变的概述，这些内容会作为该release发布日志的一部分。下面是一个例子："
#: ../../../CONTRIBUTING.rst:104 24a4d63624f44f63a0ce809901455c02
msgid ""
"Check for unnecessary whitespace via ``git diff --check`` before "
"committing."
msgstr ""
"在提交前使用 ``git diff --check`` 来检查是否有无意义的空白字符。"
#: ../../../CONTRIBUTING.rst:105 11c5b82604fe4638bf9ee6e9ef0a401b
msgid ""
"First line of your commit message should start with present-tense verb, "
"be 50 characters or less, and include the relevant issue number(s) if "
"applicable. *Example:* ``Ensure proper PLUGIN_PATH behavior. Refs #428.``"
" If the commit *completely fixes* an existing bug report, please use "
"``Fixes #585`` or ``Fix #585`` syntax (so the relevant issue is "
"automatically closed upon PR merge)."
msgstr ""
"commit信息的第一行应该以现在时动词开头，并且第一行尽量保持在50字以下，并且包含相关联"
"issue的编号（如果有的话）。 例如： ``Ensure proper PLUGIN_PATH behavior. "
"Refs #428.`` 如果此项提交 *完全修复* 了某项已报告的bug，请使用例如 ``Fixes #585`` "
"或 ``Fix #585`` 的语法（这样的话相关的issue会在PR合并后自动关闭）。"
#: ../../../CONTRIBUTING.rst:110 0c1ff9d0738440e1bce853fc830278af
msgid ""
"After the first line of the commit message, add a blank line and then a "
"more detailed explanation (when relevant)."
msgstr ""
"在第一行commit信息后添加一行空白行，再进行更多相关的细节描述。"
#: ../../../CONTRIBUTING.rst:112 d817ad5d9e35488eb45d88828ee9f053
msgid ""
"`Squash your commits`_ to eliminate merge commits and ensure a clean and "
"readable commit history."
msgstr ""
"`压缩commit`_ 来消除合并commits，确保你的commit历史记录是干净可读的。"
#: ../../../CONTRIBUTING.rst:114 b7064f44923a499da3c3ce078470e269
msgid ""
"After you have issued a pull request, the continuous integration (CI) "
"system will run the test suite on all supported Python versions and check"
" for code style compliance. If any of these checks fail, you should fix "
"them. (If tests fail on the CI system but seem to pass locally, ensure "
"that local test runs aren't skipping any tests.)"
msgstr ""
"在你发出PR后，持续集成（CI）系统会在所有支持的Python版本上运行测试套件，并且"
"检查代码风格的合规性。如果出现了错误，你应该将其修复。（如果没有通过CI系统上的"
"测试但是本地测试通过了，请再检查一下，确保在本地进行了所有CI系统中的检查）"
#: ../../../CONTRIBUTING.rst:121 342f2e6c14b9441caaf3f9b6d2eb764b
msgid "Contribution quality standards"
msgstr "贡献的质量标准"
#: ../../../CONTRIBUTING.rst:123 842514f115634a5d821d48490d4aed7b
msgid ""
"Adhere to the project's code style standards. See: `Development "
"Environment`_"
msgstr ""
"遵循项目的代码风格标准。详见 `开发环境`_"
#: ../../../CONTRIBUTING.rst:124 4719590d89be4a5e94817902cc424be5
msgid ""
"Ensure your code is compatible with the `officially-supported Python "
"releases`_."
msgstr ""
"确保你的代码可以兼容 `python的官方发布版本`_"
#: ../../../CONTRIBUTING.rst:125 fa0ad5dd93e149fa8a12dd339bef9056
msgid ""
"Add docs and tests for your changes. Undocumented and untested features "
"will not be accepted."
msgstr ""
"请为你修改的内容添加文档与测试。未注有文档或没有对应测试的特性会被拒绝。"
#: ../../../CONTRIBUTING.rst:127 dc4db53c2ce34e5490a0c57ea800a4da
msgid ""
":pelican-doc:`Run all the tests <contribute>` **on all versions of Python"
" supported by Pelican** to ensure nothing was accidentally broken."
msgstr ""
"**在Pelican支持的所有Python版本上** :pelican-doc:`执行所有测试 <contribute>` ，"
"以确保没有意料之外的问题。"
#: ../../../CONTRIBUTING.rst:130 3a88c2e8326a4acd896d0ac75d4c9ccb
msgid ""
"Check out our `Git Tips`_ page or `ask for help`_ if you need assistance "
"or have any questions about these guidelines."
msgstr ""
"若需要帮助或对以上指南有任何疑惑，还可以查看我们的 `Git提示`_ 页面和 `请求帮助`_ 部分。"
#: ../../contribute.rst:15 daead9e8fb804eb6acd152b85d837182
msgid "Setting up the development environment"
msgstr "配置开发环境"
#: ../../contribute.rst:17 1ab6df98bcb141f49e278d153cc96e22
msgid ""
"While there are many ways to set up one's development environment, the "
"following 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."
msgstr ""
"在配置开发环境时往往有很多种方式，但下面的指南会使用 Pip_ 和 PDM_ 完成配置。这两个工具"
"都可以用于管理虚拟环境，使得不同的Python项目相互隔离，这样就可以很方便的在不同的项目中"
"使用不同的库（以及不同的库版本）。"
#: ../../contribute.rst:22 6a9c8f6ddb1d495f8a9bd1b8a131cabd
msgid "Please note that Python |min_python| is required for Pelican development."
msgstr "请注意，要进行Pelican的开发，至少需要Python |min_python|"
#: ../../contribute.rst:24 3d994e2a522141d7ada0a8fe13eb4c64
msgid ""
"*(Optional)* If you prefer to `install PDM "
"<https://pdm.fming.dev/latest/#installation>`_ once for use with multiple"
" projects, you can install it via::"
msgstr ""
"*（可选）* 若您想要 `安装PDM <https://pdm.fming.dev/latest/#installation>`_ ，"
"可以使用下面这条命令："
#: ../../contribute.rst:29 dbaa532c292048cb87926dd8b6e3141a
msgid ""
"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 as a Git remote::"
msgstr ""
"在Web浏览器中进入 `Pelican的代码仓库`_ ，点击右上角的 **Fork** 按钮。然后克隆"
"你自己的这份fork，最后添加项目的原仓库为远程仓库upstream："
#: ../../contribute.rst:38 adbe5d876f114645a3e1b489b2a34bd9
msgid ""
"While PDM can dynamically create and manage virtual environments, we're "
"going to manually create and activate a virtual environment::"
msgstr ""
"通过下面的命令可以手动创建并激活一个虚拟环境："
#: ../../contribute.rst:45 ../../contribute.rst:181
#: 6ede38ac05174bc19df4198e735342e0 f6d42cdd70384eaebbe115aefd0d01ec
msgid "Install the needed dependencies and set up the project::"
msgstr "安装必需的依赖并配置项目："
#: ../../contribute.rst:50 d863bf4dc76e4b18b933f2635a6a3af3
msgid "Your local environment should now be ready to go!"
msgstr "现在，你的本地开发环境就配置完成了！"
#: ../../contribute.rst:57 dc19edf71c914f48a953b379efa076c0
msgid "Development"
msgstr "开发"
#: ../../contribute.rst:59 6082eb5afbf14f86a031ed4f53d2943c
msgid ""
"Once Pelican has been set up for local development, create a topic branch"
" for your bug fix or feature::"
msgstr ""
"在配置好Pelican的本地开发环境后，请先为你的bug修复或特性增加创建一个分支："
#: ../../contribute.rst:64 1cafbaea6ec04597b62e871c0f0793b2
msgid ""
"Now you can make changes to Pelican, its documentation, and/or other "
"aspects of the project."
msgstr ""
"在切换到新建的分支后，就可以开始对Pelican的文档或其他内容做更改了。"
#: ../../contribute.rst:68 e0f5da1e216f499d86427e21c23557d4
msgid "Setting up ``git blame`` (optional)"
msgstr "配置 ``git blame`` （可选）"
#: ../../contribute.rst:70 2906e116c2dc4a2c8db78fa64820af56
msgid ""
"``git blame`` annotates lines in a file with information about the pull "
"request that last modified it. Sweeping shallow changes (like formatting)"
" can make that information less useful, so we keep a list of such changes"
" to be ignored. Run the following command to set this up in your "
"repository, adding ``--global`` if you want this setting to apply to all "
"repositories::"
msgstr ""
"``git blame`` 会在文件中的行上标注有关最后一次修改该行的PR信息。对浅层变化（如格式化）"
"进行批量更改可能会使这些信息变得不那么有用，因此我们维护一个包含此类更改的列表，"
"以便忽略它们。运行以下命令在您的存储库中设置此配置，如果希望此设置适用于所有存储库，"
"请添加 ``--global`` ："
#: ../../contribute.rst:78 36f257406a294713835841cf549e0f67
msgid ""
"As noted in a `useful article`_ about ``git blame``, there are other "
"related settings you may find to be beneficial::"
msgstr ""
"就像在 `这篇文章`_ 中提到的，还可以进行一些可能有用的额外设置："
#: ../../contribute.rst:89 37a3a813eeb84f408546bf6a83fdafd6
msgid "Running the test suite"
msgstr "运行测试套件"
#: ../../contribute.rst:91 44276ab045104e5c9ab3d2425172d7ac
msgid ""
"Each time you make changes to Pelican, there are two things to do "
"regarding tests: check that the existing tests pass, and add tests for "
"any new features or bug fixes. The tests are located in "
"``pelican/tests``, and you can run them via::"
msgstr ""
"每次对Pelican做出修改后，在测试方面需要做两个工作：检查是否能通过已有的测试、"
"为新增特性或bug修复创建测试。请将自动化测试文件放在 ``pelican/tests`` 中，"
"接着执行以下命令："
#: ../../contribute.rst:98 9557eb87ac4945ccbaf8775aa7768f6e
msgid ""
"(For more on Invoke, see ``invoke -l`` to list tasks, or "
"https://pyinvoke.org for documentation.)"
msgstr ""
"（执行 ``invoke -l`` 会列出可以调用的测试任务，关于此的更多文档请参阅 "
"https://pyinvoke.org ）"
#: ../../contribute.rst:101 d1cebbdf4fcf4be5b918613c5050d638
msgid ""
"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::"
msgstr ""
"除了运行测试套件外，还要确保修改了的部分遵循代码风格指南。可以通过下面的命令"
"检查代码风格："
#: ../../contribute.rst:106 7a0b9ebf408f472aa786f6c3ac639240
msgid ""
"If code style violations are found in lines you changed, correct those "
"lines and re-run the above lint command until they have all been fixed. "
"You do not need to address style violations, if any, for code lines you "
"did not touch."
msgstr ""
"如果在修改过的代码中有地方违反了代码风格规范，请纠正并再次运行上述命令，直到全部纠正。"
"但是若是发现违反代码风格的地方并不是你修改的，请忽略之，不要进行纠正。"
#: ../../contribute.rst:110 74ec20f2daf74ad18cc083ad48b89dfe
msgid ""
"After making your changes and running the tests, you may see a test "
"failure mentioning that \"some generated files differ from the expected "
"functional tests output.\" If you have made changes that affect the HTML "
"output generated by Pelican, and the changes to that output are expected "
"and deemed correct given the nature of your changes, then you should "
"update the output used by the functional tests. To do so, **make sure you"
" have both** ``en_EN.utf8`` **and** ``fr_FR.utf8`` **locales installed**,"
" and then run the following command::"
msgstr ""
"在修改完代码，运行测试的过程中，你可能会看到测试失败中有提到“some generated files "
"differ from the expected functional tests output” 。这可能是由于你对代码的修改"
"影响到了Pelican的HTML输出，若输出的结果确实是你想要的，请更新功能测试所用的输出用例。"
"请确保你安装了 ``en_EN.utf8`` 和 ``fr_FR.utf8`` ，然后执行下述命令："
#: ../../contribute.rst:120 4299259dadd748238f9465eefb84727c
msgid ""
"You may also find that some tests are skipped because some dependency "
"(e.g., Pandoc) is not installed. This does not automatically mean that "
"these tests have passed; you should at least verify that any skipped "
"tests are not affected by your changes."
msgstr ""
"你还可能会发现有一些测试由于缺少依赖（例如 Pandoc）而被跳过。这并不意味着通过"
"了这些测试，请至少确保对代码的修改不会影响到这些被跳过的测试。"
#: ../../contribute.rst:125 a8835ccddf624fc1994c618ded8cc5ba
msgid ""
"You should run the test suite under each of the supported versions of "
"Python. This is best done by creating a separate Python environment for "
"each version. Tox_ is a useful tool to automate running tests inside "
"``virtualenv`` environments."
msgstr ""
"你应该在Pelican支持的所有Python版本下运行测试套件。一般会通过为每一个Python版本"
"创建一个虚拟环境来实现这一点。Tox_ 是一个用于在 ``virtualenv`` 环境中自动运行"
"测试的工具。"
#: ../../contribute.rst:133 b8b8c16b0d0743b98de5d759f79d07ba
msgid "Running a code coverage report"
msgstr "运行代码测试覆盖报告"
#: ../../contribute.rst:135 674a92a42d924931801c9f9c02463cd5
msgid ""
"Code is more likely to stay robust if it is tested. Coverage_ is a "
"library that measures how much of the code is tested. To run it::"
msgstr ""
"经过测试的代码往往具有更好的健壮性。 Coverage_ 是一个用于衡量代码测试覆盖率的库"
"执行下面的命令以调取之："
#: ../../contribute.rst:140 ecb5e7f9e83c4243ba04b58764e573b6
msgid ""
"This will show overall coverage, coverage per file, and even line-by-line"
" coverage. There is also an HTML report available::"
msgstr ""
"该命令会展示总体覆盖率以及在每个文件上的覆盖率，甚至还会展示每一行的覆盖情况。"
"同样也会有一份HTML格式的报告供您查看："
#: ../../contribute.rst:148 bad31d4cb0b644ac8ecb7885b22072a7
msgid "Building the docs"
msgstr "构建文档"
#: ../../contribute.rst:150 47e1f1caa594462d9b3b4403645abf3b
msgid ""
"If you make changes to the documentation, you should build and inspect "
"your changes before committing them::"
msgstr ""
"若你对文档进行过修改，请在commit前完成构建和检查："
#: ../../contribute.rst:155 a4961ae22c2c4de9bbc8bb98d3a3ec81
msgid ""
"Open http://localhost:8000 in your browser to review the documentation. "
"While the above task is running, any changes you make and save to the "
"documentation should automatically appear in the browser, as it live-"
"reloads when it detects changes to the documentation source files."
msgstr ""
"执行上述命令后，请在Web浏览器中打开 http://localhost:8000 来查看文档。"
"在上述命令执行时，对文档做的任何修改应该会自动反映在浏览器中。"
#: ../../contribute.rst:161 7740ec477ad747ebaa2dde2b2aef45d5
msgid "Plugin development"
msgstr "插件开发"
#: ../../contribute.rst:163 9505da5fcac24d718f59c797061d2b0f
msgid ""
"To create a *new* Pelican plugin, please refer to the `plugin template`_ "
"repository for detailed instructions."
msgstr ""
"要创建一个 *新的* Pelican插件，请参阅 `插件模板`_ 仓库以获得更为详细的指导。"
#: ../../contribute.rst:166 5fdae4611a6949b9a4c3bc82c52d3bc6
msgid ""
"If you want to contribute to an *existing* Pelican plugin, follow the "
"steps above to set up Pelican for local development, and then create a "
"directory to store cloned plugin repositories::"
msgstr ""
"若你想在 *已有* Pelican插件中做贡献，请先按前文所述步骤配置Pelican的本地开发环境，"
"然后创建一个文件夹来存放克隆下来的插件仓库："
#: ../../contribute.rst:172 0f50b12aaf3b4049999130a92fa6b670
msgid ""
"Assuming you wanted to contribute to the Simple Footnotes plugin, you "
"would first browse to the `Simple Footnotes`_ repository on GitHub and "
"tap the **Fork** button at top-right. Then clone the source for your fork"
" and add the upstream project as a Git remote::"
msgstr ""
"假设想要为Simple Footnotes插件做贡献，你应该先查看并fork `Simple Footnotes`_ "
"的Github仓库，然后克隆你自己fork的那一份，再添加原仓库作为Git远程仓库upstream："
#: ../../contribute.rst:185 2efe992372f149c3b63ca22016f8501b
msgid "Create a topic branch for your plugin bug fix or feature::"
msgstr "同样地，为你想要进行的bug修复或特性添加创建一个分支："
#: ../../contribute.rst:189 40f3c07d12cc4630bc75355c3449196d
msgid ""
"After writing new tests for your plugin changes, run the plugin test "
"suite and check for code style compliance via::"
msgstr ""
"完成修改并添加测试后，运行测试套件，并检查代码风格："
#: ../../contribute.rst:195 ba97ce962daa437cbcf2d09897394aed
msgid ""
"If style violations are found, many of them can be addressed "
"automatically via::"
msgstr ""
"若存在不合规范风格的代码，大多数情况下可以通过下述命令自动纠正："
#: ../../contribute.rst:199 a0ee1e11aaea4f5c8ba4c4704678bbaf
msgid ""
"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 reports any code style violations."
msgstr ""
"如果在自动格式化后仍存在代码风格上的问题，请手动修正这些问题，直到执行 "
"``invoke lint`` 时不再报告问题。"
#: ../../contribute.rst:207 e9d1e344bb0d4b2fb9d08c2d71d9a342
msgid "Submitting your changes"
msgstr "提交更改"
#: ../../contribute.rst:209 716c9f94166d42299d9ee58eed4f9b53
msgid ""
"Assuming linting validation and tests pass, add a ``RELEASE.md`` file in "
"the root of the project that contains the release type (major, minor, "
"patch) and a summary of the changes that will be used as the release "
"changelog entry. For example::"
msgstr ""
"通过了风格检查和所有测试后，请在项目的根目录下添加一个 ``RELEASE.md`` 文件，"
"其中应包含发布的类型（major、minor、patch）以及代码变更的摘要，这份摘要会被用作"
"更新日志的条目。下面是一个例子："
#: ../../contribute.rst:218 656309283e5642b99981c84da9b04c86
msgid "Commit your changes and push your topic branch::"
msgstr "commit你的更改，并push对应分支："
#: ../../contribute.rst:224 16617b687db94783b5488884e4c9be1b
msgid ""
"Finally, browse to your repository fork on GitHub and submit a pull "
"request."
msgstr ""
"最后，前往Github，从你fork的仓库向原仓库提出PR。"
#: ../../contribute.rst:228 629ae326bd4e4718a8865d3925c02c3e
msgid "Logging tips"
msgstr "日志技巧"
#: ../../contribute.rst:230 486bb6ae6c484431923a96b7a7aff0c5
msgid "Try to use logging with appropriate levels."
msgstr "请仔细斟酌合适的日志等级。"
#: ../../contribute.rst:232 fbe2aed8f0f5412081461fce5d36e51e
msgid "For logging messages that are not repeated, use the usual Python way::"
msgstr "对于不重复的日志消息，使用一般的方式即可："
#: ../../contribute.rst:241 bab220240a0744f5b1170783098b5eac
#, python-format
msgid ""
"Do not format log messages yourself. Use ``%s`` formatting in messages "
"and pass arguments to logger. This is important, because the Pelican "
"logger will preprocess some arguments, such as exceptions."
msgstr ""
"请不要自己格式化日志消息，而是使用在日志消息中使用 ``%s`` 并向logger传入参数。请务必"
"遵循这一规则，因为Pelican的logger会自动预处理一些特殊的参数，例如exception。"
#: ../../contribute.rst:246 a760419565b8440ebc8b4dc8898520db
msgid "Limiting extraneous log messages"
msgstr "限制低关联日志消息"
#: ../../contribute.rst:248 dcf900d9f7d0424fabff4a9c5a7e5dc8
msgid ""
"If the log message can occur several times, you may want to limit the log"
" to prevent flooding. In order to do that, use the ``extra`` keyword "
"argument for the logging message in the following format::"
msgstr ""
"如果同一日志消息会重复多次，你会希望限制这些多余的内容。使用 ``extra`` "
"命名参数来实现这一点："
#: ../../contribute.rst:255 1ca7d769fc9348f8a5f9eef7b614522b
msgid ""
"Optionally, you can also set ``'limit_args'`` as a tuple of arguments in "
"``extra`` dict if your generic message needs formatting."
msgstr ""
"可选的，如果通用日志消息需要格式化，可以添加 ``'limit_args'`` 参数并将其对应值"
"设为一个元组。"
#: ../../contribute.rst:258 85328a267c464f9aaacb1b0ef289d624
msgid ""
"Limit is set to ``5``, i.e, first four logs with the same ``'limit_msg'``"
" are outputted normally but the fifth one will be logged using "
"``'limit_msg'`` (and ``'limit_args'`` if present). After the fifth, "
"corresponding log messages will be ignored."
msgstr ""
"限制数默认设为了 ``5`` ，即前四个有相同 ``'limit_msg'`` 参数的日志消息会正常输出，"
"但第五条这样的日志消息会呈现为 ``'limit_msg'`` 参数值本身（ ``'limit_args'`` 同理）。"
"第六条及之后的日志消息会被直接忽略。"
#: ../../contribute.rst:263 7a51dbb9559d4a579654b2ab0938d09b
msgid ""
"For example, if you want to log missing resources, use the following "
"code::"
msgstr ""
"例如，如果你想要用日志记录资源缺失的信息，可以使用下面的代码："
#: ../../contribute.rst:271 8db05f7332f3475b940fb79d24e74ce7
msgid "The log messages will be displayed as follows::"
msgstr "最终的日志消息看起来会像这样："
#: ../../contribute.rst:281 93d618c58e6e4688bebb999ddf591eaa
msgid "Outputting traceback in the logs"
msgstr "在日志中输出traceback信息"
#: ../../contribute.rst:283 3d56bb4bc804499a8d3c8f14dc614916
msgid ""
"If you're logging inside an ``except`` block, you may want to provide the"
" traceback information as well. You can do that by setting ``exc_info`` "
"keyword argument to ``True`` during logging. However, doing so by default"
" can be undesired because tracebacks are long and can be confusing to "
"regular users. Try to limit them to ``--debug`` mode like the following::"
msgstr ""
"当在 ``except`` 块中进行日志记录时，你可能会希望同时输出traceback信息。可以"
"简单地将 ``exc_info`` 参数设为 ``True`` 来实现这一功能。但是通过此方法输出的"
"traceback信息会非常长，不便于理解。可以像下述代码一样将这些信息限制在 "
"``--debug`` 模式中："
#~ msgid "latest Pelican release (or an up-to-date Git clone of Pelican master)"
#~ msgstr ""
#~ msgid ""
#~ "`Create a new branch`_ specific to "
#~ "your change (as opposed to making "
#~ "your commits in the master branch)."
#~ msgstr ""

457
docs/locale/zh_CN/LC_MESSAGES/faq.po
View file

@ -1,457 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-07-31 22:54+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../faq.rst:2 87acb7c16d974b4eb060949b8ce40914
msgid "Frequently Asked Questions (FAQ)"
msgstr "常见问题解答"
#: ../../faq.rst:4 76aee892f7f14d0590db2d76c7cc0123
msgid "Here are some frequently asked questions about Pelican."
msgstr "以下是一些Pelican的常见问题解答。"
#: ../../faq.rst:7 c98549fdd5814984bfa3a6eaf4631d37
msgid "What's the best way to communicate a problem, question, or suggestion?"
msgstr "交流问题、疑问或提建议的最佳方式是什么？"
#: ../../faq.rst:9 dbecb306adeb482ba3b9bd68483bc372
msgid "Please read our :doc:`feedback guidelines <contribute>`."
msgstr "请参阅文档 :doc:`项目贡献与意见反馈 <contribute>` 。"
#: ../../faq.rst:12 8fe91d51140946f1b2cb131d786c1814
msgid "How can I help?"
msgstr "我可以帮上什么忙？"
#: ../../faq.rst:14 d8477da414c446b3936e73931eb4f63a
msgid ""
"There are several ways to help out. First, you can communicate any "
"Pelican suggestions or problems you might have via `Pelican Discussions "
"<https://github.com/getpelican/pelican/discussions>`_. Please first check"
" the existing list of discussions and issues (both open and closed) in "
"order to avoid submitting topics that have already been covered before."
msgstr ""
"有好多种方法可以提供帮助。首先，可以在 `Pelican讨论板块 "
"<https://github.com/getpelican/pelican/discussions>`_ "
"中提出任何关于Pelican的建议或是问题。在提问或建议之前，请先查看已关闭或开放的issues中是否已有相关内容，以避免内容上的重复。"
#: ../../faq.rst:20 95a29a97e08a452f89aa4eaad191b698
msgid ""
"If you want to contribute, please fork `the Git repository "
"<https://github.com/getpelican/pelican/>`_, create a new feature branch, "
"make your changes, and issue a pull request. Someone will review your "
"changes as soon as possible. Please refer to the :doc:`How to Contribute "
"<contribute>` section for more details."
msgstr ""
"如果你想要对项目进行贡献，请fork `Git仓库 <https://github.com/getpelican/pelican/>`_ "
"，创建一个新的功能分支，并在其中进行修改，在修改完成后提出一个PR。项目组会尽快审核你的PR。关于此的更多内容，请参见 "
":doc:`项目贡献与意见反馈 <contribute>` 一节。"
#: ../../faq.rst:26 bf7a6828eec74dc588c18e185bdd7090
msgid ""
"You can also contribute by creating themes and improving the "
"documentation."
msgstr "你可以发起的贡献当然也包括创建主题和改进文档。"
#: ../../faq.rst:29 2ce846241ce744fd81981a376d3f5fe2
msgid "Is the Pelican settings file mandatory?"
msgstr "Pelican配置文件是必要的吗？"
#: ../../faq.rst:31 527720062339422095e2c95755af5584
msgid ""
"Configuration files are optional and are just an easy way to configure "
"Pelican. For basic operations, it's possible to specify options while "
"invoking Pelican via the command line. See ``pelican --help`` for more "
"information."
msgstr ""
"配置文件是可选的，其本质是使您可以更方便地配置Pelican。对于一些基本的配置操作，完全可以在命令行中指定，调用 ``pelican "
"--help`` 可以查看pelican命令的更多信息。"
#: ../../faq.rst:36 d0ca19a2e40c4ecaa9ecba6cc677f142
msgid "Changes to the settings file take no effect"
msgstr "修改后的配置文件没有生效"
#: ../../faq.rst:38 5b741cbb28854893818826c593f8e323
msgid ""
"When experimenting with different settings (especially the metadata ones)"
" caching may interfere and the changes may not be visible. In such cases,"
" ensure that caching is disabled via ``LOAD_CONTENT_CACHE = False`` or "
"use the ``--ignore-cache`` command-line switch."
msgstr ""
"在尝试不同的配置时（尤其是尝试不同元数据时），缓存很可能会产生干扰，使得修改不可见。此时，确保配置了 ``LOAD_CONTENT_CACHE ="
" False`` 或在命令行中加上 ``--ignore-cache`` 以禁用缓存。"
#: ../../faq.rst:44 439f2221927b42f7a4c219ab1a76f849
msgid "I'm creating my own theme. How do I use Pygments for syntax highlighting?"
msgstr "在自己创建主题时，如何使用Pygments来调整语法高亮？"
#: ../../faq.rst:46 3475c1550e584c84a118ac061461f9f6
msgid ""
"Pygments adds some classes to the generated content. These classes are "
"used by themes to style code syntax highlighting via CSS. Specifically, "
"you can customize the appearance of your syntax highlighting via the "
"``.highlight pre`` class in your theme's CSS file. To see how various "
"styles can be used to render Django code, for example, use the style "
"selector drop-down at top-right on the `Pygments project demo site "
"<https://pygments.org/demo/>`_."
msgstr ""
"Pygments会为生成的内容添加一些CSS类。这些类会为主题所用，主题会通过CSS来为代码添加语法高亮。具体来说，你可以通过主题CSS文件中的 "
"``.highlight pre`` 类来自定义语法高亮的外观。在 `Pygments 项目的demo网站 "
"<https://pygments.org/demo/>`_ 上可以预览能够渲染的代码类型。"
#: ../../faq.rst:53 ecffb1f9501f46c88f799b79fc0ba343
msgid ""
"You can use the following example commands to generate a starting CSS "
"file from a Pygments built-in style (in this case, \"monokai\") and then "
"copy the generated CSS file to your new theme::"
msgstr "你可以使用下面的命令来让Pygments使用内置风格（此处为“monokai”）生成一个初始CSS文件，然后将此文件拷贝到新主题中："
#: ../../faq.rst:60 8fc71763c5c243339c9e737cc55b99da
msgid "Don't forget to import your ``pygment.css`` file from your main CSS file."
msgstr "不要忘了在你的CSS主文件中引入 ``pygment.css`` 文件。"
#: ../../faq.rst:63 ad118f1f46db423fab19f570cd789798
msgid "How do I create my own theme?"
msgstr "如何创建我自己的主题？"
#: ../../faq.rst:65 1674585960e742cbade644b63d3bb32a
msgid "Please refer to :ref:`theming-pelican`."
msgstr "请参阅 :ref:`theming-pelican` 。"
#: ../../faq.rst:68 b06c6a8df1634d20b988515af6536e2c
msgid "I want to use Markdown, but I got an error."
msgstr "我想要使用Markdown，但是出错了。"
#: ../../faq.rst:70 c0a89314dbdf4368b2e32d781c0ae95b
msgid ""
"If you try to generate Markdown content without first installing the "
"Markdown library, you may see a message that says ``No valid files found "
"in content``. Markdown is not a hard dependency for Pelican, so if you "
"have content in Markdown format, you will need to explicitly install the "
"Markdown library. You can do so by typing the following command, "
"prepending ``sudo`` if permissions require it::"
msgstr ""
"如果没有事先安装Markdown库，在生成Markdown内容时会看到一条提示 ``No valid files found in "
"content`` "
"。虽然Markdown并不是必需依赖，但如果你写的内容中含有Markdown格式，就需要安装Markdown库了。输入下面的命令以安装Markdown库，如果需要权限，请在前面添加"
" ``sudo`` ："
#: ../../faq.rst:80 a4c93b71eb914652b3f05357067f87b3
msgid "Can I use arbitrary metadata in my templates?"
msgstr "在模板中可以使用任意元数据吗？"
#: ../../faq.rst:82 6ac1579e5d8842f5bf97b87745848c6a
msgid ""
"Yes. For example, to include a modified date in a Markdown post, one "
"could include the following at the top of the article::"
msgstr "当然可以。例如，可以在Markdown帖子中包含一个“修改日期”，加在文章开头即可："
#: ../../faq.rst:87 d1ad8fa8e07c4500ab754962064749a8
msgid ""
"For reStructuredText, this metadata should of course be prefixed with a "
"colon::"
msgstr "对于reStructuredText，此元数据也应当以冒号为前缀："
#: ../../faq.rst:91 e3c9814b5b3849a7957f964565038e45
msgid ""
"This metadata can then be accessed in templates such as ``article.html`` "
"via::"
msgstr "此元数据可以在模板中获取到，例如在 ``article.html`` 中，可以像这样获取："
#: ../../faq.rst:97 11d953b5718c4baeb7f7fbbb9538c763
msgid ""
"If you want to include metadata in templates outside the article context "
"(e.g., ``base.html``), the ``if`` statement should instead be::"
msgstr "如果您想在其他模板（例如 ``base.html`` ）中获取此元数据，则 ``if`` 语句应改为："
#: ../../faq.rst:103 99ca0aeea6d14c159cf1f1b8d9cf016d
msgid ""
"How do I make my output folder structure identical to my content "
"hierarchy?"
msgstr "如何使得输出目录的结构和content目录的结构保持一致？"
#: ../../faq.rst:105 e97223e6c7c94c08a1d42f783fd67f7e
msgid "Try these settings::"
msgstr "可以尝试如下配置："
#: ../../faq.rst:112 d35f11a227ba421596458ea8f26ecde0
msgid "How do I assign custom templates on a per-page basis?"
msgstr "如何为某个页面指定某个模板？"
#: ../../faq.rst:114 287bac0946dc47feab068bdb76d0bc2e
msgid ""
"It's as simple as adding an extra line of metadata to any page or article"
" that you want to have its own template. For example, this is how it "
"would be handled for content in reST format::"
msgstr "这非常简单，在任何页面或者文章中，都可以通过多添加一行元数据来指定特定模板。例如，在reST中，使用："
#: ../../faq.rst:120 b845784299bf47629e616505000724c1
msgid "For content in Markdown format::"
msgstr "对于Markdown，则使用："
#: ../../faq.rst:124 fa734dbb540e4cda8a5be5fb1b2da124
msgid ""
"Then just make sure your theme contains the relevant template file (e.g. "
"``template_name.html``)."
msgstr "确保对应的模板文件在主题中存在即可（例如 ``template_name.html`` ）。"
#: ../../faq.rst:128 bdee9be4397f4839855295ee1a0fdd12
msgid "How can I override the generated URL of a specific page or article?"
msgstr "如何重写某一个页面或文章生成的URL？"
#: ../../faq.rst:130 ed91b5bdcbe24473a6fed738784311b8
msgid ""
"Include ``url`` and ``save_as`` metadata in any pages or articles that "
"you want to override the generated URL. Here is an example page in reST "
"format::"
msgstr "在任意页面或文章中都可以添加 ``url`` 和 ``save_as`` 元数据，这样就可以重写URL了。下面以reST格式为例："
#: ../../faq.rst:139 5aa733d8d3bd4d86920e7e142715b1f4
msgid ""
"With this metadata, the page will be written to "
"``override/url/index.html`` and Pelican will use the URL "
"``override/url/`` to link to this page."
msgstr ""
"有了这样的元数据，此页面会保存为 ``override/url/index.html`` ，Pelican会将 ``override/url/``"
" 作为链接到此页面的URL。"
#: ../../faq.rst:143 04d9890aa34d4c1e86bc7a49cd64938a
msgid "How can I use a static page as my home page?"
msgstr "如何使用一个静态页面作为主页？"
#: ../../faq.rst:145 d3e8a4e2d453446f9037fa46e6775080
msgid ""
"The override feature mentioned above can be used to specify a static page"
" as your home page. The following Markdown example could be stored in "
"``content/pages/home.md``::"
msgstr "上一个问题中提到的特性可以用于实现此需求。下面例子中的Markdown文件保存为 ``content/pages/home.md`` ："
#: ../../faq.rst:155 739da75e7ce946af99c9f577e8a284ff
msgid ""
"If the original blog index is still wanted, it can then be saved in a "
"different location by setting ``INDEX_SAVE_AS = 'blog_index.html'`` for "
"the ``'index'`` direct template."
msgstr ""
"如果仍需要原来的博客主页（即 ``'index'`` 直接模板），可以通过设置 ``INDEX_SAVE_AS = "
"'blog_index.html'`` 将其存储在其他位置。"
#: ../../faq.rst:160 5224f09821d24e4a8db6870da1266a20
msgid "What if I want to disable feed generation?"
msgstr "可以禁用订阅源生成吗？"
#: ../../faq.rst:162 8f014ffab3c44b0ebf2b0d9872bfbfa7
msgid ""
"To disable feed generation, all feed settings should be set to ``None``. "
"All but three feed settings already default to ``None``, so if you want "
"to disable all feed generation, you only need to specify the following "
"settings::"
msgstr ""
"要禁用订阅源，所有订阅源相关的配置都应被设为 ``None`` 。其中有三项设置默认为 ``None`` "
"，因此如果要彻底不生成订阅源，你只需要指定下面这些设置："
#: ../../faq.rst:172 9ab29ccca83c4ecfabcb3ad4dd17c751
msgid ""
"The word ``None`` should not be surrounded by quotes. Please note that "
"``None`` and ``''`` are not the same thing."
msgstr "``None`` 两侧不需要加引号。请注意 ``None`` 和 ``''`` 不是同一个东西。"
#: ../../faq.rst:176 fd8cbe4962d145ccadfd480419dbea9e
msgid ""
"I'm getting a warning about feeds generated without SITEURL being set "
"properly"
msgstr "Pelican警告说由于SITEURL设置不正确，无法正常生成订阅源"
#: ../../faq.rst:178 e3135e5903ec422f8d7895866ca6f365
msgid ""
"`RSS and Atom feeds require all URL links to be absolute "
"<https://validator.w3.org/feed/docs/rss2.html#comments>`_. In order to "
"properly generate links in Pelican you will need to set ``SITEURL`` to "
"the full path of your site."
msgstr ""
"`RSS和Atom订阅源要求所有URL都要链接到绝对地址 "
"<https://validator.w3.org/feed/docs/rss2.html#comments>`_ "
"。为了使得Pelican能正确生成链接，你需要将站点的 ``SITEURL`` 设置为完整路径。"
#: ../../faq.rst:183 4f2cd929dda7464cbd577d1249969920
msgid ""
"Feeds are still generated when this warning is displayed, but links "
"within may be malformed and thus the feed may not validate."
msgstr "虽然Pelican提出了警告，但是仍会生成订阅源，但其中的链接可能是无效的，这会导致订阅源不可用。"
#: ../../faq.rst:187 a9f3465fda8c4a0d9395b2d6d9d5478f
msgid "Can I force Atom feeds to show only summaries instead of article content?"
msgstr "可以让Atom订阅源只显示摘要，不显示文章内容吗？"
#: ../../faq.rst:189 baf140533501453aa8caeddfc276d8fb
msgid ""
"Instead of having to open a separate browser window to read articles, the"
" overwhelming majority of folks who use feed readers prefer to read "
"content within the feed reader itself. Mainly for that reason, Pelican "
"does not support restricting Atom feeds to only contain summaries. Unlike"
" Atom feeds, the RSS feed specification does not include a separate "
"``content`` field, so by default Pelican publishes RSS feeds that only "
"contain summaries (but can optionally be set to instead publish full "
"content RSS feeds). So the default feed generation behavior provides "
"users with a choice: subscribe to Atom feeds for full content or to RSS "
"feeds for just the summaries."
msgstr ""
"绝大多数使用订阅源阅读器的人都更喜欢直接在阅读器中阅读文章内容，而不是另外再打开窗口来阅读。因此，Pelican不支持使Atom只包含摘要。但是由于RSS不包含单独的"
" ``content`` "
"字段，因此Pelican在发布RSS时默认只包含摘要（当然也可以设置为包含文章内容）。Pelican在订阅源生成上的如此行为就可以让用户自行选择订阅类型：包含了完整内容的Atom或是只包含摘要的RSS。"
#: ../../faq.rst:200 850ac093f2764547a7df74d5d055cbd4
msgid "Is Pelican only suitable for blogs?"
msgstr "Pelican只适合用于博客吗？"
#: ../../faq.rst:202 1fb5d92096b242d09da5e0e490b34685
msgid ""
"No. Pelican can be easily configured to create and maintain any type of "
"static site. This may require a little customization of your theme and "
"Pelican configuration. For example, if you are building a launch site for"
" your product and do not need tags on your site, you could remove the "
"relevant HTML code from your theme. You can also disable generation of "
"tag-related pages via::"
msgstr "不是的。Pelican可以方便地用于创建维护任何静态站点，为此你需要对主题和配置做一些定制。例如，如果要为你的产品构建一个宣传网站，即不需要使用标签特性，从主题中移除与标签相关的HTML代码即可。另外，还可以通过下面的设置来禁用标签相关页面的生成："
#: ../../faq.rst:212 5452959b3b694cbc89bb8e91bfbef840
msgid ""
"Why does Pelican always write all HTML files even with content caching "
"enabled?"
msgstr "启用内容缓存后，为什么Pelican仍会每次都写入所有HTML文件？"
#: ../../faq.rst:214 b27b4b7256f749f1bc5970b95fa742ab
msgid ""
"In order to reliably determine whether the HTML output is different "
"before writing it, a large part of the generation environment including "
"the template contexts, imported plugins, etc. would have to be saved and "
"compared, at least in the form of a hash (which would require special "
"handling of unhashable types), because of all the possible combinations "
"of plugins, pagination, etc. which may change in many different ways. "
"This would require a lot more processing time and memory and storage "
"space. Simply writing the files each time is a lot faster and a lot more "
"reliable."
msgstr "为了确定HTML输出确实和之前的不同，模板上下文、插件等很多生成环境都需要保存并比较某种哈希值（对于不可哈希的内容类型还需要进行一些额外处理）。另外，由于插件、分页等内容的存在，输出的HTML很可能会与之前不同。因此，考虑到处理时间和存储空间，每次都重新写入全部HTML会更快更可靠。"
#: ../../faq.rst:223 dcb5b1cf0e1b413bb7c04f6deb4ad5d7
msgid ""
"However, this means that the modification time of the files changes every"
" time, so a ``rsync`` based upload will transfer them even if their "
"content hasn't 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."
msgstr ""
"然而，这样的机制会使得在每次生成站点后，文件的修改时间都会变化，因此基于 ``rsync`` "
"上传时会把没有变化的内容也进行上传。一个简便的解决方法就是给 ``rsync`` 加上 ``--checksum`` "
"选项，这会比Pelican在生成时进行校验更快。"
#: ../../faq.rst:230 628a1180f3fd4c0b8301b33e0728d2c2
msgid "How to process only a subset of all articles?"
msgstr "如何只处理一部分文章？"
#: ../../faq.rst:232 c2bfe768775342bb8386255ea1bbbe4e
msgid ""
"It is often useful to process only e.g. 10 articles for debugging "
"purposes. This can be achieved by explicitly specifying only the "
"filenames of those articles in ``ARTICLE_PATHS``. A list of such "
"filenames could be found using a command similar to ``cd content; find "
"-name '*.md' | head -n 10``."
msgstr ""
"简便起见，在调试时可能只需要处理几篇文章。可以直接在配置项 ``ARTICLE_PATHS`` 中添加需要处理文章的文件名。可以通过像 ``cd "
"content; find -name '*.md' | head -n 10`` 这样的命令获取文章文件名的列表。"
#: ../../faq.rst:238 72d30cb7a6e348c483cba0c6b6de8d3a
msgid "My tag cloud is missing/broken since I upgraded Pelican"
msgstr "在升级Pelican后，标签云消失或不可用了"
#: ../../faq.rst:240 7d07dcddab5d42d1aab6a8dbd27ce36c
msgid ""
"In an ongoing effort to streamline Pelican, tag cloud generation has been"
" moved out of Pelican core and into a separate `plugin "
"<https://github.com/pelican-plugins/tag-cloud>`_. See the :ref:`plugins` "
"documentation for further information about the Pelican plugin system."
msgstr ""
"我们一直致力于精简Pelican，标签云生成的功能已经从Pelican核心中移除，转而放到了一个单独的 `tag-cloud插件 "
"<https://github.com/pelican-plugins/tag-cloud>`_ 中。查看 :ref:`plugins` "
"文档获取更多关于Pelican插件系统的信息。"
#: ../../faq.rst:246 51c727bc21f946b8915f958312369e0f
msgid "Since I upgraded Pelican my pages are no longer rendered"
msgstr "升级Pelican后，一些页面没有被渲染"
#: ../../faq.rst:248 4a0d962bc2d844cbab3d0b3e7f6f7bba
msgid ""
"Pages were available to themes as lowercase ``pages`` and uppercase "
"``PAGES``. To bring this inline with the :ref:`templates-variables` "
"section, ``PAGES`` has been removed. This is quickly resolved by updating"
" your theme to iterate over ``pages`` instead of ``PAGES``. Just "
"replace::"
msgstr ""
"在以前的版本中，主题通过小写的 ``pages`` 和大写的 ``PAGES`` 都能获取到页面。为了使之与 :ref:`templates-"
"variables` 一节中的内容保持一致，大写的 ``PAGES`` 被删除了。只要将主题中的 ``PAGES`` 替换为 ``pages`` "
"，问题即可解决。例如将原先的："
#: ../../faq.rst:255 6167ad6b52db43d384247747db1884ca
msgid "with something like::"
msgstr "替换为："
#: ../../faq.rst:260 a7a04eb9e8e549fa8a2a72db3f35b532
msgid "How can I stop Pelican from trying to parse my static files as content?"
msgstr "如何避免让Pelican将我的静态文件解析为内容文件？（译者注：例如要将一个HTML文件作为静态文件）？"
#: ../../faq.rst:262 6baaf265738d4acaa26f7829c64a0ac5
msgid ""
"Pelican's article and page generators run before it's static generator. "
"That means if you use a setup similar to the default configuration, where"
" a static source directory is defined inside a ``*_PATHS`` setting, all "
"files that have a valid content file ending (``.html``, ``.rst``, "
"``.md``, ...) will be treated as articles or pages before they get "
"treated as static files."
msgstr ""
"Pelican的文章与页面生成器会先于静态文件生成器运行。这意味着若使用默认配置，即静态资源文件夹定义在某个 ``*_PATHS`` "
"配置项中，所有以有效内容文件后缀结尾的文件（ ``.html`` 、 ``.rst`` 、 ``.md`` "
"等）都会被视为文章或者页面，而不是静态文件。"
#: ../../faq.rst:268 e4591dd94ddd4199900b9a451d12929e
msgid ""
"To circumvent this issue either use the appropriate ``*_EXCLUDES`` "
"setting or disable the offending reader via ``READERS`` if you don't need"
" it."
msgstr ""
"为了避免这个问题，使用合适的 ``*_EXCLUDES`` 配置，在必要时还可以通过 ``READERS`` "
"配置项来直接禁用产生问题的reader。"
#: ../../faq.rst:272 ca927fe2be10411ab365bcc3e4fa4dbd
msgid "Why is [arbitrary Markdown syntax] not supported?"
msgstr "为什么不是所有的Markdown语法都支持？"
#: ../../faq.rst:274 5c9cc929a6bf4f1db9d4eed5f37fc0af
msgid ""
"Pelican does not directly handle Markdown processing and instead "
"delegates that task to the Python-Markdown_ project, the core of which "
"purposefully follows the original Markdown syntax rules and not the "
"myriad Markdown \"flavors\" that have subsequently propagated. That said,"
" Python-Markdown_ is quite modular, and the syntax you are looking for "
"may be provided by one of the many available `Markdown Extensions`_. "
"Alternatively, some folks have created Pelican plugins that support "
"Markdown variants, so that may be your best choice if there is a "
"particular variant you want to use when writing your content."
msgstr ""
"Pelican并不直接对Markdown进行处理，而是将此任务交给 Python-Markdown_ "
"项目，此项目的核心有意只遵循原始的Markdown语法规则，而不服从之后传播开的大量Markdown风格。另外， Python-Markdown_"
" 是相当模块化的，你想要使用的语法可能已经有现成的 `Markdown扩展`_ "
"进行了实现。或者，也有人创建了支持Markdown变体的Pelican插件，如果你想要用某种Markdown变体，可以在这些地方寻找支持。"

321
docs/locale/zh_CN/LC_MESSAGES/importer.po
View file

@ -1,321 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../importer.rst:4 2e58a5582f664ba0af49aac4480bc799
msgid "Importing an existing site"
msgstr "导入已有站点"
#: ../../importer.rst:7 5182de0b717543c7a4813491755b720a
msgid "Description"
msgstr "简介"
#: ../../importer.rst:9 29a8bae0ba78486894ed4c286cd2f3b4
msgid ""
"``pelican-import`` is a command-line tool for converting articles from "
"other software to reStructuredText or Markdown. The supported import "
"formats are:"
msgstr ""
"命令行工具 ``pelican-import`` 用于将其他软件生成的文章转换成reStructuredText"
"或Markdown格式。支持导入下面这些格式："
#: ../../importer.rst:12 c670f6055ad24d818132d74951c9928c
msgid "Blogger XML export"
msgstr "Blogger XML export"
#: ../../importer.rst:13 d31ddaa8c7d54a268b379f706164de39
msgid "Dotclear export"
msgstr "Dotclear export"
#: ../../importer.rst:14 5102eb70c58240b2ad4d508a196b176e
msgid "Medium export"
msgstr "Medium export"
#: ../../importer.rst:15 2cfcdf575387417bae3a9938aa55b0e6
msgid "Tumblr API"
msgstr "Tumblr API"
#: ../../importer.rst:16 42233d68a4bc46339b284681bdbdd19c
msgid "WordPress XML export"
msgstr "WordPress XML export"
#: ../../importer.rst:17 0170dad08a80435b99a39ccaf887c5bb
msgid "RSS/Atom feed"
msgstr "RSS/Atom feed"
#: ../../importer.rst:19 077a8220f4a84dd297ec5aa7cff15a24
msgid ""
"The conversion from HTML to reStructuredText or Markdown relies on "
"`Pandoc`_. For Dotclear, if the source posts are written with Markdown "
"syntax, they will not be converted (as Pelican also supports Markdown)."
msgstr ""
"从HTML转换到reStructuredText或Markdown是依赖 `Pandoc`_ "
"完成的。对于Dotclear，若原帖子是由Markdown语法写的，则无需转换"
"（因为Pelican本就支持Markdown）。"
#: ../../importer.rst:25 e9b94b6029204b82b009d3ef23c19814
msgid ""
"Unlike Pelican, Wordpress supports multiple categories per article. These"
" are imported as a comma-separated string. You have to resolve these "
"manually, or use a plugin such as `More Categories`_ that enables "
"multiple categories per article."
msgstr ""
"和Pelican不同，在Wordpress中可以将一篇文章同时放在多个分类中。在导入时，各个分类"
"会以逗号分隔，你必须自己手动进行处理。或者也可以使用例如 `More Categories`_ "
"这样的插件，使得文章可以同时存在于多个分类中。"
#: ../../importer.rst:32 f7add19b68754b6e8a617a1d50dee759
msgid ""
"Imported pages may contain links to images that still point to the "
"original site. So you might want to download those images into your local"
" content and manually re-link them from the relevant pages of your site."
msgstr ""
"要导入的内容中可能会包含指向原站点的图片链接，你可能希望将他们全部下载下来，然后再"
"重新手动调整这些链接。"
#: ../../importer.rst:37 22cc1a514c4f42efbcf9afc3d987c42e
msgid "Dependencies"
msgstr "依赖"
#: ../../importer.rst:39 6139199770a24fc7af7ca7e556d18d5f
msgid ""
"``pelican-import`` has some dependencies not required by the rest of "
"Pelican:"
msgstr ""
"``pelican-import`` 需要用到一些其他依赖，这些依赖只会被 ``pelican-import`` 用到："
#: ../../importer.rst:41 0e8eb04bb07f4752880b873e73e7f7e5
msgid ""
"*BeautifulSoup4* and *lxml*, for WordPress and Dotclear import. Can be "
"installed like any other Python package (``pip install BeautifulSoup4 "
"lxml``)."
msgstr ""
"为了能够导入WordPress和Dotclear的内容，需要 *BeautifulSoup4* 与 *lxml* 。"
"安装方法与其他Python包相同（ ``pip install BeautifulSoup4 lxml`` ）"
#: ../../importer.rst:44 7d31c1ad4ecb4014a3ef240436b9b3e1
msgid "*Feedparser*, for feed import (``pip install feedparser``)."
msgstr "为了能够导入订阅源，需要 *Feedparser* （ ``pip install feedparser`` ）"
#: ../../importer.rst:45 db7a18b1a4534a17956c9d030dddff56
msgid ""
"*Pandoc*, see the `Pandoc site`_ for installation instructions on your "
"operating system."
msgstr ""
"还需要 *Pandoc* ，参照 `Pandoc官方网站`_ 进行安装。"
#: ../../importer.rst:53 9952881aed104ef0ac82af5339e6b149
msgid "Usage"
msgstr "用法"
#: ../../importer.rst:63 83dbe43e4d2e4d8eaf3e37724ac119e3
msgid "Positional arguments"
msgstr "位置参数"
#: ../../importer.rst:65 4a12692744024752be75d82ed74d369d
msgid "``input``"
msgstr "``input``"
#: ../../importer.rst:65 52f62f22221f4c3d964df5aced3d2a2b
msgid "The input file to read"
msgstr "需要读取的输入文件"
#: ../../importer.rst:66 acc46432d5c14ea8a5e27e6ec2b84d18
msgid "``api_key``"
msgstr "``api_key``"
#: ../../importer.rst:66 29dd358bf2fe49d8a218c56ca376f6a6
msgid ""
"(Tumblr only) api_key can be obtained from "
"https://www.tumblr.com/oauth/apps"
msgstr ""
"（只会在Tumblr中用到）从 https://www.tumblr.com/oauth/apps 中获取到的api_key"
#: ../../importer.rst:70 a81b90d51a9f4c28adc09038715cf5c2
msgid "Optional arguments"
msgstr "可选参数"
#: ../../importer.rst:72 d4d5211b75aa4103b06ad7685368af06
msgid "Show this help message and exit"
msgstr "显示此帮助信息并退出 ``pelican-import`` "
#: ../../importer.rst:73 a7bae87fe16644f4b5da7d32fdc05f95
msgid "Blogger XML export (default: False)"
msgstr "输入是否为Blogger XML格式（默认：False）"
#: ../../importer.rst:74 e8c133125ed04120bcc3737fa2a0ba60
msgid "Dotclear export (default: False)"
msgstr "输入是否为Dotclear格式（默认：False）"
#: ../../importer.rst:75 caffd159f92a4f36aadedec398823ac3
msgid "Medium export (default: False)"
msgstr "输入是否为Medium格式（默认：False）"
#: ../../importer.rst:76 f1bcaccf8e2f43f6894f2f0540c9d7ba
msgid "Tumblr API (default: False)"
msgstr "输入是否为Tumblr API格式（默认：False）"
#: ../../importer.rst:77 6131f8fa00294515a028f4bb1a3a3053
msgid "WordPress XML export (default: False)"
msgstr "输入是否为WordPress XML格式（默认：False）"
#: ../../importer.rst:78 dad00ee0aebb4550acae995ecdbb622f
msgid "Feed to parse (default: False)"
msgstr "输入是否为订阅源格式（默认：False）"
#: ../../importer.rst:80 0ca3cbbc57c64b5b88444ccde94f94ce
msgid "Output path (default: content)"
msgstr "输出路径（默认：content）"
#: ../../importer.rst:82 baa2762a4ee745028e29865720ca299d
msgid ""
"Output markup format: ``rst``, ``markdown``, or ``asciidoc`` (default: "
"``rst``)"
msgstr ""
"输出格式，可选值为： ``rst`` 、 ``markdown`` 、 ``asciidoc`` （默认： ``rst`` ）"
#: ../../importer.rst:84 53232a317a58422d8f070c245d3b7409
msgid "Put files in directories with categories name (default: False)"
msgstr "是否要将输出文件按分类名放到各文件夹中（默认：False）"
#: ../../importer.rst:86 f72e1895d9fc4facb90ddffb53b31a0a
msgid ""
"Put files recognised as pages in \"pages/\" sub- directory (blogger and "
"wordpress import only) (default: False)"
msgstr ""
"将识别为页面的文件放入“pages/” 子文件夹中（仅在blogger和wordpress中有用）（默认：False）"
#: ../../importer.rst:89 3f9315af4f1e4ced8ece96fca71cb1e7
msgid "Import only post from the specified author"
msgstr "仅导入某个作者的帖子"
#: ../../importer.rst:90 0b34125f0bb744b089fe77b86b3e50f7
msgid ""
"Strip raw HTML code that can't be converted to markup such as flash "
"embeds or iframes (default: False)"
msgstr ""
"删除无法转换的HTML代码，例如嵌入的flash或iframe（默认：False）"
#: ../../importer.rst:92 f899a119b708450bbd38913f813255c2
msgid ""
"Put wordpress custom post types in directories. If used with --dir-cat "
"option directories will be created as \"/post_type/category/\" (wordpress"
" import only)"
msgstr ""
"将wordpress中的自定义类型博文放到对应文件夹中。如果同时还使用了 --dir-cat 选项，"
"输出转换后文件时会创建诸如“/post_type/category/” 的文件夹（只在wordpress中有效）"
#: ../../importer.rst:95 627c041fab81460eafd4f5fe361bcd1a
msgid ""
"Download files uploaded to wordpress as attachments. Files will be added "
"to posts as a list in the post header and links to the files within the "
"post will be updated. All files will be downloaded, even if they aren't "
"associated with a post. Files will be downloaded with their original path"
" inside the output directory, e.g. \"output/wp-"
"uploads/date/postname/file.jpg\". (wordpress import only) (requires an "
"internet connection)"
msgstr ""
"下载作为附件上传到WordPress的文件。文件会以列表形式添加到帖子的开头，并且到这些"
"文件的链接都会进行更新。另外，即使某些文件没有在任何帖子中用到，也同样会被下载。"
"文件会被下载到输出文件夹下，并保持原始路径，例如"
"“output/wp-uploads/date/postname/file.jpg” 。（仅在wordpress中有效，"
"且需要互联网连接）"
#: ../../importer.rst:104 11162d8c497b4108a38c2a60af4a4215
msgid ""
"Disable storing slugs from imported posts within output. With this "
"disabled, your Pelican URLs may not be consistent with your original "
"posts. (default: False)"
msgstr ""
"不保存导入推文的slug，会导致Pelican的URL和原推文不一致。（默认：False）"
#: ../../importer.rst:109 f4f4b6e918d3498e927b59c5d0bae05a
msgid "Blog name used in Tumblr API"
msgstr "Tumblr API中使用的博客名"
#: ../../importer.rst:113 16e0f9bd1c6e4b338673f1800e6a4995
msgid "Examples"
msgstr "例子"
#: ../../importer.rst:115 0cf17b9fd72940c391a1bb8bf7de534b
msgid "For Blogger::"
msgstr "导入Blogger："
#: ../../importer.rst:119 3fc79daf9e9e4f5ba1a121faaabd0c9e
msgid "For Dotclear::"
msgstr "导入Dotclear："
#: ../../importer.rst:123 328ff8145b464fa2ab59505a8bc3236a
msgid "For Medium::"
msgstr "导入Medium："
#: ../../importer.rst:127 8ca5f721833142249b6d798efcb77458
msgid ""
"The Medium export is a zip file. Unzip it, and point this tool to the "
"\"posts\" subdirectory. For more information on how to export, see "
"https://help.medium.com/hc/en-us/articles/115004745787-Export-your-"
"account-data."
msgstr ""
"Medium中导出的是一个zip文件。请先解压之，然后再将其中的“posts”子目录传给此工具。 "
"https://help.medium.com/hc/en-us/articles/115004745787-Export-your-account-data "
"中有更详细的导出指导。"
#: ../../importer.rst:131 516a83a4d8cf4570a9a6fff416e5cf5a
msgid "For Tumblr::"
msgstr "导入Tumblr："
#: ../../importer.rst:135 8fcab620c0d44bb29a120d8d781f4daa
msgid "For WordPress::"
msgstr "导入WordPress："
#: ../../importer.rst:139 a929213eb21f4118b9adbb6199bd78ea
msgid "For Medium (an example of using an RSS feed):"
msgstr "导入Medium（例子中使用了RSS订阅源）："
#: ../../importer.rst:141 5e23c5d167ef4db1994f4323ac3d120e
msgid ""
"$ python -m pip install feedparser $ pelican-import --feed "
"https://medium.com/feed/@username"
msgstr ""
"$ python -m pip install feedparser $ pelican-import --feed "
"https://medium.com/feed/@username"
#: ../../importer.rst:146 b44dfe0f807049899c0560c6bf62c386
msgid "The RSS feed may only return the most recent posts — not all of them."
msgstr "RSS订阅源可能只会返回最新的帖子，而不是所有帖子。"
#: ../../importer.rst:149 575426ff787d4647b3aa2469b8b52412
msgid "Tests"
msgstr "测试"
#: ../../importer.rst:151 036d2119412b41f3a3cb69cec74ecc81
msgid "To test the module, one can use sample files:"
msgstr "可以使用下面的文件作为样例进行测试："
#: ../../importer.rst:153 482b30f9aab54717bb14218ae5fa8ea6
msgid ""
"for WordPress: https://www.wpbeginner.com/wp-themes/how-to-add-dummy-"
"content-for-theme-development-in-wordpress/"
msgstr ""
"WordPress： https://www.wpbeginner.com/wp-themes/how-to-add-dummy-content-"
"for-theme-development-in-wordpress/"
#: ../../importer.rst:154 6cb1bd10d37e4993aabece8aaed20171
msgid "for Dotclear: http://media.dotaddict.org/tda/downloads/lorem-backup.txt"
msgstr "Dotclear： http://media.dotaddict.org/tda/downloads/lorem-backup.txt"

134
docs/locale/zh_CN/LC_MESSAGES/index.po
View file

@ -1,134 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../index.rst:2 160b5c32c524404ba295da4e89124739
msgid "Pelican |release|"
msgstr "Pelican |release|"
#: ../../index.rst:4 19170a80b4274f71b77062c7a6b90726
msgid ""
"Pelican is a static site generator, written in Python_. Highlights "
"include:"
msgstr ""
"Pelican是一个用 Python_ 写的静态站点生成器，它有诸多亮点："
#: ../../index.rst:6 6ab42a346f2c46d789cd46655195f2d3
msgid ""
"Write your content directly with your editor of choice in "
"reStructuredText_ or Markdown_ formats"
msgstr ""
"你可以直接在自己的编辑器中用 reStructuredText_ 或 Markdown_ 完成内容创作"
#: ../../index.rst:8 dbd17888530e43ce8bdfc1594947032c
msgid "Includes a simple CLI tool to (re)generate your site"
msgstr "自带了一个简单的命令行工具，你可以用它来生成你的站点"
#: ../../index.rst:9 2bbe72bda8db457a88f3d3a94d16cc0c
msgid "Easy to interface with distributed version control systems and web hooks"
msgstr "易于与分布式版本控制系统和webhook交互"
#: ../../index.rst:10 24af69b083024f2a9c4f162d54fa57c6
msgid "Completely static output is easy to host anywhere"
msgstr "生成的站点是完全静态的，可以在任何主机上轻松地部署"
#: ../../index.rst:12 1e2090f3f19d49a19a6c50524e4cd0b7
msgid "Ready to get started? Check out the :doc:`Quickstart<quickstart>` guide."
msgstr "准备好开始体验了吗？请查看 :doc:`快速入门<quickstart>` 指南。"
#: ../../index.rst:15 481a352565e84c848e018de507fbe9af
msgid "Features"
msgstr "特性"
#: ../../index.rst:17 6c7b5d9b43ca42f1b1df139e7f884d26
msgid "Pelican’s feature highlights include:"
msgstr "Pelican在特性上也有很多亮点："
#: ../../index.rst:19 464e5e8ea8324fab9c5496b317a6db97
msgid ""
"Articles (e.g., blog posts) and pages (e.g., \"About\", \"Projects\", "
"\"Contact\")"
msgstr ""
"可以生成文章（例如博客推文）和页面（例如“关于”、“联系我们”、“项目”）"
#: ../../index.rst:20 c7cc4fe6ea8145feb0ace7d0965e2634
msgid "Integration with external services"
msgstr "可以和外部服务集成"
#: ../../index.rst:21 ceb2c8a629024157946eba53638d7eb1
msgid "Site themes (created using Jinja2_ templates)"
msgstr "可以使用主题（主题使用 Jinja2_ 模板引擎创建）"
#: ../../index.rst:22 51c3defcba6c4d31a77c3aade6826f1a
msgid "Publication of articles in multiple languages"
msgstr "可以为同一篇文章发布多种语言版本"
#: ../../index.rst:23 6f7cbfae94c54318a904e9725ce73677
msgid "Generation of Atom and RSS feeds"
msgstr "可以生成Atom和Rss订阅源"
#: ../../index.rst:24 3d667d2ed98a489788f6c38a4e4a6752
msgid "Code syntax highlighting"
msgstr "可以渲染代码高亮"
#: ../../index.rst:25 bf1a1f91b821464182471a3760a59d4f
msgid "Import existing content from WordPress, Dotclear, or RSS feeds"
msgstr "可以从WordPress、Dotclear或Rss订阅源导入已有的内容"
#: ../../index.rst:26 bd82641c549645cb8b4cd3187800397c
msgid "Fast rebuild times thanks to content caching and selective output writing"
msgstr "得益于内容缓存和选择性生成设计，可以快速重新生成站点"
#: ../../index.rst:27 8dec47d1ab13410c9b99db0709c860a3
msgid "Extensible via a rich plugin ecosystem: `Pelican Plugins`_"
msgstr "可扩展性强，有丰富的插件生态： `Pelican Plugins`_"
#: ../../index.rst:30 c7e090d7d2e04ff1ac1844e56209d75b
msgid "Why the name \"Pelican\"?"
msgstr "为什么叫做“Pelican”？"
#: ../../index.rst:32 8c31222af5e24ba69acb5dd07a5b5d56
msgid ""
"\"Pelican\" is an anagram for *calepin*, which means \"notebook\" in "
"French. ;)"
msgstr ""
"“Pelican”是法语词笔记本 *calepin* 读音的回文。;)"
#: ../../index.rst:35 188f72b2bb644f978180eba22009ebc6
msgid "Source code"
msgstr "源码"
#: ../../index.rst:37 2c8804f173fb4aa8973fb4d2413c263b
msgid "You can access the source code at: https://github.com/getpelican/pelican"
msgstr "在这里可以获取Pelican的源码： https://github.com/getpelican/pelican"
#: ../../index.rst:40 06ab21b7cde94cee92193199ddc69775
msgid "How to get help, contribute, or provide feedback"
msgstr "如何获取帮助、贡献内容或是提供反馈"
#: ../../index.rst:42 7fdcc2bcaac04317a6f4114f1d9c327f
msgid ""
"See our :doc:`feedback and contribution submission guidelines "
"<contribute>`."
msgstr ""
"请查看文档 :doc:`反馈意见和贡献的提交指南 <contribute>`。"
#: ../../index.rst:45 3d15499d76e1489d8e8782c65f73bb29
msgid "Documentation"
msgstr "文档"

244
docs/locale/zh_CN/LC_MESSAGES/install.po
View file

@ -1,244 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-25 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../install.rst:2 32d9c99d9171418c89daafbe7260daa9
msgid "Installing Pelican"
msgstr "安装Pelican"
#: ../../install.rst:4 73ec02b650044be6bb17951f4a915075
msgid ""
"Pelican currently runs best on |min_python|; earlier versions of Python "
"are not supported."
msgstr ""
"Pelican需要 |min_python| 以上版本的Python，不支持更低版本。"
#: ../../install.rst:6 9134a5a1bd9a4f54a36a3da163d859d8
msgid ""
"You can install Pelican via several different methods. The simplest is "
"via Pip_::"
msgstr ""
"有多种方法可以安装Pelican，最简单的就是通过 Pip_："
#: ../../install.rst:10 22d5948b07d14a13bc45aa14ef11e856
msgid "Or, if you plan on using Markdown::"
msgstr "如果您需要使用Markdown，请使用下面的命令安装："
#: ../../install.rst:14 b910f7faa2c84e5eb62fbd0fae2544d3
msgid ""
"(Keep in mind that some operating systems will require you to prefix the "
"above command with ``sudo`` in order to install Pelican system-wide.)"
msgstr ""
"（在某些操作系统中，需要在命令前加 ``sudo`` 才能在整个系统上安装Pelican）"
#: ../../install.rst:17 afb018b5d42e433e8107ca38dfcb545f
msgid ""
"While the above is the simplest method, the recommended approach is to "
"create a virtual environment for Pelican via virtualenv_ before "
"installing Pelican. Assuming you have virtualenv_ installed, you can then"
" open a new terminal session and create a new virtual environment for "
"Pelican::"
msgstr ""
"尽管上面是最简单的安装方法，但我们推荐使用虚拟环境 virtualenv_ 完成"
"Pelican的安装。当您安装好 virtualenv_ 后，打开一个新的命令行并"
"为Pelican创建一个虚拟环境："
#: ../../install.rst:26 7d981233f13e42b6b07fbd5fa58f69fc
msgid ""
"Once the virtual environment has been created and activated, Pelican can "
"be installed via ``python -m pip install pelican`` as noted above. "
"Alternatively, if you have the project source, you can install Pelican "
"using the distutils method::"
msgstr ""
"当创建并激活虚拟环境后，使用之前提到过的命令 ``python -m pip install pelican`` "
"就可以安装Pelican了。或者，如果您想要从源码安装，可以使用distutils方式："
#: ../../install.rst:33 c8109ae3e44541e18e713e39690009ae
msgid ""
"If you have Git installed and prefer to install the latest bleeding-edge "
"version of Pelican rather than a stable release, use the following "
"command::"
msgstr ""
"如果安装过Git，并且您希望安装Pelican的最最新版本（而不是稳定版），"
"请使用下面的命令："
#: ../../install.rst:38 2ba389e93d084dea8b702336479a0470
msgid ""
"Once Pelican is installed, you can run ``pelican --help`` to see basic "
"usage options. For more detail, refer to the :doc:`Publish<publish>` "
"section."
msgstr ""
"当您安装好Pelican，可以执行 ``pelican --help`` 命令来查看一些基本用法。"
"在 :doc:`发布站点<publish>` 章节中可以了解更多信息。"
#: ../../install.rst:42 d1850a31cca24c5281cc7c9fd748b56b
msgid "Optional packages"
msgstr "可选包"
#: ../../install.rst:44 8428281e15354c71a5aec92e9e0041b9
msgid ""
"If you plan on using `Markdown <https://pypi.org/project/Markdown/>`_ as "
"a markup format, you can install Pelican with Markdown support::"
msgstr ""
"如您希望使用 `Markdown <https://pypi.org/project/Markdown/>`_ "
"来写作，执行下面的命令来安装Markdown支持："
#: ../../install.rst:49 6dcdacecb0874afd8c88cbf814c522ba
msgid ""
"Typographical enhancements can be enabled in your settings file, but "
"first the requisite `Typogrify <https://pypi.org/project/typogrify/>`_ "
"library must be installed::"
msgstr ""
"Pelican还支持排版增强，若您需要使用，请先安装 `Typogrify "
"<https://pypi.org/project/typogrify/>`_ 库，稍后您可以在设置文件中启用它。"
#: ../../install.rst:56 d3ff6383ae9745bc9bfed85654086311
msgid "Dependencies"
msgstr "依赖"
#: ../../install.rst:58 2dc22a3fa6c242bdb5b61005e1910d79
msgid ""
"When Pelican is installed, the following dependent Python packages should"
" be automatically installed without any action on your part:"
msgstr ""
"当Pelican安装完成后，下面的所有Python依赖应该都会自动安装，"
"无需另外做任何操作："
#: ../../install.rst:61 4c7a644a29b540869d69acd10e032039
msgid ""
"`feedgenerator <https://pypi.org/project/feedgenerator/>`_, to generate "
"the Atom feeds"
msgstr ""
"`feedgenerator <https://pypi.org/project/feedgenerator/>`_，"
"用于生成Atom feeds"
#: ../../install.rst:63 365c8fb0938e4d9fbf78d110b05cb99f
msgid "`jinja2 <https://pypi.org/project/Jinja2/>`_, for templating support"
msgstr "`jinja2 <https://pypi.org/project/Jinja2/>`_，用于模板系统"
#: ../../install.rst:64 5db63207e60c4997924c3baf8aec8524
msgid "`pygments <https://pypi.org/project/Pygments/>`_, for syntax highlighting"
msgstr "`pygments <https://pypi.org/project/Pygments/>`_，用于语法高亮"
#: ../../install.rst:65 72bfb5fc2b514031a42952502746c100
msgid ""
"`docutils <https://pypi.org/project/docutils/>`_, for supporting "
"reStructuredText as an input format"
msgstr ""
"`docutils <https://pypi.org/project/docutils/>`_，"
"用于reStructuredText格式"
#: ../../install.rst:67 d00ac0c26d884a2d9d7f02fa89491892
msgid ""
"`blinker <https://pypi.org/project/blinker/>`_, an object-to-object and "
"broadcast signaling system"
msgstr ""
"`blinker <https://pypi.org/project/blinker/>`_，"
"对象-对象的信号广播系统"
#: ../../install.rst:69 0d317b007acf49fc879203fa8ffb4048
msgid ""
"`unidecode <https://pypi.org/project/Unidecode/>`_, for ASCII "
"transliterations of Unicode text utilities"
msgstr ""
"`unidecode <https://pypi.org/project/Unidecode/>`_，"
"用于将Unicode文本转为ASCII字符的音译"
#: ../../install.rst:72 ded0aae575854f149bcf2ea9efa4ba21
msgid ""
"`MarkupSafe <https://pypi.org/project/MarkupSafe/>`_, for a markup-safe "
"string implementation"
msgstr ""
"`MarkupSafe <https://pypi.org/project/MarkupSafe/>`_，"
"用于转义字符的安全处理"
#: ../../install.rst:74 eae7d8f6f84040339ccfef98e20502d8
msgid ""
"`python-dateutil <https://pypi.org/project/python-dateutil/>`_, to read "
"the date metadata"
msgstr ""
"`python-dateutil <https://pypi.org/project/python-dateutil/>`_，"
"用于读取日期相关的元数据"
#: ../../install.rst:78 cd33ec4583574c5bb879f08813b9932c
msgid "Upgrading"
msgstr "更新升级"
#: ../../install.rst:80 1513dd1e43564cb29da0a14988e0791d
msgid ""
"If you installed a stable Pelican release via Pip_ and wish to upgrade to"
" the latest stable release, you can do so by adding ``--upgrade``::"
msgstr ""
"若是通过 Pip_ 安装了稳定版本的Pelican，可以通过在安装命令中"
"添加 ``--upgrade`` 来升级到最新版："
#: ../../install.rst:85 fae6900b3acc41d4b7bb34c192fe4c08
msgid ""
"If you installed Pelican via distutils or the bleeding-edge method, "
"simply perform the same step to install the most recent version."
msgstr ""
"若是通过distutils安装或是通过Git安装了测试版的Pelican"
"重新进行一遍和安装时同样的步骤即可。"
#: ../../install.rst:89 89392d36f81f4c7eb75e9a74d1795faa
msgid "Kickstart your site"
msgstr "启动网站"
#: ../../install.rst:91 a8517a0fbbb1420297df214f50d8792d
msgid ""
"Once Pelican has been installed, you can create a skeleton project via "
"the ``pelican-quickstart`` command, which begins by asking some questions"
" about your site::"
msgstr ""
"Pelican安装完成后，通过 ``pelican-quickstart`` 命令创建项目的整体框架，"
"在运行这个命令时，您需要输入一些与站点相关的信息："
#: ../../install.rst:97 50231ba4b02d4e868995bdacbd02b27d
msgid ""
"If run inside an activated virtual environment, ``pelican-quickstart`` "
"will look for an associated project path inside "
"``$VIRTUAL_ENV/.project``. If that file exists and contains a valid "
"directory path, the new Pelican project will be saved at that location. "
"Otherwise, the default is the current working directory. To set the new "
"project path on initial invocation, use: ``pelican-quickstart --path "
"/your/desired/directory``"
msgstr ""
"如果是在虚拟环境中执行 ``pelican-quickstart`` ，系统会自动在 "
"``$VIRTUAL_ENV/.project`` 目录中查找这个命令。若这个这个命令存在"
"并且路径是正确的，一个新的Pelican项目就会在目标位置创建。否则，"
"会默认在当前的工作目录下创建这个项目。若要在初始化时指定项目路径，请使用 "
"``pelican-quickstart --path /your/desired/directory``。"
#: ../../install.rst:104 ea893addf15c47f182384509b1a3a2f7
msgid ""
"Once you finish answering all the questions, your project will consist of"
" the following hierarchy (except for *pages* — shown in parentheses below"
" — which you can optionally add yourself if you plan to create non-"
"chronological content)::"
msgstr ""
"当您回答完所有问题后，项目就会成功创建。项目中会包含下述的一些层级结构"
"（除了用括号括起来的 *pages*）。如果有一些内容不需要按时间排序，"
"您可以将它们放在（pages）所在的位置："
#: ../../install.rst:118 7d13a0cc5ebd44159fddc8de68993fc7
msgid ""
"The next step is to begin to adding content to the *content* folder that "
"has been created for you."
msgstr ""
"接下来就可以开始往 *content* 目录中添加自己创作的内容了。"

172
docs/locale/zh_CN/LC_MESSAGES/internals.po
View file

@ -1,172 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../internals.rst:2 5d90a7c7f9dd42b5ba1fdfc05c5e9c3c
msgid "Pelican internals"
msgstr "Pelican内部机制"
#: ../../internals.rst:4 fa53597118244e8585b3b0a9fb4336c0
msgid ""
"This section describe how Pelican works internally. As you'll see, it's "
"quite simple, but a bit of documentation doesn't hurt. :)"
msgstr ""
"这一节描述了Pelican的内部运行机制。你会发现，Pelican的内部其实并不复杂。 :)"
#: ../../internals.rst:7 c9a34db098f34796b80ee62896702be2
msgid ""
"You can also find in the :doc:`report` section an excerpt of a report the"
" original author wrote with some software design information."
msgstr "你可以在 :doc:`report` 一节中找到原作者用软件设计相关内容报告的节选。"
#: ../../internals.rst:13 ac2af84842574bef9a791b416e21834e
msgid "Overall structure"
msgstr "总体结构"
#: ../../internals.rst:15 fb7aea45b8f74c9c877bf2640d47aaac
msgid ""
"What Pelican does is take a list of files and process them into some sort"
" of output. Usually, the input files are reStructuredText and Markdown "
"files, and the output is a blog, but both input and output can be "
"anything you want."
msgstr ""
"Pelican做的事情其实很简单：获取一个文件列表，并将它们处理为某种输出。通常，输入文件是"
"reStructuredText和Markdown文件，输出是一个博客，但事实上输入和输出都可以是你想要的"
"任何内容。"
#: ../../internals.rst:19 599649d1e9da4355ab02b50ea4fbdb19
msgid "The logic is separated into different classes and concepts:"
msgstr "系统的整体逻辑可以分为几个不同的类和概念："
#: ../../internals.rst:21 8ec0821a726e4ade8046921cc09b3ea3
msgid ""
"**Writers** are responsible for writing files: .html files, RSS feeds, "
"and so on. Since those operations are commonly used, the object is "
"created once and then passed to the generators."
msgstr ""
"**Writers** 负责完成 html、RSS订阅源等等内容的文件写入。因为这些操作都是比较常用的，"
"这个类只会被创建一次，然后再传给Generators。"
#: ../../internals.rst:25 63c9a61869884147a8752e9be188e0e9
msgid ""
"**Readers** are used to read from various formats (HTML, Markdown and "
"reStructuredText for now, but the system is extensible). Given a file, "
"they return metadata (author, tags, category, etc.) and content (HTML-"
"formatted)."
msgstr ""
"**Readers** 用于读取不同格式的文件（目前支持HTML、Markdown、reStructuredText，"
"但可以继续扩展）。向**Readers**输入一个文件，它会返回文档的元数据（作者、标签、"
"分类等等）与HTML格式的文档正文内容。"
#: ../../internals.rst:29 d9bc146ae213415b804cd93ebf43e340
msgid ""
"**Generators** generate the different outputs. For instance, Pelican "
"comes with ``ArticlesGenerator`` and ``PageGenerator``. Given a "
"configuration, they can do whatever they want. Most of the time, it's "
"generating files from inputs."
msgstr ""
"**Generators** 用以生成不同的输出，Pelican自带了 ``ArticlesGenerator`` 和 "
"``PageGenerator`` 。给定一套配置信息， **Generators** 可以做几乎任何事。"
"但大多数情况下，它的工作就是从输入生成文件。"
#: ../../internals.rst:34 49ef39e8677a4529a3ee226faae1526b
msgid ""
"Pelican also uses templates, so it's easy to write your own theme. The "
"syntax is `Jinja2 <https://palletsprojects.com/p/jinja/>`_ and is very "
"easy to learn, so don't hesitate to jump in and build your own theme."
msgstr ""
"Pelican使用了模板引擎，因此可以较为简单地编写自定义主题。模板语法使用的是易于学习的 "
"`Jinja2 <https://palletsprojects.com/p/jinja/>`_ ，因此快去构建你自己的主题吧。"
#: ../../internals.rst:39 1aef766f93d549afa332fad4278c4063
msgid "How to implement a new reader?"
msgstr "如何实现一个新的reader？"
#: ../../internals.rst:41 abbbfc19ccea4e3ea3716179981e3c1d
msgid ""
"Is there an awesome markup language you want to add to Pelican? Well, the"
" only thing you have to do is to create a class with a ``read`` method "
"that returns HTML content and some metadata."
msgstr ""
"若是希望为Pelican添加一个标记语言，只需要创建一个类，实现 ``read`` 方法，并在其中"
"返回元数据和以HTML表示的正文内容。"
#: ../../internals.rst:45 1e9fc1bcc9444db4b751f1c621280a32
msgid "Take a look at the Markdown reader::"
msgstr "可以看一看Markdown的reader："
#: ../../internals.rst:71 cbc4f49384964be3a0a68b1083100839
msgid "Simple, isn't it?"
msgstr "是不是很简单呢？"
#: ../../internals.rst:73 02643c7e485d49e39344570ba5639a60
msgid ""
"If your new reader requires additional Python dependencies, then you "
"should wrap their ``import`` statements in a ``try...except`` block. "
"Then inside the reader's class, set the ``enabled`` class attribute to "
"mark import success or failure. This makes it possible for users to "
"continue using their favourite markup method without needing to install "
"modules for formats they don't use."
msgstr ""
"如果新创建的reader需要额外的Python依赖，应该把 ``import`` 放在 ``try...except`` "
"块中。在reader类中，设置类属性 ``enabled`` 来标记import是否成功。这使得用户能"
"继续使用他们喜欢的标记语言而无需安装用不到的模块。"
#: ../../internals.rst:80 02deeeac368b4dbc8c7b1025275d5bd5
msgid "How to implement a new generator?"
msgstr "如何实现一个新的generator？"
#: ../../internals.rst:82 f7e5c28efbdb40c0bac7b985e8264310
msgid ""
"Generators have two important methods. You're not forced to create both; "
"only the existing ones will be called."
msgstr ""
"generator有两个重要方法。不一定两个都要创建，若只创建了一个，就会自动调用存在的方法。"
#: ../../internals.rst:85 01f2801461e043e7882167907e337d2c
msgid ""
"``generate_context``, that is called first, for all the generators. Do "
"whatever you have to do, and update the global context if needed. This "
"context is shared between all generators, and will be passed to the "
"templates. For instance, the ``PageGenerator`` ``generate_context`` "
"method finds all the pages, transforms them into objects, and populates "
"the context with them. Be careful *not* to output anything using this "
"context at this stage, as it is likely to change by the effect of other "
"generators."
msgstr ""
"``generate_context`` 会优先被调用，其中可以完成任何你想要做的事，如果需要的话，还要"
"更新全局上下文。全局上下文会在所有generator间共享，并在之后传给模板。例如 "
"``PageGenerator`` 的 ``generate_context`` 方法会找寻所有页面，并将他们转换为对象，"
"再将上下文传入其中。注意，请 *不要* 在此阶段使用该上下文输出任何内容，因为其他"
"generator还会继续影响上下文。"
#: ../../internals.rst:93 3241d04af8944c48bf162963a774000c
msgid ""
"``generate_output`` is then called. And guess what is it made for? Oh, "
"generating the output. :) It's here that you may want to look at the "
"context and call the methods of the ``writer`` object that is passed as "
"the first argument of this function. In the ``PageGenerator`` example, "
"this method will look at all the pages recorded in the global context and"
" output a file on the disk (using the writer method ``write_file``) for "
"each page encountered."
msgstr ""
"``generate_output`` 会在 ``generate_context`` 之后被调用，用于生成要输出的内容。"
"此时就需要使用上下文并调用 ``writer`` 对象的方法，此 ``writer`` 就是传入 "
"``generate_output`` 方法的第一个参数。``PageGenerator`` 的 ``generate_output`` "
"方法中，会使用writer的 ``write_file`` 方法为全局上下文中的每一个页面输出一个文件。"

206
docs/locale/zh_CN/LC_MESSAGES/pelican-themes.po
View file

@ -1,206 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../pelican-themes.rst:2 1fce54d5389b41f4a588e9b23b646aee
msgid "pelican-themes"
msgstr "pelican-themes"
#: ../../pelican-themes.rst:7 6158b329ed7b469286405115e2ed7fa0
msgid "Description"
msgstr "简介"
#: ../../pelican-themes.rst:9 3df74d6d079945f7a4e0062ed5ea3eed
msgid ""
"``pelican-themes`` is a command line tool for managing themes for "
"Pelican. See :ref:`settings/themes` for settings related to themes."
msgstr ""
"``pelican-themes`` 是一个命令行工具，用于管理Pelican主题。有关主题的配置，"
"请参考 :ref:`设置章节中的主题 <settings/themes>` 。"
#: ../../pelican-themes.rst:14 03eb76faf4544c8dbf478752096c7d7c
msgid "Usage"
msgstr "用法"
#: ../../pelican-themes.rst:16 d5dcdc6c26094f5695061f9c53633589
msgid "pelican-themes [-h] [-l] [-i theme path [theme path ...]]"
msgstr "pelican-themes [-h] [-l] [-i theme path [theme path ...]]"
#: ../../pelican-themes.rst:17 99b7a21ca612425da217b72b8c0c9b64
msgid "[-r theme name [theme name ...]]"
msgstr "[-r theme name [theme name ...]]"
#: ../../pelican-themes.rst:18 1f64db909173426dabee822aea3b269b
msgid "[-s theme path [theme path ...]] [-v] [--version]"
msgstr "[-s theme path [theme path ...]] [-v] [--version]"
#: ../../pelican-themes.rst:21 63ef4d44a1db4176b4c3866671a93603
msgid "Optional arguments:"
msgstr "可选参数："
#: ../../pelican-themes.rst:24 348360945a0943ffa8122aad16bf0ec1
msgid "Show the help and exit"
msgstr "显示帮助信息并退出"
#: ../../pelican-themes.rst:26 aaec8d28264b45b7aac617b7140b5b13
msgid "Show the themes already installed"
msgstr "显示已安装的主题"
#: ../../pelican-themes.rst:28 c8d44b6ac6754f4e8e10a39848f042d0
msgid "One or more themes to install"
msgstr "安装一个或多个主题"
#: ../../pelican-themes.rst:30 18077fbf428e476aa218464fb0f18d8d
msgid "One or more themes to remove"
msgstr "移除一个或多个主题"
#: ../../pelican-themes.rst:32 e328d59886be45a6ae9530a0f2bea3ca
msgid ""
"Same as ``--install``, but create a symbolic link instead of copying the "
"theme. Useful for theme development"
msgstr ""
"和 ``--install`` 相同，区别在于此选项仅会创建一个符号链接到给定的目录，"
"而不会将主题完整拷贝。一般用于主题的开发"
#: ../../pelican-themes.rst:35 481c7a32a5e6400d83c9e2e56e6b94a4
msgid "Verbose output"
msgstr "开启详细输出"
#: ../../pelican-themes.rst:37 d7889dd20ac643ecad73e464ec4cfa55
msgid "Print the version of this script"
msgstr "显示此工具的版本信息"
#: ../../pelican-themes.rst:42 5c3d3aabd5304e8f9a6f0593824f1da6
msgid "Examples"
msgstr "例子"
#: ../../pelican-themes.rst:46 4d6ff63aae06482dbf22f41d4111b001
msgid "Listing the installed themes"
msgstr "列出已安装主题"
#: ../../pelican-themes.rst:48 91a9e942ea36479999586426afead753
msgid ""
"With ``pelican-themes``, you can see the available themes by using the "
"``-l`` or ``--list`` option:"
msgstr ""
"在 ``pelican-themes`` 中使用 ``-l`` 或 ``--list`` 选项，查看可用主题："
#: ../../pelican-themes.rst:62 7a2f7dc98fcc45cabc4639576d503c28
msgid ""
"In this example, we can see there are three themes available: "
"``notmyidea``, ``simple``, and ``two-column``."
msgstr ""
"在上面的例子中，可以看到有三个主题可供使用： ``notmyidea`` 、 "
"``simple`` 、和 ``two-column`` 。"
#: ../../pelican-themes.rst:65 8c03dfa908114d92b8a9aeb6673555ce
msgid ""
"``two-column`` is followed by an ``@`` because this theme is not copied "
"to the Pelican theme path, but is instead just linked to it (see "
"`Creating symbolic links`_ for details about creating symbolic links)."
msgstr ""
"主题 ``two-column`` 后有一个 ``@`` ，这是因为该主题没有被拷贝到Pelican的主题"
"路径下，而只是为其创建了一个符号链接 （详见 `创建符号链接`_ ）。"
#: ../../pelican-themes.rst:69 bc91e8c3ff4a44dd9234d0ab186d8515
msgid ""
"Note that you can combine the ``--list`` option with the ``-v`` or "
"``--verbose`` option to get more verbose output, like this:"
msgstr ""
"当然，你可以将 ``--list`` 选项和 ``-v`` 或 ``--verbose`` 结合起来，从而"
"得到更详细的输出："
#: ../../pelican-themes.rst:81 0b407ed71e6a4b428f5a582b58a47f3c
msgid "Installing themes"
msgstr "安装主题"
#: ../../pelican-themes.rst:83 e95f78a5c3b844b9a6fd2924f455748f
msgid ""
"You can install one or more themes using the ``-i`` or ``--install`` "
"option. This option takes as argument the path(s) of the theme(s) you "
"want to install, and can be combined with the ``--verbose`` option:"
msgstr ""
"使用 ``-i`` 或 ``--install`` 选项可以安装一个或多个主题。此选项将一个"
"或多个到达主题的路径作为参数，同样可以结合 ``--verbose`` 选项："
#: ../../pelican-themes.rst:103 5b20e90396564e08860b2b3a569e7166
msgid "Removing themes"
msgstr "移除主题"
#: ../../pelican-themes.rst:105 2415bf89e3804c9dbdc34814b0132b8c
msgid ""
"The ``pelican-themes`` command can also remove themes from the Pelican "
"themes path. The ``-r`` or ``--remove`` option takes as argument the "
"name(s) of the theme(s) you want to remove, and can be combined with the "
"``--verbose`` option."
msgstr ""
"``pelican-themes`` 命令同样可用于移除Pelican主题文件夹下的主题。 ``-r`` 或 "
"``--remove`` 选项以一个或多个主题的名称为参数，同样也可以结合 ``--verbose`` "
"选项使用。"
#: ../../pelican-themes.rst:122 9ea5149543a648049444220a4041da69
msgid "Creating symbolic links"
msgstr "创建符号链接"
#: ../../pelican-themes.rst:124 17cdf3146683485ea72db5fbd9c1f60a
msgid ""
"``pelican-themes`` can also install themes by creating symbolic links "
"instead of copying entire themes into the Pelican themes path."
msgstr ""
"``pelican-themes`` 也可以通过创建符号链接来安装主题，如此便无需完整拷贝主题。"
#: ../../pelican-themes.rst:127 1d2c60b41c374936a9986a852d50e898
msgid ""
"To symbolically link a theme, you can use the ``-s`` or ``--symlink``, "
"which works exactly as the ``--install`` option:"
msgstr ""
"使用 ``-s`` 或 ``--symlink`` 选项来为主题创建符号链接，用法和 ``--install`` 选项相同："
#: ../../pelican-themes.rst:134 66707a8607f549199dca6f93586d2d87
msgid ""
"In this example, the ``two-column`` theme is now symbolically linked to "
"the Pelican themes path, so we can use it, but we can also modify it "
"without having to reinstall it after each modification."
msgstr ""
"在上面的例子中， ``two-column`` 主题就已经在Pelican主题目录下创建了符号链接，"
"也可以正常使用。如此，当我们修改主题后就无需重新进行安装。"
#: ../../pelican-themes.rst:138 93ec27a473b04bca9d2930a7cb6b609c
msgid "This is useful for theme development:"
msgstr "这对主题的开发是很有用的："
#: ../../pelican-themes.rst:155 66d808308aa64fc9afcef8bdf03bca8b
msgid "Doing several things at once"
msgstr "同时执行多个操作"
#: ../../pelican-themes.rst:157 ace10a2c2f4d4adab9ade60631e82c38
msgid ""
"The ``--install``, ``--remove`` and ``--symlink`` options are not "
"mutually exclusive, so you can combine them in the same command line to "
"do more than one operation at time, like this:"
msgstr ""
"``--install`` 、 ``--remove`` 和 ``--symlink`` 可以同时使用，不会冲突，"
"因此可以在同一行命令中同时做多个操作："
#: ../../pelican-themes.rst:169 e7adbac04b6a40fd986c02e834cc1756
msgid ""
"In this example, the theme ``notmyidea-cms`` is replaced by the theme "
"``notmyidea-cms-fr``"
msgstr ""
"在上面的例子中，用 ``notmyidea-cms-fr`` 替换了 ``notmyidea-cms`` 主题。"

711
docs/locale/zh_CN/LC_MESSAGES/plugins.po
View file

@ -1,711 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-26 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../plugins.rst:4 b1b40bca7d3748008eefe26806d5d5ef
msgid "Plugins"
msgstr "插件"
#: ../../plugins.rst:6 42ca486828e4442a9d74216d0d8bb37d
msgid ""
"Beginning with version 3.0, Pelican supports plugins. Plugins are a way "
"to add features to Pelican without having to directly modify the Pelican "
"core."
msgstr ""
"Pelican从3.0版本开始支持插件。通过插件，不必直接修改Pelican的核心代码就可以给"
"Pelican添加新功能。"
#: ../../plugins.rst:10 6bb8ab4cb7eb44ddb1ed4734f47f6781
msgid "How to use plugins"
msgstr "如何使用插件"
#: ../../plugins.rst:12 822e0bd7ce2f4433a7c39b3accde01a1
msgid ""
"Starting with version 4.5, Pelican moved to a new plugin structure "
"utilizing namespace packages that can be easily installed via Pip_. "
"Plugins supporting this structure will install under the namespace "
"package ``pelican.plugins`` and can be automatically discovered by "
"Pelican. To see a list of Pip-installed namespace plugins that are active"
" in your environment, run::"
msgstr ""
"Pelican从4.5版本开始使用了一种全新的插件结构，利用了命名空间包，"
"并且可以轻松地通过 Pip_ 进行安装。支持此结构地插件都会被安装在命名空间包 "
"``pelican.plugins`` 下，因此Pelican可以自动发现他们。下面的命令可以用于"
"查看环境中用Pip安装的所有插件："
#: ../../plugins.rst:20 2b59c5d107dc4b118dc76116910e9495
msgid ""
"If you leave the ``PLUGINS`` setting as default (``None``), Pelican will "
"automatically discover namespace plugins and register them. If, on the "
"other hand, you specify a ``PLUGINS`` setting as a list of plugins, this "
"auto-discovery will be disabled. At that point, only the plugins you "
"specify will be registered, and you must explicitly list any namespace "
"plugins as well."
msgstr ""
"若将 ``PLUGINS`` 配置项设为默认的 ``None`` ，Pelican会自动发现命名空间中的"
"插件并且将他们全部加载；若你在 ``PLUGINS`` 设置项中指定了一系列的插件，"
"Pelican就不会去自动发现插件，也就是说，你需要显式地指定所有要使用的插件。"
#: ../../plugins.rst:26 52d1968196294569a478931f7022e686
msgid ""
"If you are using the ``PLUGINS`` setting, you can specify plugins in two "
"ways. The first method specifies plugins as a list of strings. Namespace "
"plugins can be specified either by their full names "
"(``pelican.plugins.myplugin``) or by their short names (``myplugin``)::"
msgstr ""
"在配置 ``PLUGINS`` 时，有两种方式。一是用字符串列表指定插件的名称，可以是包含"
"命名空间的完整名称（例如 ``pelican.plugins.myplugin`` ），也可以是简短名称"
"（ ``myplugin``）："
#: ../../plugins.rst:35 b2c75e52e66e4000968e744ffa4b89a9
msgid ""
"Alternatively, you can import them in your settings file and pass the "
"modules::"
msgstr ""
"二是在设置文件中先import进来，再将import进的模块放在 ``PLUGINS`` 设置项中："
#: ../../plugins.rst:43 88af9139373f4cd89fa5b958196c9448
msgid ""
"When experimenting with different plugins (especially the ones that deal "
"with metadata and content) caching may interfere and the changes may not "
"be visible. In such cases disable caching with ``LOAD_CONTENT_CACHE = "
"False`` or use the ``--ignore-cache`` command-line switch."
msgstr ""
"在尝试不同的插件时（尤其是那些处理元数据和内容的插件），缓存可能会相互干扰，"
"一些更改不会生效。发生这种情况时，就需要通过设置 ``LOAD_CONTENT_CACHE = False`` "
"或使用 ``--ignore-cache`` 命令行选项禁用缓存。"
#: ../../plugins.rst:48 d0e3cd59052c4a7d995fb5e1e15d9799
msgid ""
"If your plugins are not in an importable path, you can specify a list of "
"paths via the ``PLUGIN_PATHS`` setting. As shown in the following "
"example, paths in the ``PLUGIN_PATHS`` list can be absolute or relative "
"to the settings file::"
msgstr ""
"如果插件处于无法直接进行import的路径，可以在 ``PLUGIN_PATHS`` 配置项中指定这些路径。"
"如下例所示， ``PLUGIN_PATHS`` 中的路径可以是绝对的，也可以是相对于设置文件的："
#: ../../plugins.rst:56 4c3de952a8514e5caea402392b911f0b
msgid "Where to find plugins"
msgstr "在哪儿下载插件"
#: ../../plugins.rst:57 16173c9dceb0409f89964412dd7e71e9
msgid ""
"Namespace plugins can be found in the `pelican-plugins organization`_ as "
"individual repositories. Legacy plugins are located in the `pelican-"
"plugins repository`_ and will be gradually phased out in favor of the "
"namespace versions."
msgstr ""
"新的命名空间插件可以在GitHub的 `pelican-plugins 组织`_ 中找到，每个插件都是"
"一个独立的仓库。而老的插件则可以在GitHub的 `pelican-plugins 仓库`_ 中找到。"
"这些老的插件会逐步淘汰并转移到新的命名空间版本。"
#: ../../plugins.rst:65 a30a9862112b47128f6e7b28c6836f27
msgid ""
"Please note that while we do our best to review and maintain these "
"plugins, they are submitted by the Pelican community and thus may have "
"varying levels of support and interoperability."
msgstr ""
"请注意，尽管我们尽全力审查和维护这些插件，但这些插件是Pelican社区提交的，"
"因此支持性和互操作性程度各不相同。"
#: ../../plugins.rst:70 f4e140c61c0f45ed8ac53dca3b05b1f1
msgid "How to create plugins"
msgstr "如何创建插件"
#: ../../plugins.rst:72 43013c6cf4f34ca09205e8dab0b9fa6d
msgid ""
"Plugins are based on the concept of signals. Pelican sends signals, and "
"plugins subscribe to those signals. The list of available signals is "
"documented in a subsequent section."
msgstr ""
"插件是基于信号这一概念的。Pelican会发送信号，插件则订阅这些信号。可用的信号"
"在下一节会贴出来。"
#: ../../plugins.rst:76 5377a966ab114a29acb61f79eadc632b
msgid ""
"The only rule to follow for plugins is to define a ``register`` callable,"
" in which you map the signals to your plugin logic. Let's take a simple "
"example::"
msgstr ""
"对于插件来说，唯一需要遵循的规则就是一定要定义一个可调用的 ``register`` ，"
"在 ``register`` 中需要将信号映射到插件逻辑上。下面是一个简单的例子："
#: ../../plugins.rst:93 2217318326524c62804ec94e55a4ca20
msgid ""
"Signal receivers are weakly-referenced and thus must not be defined "
"within your ``register`` callable or they will be garbage-collected "
"before the signal is emitted."
msgstr ""
"信号接收器在Pelican中是弱引用的，因此不能将它定义在可调用的 ``register`` 中，"
"否则接收器在信号发送之前就会被回收。"
#: ../../plugins.rst:97 6731cc78478a46c5a0cb51a8cd477318
msgid ""
"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."
msgstr ""
"如果多个插件关联到同一个信号，插件将按照它们关联的前后顺序执行。但若设置了 "
"``PLUGINS`` 配置项会以此配置项中的顺序为准。如果您使用了无需PLUGINS设置的新版"
"命名空间插件，它们将按照被探测到的顺序进行连接（与 pelican-plugins 输出的顺序相同）。"
#: ../../plugins.rst:105 6dad534cc0014b78a3638a91cc4a1120
msgid "Namespace plugin structure"
msgstr "命名空间插件的结构"
#: ../../plugins.rst:107 aa6f290c3f4d42558b684d0e3487af95
msgid ""
"Namespace plugins must adhere to a certain structure in order to function"
" properly. They need to be installable (i.e. contain ``setup.py`` or "
"equivalent) and have a folder structure as follows::"
msgstr ""
"命名空间插件必须遵循特定的结构才能正常工作。这些插件需要是可安装的"
"（即包含 ``setup.py`` 或其他等效文件），并且遵循下述文件夹结构："
#: ../../plugins.rst:120 b8d73cfdb5f042cca1705f97d693263d
msgid ""
"It is crucial that ``pelican`` or ``pelican/plugins`` folder **not** "
"contain an ``__init__.py`` file. In fact, it is best to have those "
"folders empty besides the listed folders in the above structure and keep "
"your plugin related files contained solely in the "
"``pelican/plugins/myplugin`` folder to avoid any issues."
msgstr ""
"非常关键的一点就是， ``pelican`` 和 ``pelican/plugins`` 文件夹下都 **不能** 包含 "
"``__init__.py`` 文件。事实上，这两个文件夹下最好是只有上面列出的文件夹，"
"并且保证与插件相关的文件都仅包含在 ``pelican/plugins/myplugin`` 文件夹中，"
"以避免奇奇怪怪的问题。"
#: ../../plugins.rst:126 c3f08ae8c0d7415098157bbd1c99ce08
msgid ""
"To easily set up the proper structure, a `cookiecutter template for "
"plugins`_ is provided. Refer to that project's README for instructions on"
" how to use it."
msgstr ""
"为了让大家更容易就能建立正确的结构，我们为插件提供了一个 `cookiecutter模板`_ ，"
"使用方法参考此项目README文件中的指示即可。"
#: ../../plugins.rst:132 c2321eec3dc84224918172c5040a259f
msgid "List of signals"
msgstr "信号列表"
#: ../../plugins.rst:134 78c4cfefae7e412f8f6287da2e3c8d34
msgid "Here is the list of currently implemented signals:"
msgstr "下面是目前已经实现了的信号："
#: ../../plugins.rst:137 7a3c3b8b0f114d54b497ab77b09dc558
msgid "Signal"
msgstr "信号"
#: ../../plugins.rst:137 781b5c11f87f43b9ba4b3e75bee696d0
msgid "Arguments"
msgstr "参数"
#: ../../plugins.rst:137 df7d14950fed44f4a4b93908aed36060
msgid "Description"
msgstr "描述"
#: ../../plugins.rst:139 598901e7cb5b49ac9acb5f148bf7c0e7
msgid "initialized"
msgstr "initialized"
#: ../../plugins.rst:139 ../../plugins.rst:140 ../../plugins.rst:158
#: ../../plugins.rst:161 4cedbf9ee7fb4c7abe20e15e4ee1c7fb
#: 704ff7e1ddfc4eb3bd7798d25df1e668 bc98001ef73d419b8f811bbb3d3a571a
#: c9104ccaf84c48d98fafca001ec187e2
msgid "pelican object"
msgstr "pelican object"
#: ../../plugins.rst:140 6f1a09178e2c44c9bda76ed0c0025bef
msgid "finalized"
msgstr "finalized"
#: ../../plugins.rst:140 175a1d1ab8374325812a00cfd581e54e
msgid ""
"invoked after all the generators are executed and just before pelican "
"exits useful for custom post processing actions, such as: - minifying "
"js/css assets. - notify/ping search engines with an updated sitemap."
msgstr ""
"所有generator执行完成后调用，即pelican退出之前。这对于自定义后处理操作是"
"非常有用的，例如可以简化js/css资源、向搜索引擎告知更新后的sitemap。"
#: ../../plugins.rst:144 8d390b6db281423d92a4d7bd4921b4b4
msgid "generator_init"
msgstr "generator_init"
#: ../../plugins.rst:144 fef4d6e70a4c4365be408a5f1579135c
msgid "generator"
msgstr "generator"
#: ../../plugins.rst:144 dbe5ff1590dc4df38cb8fd234708c7bd
msgid "invoked in the Generator.__init__"
msgstr "在Generator.__init__中调用"
#: ../../plugins.rst:145 0324812d14d9452fbf28c286c2a10834
msgid "all_generators_finalized"
msgstr "all_generators_finalized"
#: ../../plugins.rst:145 f6170ebf34b247868d149f0efca462b3
msgid "generators"
msgstr "generators"
#: ../../plugins.rst:145 d67dff93c28146498074abbf3aeb5103
msgid "invoked after all the generators are executed and before writing output"
msgstr "在所有generator执行完后，写入输出内容前调用，"
#: ../../plugins.rst:146 0e9feed7804b4bbdb23711f9d6ad4f40
msgid "readers_init"
msgstr "readers_init"
#: ../../plugins.rst:146 f0de00423c104ecd8e60fb3450b534b4
msgid "readers"
msgstr "readers"
#: ../../plugins.rst:146 b554b35806e34e51bc5ab974fb517541
msgid "invoked in the Readers.__init__"
msgstr "在Readers.__init__中调用"
#: ../../plugins.rst:147 ../../plugins.rst:201 003cdeb23b67433e8cf70c600a42e8e4
#: 7f4a2f6665064a16bcd1b7ea347f5b49
msgid "article_generator_context"
msgstr "article_generator_context"
#: ../../plugins.rst:147 8997b3fd1a8d4efb86245916e50c31b9
msgid "article_generator, metadata"
msgstr "article_generator, metadata"
#: ../../plugins.rst:148 ../../plugins.rst:203 4496df152e48410995ae35f73e3ce0e9
#: f46672e3f919441ba2486f9641752913
msgid "article_generator_preread"
msgstr "article_generator_preread"
#: ../../plugins.rst:148 ../../plugins.rst:150 ../../plugins.rst:151
#: ../../plugins.rst:154 3408ba823f14463196f2296480e25c7d
#: 43b073d3f3ad4a2ba3d0c18447cb7cf6 c776a7323f0a41babb44daf3abfd6b85
#: f47ca0a3f9654ed4b7653fd946b2d9b6
msgid "article_generator"
msgstr "article_generator"
#: ../../plugins.rst:148 94e2a57c5b074d068f051d5de850060c
msgid ""
"invoked before a article is read in ArticlesGenerator.generate_context; "
"use if code needs to do something before every article is parsed"
msgstr ""
"在ArticlesGenerator.generate_context读取文章之前调用；若代码需要在解析每篇文章前"
"执行某些操作，就可以使用此信号。"
#: ../../plugins.rst:150 c58f32123f234e6cafa42aa4ede5bf73
msgid "article_generator_init"
msgstr "article_generator_init"
#: ../../plugins.rst:150 10d3585dc8f94d978643a9c2dc9219a9
msgid "invoked in the ArticlesGenerator.__init__"
msgstr "在ArticlesGenerator.__init__中调用"
#: ../../plugins.rst:151 93ec423e266b4ba9b941a5826e290fec
msgid "article_generator_pretaxonomy"
msgstr "article_generator_pretaxonomy"
#: ../../plugins.rst:151 27290d55819e4bfabe1624059956258f
msgid ""
"invoked before categories and tags lists are created useful when e.g. "
"modifying the list of articles to be generated so that removed articles "
"are not leaked in categories or tags"
msgstr ""
"在创建类别和标签列表之前调用。例如，当需要变更要生成的文章列表时可以使用，"
"如此可以避免一些已移除文章在分类或标签列表中泄露。"
#: ../../plugins.rst:154 ../../plugins.rst:202 12c99acda2ac45debe4fc574a246fc63
#: f3bfb220e59d473bb27601c16f5a1625
msgid "article_generator_finalized"
msgstr "article_generator_finalized"
#: ../../plugins.rst:154 4cb8ed5b4701426b8e1707c6c6b0d48f
msgid "invoked at the end of ArticlesGenerator.generate_context"
msgstr "在ArticlesGenerator.generate_context的最后调用"
#: ../../plugins.rst:155 c19a632018d44ad2b72d5cf6b7cc9c14
msgid "article_generator_write_article"
msgstr "article_generator_write_article"
#: ../../plugins.rst:155 9da20e77d40b45e292ae994fb0fbe97c
msgid "article_generator, content"
msgstr "article_generator, content"
#: ../../plugins.rst:155 a2d5bc3f72b64e47bcaccff3bf27dec2
msgid "invoked before writing each article, the article is passed as content"
msgstr "在写入每篇文章前调用，文章以内容的形式作为参数传入。"
#: ../../plugins.rst:156 0db965f5b99f49e48fc1db531c139f13
msgid "article_writer_finalized"
msgstr "article_writer_finalized"
#: ../../plugins.rst:156 c6af98478be14eb283bb95e7b6a3118c
msgid "article_generator, writer"
msgstr "article_generator, writer"
#: ../../plugins.rst:156 c48e1152864c4249886f3c7ed4ece85b
msgid ""
"invoked after all articles and related pages have been written, but "
"before the article generator is closed."
msgstr ""
"在所有文章及相关联页面写入完成后，在文章generator关闭前调用。"
#: ../../plugins.rst:158 f6af27fc844d43779d581cb4383b97ed
msgid "get_generators"
msgstr "get_generators"
#: ../../plugins.rst:158 b41e27f19c47478a8ece4f43a685f6be
msgid ""
"invoked in Pelican.get_generator_classes, can return a Generator, or "
"several generators in a tuple or in a list."
msgstr ""
"在Pelican.get_generator_classes中调用，可以返回一个Generator，也可以以一个"
"元组或列表的形式返回多个generator。"
#: ../../plugins.rst:161 f23075094c4f46958de609a44850eb6d
msgid "get_writer"
msgstr "get_writer"
#: ../../plugins.rst:161 365671a73e17434f90973ee8e632fa32
msgid "invoked in Pelican.get_writer, can return a custom Writer."
msgstr "在Pelican.get_writer前调用，可以返回一个自定义Writer。"
#: ../../plugins.rst:163 ../../plugins.rst:204 299eef53e530489a9e7366042919059f
#: 917cc78965d84285bc832cecf181ce55
msgid "page_generator_context"
msgstr "page_generator_context"
#: ../../plugins.rst:163 26f64e1dbe854ca287aa0f59b269477c
msgid "page_generator, metadata"
msgstr "page_generator, metadata"
#: ../../plugins.rst:164 ../../plugins.rst:205 c2ec4e60dda142569cdcfe5a311b21a5
#: fcd417f63054406ea7869a2a945dc819
msgid "page_generator_preread"
msgstr "page_generator_preread"
#: ../../plugins.rst:164 ../../plugins.rst:166 ../../plugins.rst:167
#: 89c2d7a279604926a290c2665fe8082a 98ab9a5bc2804442a217233f4ab8a003
#: fca779509f1742e99e3d10a6602561c9
msgid "page_generator"
msgstr "page_generator"
#: ../../plugins.rst:164 295fe11e61ba4f80a145ce06a1ffc777
msgid ""
"invoked before a page is read in PageGenerator.generate_context; use if "
"code needs to do something before every page is parsed."
msgstr ""
"在PageGenerator.generate_context读取页面前调用，若代码需要在解析每个页面前"
"执行某些操作，就可以使用此信号。"
#: ../../plugins.rst:166 ../../plugins.rst:207 4f2b1db9b6054af2b0fd0545082bcafd
#: db8ee3e356d84758b427d9f29d034000
msgid "page_generator_init"
msgstr "page_generator_init"
#: ../../plugins.rst:166 1d4e2e940e0f4dd5a151519aea710454
msgid "invoked in the PagesGenerator.__init__"
msgstr "在PagesGenerator.__init__中调用"
#: ../../plugins.rst:167 ../../plugins.rst:206 319e921c48474a43bbdac4bf43a688f2
#: 5e9b33a48c51417fb5211824b0ad008d
msgid "page_generator_finalized"
msgstr "page_generator_finalized"
#: ../../plugins.rst:167 019fa3fddf2e4725b978326f221c80bd
msgid "invoked at the end of PagesGenerator.generate_context"
msgstr "在PagesGenerator.generate_context的最后调用"
#: ../../plugins.rst:168 0f77c3c609594768a0aaed6529260b97
msgid "page_generator_write_page"
msgstr "page_generator_write_page"
#: ../../plugins.rst:168 0ca5fb200a254cff8529cb5d95e8e26e
msgid "page_generator, content"
msgstr "page_generator, content"
#: ../../plugins.rst:168 164d45dac5ab4df8abd898c1466e186d
msgid "invoked before writing each page, the page is passed as content"
msgstr "在写入每个页面前调用，页面以内容形式作为参数传入"
#: ../../plugins.rst:169 4780473ba6ae47998f891232f122b34a
msgid "page_writer_finalized"
msgstr "page_writer_finalized"
#: ../../plugins.rst:169 6c516a5ae777406ca9ed7bf27b7124c7
msgid "page_generator, writer"
msgstr "page_generator, writer"
#: ../../plugins.rst:169 e8978d0fb878427cbf686608c593aa67
msgid ""
"invoked after all pages have been written, but before the page generator "
"is closed."
msgstr "调用于所有页面写入完成后，在页面generator关闭前。"
#: ../../plugins.rst:171 ../../plugins.rst:208 47bf9969c38b4fef9e15e9d7ea67630e
#: d9a3d5d939d4499b9320ea15dbd3f26e
msgid "static_generator_context"
msgstr "static_generator_context"
#: ../../plugins.rst:171 47064012c4e447f5a1f087a7af420f8f
msgid "static_generator, metadata"
msgstr "static_generator, metadata"
#: ../../plugins.rst:172 ../../plugins.rst:209 7050e1889934465a8837ba65fa249118
#: f45c31c591fd450badd89a7f87c6f991
msgid "static_generator_preread"
msgstr "static_generator_preread"
#: ../../plugins.rst:172 ../../plugins.rst:175 ../../plugins.rst:176
#: 1e99fc14855a4a2e8d1f4758e12792d9 45cdf5c2a8d049889b4315d1ea78f462
#: b7ae37b94f2f44feb24ac32b0cdfa447
msgid "static_generator"
msgstr "static_generator"
#: ../../plugins.rst:172 431017db31bf439f8d3fb5e16b020376
msgid ""
"invoked before a static file is read in StaticGenerator.generate_context;"
" use if code needs to do something before every static file is added to "
"the staticfiles list."
msgstr ""
"在StaticGenerator.generate_context读取静态文件前调用，若代码需要在每个静态文件"
"加入静态文件列表前进行一些修改，就可以使用此信号。"
#: ../../plugins.rst:175 2a380c26f2984e659ec36248a543a4c3
msgid "static_generator_init"
msgstr "static_generator_init"
#: ../../plugins.rst:175 832447303775460c83743d831aa58290
msgid "invoked in the StaticGenerator.__init__"
msgstr "在StaticGenerator.__init__中调用"
#: ../../plugins.rst:176 b01307445d54485a9036fb0f9619ff78
msgid "static_generator_finalized"
msgstr "static_generator_finalized"
#: ../../plugins.rst:176 2f7e7e25668b44fc824bb39270c3de96
msgid "invoked at the end of StaticGenerator.generate_context"
msgstr "在StaticGenerator.generate_context的最后调用"
#: ../../plugins.rst:177 2a34785767ee416dbe41a6aa1f7e4ab1
msgid "content_object_init"
msgstr "content_object_init"
#: ../../plugins.rst:177 c41d8a8653a94d648b573b5c13db3954
msgid "content_object"
msgstr "content_object"
#: ../../plugins.rst:177 379b6d76d2f14d05bf1502d2c55b125f
msgid "invoked at the end of Content.__init__"
msgstr "在Content.__init__的最后调用"
#: ../../plugins.rst:178 10761aa6a1d54ee0a28e562bdacffebf
msgid "content_written"
msgstr "content_written"
#: ../../plugins.rst:178 001ad90e09ab4b21a702b2ed9771a156
msgid "path, context"
msgstr "path, context"
#: ../../plugins.rst:178 69b05b02e1564fe4b48dbd2926fdaec3
msgid "invoked each time a content file is written."
msgstr "每一次内容文件写入后调用。"
#: ../../plugins.rst:179 30938518f54f46028c8fd03808471be7
msgid "feed_generated"
msgstr "feed_generated"
#: ../../plugins.rst:179 e29bf37e7114454099baa21955b7fce0
msgid "context, feed"
msgstr "context, feed"
#: ../../plugins.rst:179 366ba164593242309dab922c36667dc3
msgid ""
"invoked each time a feed gets generated. Can be used to modify a feed "
"object before it gets written."
msgstr "每个feed生成前调用。可以用于在feed写入前修改之。"
#: ../../plugins.rst:181 0b6d7fc85d374b9c82c60d4a0df69fcd
msgid "feed_written"
msgstr "feed_written"
#: ../../plugins.rst:181 d3fdc3a669e9418b9f6e738c549fa151
msgid "path, context, feed"
msgstr "path, context, feed"
#: ../../plugins.rst:181 3da952e464034f8c8491caa94f0aec2d
msgid "invoked each time a feed file is written."
msgstr "每一个feed文件写入后调用。"
#: ../../plugins.rst:186 24bf768827184a8a9c2ad9d23d3549e4
msgid ""
"Avoid ``content_object_init`` signal if you intend to read ``summary`` or"
" ``content`` properties of the content object. That combination can "
"result in unresolved links when :ref:`ref-linking-to-internal-content` "
"(see `pelican-plugins bug #314`_). Use ``_summary`` and ``_content`` "
"properties instead, or, alternatively, run your plugin at a later stage "
"(e.g. ``all_generators_finalized``)."
msgstr ""
"请避免使用 ``content_object_init`` 信号读取content对象的 ``summary`` 或 "
"``content`` 属性，这可能导致在 :ref:`ref-linking-to-internal-content` 时无法"
"解析链接（请参阅 `pelican-plugins bug #314`_ ）。请改用 ``_summary`` 和 "
"``_content`` 属性，或者就在后续阶段再运行插件（例如 ``all_generators_finalized`` 时）。"
#: ../../plugins.rst:195 9222300d10c74a9eb27fc229488e63a4
msgid ""
"After Pelican 3.2, signal names were standardized. Older plugins may "
"need to be updated to use the new names:"
msgstr ""
"Pelican3.2之后，信号名都进行了标准化，较老的插件可能需要进行更新："
#: ../../plugins.rst:199 2ba779a696064672965e17c70f70d927
msgid "Old name"
msgstr "旧名称"
#: ../../plugins.rst:199 d21e933be9064983aa2cfaeca4f00cb9
msgid "New name"
msgstr "新名称"
#: ../../plugins.rst:201 805ac7c62fc94113a3481890793f5417
msgid "article_generate_context"
msgstr "article_generate_context"
#: ../../plugins.rst:202 d6f1a03ae49349b091045c8079b80d44
msgid "article_generate_finalized"
msgstr "article_generate_finalized"
#: ../../plugins.rst:203 c967c8322a744c2c970beb6b98b90743
msgid "article_generate_preread"
msgstr "article_generate_preread"
#: ../../plugins.rst:204 71adeb83fba74317ad0fac5784612a3d
msgid "pages_generate_context"
msgstr "pages_generate_context"
#: ../../plugins.rst:205 d2297a5ec351411e8a66a74d8168caa0
msgid "pages_generate_preread"
msgstr "pages_generate_preread"
#: ../../plugins.rst:206 fb572935b7f445d298ff2c9c89c59c4e
msgid "pages_generator_finalized"
msgstr "pages_generator_finalized"
#: ../../plugins.rst:207 0bb615d8a6f643a3a1a9abac2ec4f712
msgid "pages_generator_init"
msgstr "pages_generator_init"
#: ../../plugins.rst:208 beddb5f81a62458b87c0703355a7b5a4
msgid "static_generate_context"
msgstr "static_generate_context"
#: ../../plugins.rst:209 8fe8895dcb464e11bb01657e975f1352
msgid "static_generate_preread"
msgstr "static_generate_preread"
#: ../../plugins.rst:213 44b14caddfd245c18cacd755fd0023e9
msgid "Recipes"
msgstr "具体使用方法举例"
#: ../../plugins.rst:215 c24473f41cc84d028c99fa56af636037
msgid ""
"We eventually realised some of the recipes to create plugins would be "
"best shared in the documentation somewhere, so here they are!"
msgstr ""
"下面分享了一些创建插件的具体方法，请享用！"
#: ../../plugins.rst:219 96de26e8150e4339b3461d2dcc478cf3
msgid "How to create a new reader"
msgstr "如何创建一个新的reader"
#: ../../plugins.rst:221 3f26c1183b814401b333bbd8528675d9
msgid ""
"One thing you might want is to add support for your very own input "
"format. While it might make sense to add this feature in Pelican core, we"
" wisely chose to avoid this situation and instead have the different "
"readers defined via plugins."
msgstr ""
"你可能需要添加对输入文件格式的特殊支持。这似乎可以作为Pelican核心的一个功能，"
"但我们选择避免将此功能放在核心中，而是通过插件实现不同的reader。"
#: ../../plugins.rst:226 8167dcbaa6864da3b2262a2a99e08a15
msgid ""
"The rationale behind this choice is mainly that plugins are really easy "
"to write and don't slow down Pelican itself when they're not active."
msgstr ""
"做出这个决定主要是因为实现这样的格式支持插件非常容易，而且这样在不需要此功能时"
"也不会影响Pelican自身的速度。"
#: ../../plugins.rst:229 26c8185062964b52921860cfa2ce508c
msgid "No more talking — here is an example::"
msgstr "多说无益，下面是一个具体例子："
#: ../../plugins.rst:265 ea51efb1925f45e79c87d6e5488cbbcd
msgid "Adding a new generator"
msgstr "添加新的generator"
#: ../../plugins.rst:267 9e04f17a5fa1488d82d3629edf8cdf3f
msgid ""
"Adding a new generator is also really easy. You might want to have a look"
" at :doc:`internals` for more information on how to create your own "
"generator."
msgstr ""
"添加一个generator也非常简单，你可能会想要看一看 :doc:`internals` ，其中有关于"
"如何创建generator的内容。"
#: ../../plugins.rst:281 f4c92958e88a41a7a0deee697b48fc58
msgid "Adding a new writer"
msgstr "添加新的writer"
#: ../../plugins.rst:283 188bf0e8a68446458ae525c67cfe098c
msgid ""
"Adding a writer will allow you to output additional file formats to disk,"
" or change how the existing formats are written to disk. Note that only "
"one writer will be active at a time, so be sure to either subclass the "
"built-in Writer, or completely re-implement it."
msgstr ""
"添加writer可以让你将其他文件格式输出到磁盘，或者可以改变现有格式写入磁盘的方式。"
"请注意，一次只能启用一个writer，因此请确保继承了内置的Writer，并且完全重新实现之。"
#: ../../plugins.rst:288 edb5d1fa15bc48859c2912ba7c344286
msgid "Here is a basic example of how to set up your own writer::"
msgstr "下面是启用你的自定义writer的一个基本例子："
#: ../../plugins.rst:308 0df8f3318357472cbd72e17e1b5085b2
msgid "Using Plugins to Inject Content"
msgstr "使用插件添加内容"
#: ../../plugins.rst:310 d0161dbe86c44111a6295259ec8cab54
msgid ""
"You can programmatically inject articles or pages using plugins. This can"
" be useful if you plan to fetch articles from an API, for example."
msgstr ""
"可以通过插件以可编程的方式添加文章或页面。如果你打算从某些API获取文章，这就会很有用。"
#: ../../plugins.rst:313 5d5c41dbeb7243d4b497752771bc7858
msgid ""
"Following is a simple example of how one can build a plugin that injects "
"a custom article, using the ``article_generator_pretaxonomy`` signal::"
msgstr ""
"下面是一个简单的示例，说明了如何使用 ``article_generator_pretaxonomy`` "
"信号构建一个添加自定义文章的插件："

329
docs/locale/zh_CN/LC_MESSAGES/publish.po
View file

@ -1,329 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-25 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../publish.rst:2 65617cfb871b492589d55186b708a1ce
msgid "Publish your site"
msgstr "发布站点"
#: ../../publish.rst:7 dc4c9b1c1afd477d906b892dc592bdcd
msgid "Site generation"
msgstr "站点生成"
#: ../../publish.rst:9 610c37360e2b49ec8ea630ddc224d2b7
msgid ""
"Once Pelican is installed and you have some content (e.g., in Markdown or"
" reST format), you can convert your content into HTML via the ``pelican``"
" command, specifying the path to your content and (optionally) the path "
"to your :doc:`settings<settings>` file::"
msgstr ""
"您应该已经安装好Pelican并且已经创作了一些内容了吧（以Markdown或是reST格式），"
"现在就可以将这些内容通过 ``pelican`` 命令转换为HTML了，在转换时需要指定"
"创作内容存放的路径；如果有需要， :doc:`配置<settings>` 文件的路径也可单独指定："
#: ../../publish.rst:16 6f353c84f5204d2b84c49d1557010b19
msgid ""
"The above command will generate your site and save it in the ``output/`` "
"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."
msgstr ""
"上面的指令会在 ``output/`` 目录下生成站点，使用的是默认的主题。默认主题只使用"
"一些简单的HTML并且不包含样式，大家往往以这个简单主题为基础来创作自己的主题。"
#: ../../publish.rst:21 bb5064d57ed144e6b85d7d3d0938f91c
msgid ""
"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 environments, this option can also be combined "
"with the ``-l`` or ``--listen`` option to simultaneously both auto-"
"regenerate *and* serve the output at http://localhost:8000::"
msgstr ""
"你也可以让Pelican来监听对源内容文件的修改，而不是在每次修改内容后重新手动执行命令"
"来生成站点。在执行 ``pelican`` 命令时，加上 ``-r`` 或者 ``--autoreload`` 选项"
"就可以做到这一点。在非Windows环境下，这个选项还可以和 ``-l`` 或 ``--listen`` "
"搭配使用，这样就可以在自动重生成站点的基础上，同时提供在 http://localhost:8000 "
"上的访问："
#: ../../publish.rst:30 40089a6762204e27bd16afaa038a8277
msgid ""
"Pelican has other command-line switches available. Have a look at the "
"help to see all the options you can use::"
msgstr ""
"Pelican还有一些其他的命令行选项。可以在帮助中看到所有可用选项："
#: ../../publish.rst:36 4484bb6f6e2b4bd49027c98be4fa2cd8
msgid "Viewing the generated files"
msgstr "浏览生成的文件"
#: ../../publish.rst:38 4dc83b844c964bcab17af21fabd5e6b2
msgid ""
"The files generated by Pelican are static files, so you don't actually "
"need anything special to view them. You can use your browser to open the "
"generated HTML files directly::"
msgstr ""
"Pelican生成的文件都是静态的，也就是说不需要使用什么特殊的手段就可以浏览。"
"您可以直接使用浏览器打开生成的HTML文件："
#: ../../publish.rst:44 c5774634f7da4f64bb7c7d0adbcdb65b
msgid ""
"Because the above method may have trouble locating your CSS and other "
"linked assets, running Pelican's simple built-in web server will often "
"provide a more reliable previewing experience::"
msgstr ""
"事实上，上面所说的直接打开的方式可能会使CSS或其他链接上出现问题，"
"可以运行Pelican自带的简易web服务器，如此便可以获得可靠的预览体验："
#: ../../publish.rst:50 b2eab6914b854b40bd769433fbad21b7
msgid ""
"Once the web server has been started, you can preview your site at: "
"http://localhost:8000/"
msgstr ""
"当web服务器启动后，可以访问 http://localhost:8000/ 来预览您的站点。"
#: ../../publish.rst:54 3b7344cad46a4dfaa01c067dd1f4009b
msgid "Deployment"
msgstr "部署"
#: ../../publish.rst:56 de2815c211b84291a985a1d808ffbfe7
msgid ""
"After you have generated your site, previewed it in your local "
"development environment, and are ready to deploy it to production, you "
"might first re-generate your site with any production-specific settings "
"(e.g., analytics, feeds, etc.) that you may have defined::"
msgstr ""
"当您生成好站点后，可以在本地先进行预览，确认无误后，在部署前可能还需使用"
"生产环境特定的配置文件重新生成站点："
#: ../../publish.rst:63 56e568114b72443ebcf1f741f07504dc
msgid ""
"To base your publish configuration on top of your ``pelicanconf.py``, you"
" can import your ``pelicanconf`` settings by including the following line"
" in your ``publishconf.py``::"
msgstr ""
"您可以基于 ``pelicanconf.py`` 进行设置文件的配置， 在 ``publishconf.py`` "
"中import ``pelicanconf`` 就可实现（译者注：配置文件其实本质上就是一些"
"Python变量，因此import后就可以全部引入）："
#: ../../publish.rst:69 b9e1243ed9ba409890d86ef8ff85499d
msgid ""
"If you have generated a ``publishconf.py`` using ``pelican-quickstart``, "
"this line is included by default."
msgstr ""
"如果 ``publishconf.py`` 是通过 ``pelican-quickstart`` 生成的，上面这行默认就有。"
#: ../../publish.rst:72 39671d42b0bb4c828fc51c63c351402c
msgid ""
"The steps for deploying your site will depend on where it will be hosted."
" If you have SSH access to a server running Nginx or Apache, you might "
"use the ``rsync`` tool to transmit your site files::"
msgstr ""
"部署站点的方法步骤取决于网站托管的位置。对于使用SSH访问的运行着Nginx或"
"Apache的服务器，您可能需要使用 ``rsync`` 工具来传输站点文件："
#: ../../publish.rst:78 523ed256e0164a968d8580310e4a9304
msgid ""
"There are many other deployment options, some of which can be configured "
"when first setting up your site via the ``pelican-quickstart`` command. "
"See the :doc:`Tips<tips>` page for detail on publishing via GitHub Pages."
msgstr ""
"还有很多其他的部署方式供您选择，有一些在第一次通过 ``pelican-quickstart`` "
"命令建立站点时就已经配置。在 :doc:`小技巧<tips>` 中可以查看如何通过"
"Github Pages部署站点。"
#: ../../publish.rst:83 c44ecc79922d419b8627706a6694dd8c
msgid "Automation"
msgstr "自动化"
#: ../../publish.rst:85 b892dcba14a84306aa6b39295b5f81e3
msgid ""
"While the ``pelican`` command is the canonical way to generate your site,"
" automation tools can be used to streamline the generation and "
"publication flow. One of the questions asked during the ``pelican-"
"quickstart`` process pertains to whether you want to automate site "
"generation and publication. If you answered \"yes\" to that question, a "
"``tasks.py`` and ``Makefile`` will be generated in the root of your "
"project. These files, pre-populated with certain information gleaned from"
" other answers provided during the ``pelican-quickstart`` process, are "
"meant as a starting point and should be customized to fit your particular"
" needs and usage patterns. If you find one or both of these automation "
"tools to be of limited utility, these files can be deleted at any time "
"and will not affect usage of the canonical ``pelican`` command."
msgstr ""
"``pelican`` 命令是生成站点的标准方法，但同时也有自动化工具可以用来简化生成与"
"发布流程。在 ``pelican-quickstart`` 的过程中，其中一个问题就是是否启用自动站点"
"生成与发布。若您选择了 “yes”，在项目的根目录中就会生成 ``tasks.py`` "
"和 ``Makefile`` 。这些文件中预填充了一些从 ``pelican-quickstart`` 过程中"
"收集的信息，您应该从这个生成好的文件出发，再根据实际需要进一步修改。"
"另外，如果您认为这些自动化脚本文件没什么用，完全可以将他们删除，这不会对标准命令 "
"``pelican`` 产生任何影响。"
#: ../../publish.rst:98 4c49ca3a24e3462a984dda738875ed4e
msgid ""
"Following are automation tools that \"wrap\" the ``pelican`` command and "
"can simplify the process of generating, previewing, and uploading your "
"site."
msgstr ""
"下面是一些自动化工具，其中包装了 ``pelican`` 命令，可以用于简化生成、预览和"
"上传站点的过程。"
#: ../../publish.rst:102 103fb7405038442aae62b62ea0fcdbe5
msgid "Invoke"
msgstr "Invoke"
#: ../../publish.rst:104 d3e46bf8da96489e923f6497e8932538
msgid ""
"The advantage of Invoke_ is that it is written in Python and thus can be "
"used in a wide range of environments. The downside is that it must be "
"installed separately. Use the following command to install Invoke, "
"prefixing with ``sudo`` if your environment requires it::"
msgstr ""
"Invoke_ 工具使用Python作为编程语言，并且能够用在很多不同的环境中。它需要使用"
"下面的命令单独安装，在某些操作系统中可能需要在前面加上 ``sudo`` ："
#: ../../publish.rst:111 786359d08e8f45598df7b1c45e32ca0a
msgid ""
"Take a moment to open the ``tasks.py`` file that was generated in your "
"project root. You will see a number of commands, any one of which can be "
"renamed, removed, and/or customized to your liking. Using the out-of-the-"
"box configuration, you can generate your site via::"
msgstr ""
"可以打开 ``tasks.py`` 文件看看其中的代码，可以尝试更改和删除其中的命令，"
"也可以按照您的喜好自行进行其他修改。生成好的文件是开箱即用的，您可以通过"
"下面的命令生成站点："
#: ../../publish.rst:118 ../../publish.rst:166 04c6045b58c24bc1a1fd594cdcf4ef5c
#: 1e9cf29276ec4446b1b0f4a55a1ef4b8
msgid ""
"If you'd prefer to have Pelican automatically regenerate your site every "
"time a change is detected (which is handy when testing locally), use the "
"following command instead::"
msgstr ""
"若您希望Pelican在检测到变化时自动重新生成站点（在本地测试的时候很实用），"
"可以使用下面的命令："
#: ../../publish.rst:124 ../../publish.rst:172 fabe0ce08eca4c5ebd9ca65898dab138
#: ff42351e29b944a59e8df22b1cbb20f5
msgid ""
"To serve the generated site so it can be previewed in your browser at "
"http://localhost:8000/::"
msgstr ""
"下面的命令则可以让您在生成后通过浏览器访问 http://localhost:8000/ 来预览站点"
#: ../../publish.rst:129 e1b12a6c64b246f89aea105b8d7febbc
msgid ""
"To serve the generated site with automatic browser reloading every time a"
" change is detected, first ``python -m pip install livereload``, then use"
" the following command::"
msgstr ""
"在每次检测到修改重生成站点后，可以让浏览器自动进行重载。先运行 "
"``python -m pip install livereload`` 安装，再运行下面的这条命令就可以实现："
#: ../../publish.rst:135 bf0d6c7770fe4a399b81b9ebdd48fa4e
msgid ""
"If during the ``pelican-quickstart`` process you answered \"yes\" when "
"asked whether you want to upload your site via SSH, you can use the "
"following command to publish your site via rsync over SSH::"
msgstr ""
"如果在 ``pelican-quickstart`` 过程中，对是否要通过SSH上传站点问题回答了“yes”，"
"您就可以使用下面的命令借助rsync在SSH上发布站点："
#: ../../publish.rst:141 9bea9f82ce164ee5ba07349a4c4d58ea
msgid ""
"These are just a few of the commands available by default, so feel free "
"to explore ``tasks.py`` and see what other commands are available. More "
"importantly, don't hesitate to customize ``tasks.py`` to suit your "
"specific needs and preferences."
msgstr ""
"默认就可以使用的命令远不止这些，在 ``tasks.py`` 中可以找到更多可用的命令。"
"更重要的是，当您有特定需求和偏好时，直接修改 ``tasks.py`` 即可。"
#: ../../publish.rst:147 06a6e7232c6243d79ab9f43ddc28590d
msgid "Make"
msgstr "Make"
#: ../../publish.rst:149 a2a5b589cf804fcd83ee2d0fbf98c12d
msgid ""
"A ``Makefile`` is also automatically created for you when you say \"yes\""
" to the relevant question during the ``pelican-quickstart`` process. The "
"advantage of this method is that the ``make`` command is built into most "
"POSIX systems and thus doesn't require installing anything else in order "
"to use it. The downside is that non-POSIX systems (e.g., Windows) do not "
"include ``make``, and installing it on those systems can be a non-trivial"
" task."
msgstr ""
"``Makefile`` 也是自动生成的。在大多数POSIX系统中都内置了 ``make`` 命令，"
"无需安装即可使用。但在非POSIX系统（例如Windows）中并没有 ``make`` ，在这些"
"系统中安装 ``make`` 则往往比较麻烦。"
#: ../../publish.rst:156 68c38c3eb34e4e6ca9cd4a2d3646d5cb
msgid ""
"If you want to use ``make`` to generate your site using the settings in "
"``pelicanconf.py``, run::"
msgstr ""
"使用 ``make`` 命令是以 ``pelicanconf.py`` 作为配置文件来生成站点的："
#: ../../publish.rst:161 133e6e1ebf92412a85eedbe56e0b91af
msgid ""
"To generate the site for production, using the settings in "
"``publishconf.py``, run::"
msgstr ""
"使用 ``publishconf.py`` 作为配置文件来为生产环境生成站点："
#: ../../publish.rst:177 f4e250949c2145ceb03b65c875767abc
msgid ""
"Normally you would need to run ``make regenerate`` and ``make serve`` in "
"two separate terminal sessions, but you can run both at once via::"
msgstr ""
"一般来说， ``make regenerate`` 和 ``make serve`` 需要在分别在单独的终端会话中"
"运行，下面的命令相当于同时运行上述两个命令："
#: ../../publish.rst:182 1f83bbcf60134eef959370bb5ca402d9
msgid ""
"The above command will simultaneously run Pelican in regeneration mode as"
" well as serve the output at http://localhost:8000."
msgstr ""
"上面的命令会让Pelican在重生成模式下持续运行，同样地，您可以通过 "
"http://localhost:8000 访问生成的站点。"
#: ../../publish.rst:185 9274a68b1e3b4639bf638a044eda613d
msgid ""
"When you're ready to publish your site, you can upload it via the "
"method(s) you chose during the ``pelican-quickstart`` questionnaire. For "
"this example, we'll use rsync over ssh::"
msgstr ""
"当准备好发布站点时，可以使用在 ``pelican-quickstart`` 过程中选择的方法进行上传。"
"下面的例子使用rsync在ssh上完成这一工作："
#: ../../publish.rst:191 9d7e7927c183491f981aacebe14e5bf1
msgid "That's it! Your site should now be live."
msgstr "OK！您的站点现在已经可以访问了。"
#: ../../publish.rst:193 8f570acd5f494f5b9645fdbca6db6fbb
msgid ""
"(The default ``Makefile`` and ``devserver.sh`` scripts use the ``python``"
" and ``pelican`` executables to complete its tasks. If you want to use "
"different executables, such as ``python3``, you can set the ``PY`` and "
"``PELICAN`` environment variables, respectively, to override the default "
"executable names.)"
msgstr ""
"（默认的 ``Makefile`` 和 ``devserver.sh`` 脚本执行 ``python`` 和 ``pelican`` "
"来完成任务。若您希望使用其他的可执行文件，例如 ``python3`` ，设置环境变量 ``PY`` "
"和 ``PELICAN`` 来覆盖默认的可执行文件名）"

151
docs/locale/zh_CN/LC_MESSAGES/quickstart.po
View file

@ -1,151 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-25 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../quickstart.rst:2 e5f32d61440744aab3f878488ef9e1e3
msgid "Quickstart"
msgstr "快速开始"
#: ../../quickstart.rst:4 d3762ec7c3934f85b25b04cf4024a90c
msgid ""
"Reading through all the documentation is highly recommended, but for the "
"truly impatient, following are some quick steps to get started."
msgstr ""
"强烈建议将所有文档完整地看一遍，但如果您目前没空，下面的步骤可以帮助您快速开始"
"使用Pelican。"
#: ../../quickstart.rst:8 c5982d5ecf7c445590254370b84995be
msgid "Installation"
msgstr "安装"
#: ../../quickstart.rst:10 fda7d08c05f14e2fa0c07a4a1d216db5
msgid ""
"Install Pelican (and optionally Markdown if you intend to use it) on "
"Python |min_python| by running the following command in your preferred "
"terminal, prefixing with ``sudo`` if permissions warrant::"
msgstr ""
"在命令行中执行下面的命令以安装Pelican（如果您需要Markdown支持的话，也可以同时安装之）。"
"Pelican需要使用 |min_python| 以上版本的Python。在必要情况下，请在命令前加上 ``sudo`` 。"
#: ../../quickstart.rst:17 9db650d9dc9d4ac48df4dd9fc0a246ac
msgid "Create a project"
msgstr "创建项目"
#: ../../quickstart.rst:19 2e9a72a878754604abdb27d9ec37937e
msgid ""
"First, choose a name for your project, create an appropriately-named "
"directory for your site, and switch to that directory::"
msgstr ""
"首先，给您的项目想个名字，并以合适的名字创建一个文件夹来存放您的站点。"
"接着，进入这个新创建的文件夹："
#: ../../quickstart.rst:25 da759420dd8440b485936a5a054f142a
msgid ""
"Create a skeleton project via the ``pelican-quickstart`` command, which "
"begins by asking some questions about your site::"
msgstr ""
"通过 ``pelican-quickstart`` 命令创建一个项目的框架，执行这个命令后，"
"您需要输入一些站点相关的信息："
#: ../../quickstart.rst:30 eb2d702c9f5a4981a93f805e98674cfe
msgid ""
"For questions that have default values denoted in brackets, feel free to "
"use the Return key to accept those default values [#tzlocal_fn]_. When "
"asked for your URL prefix, enter your domain name as indicated (e.g., "
"``https://example.com``)."
msgstr ""
"对于那些在括号中写了默认值的问题，完全可以直接回车以使用预设值 [#tzlocal_fn]_。"
"在输入站点URL的前缀（prefix）时，请根据提示的格式输入站点的域名（例如 "
"``https://example.com``）。"
#: ../../quickstart.rst:36 66d29d63cce0488a8ec9e43ce97035f9
msgid "Create an article"
msgstr "创作文章"
#: ../../quickstart.rst:38 03af35552ef84e4491b46d8bf8c0f51e
msgid ""
"You cannot run Pelican until you have created some content. Use your "
"preferred text editor to create your first article with the following "
"content::"
msgstr ""
"您可以使用喜欢的文本编辑器来创建第一篇文章。下面是一个样例，可以将它作为您的第一篇文章："
#: ../../quickstart.rst:47 165d46a3f9da4f949375c70115fdeb3b
msgid ""
"Given that this example article is in Markdown format, save it as "
"``~/projects/yoursite/content/keyboard-review.md``."
msgstr ""
"上面这篇文章是以Markdown的格式完成的，一定要将其保存在站点目录的content文件夹下，例如 "
"``~/projects/yoursite/content/keyboard-review.md``。"
#: ../../quickstart.rst:51 5cc306848439434f81708eddee812f0e
msgid "Generate your site"
msgstr "生成站点"
#: ../../quickstart.rst:53 03037d0c3b0b4a64b957f8284f008c9d
msgid ""
"From your project root directory, run the ``pelican`` command to generate"
" your site::"
msgstr ""
"在项目的根目录下，直接运行命令 ``pelican`` 就可以生成您自己的站点了："
#: ../../quickstart.rst:57 abadae17b6f94e36b8603bad69f6e24f
msgid ""
"Your site has now been generated inside the ``output/`` directory. (You "
"may see a warning related to feeds, but that is normal when developing "
"locally and can be ignored for now.)"
msgstr ""
"站点会生成在 ``output/`` 目录下。（此时可能会显示和feeds有关的警告，这和当前的"
"本地开发环境有关，目前可以忽略之）"
#: ../../quickstart.rst:62 7cf36e609f544f02a0c800f8412cf79c
msgid "Preview your site"
msgstr "预览站点"
#: ../../quickstart.rst:64 1a64015c5cc9401bac0a6ac953164fb3
msgid ""
"Open a new terminal session, navigate to your project root directory, and"
" run the following command to launch Pelican's web server::"
msgstr ""
"打开一个新的命令行，进入刚才项目的根目录，执行下面的命令以运行一个Pelican web服务器："
#: ../../quickstart.rst:69 eb286b4785304d22a46e90884d26de07
msgid "Preview your site by navigating to http://localhost:8000/ in your browser."
msgstr "打开浏览器，进入 http://localhost:8000/ 就可以看到刚刚生成的站点了。"
#: ../../quickstart.rst:71 1dc30b5cb267402c9da251303ff59dbf
msgid ""
"Continue reading the other documentation sections for more detail, and "
"check out the Pelican wiki's Tutorials_ page for links to community-"
"published tutorials."
msgstr ""
"请继续阅读文档中的其他部分来了解Pelican的更多用法，也可以前往Pelican的"
"wiki 教程_ 页面获取社区发布的教程。"
#: ../../quickstart.rst:78 6c135ea1cbb44400b446c0f9074e0fc5
msgid "Footnotes"
msgstr "脚注"
#: ../../quickstart.rst:80 911df4217fd94e6184502153ed0e53dc
msgid ""
"You can help localize default fields by installing the optional `tzlocal "
"<https://pypi.org/project/tzlocal/>`_ module."
msgstr ""
"您可以安装可选模块 `tzlocal <https://pypi.org/project/tzlocal/>`_ 来"
"本地化默认字段。"

249
docs/locale/zh_CN/LC_MESSAGES/report.po
View file

@ -1,249 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../report.rst:2 bc25575efa494c7b9455e02eb5c514ab
msgid "Some history about Pelican"
msgstr "Pelican的一些历史"
#: ../../report.rst:6 959bbe068d2e4fd19e48be22706070d2
msgid ""
"This page comes from a report the original author (Alexis Métaireau) "
"wrote right after writing Pelican, in December 2010. The information may "
"not be up-to-date."
msgstr ""
"此页面来自原作者 Alexis Métaireau 在2010年12月完成Pelican后作的一篇报告，因此"
"其中涉及的具体内容可能和最新的Pelican有些出入。"
#: ../../report.rst:10 598beb4776eb4a7bb1c928979752b1f1
msgid ""
"Pelican is a simple static blog generator. It parses markup files "
"(Markdown or reStructuredText for now) and generates an HTML folder with "
"all the files in it. I've chosen to use Python to implement Pelican "
"because it seemed to be simple and to fit to my needs. I did not wanted "
"to define a class for each thing, but still wanted to keep my things "
"loosely coupled. It turns out that it was exactly what I wanted. From "
"time to time, thanks to the feedback of some users, it took me a very few"
" time to provide fixes on it. So far, I've re-factored the Pelican code "
"by two times; each time took less than 30 minutes."
msgstr ""
"Pelican是一个简单的静态博客生成器。它解析标记文件（目前主要是Markdown和"
"reStructuredText），并生成一个文件夹，其中包含了对应于标记文件的HTML。由于Python"
"很简单并且符合需求，我选择使用Python来实现Pelican。我不想为每个东西定义一个类，"
"但同时又想要各部件之间低耦合。事实证明，这正是我想要的。在发展过程中，多亏了用户"
"给的反馈，我花了些时间修复了一些问题。到目前为止，我已经将Pelican的代码重构了两次，"
"每次重构都不会超过30分钟。"
#: ../../report.rst:21 1709ab99c3144cb692afd1d1bc388921
msgid "Use case"
msgstr "使用场景"
#: ../../report.rst:23 119f315a8e6c409d98783a636ac2147c
msgid ""
"I was previously using WordPress, a solution you can host on a web server"
" to manage your blog. Most of the time, I prefer using markup languages "
"such as Markdown or reStructuredText to type my articles. To do so, I use"
" vim. I think it is important to let the people choose the tool they want"
" to write the articles. In my opinion, a blog manager should just allow "
"you to take any kind of input and transform it to a weblog. That's what "
"Pelican does. You can write your articles using the tool you want, and "
"the markup language you want, and then generate a static HTML weblog."
msgstr ""
"我之前使用的是WordPress，你可以将它部署在Web服务器上来管理博客。大多数时候，"
"我更喜欢使用Markdown或reStructuredText等标记语言来撰写文章。为此，我一般用vim"
"来写这些文章。我认为让大家自行选择用于写文章的工具是很重要的。在我看来，博客管理器"
"应该能够接受任何类型的输入并将其转换为博客站。Pelican就采取这一思想。您可以选择自己"
"喜欢的工具以及标记语言来撰写文章，然后生成静态的HTML博客站。"
#: ../../report.rst:34 1a087a07690c4c35873a7f4ce18ba52b
msgid ""
"To be flexible enough, Pelican has template support, so you can easily "
"write your own themes if you want to."
msgstr ""
"为了足够的灵活性，Pelican中支持使用模板，这样你就可以编写自己的主题了。"
#: ../../report.rst:38 fca5a0962a0d4c27aa163f2aec94b1cf
msgid "Design process"
msgstr "设计过程"
#: ../../report.rst:40 073dd0b024fa4701acc0078b84c45648
msgid ""
"Pelican came from a need I have. I started by creating a single file "
"application, and I have make it grow to support what it does by now. To "
"start, I wrote a piece of documentation about what I wanted to do. Then, "
"I created the content I wanted to parse (the reStructuredText files) and "
"started experimenting with the code. Pelican was 200 lines long and "
"contained almost ten functions and one class when it was first usable."
msgstr ""
"Pelican来源于我的需求。从单文件应用程序出发，不断成长为现在功能丰富的应用。首先，我"
"写了一份需求文档；然后创建了我想要解析的内容（reStructuredText文件），并开始"
"实验性的编写代码。Pelican的第一个能够使用的版本包含了200行代码、10个函数以及1个类。"
#: ../../report.rst:47 f407fc9ad9434f1082014eeca8c4cc89
msgid ""
"I have been facing different problems all over the time and wanted to add"
" features to Pelican while using it. The first change I have done was to "
"add the support of a settings file. It is possible to pass the options to"
" the command line, but can be tedious if there is a lot of them. In the "
"same way, I have added the support of different things over time: Atom "
"feeds, multiple themes, multiple markup support, etc. At some point, it "
"appears that the \"only one file\" mantra was not good enough for "
"Pelican, so I decided to rework a bit all that, and split this in "
"multiple different files."
msgstr ""
"我不断遇到各种问题，在使用过程中还想要往Pelican中添加功能。在对代码的第一次修改中，"
"添加了对配置文件的支持。虽然可以在命令行中往里传入选项，但当配置项多起来后，就会变得"
"异常冗长。同样地，Pelican支持了越来越多的功能：Atom订阅源、多主体支持、多标记语言"
"支持等等。在某一时刻，单文件应用已经不适合Pelican了，因此我决定多做些工作，将应用分离"
"到多个文件中。"
#: ../../report.rst:56 57b3d1ba492646e28e20396b78df8ea0
msgid "I’ve separated the logic in different classes and concepts:"
msgstr "我将系统整体逻辑分为如下几个类和概念："
#: ../../report.rst:58 2d4090dba6674569a7e1088919185aa5
msgid ""
"*writers* are responsible of all the writing process of the files. They "
"are responsible of writing .html files, RSS feeds and so on. Since those "
"operations are commonly used, the object is created once, and then passed"
" to the generators."
msgstr ""
"**Writers** 负责文件的写入工作，即负责完成 html、RSS订阅源等文件的写入。因为这些"
"操作都是比较常用的，这个类只会被创建一次，然后再传给Generators。"
#: ../../report.rst:63 a4cff6dceb8f430791edaeb3b2280924
msgid ""
"*readers* are used to read from various formats (Markdown and "
"reStructuredText for now, but the system is extensible). Given a file, "
"they return metadata (author, tags, category, etc) and content (HTML "
"formatted)."
msgstr ""
"**Readers** 用于读取不同格式的文件（目前支持Markdown、reStructuredText，"
"但可以继续扩展）。向 **Readers** 输入一个文件，它会返回文档的元数据（作者、标签、"
"分类等等）与HTML格式的文档正文内容。"
#: ../../report.rst:67 6ed9719c06c2477ea05ea30e4806ad14
msgid ""
"*generators* generate the different outputs. For instance, Pelican comes "
"with an ArticlesGenerator and PagesGenerator, into others. Given a "
"configuration, they can do whatever you want them to do. Most of the time"
" it's generating files from inputs (user inputs and files)."
msgstr ""
"**Generators** 用以生成不同的输出，Pelican自带了 ``ArticlesGenerator`` 和 "
"``PageGenerator`` 。给定一套配置信息， **Generators** 可以做几乎任何事。"
"但大多数情况下，它的工作就是从输入生成文件。"
#: ../../report.rst:72 cb5129c105b04d788a908f580a83e7e1
msgid ""
"I also deal with contents objects. They can be ``Articles``, ``Pages``, "
"``Quotes``, or whatever you want. They are defined in the ``contents.py``"
" module and represent some content to be used by the program."
msgstr ""
"同样，还要处理正文对象。正文对象可以是 ``Articles`` 、 ``Pages`` 、 ``Quotes`` "
"或者其他你想要的类型。这些对象在 ``contents.py`` 模块中完成定义，同时代表了应用中"
"使用到的内容。"
#: ../../report.rst:77 4123da2b628448359aa9ed20b2ca87d2
msgid "In more detail"
msgstr "更细节的内容"
#: ../../report.rst:79 8482492940524edf8244fc220553cd3c
msgid "Here is an overview of the classes involved in Pelican."
msgstr "以下是Pelican中涉及的类的概述。"
#: ../../report.rst:83 a8a39a1ccc154604b8bb000dff44982d
msgid ""
"The interface does not really exist, and I have added it only to clarify "
"the whole picture. I do use duck typing and not interfaces."
msgstr ""
"上图中的接口事实上并不存在，我是为了整张图的完整性才加上去的。在实际实现中，使用了"
"鸭子类型而不是接口。"
#: ../../report.rst:86 889dfae0dc4242f0b21ce831c7172001
msgid "Internally, the following process is followed:"
msgstr "应用内部按以下流程进行处理："
#: ../../report.rst:88 fc5cbf8ca65c456c90c56c00cf5ab93f
msgid ""
"First of all, the command line is parsed, and some content from the user "
"is used to initialize the different generator objects."
msgstr ""
"首先，解析命令行，并根据用户给入的一些内容来初始化不同的generator对象。"
#: ../../report.rst:91 5d0c1dc643364248820fad76c204f663
msgid ""
"A ``context`` is created. It contains the settings from the command line "
"and a settings file if provided."
msgstr ""
"创建一个 ``context`` ，其中包含了来自命令行和文件的配置信息。"
#: ../../report.rst:93 36725875f2c14e0bb8fc60b16afa1367
msgid ""
"The ``generate_context`` method of each generator is called, updating the"
" context."
msgstr ""
"调用各generator对象的 ``generate_context`` 方法来更新 ``context`` 。"
#: ../../report.rst:95 d50a4b2e38884eb38f1b66fdf7fb1eda
msgid ""
"The writer is created and given to the ``generate_output`` method of each"
" generator."
msgstr ""
"创建 **Writers** 并将其给入generator的 ``generate_output`` 方法。"
#: ../../report.rst:98 da8d9096940044f2849112fb5efcb4cb
msgid ""
"I make two calls because it is important that when the output is "
"generated by the generators, the context will not change. In other words,"
" the first method ``generate_context`` should modify the context, whereas"
" the second ``generate_output`` method should not."
msgstr ""
"由于当generator生成输出时并不会改变上下文，我进行了两次调用。换句话说，第一个方法 "
"``generate_context`` 会修改上下文，而第二个方法 ``generate_output`` 不会。"
#: ../../report.rst:103 a6350edba931463fb92ae51dd9bc253a
msgid ""
"Then, it is up to the generators to do what the want, in the "
"``generate_context`` and ``generate_content`` method. Taking the "
"``ArticlesGenerator`` class will help to understand some others concepts."
" Here is what happens when calling the ``generate_context`` method:"
msgstr ""
"然后，事情就取决于各generator在 ``generate_context`` 和 ``generate_content`` "
"中做的操作了。拿 ``ArticlesGenerator`` 举例可以帮助理解其他的一些概念。下面是调用 "
"``generate_context`` 方法后会发生的事情："
#: ../../report.rst:108 4b99ddf2cf344d0b8fbd080c15adfb64
msgid ""
"Read the folder “path”, looking for restructured text files, load each of"
" them, and construct a content object (``Article``) with it. To do so, "
"use ``Reader`` objects."
msgstr ""
"读取文件夹路径，查找并加载每个restructured文件，并为每个文件构建一个正文内容对象（ "
"``Article`` ）。此工作是由 ``Reader`` 对象完成的。"
#: ../../report.rst:111 176a7a5896904f2e9929623ef652660b
msgid "Update the ``context`` with all those articles."
msgstr "根据所有的文章更新 ``context`` 。"
#: ../../report.rst:113 bb88942c85004c4c9e0b55a72076b18f
msgid ""
"Then, the ``generate_content`` method uses the ``context`` and the "
"``writer`` to generate the wanted output."
msgstr ""
"然后， ``generate_content`` 方法使用 ``context`` 和 ``writer`` 来生成想要的输出。"

1815
docs/locale/zh_CN/LC_MESSAGES/settings.po
View file

File diff suppressed because it is too large Load diff

60
docs/locale/zh_CN/LC_MESSAGES/sphinx.po
View file

@ -1,60 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-24 19:06+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: \n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../_templates/page.html:68 697aead398874e06aa15cfd74d134745
msgid "Back to top"
msgstr "返回顶部"
#: ../../_templates/page.html:101 f91a64e54aae49c2bd09a944ea693193
msgid "Next"
msgstr "下一节"
#: ../../_templates/page.html:113 6c3ad069077b4e2cb6e1f77cc2962881
msgid "Previous"
msgstr "前一节"
#: ../../_templates/page.html:116 e83e03d0b50c4065a9f87db25a23b3ee
msgid "Home"
msgstr "首页"
#: ../../_templates/page.html:129 1d0fdb4c0b4e420283101ba5c21ac985
#, python-format
msgid "<a href=\"%(path)s\">Copyright</a> &#169; %(copyright)s"
msgstr "<a href=\"%(path)s\">Copyright</a> &#169; %(copyright)s"
#: ../../_templates/page.html:133 0a35c662e6574da48f7ac5c6b2c82874
#, python-format
msgid ""
"Copyright &#169; %(copyright)s, <a "
"href=\"https://justinmayer.com\">Justin Mayer</a>, Alexis Metaireau, and "
"contributors"
msgstr ""
"Copyright &#169; %(copyright)s, <a "
"href=\"https://justinmayer.com\">Justin Mayer</a>, Alexis Metaireau, and "
"contributors"
#: ../../_templates/page.html:141 07b89372db484251bfcd3b54e0845bf0
#, python-format
msgid "Last updated on %(last_updated)s"
msgstr "最后更新于 %(last_updated)s"
#: ../../_templates/page.html:187 2eb9f1b479a7405290a91d8e1962f265
msgid "On this page"
msgstr "本页目录"

1269
docs/locale/zh_CN/LC_MESSAGES/themes.po
View file

File diff suppressed because it is too large Load diff

679
docs/locale/zh_CN/LC_MESSAGES/tips.po
View file

@ -1,679 +0,0 @@
# SOME DESCRIPTIVE TITLE.
# Copyright (C) 2010–2024
# This file is distributed under the same license as the PELICAN package.
# FIRST AUTHOR <EMAIL@ADDRESS>, 2024.
#
msgid ""
msgstr ""
"Project-Id-Version: PELICAN 4\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2024-06-25 20:36+0800\n"
"PO-Revision-Date: 2024-06-27 19:00+0800\n"
"Last-Translator: GeorgeHu <dhxxhch@163.com>\n"
"Language: zh_CN\n"
"Language-Team: zh_CN <LL@li.org>\n"
"Plural-Forms: nplurals=1; plural=0;\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"
"Generated-By: Babel 2.15.0\n"
#: ../../tips.rst:2 415f61a654104cf4826423e3aa1d3807
msgid "Tips"
msgstr "小技巧"
#: ../../tips.rst:4 1bc50144d85845f3a7f21f9ef87bba44
msgid "Here are some tips about Pelican that you might find useful."
msgstr "以下是一些实用的小技巧。"
#: ../../tips.rst:7 ../../tips.rst:264 d9115f4b162d46e6aa89d56309c1ec41
#: e693dc009e5c466d99655b705223f300
msgid "Custom 404 Pages"
msgstr "自定义404页面"
#: ../../tips.rst:9 5c7cd70793f44d3c9fcf63779755d62b
msgid ""
"When a browser requests a resource that the web server cannot find, the "
"web server usually displays a generic \"File not found\" (404) error page"
" that can be stark and unsightly. One way to provide an error page that "
"matches the theme of your site is to create a custom 404 page (*not* an "
"article), such as this Markdown-formatted example stored in "
"``content/pages/404.md``::"
msgstr ""
"当浏览器请求的资源无法在服务器中找到时，web服务器常常会显示一个通用的“File not "
"found 404”的错误页面，这可能会不太美观。为了能使用一个与站点主题相匹配的404页面"
"（注意是页面而 **不是** 文章），例如下面这个Markdown格式的例子，将此文件存为了 "
"``content/pages/404.md`` ："
#: ../../tips.rst:22 cab28bb6b2a548a09f8cc6e4778f1a78
msgid ""
"The next step is to configure your web server to display this custom page"
" instead of its default 404 page. For Nginx, add the following to your "
"configuration file's ``location`` block::"
msgstr ""
"接下来就是要配置web服务器，使其显示此自定义页面而不是默认的404页面。例如对于Nginx，"
"在配置文件的 ``location`` 块中添加下面的命令："
#: ../../tips.rst:28 f8acbc4d00de4cfb8dfd9358a8168c14
msgid "For Apache::"
msgstr "对于Apache："
#: ../../tips.rst:32 3701d02f6dba4936a86a9fbb226261e8
msgid ""
"For Amazon S3, first navigate to the ``Static Site Hosting`` menu in the "
"bucket settings on your AWS console. From there::"
msgstr ""
"对于Amazon S3实例，先在控制台的设置中找到 ``Static Site Hosting`` ，并添加："
#: ../../tips.rst:38 4d111f7cca2e49828e343ff889847358
msgid "Publishing to GitHub Pages"
msgstr "发布到GitHub Pages"
#: ../../tips.rst:40 f7fa83b00f6d4dd58d6f119725474538
msgid ""
"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>`_."
msgstr ""
"如果将Pelican站点放在了 `GitHub <https://github.com/>`_ 上，那么你就可以将站点"
"免费发布在 `GitHub Pages <https://pages.github.com/>`_ 上。如果是用户或组织的"
"站点，发布的地址为 ``https://<username>.github.io`` ；如果是某个项目的站点，"
"发布的地址则为 ``https://<username>.github.io/<repository>`` 。当然也可以 "
"`在GitHub Pages上使用自定义域名 <https://docs.github.com/en/pages/configuring-a-custom-"
"domain-for-your-github-pages-site>`_ 。"
#: ../../tips.rst:46 a3167f2a605d44288b83d66f052e8cdd
msgid ""
"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>`_:"
msgstr ""
"总的来说，有 `两种将站点发布到GitHub Pages的方法 <https://docs.github.com/en/pages"
"/getting-started-with-github-pages/configuring-a-publishing-source-for-"
"your-github-pages-site>`_ ："
#: ../../tips.rst:48 b2f270c5a15d4e3e92331c3c37db25dd
msgid ""
"**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."
msgstr ""
"**从某一分支发布：** 在本地运行 ``pelican`` 后将输出文件夹push到GitHub仓库的"
"某一分支。GitHub就会将该分支的内容发布到GitHub Pages上。"
#: ../../tips.rst:51 4ffdb550d8bf468dbfe4d32dfcda21cd
msgid ""
"**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."
msgstr ""
"**从自定义GitHub Actions工作流发布：** 将内容源文件推送到GitHub仓库的默认分支，"
"然后在GitHub Actions工作流中执行 ``pelican`` 以生成输出文件夹，最后将其发布到你"
"的GitHub Pages站点。此种方法下就无需在本地执行 ``pelican`` 命令了。甚至可以直接"
"在GitHub的网页中在线修改站点内容源文件。"
#: ../../tips.rst:60 0e9c34ce1a5948098a5d0812eb8ac1b4
msgid "Publishing a Project Site to GitHub Pages from a Branch"
msgstr "从某一分支发布项目站点到GitHub Pages"
#: ../../tips.rst:62 5190ebea8d8b4542ac9ecb98c297594e
msgid ""
"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 on GitHub."
msgstr ""
"要将Pelican站点发布为项目页面，你需要将Pelican生成的 ``output`` 目录 "
"**push** 到GitHub仓库的 ``gh-pages`` 分支。"
#: ../../tips.rst:66 e12298010e9745b59d60d31ae909fd4c
msgid ""
"The excellent `ghp-import <https://github.com/davisp/ghp-import>`_, which"
" can be installed with ``pip``, makes this process really easy."
msgstr ""
"可通过 ``pip`` 安装的 `ghp-import <https://github.com/davisp/ghp-import>`_ "
"使这一步变得非常简单。"
#: ../../tips.rst:69 cd5a5847355846dd81a0ad37858358f2
msgid ""
"For example, if the source of your Pelican site is contained in a GitHub "
"repository, and if you want to publish that Pelican site in the form of "
"Project Pages to this repository, you can then use the following::"
msgstr ""
"例如，当Pelican站点的源文件已经包含在GitHub仓库中时，可以将其作为此仓库的项目页面："
#: ../../tips.rst:77 18d3e7316a5a48acb337c3c67e94084c
msgid ""
"The ``ghp-import output`` command updates the local ``gh-pages`` branch "
"with the content of the ``output`` directory (creating the branch if it "
"doesn't already exist). The ``git push origin gh-pages`` command updates "
"the remote ``gh-pages`` branch, effectively publishing the Pelican site."
msgstr ""
"``ghp-import output`` 命令会用 ``output`` 目录下的内容更新本地的 ``gh-pages`` "
"分支（如果此分支不存在则会先创建）。接着再用 ``git push origin gh-pages`` "
"命令更新远程分支 ``gh-pages`` ，如此就能够发布Pelican站点了。"
#: ../../tips.rst:84 cc8b9d96da674850b39373728000f722
msgid ""
"The ``github`` target of the Makefile (and the ``gh_pages`` task of "
"``tasks.py``) created by the ``pelican-quickstart`` command publishes the"
" Pelican site as Project Pages, as described above."
msgstr ""
"``pelican-quickstart`` 在Makefile文件中所生成的 ``github`` 目标（以及为 "
"``gh_pages`` 任务生成的 ``tasks.py`` ）使得Pelican站点能像上面描述的那样被发布"
"为项目页面。"
#: ../../tips.rst:89 41c7b129fd334796848c4d75404dbe81
msgid "Publishing a User Site to GitHub Pages from a Branch"
msgstr "从某一分支发布用户站点到GitHub Pages"
#: ../../tips.rst:91 b379f950927d484ba91fbe649a248cfe
msgid ""
"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 ``main`` "
"branch of your ``<username>.github.io`` repository on GitHub."
msgstr ""
"要以用户页面形式发布Pelican站点，你需要将Pelican生成的 ``output`` 目录内容 "
"**push** 到 ``<username>.github.io`` 仓库的 ``master`` 分支上。"
#: ../../tips.rst:95 6d1bd6c0ff25494e997c4efbdcd1d861
msgid "Again, you can take advantage of ``ghp-import``::"
msgstr "同样的，此处也可以使用 ``ghp-import`` ："
#: ../../tips.rst:101 45fb7ba534af4f7d828e1630e591c02a
msgid ""
"The ``git push`` command pushes the local ``gh-pages`` branch (freshly "
"updated by the ``ghp-import`` command) to the ``elemoine.github.io`` "
"repository's ``main`` branch on GitHub."
msgstr ""
"``git push`` 命令将本地的 ``gh-pages`` 分支（此分支在刚刚通过 ``ghp-import`` "
"命令进行了更新）push到了GitHub仓库 ``elemoine.github.io`` 的 ``master`` 分支。"
#: ../../tips.rst:107 b105e7dd1aef441896c0f59166808113
msgid ""
"To publish your Pelican site as User Pages, feel free to adjust the "
"``github`` target of the Makefile."
msgstr ""
"要将Pelican站点发布为用户页面，可以根据需要修改Makefile中的 ``github`` 目标。"
#: ../../tips.rst:110 87a89a932eec40e8bfdd5c756f4d54fc
msgid ""
"Another option for publishing to User Pages is to generate the output "
"files in the root directory of the project."
msgstr ""
"发布用户页面的另一种方法就是将输出文件生成在项目的根目录下。"
#: ../../tips.rst:113 dab76a45349c432cb4b763484661ec2c
msgid ""
"For example, your main project folder is ``<username>.github.io`` and you"
" can create the Pelican project in a subdirectory called ``Pelican``. "
"Then from inside the ``Pelican`` folder you can run::"
msgstr ""
"例如，项目的主文件夹是 ``<username>.github.io`` ，你可以在子目录 ``Pelican`` "
"中创建一个Pelican项目。然后你可以在这个 ``Pelican`` 文件夹中执行下面的命令："
#: ../../tips.rst:119 7f13464c92f14cc18f8c00f7dae78f93
msgid ""
"Now you can push the whole project ``<username>.github.io`` to the main "
"branch of your GitHub repository::"
msgstr ""
"接着可以将整个项目 ``<username>.github.io`` push到GitHub仓库的master分支中："
#: ../../tips.rst:124 e82ff566e32b4696863aa04216aaf355
msgid "(assuming origin is set to your remote repository)."
msgstr "（此处假设远程仓库命名为origin）。"
#: ../../tips.rst:127 1958522ba7c34537855505f1e64c7b43
msgid "Publishing to GitHub Pages Using a Custom GitHub Actions Workflow"
msgstr "使用自定义GitHub Actions工作流将站点发布GitHub Pages中"
#: ../../tips.rst:129 19c47b80d248451facd8407bd960b527
msgid ""
"Pelican-powered sites can be published to GitHub Pages via a `custom "
"workflow "
"<https://github.com/getpelican/pelican/blob/main/.github/workflows/github_pages.yml>`_."
" To use it:"
msgstr ""
"Pelican已经给你准备了一份 `自定义工作流 "
"<https://github.com/getpelican/pelican/blob/main/.github/workflows/github_pages.yml>`_"
" ，你可以直接使用此工作流发布站点："
#: ../../tips.rst:133 bdc132ef5b974d1eae684d8118e4d914
msgid ""
"Enable GitHub Pages in your repo: go to **Settings → Pages** and choose "
"**GitHub Actions** for the **Source** setting."
msgstr ""
"首先为仓库开启GitHub Pages： **Settings → Pages** 中有个 **Source** 设置项，"
"将其选择为 **GitHub Actions** 。"
#: ../../tips.rst:136 d7d197c176bd4127a75cfaf9dd29212b
msgid ""
"Commit a ``.github/workflows/pelican.yml`` file to your repo with these "
"contents:"
msgstr ""
"往你的仓库中commit一个 ``.github/workflows/pelican.yml`` 文件，文件内容如下："
#: ../../tips.rst:155 656a2b783b6043f2ac26b1e7b342732e
msgid ""
"You may want to replace the ``@main`` with the ID of a specific commit in"
" this repo in order to pin the version of the reusable workflow that "
"you're using: ``uses: "
"getpelican/pelican/.github/workflows/github_pages.yml@<COMMIT_ID>``. If "
"you do this you might want to get Dependabot to send you automated pull "
"requests to update that commit ID whenever new versions of this workflow "
"are published, like so:"
msgstr "你可能想要将 ``@main`` 替换为这个仓库中某个特定commit的ID，以便将你使用的"
"可重用工作流的版本固定下来，此时，可以使用 ``uses: getpelican/pelican/.github/workflows/"
"github_pages.yml@<COMMIT_ID>`` 。在这种情况下，你可能想让Dependabot自动向你发送"
"PR，以便在发布新版本的工作流时更新commit ID，如下所示:"
#: ../../tips.rst:172 0e2e10f42d6142e1b2f9d2251879ffad
msgid ""
"See `GitHub's docs about using Dependabot to keep your actions up to date"
" <https://docs.github.com/en/code-security/dependabot/working-with-"
"dependabot/keeping-your-actions-up-to-date-with-dependabot>`_."
msgstr "请参阅 `GitHub文档 <https://docs.github.com/en/code-security/"
"dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-"
"dependabot>`_ ，了解如何使用Dependabot使您的action保持最新。"
#: ../../tips.rst:174 2475397adfbb48af9a1d16fc0a24d9b9
msgid ""
"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."
msgstr ""
"选中仓库的 **Actions** 标签栏（ ``https://github.com/<username>/<repository>"
"/actions`` ），此时你应该会看到已经有一个名为 **Deploy to GitHub Pages** 的"
"action正在运行。"
#: ../../tips.rst:178 df30a15c460b442796f7f2007c283f32
msgid ""
"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."
msgstr ""
"当此action执行完成，就能够通过仓库的GitHub Pages地址 ``https://<username>."
"github.io`` 看到部署好了的用户或组织站点了，对于项目站点，可通过 ``https://"
"<username>.github.io/<repository>`` 访问。"
#: ../../tips.rst:183 f79963fcfd204f2780ff536516e6d407
msgid "Notes:"
msgstr "注意事项："
#: ../../tips.rst:185 3a2dc6a36d38454e85265ef35c5e8010
msgid ""
"You don't need to set ``SITEURL`` or ``FEED_DOMAIN`` in your Pelican "
"settings: the workflow will set them correctly for you"
msgstr ""
"无需在Pelican配置文件中设置 ``SITEURL`` ，工作流会帮你进行设置。"
#: ../../tips.rst:188 ea406746a7db49dfa10de025a3be4a31
msgid ""
"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"
msgstr ""
"无需commit ``--output`` 或 ``OUTPUT_PATH`` 所指定的目录（ ``output/`` ）："
"工作流会自己执行 ``pelican`` 命令来构建输出目录。"
#: ../../tips.rst:192 a92a4068ac294a22ac80b1db68090634
msgid ""
"See `GitHub's docs about reusable workflows "
"<https://docs.github.com/en/actions/using-workflows/reusing-workflows>`_ "
"for more information."
msgstr ""
"更多信息请参阅 `GitHub可重用工作流文档 <https://docs.github.com/en/actions/using-"
"workflows/reusing-workflows>`_ 。"
#: ../../tips.rst:195 1264d8a048aa4bd7878845ba2dac0d0d
msgid ""
"A number of optional inputs can be added to the ``with:`` block when "
"calling the workflow, for example:"
msgstr ""
"有一些可选输入可以添加到工作流的 ``with:`` 块中："
#: ../../tips.rst:206 3faf65d7567244e3bc65a15dc84cf247
msgid "Here's the complete list of workflow inputs:"
msgstr "下面是工作流可用输入参数的完整列表："
#: ../../tips.rst:209 37919ce86ddb4546bd191440ba1c5b9a
msgid "Name"
msgstr "名称"
#: ../../tips.rst:209 645ae6a27c7b40ecbc795dbd698b0649
msgid "Required"
msgstr "是否必需"
#: ../../tips.rst:209 18917f8f278440e38882a4f1ca62fc8f
msgid "Description"
msgstr "描述"
#: ../../tips.rst:209 99be24eafb6d43578e6eabba25f568fe
msgid "Type"
msgstr "值的类型"
#: ../../tips.rst:209 24860d0693b84e6c9297f8733b338824
msgid "Default"
msgstr "默认值"
#: ../../tips.rst:211 7e9bb7ea151c4e8c99116dd4decbe3c1
msgid "``settings``"
msgstr "``settings``"
#: ../../tips.rst:211 647c4173846f4057920030c8f774d5ea
msgid "Yes"
msgstr "是"
#: ../../tips.rst:211 05c57822d0a249de9718a9a3c56e9e56
msgid ""
"The path to your Pelican settings file (``pelican``'s ``--settings`` "
"option), for example: ``\"publishconf.py\"``"
msgstr ""
"Pelican配置文件的路径（会被用于 ``pelican`` 命令的 ``--settings`` 选项），例如 "
"``\"publishconf.py\"`` 。"
#: ../../tips.rst:211 ../../tips.rst:216 ../../tips.rst:223 ../../tips.rst:227
#: ../../tips.rst:231 ../../tips.rst:237 ../../tips.rst:243
#: 4e21f78e86f049048a800ddd5c51e230 618fd4eb66ff45b29c98df87b145613c
#: 93083ab6eb974293820f40d16349c100 9684f50652484820b924109f31418cd7
#: 9df48660f1a84fe1af952256c7b58aec cef3fc9239d941969fda711c74994d8c
#: d09fff93593844cfbb0b270b4cd74193
msgid "string"
msgstr "string"
#: ../../tips.rst:216 f867df810054493f9d6be16271822ddb
msgid "``requirements``"
msgstr "``requirements``"
#: ../../tips.rst:216 ../../tips.rst:223 ../../tips.rst:227 ../../tips.rst:231
#: ../../tips.rst:237 ../../tips.rst:243 019e197dd56b44229549da7a2421ce37
#: 636f76c7f1ca4c61bcea4bbe39a4eb1f 671a0ff87e294e7ab0ac8cdf70fdfe1d
#: 848f43cf99c447a595f4760e2cf25f2b b425d772694640d0a7bae06c236fa1a2
#: d145c924e4f348f5ad24b51286ce61e6
msgid "No"
msgstr "否"
#: ../../tips.rst:216 0d5ee9c193994b2cac7757e881f01a42
msgid ""
"The Python requirements to install, for example to enable markdown and "
"typogrify use: ``\"pelican[markdown] typogrify\"`` or if you have a "
"requirements file: ``\"-r requirements.txt\"``"
msgstr ""
"需要安装的Python模块，例如要开启markdown和typogrify，可指定 ``\"pelican[markdown] "
"typogrify\"`` ，或者可以指定一个requirements文件： ``\"-r requirements.txt\"`` "
#: ../../tips.rst:216 67298d60de17486dbc1b6841f2c433b9
msgid "``\"pelican\"``"
msgstr "``\"pelican\"``"
#: ../../tips.rst:223 219a8d185ac440329e8aa7306e55e708
msgid "``output-path``"
msgstr "``output-path``"
#: ../../tips.rst:223 21a3530e340349afa64d7eb69b393c98
msgid "Where to output the generated files (``pelican``'s ``--output`` option)"
msgstr "生成文件的输出位置（会被用于 ``pelican`` 命令的 ``--output`` 选项）"
#: ../../tips.rst:223 dea97da0dfc24941b8850d1d26ea3cd3
msgid "``\"output/\"``"
msgstr "``\"output/\"``"
#: ../../tips.rst:227 688ac4687d7841629137bf97ce97deee
msgid "``theme``"
msgstr "``theme``"
#: ../../tips.rst:227 2c2e6b6d8a6044c0ba64d00ea1b12d40
msgid ""
"The GitHub repo URL of a custom theme to use, for example: "
"``\"https://github.com/seanh/sidecar.git\"``"
msgstr ""
"要使用的自定义主题的GitHub仓库URL，例如： ``\"https://github.com/seanh/"
"sidecar.git\"``"
#: ../../tips.rst:227 bd63884f7e60412d9a6cccc5da9c47ac
msgid "``\"\"``"
msgstr "``\"\"``"
#: ../../tips.rst:231 9527d9e89d704210baff0bb6e3e23b20
msgid "``python``"
msgstr "``python``"
#: ../../tips.rst:231 1aa44193e62647c0ba275507ea84b42c
msgid ""
"The version of Python to use to build the site, 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)"
msgstr ""
"构建站点时使用的Python版本，例如： ``\"3.12\"`` 或 ``\"3.12.1\"``"
#: ../../tips.rst:231 d182ae2dd44c482fb3f2373a7d97087c
msgid "``\"3.12\"``"
msgstr "``\"3.12\"``"
#: ../../tips.rst:237 dc65b4e578e24d179c38066871c2c572
msgid "``siteurl``"
msgstr "``siteurl``"
#: ../../tips.rst:237 5909de5d60224c7b875753f88fd13296
msgid ""
"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."
msgstr ""
"站点的基URL，会用于配置项 ``SITEURL`` 。若未指定，默认值为GitHub Pages站点"
"的URL，这适用于大部分情况。"
#: ../../tips.rst:237 ../../tips.rst:243 0c0b86aa4b984615afb3564b76e379ff
#: c7ddd6347a7f4467b31aaa8f4d4a2309
msgid "The URL of your GitHub Pages site."
msgstr "GitHub Pages站点的URL"
#: ../../tips.rst:243 af7d2b52c5504ac2b69490a18d14f80f
msgid "``feed_domain``"
msgstr "``feed_domain``"
#: ../../tips.rst:243 2cc126862a8047c286381aa258aad013
msgid ""
"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."
msgstr ""
"订阅源URL前要附加的域名，会用于配置项 ``FEED_DOMAIN`` 。若未指定，默认值为"
"GitHub Pages站点的URL，这适用于大部分情况。"
#: ../../tips.rst:252 b86ab8a1fa24447d99becc592411010e
msgid "\"Insecure content\" warnings from browsers"
msgstr "浏览器报“不安全的内容（Insecure content）”警告"
#: ../../tips.rst:254 c81d5f8889c14a069e55fe7472a238f2
msgid ""
"If your site uses ``https://`` and is broken because the browser is "
"blocking network requests (for example for CSS files) due to \"insecure "
"content\" this may be because GitHub Pages is generating ``http://`` URLs"
" for your site."
msgstr ""
"当站点使用 ``https://`` 时，可能会损坏，无法正常显示，这是由于浏览器阻拦了一些"
"对“不安全内容”的网络请求。可能的原因之一是GitHub Pages给你的站点生成了 ``http://`` "
"URL。"
#: ../../tips.rst:258 2a53f882b7e645149d18ce81757b9758
msgid ""
"To fix this go into your site repo's settings and enable the **Enforce "
"HTTPS** setting: go to **Settings → Pages** and check **Enforce HTTPS**. "
"Then re-run the workflow to re-deploy your site. Alternatively, you can "
"use the workflow's ``siteurl`` and ``feed_domain`` settings."
msgstr ""
"要想解决这一问题，需要为站点所在仓库开启 **强制使用HTTPS** ：点击 **Settings → Pages** "
"并在其中勾选 **Enforce HTTPS** ，接着再重新执行工作流以重新部署站点。也可以尝试"
"通过配置 ``siteurl`` 与 ``feed_domain`` 解决问题。"
#: ../../tips.rst:266 483cbd21e61841d983e2ecc8bc3006bc
msgid ""
"GitHub Pages will display the custom 404 page described above, as noted "
"in the relevant `GitHub docs "
"<https://help.github.com/articles/custom-404-pages/>`_."
msgstr ""
"如果按前述进行配置，GitHub Pages是能够正确显示自定义的404页面的，相关内容在 "
"`GitHub的文档中 <https://help.github.com/articles/custom-404-pages/>`_ 也有提到。"
#: ../../tips.rst:270 6b54e9c354f34e1f9a5a3f50d96b98c3
msgid "Update your site on each commit"
msgstr "在每次commit后都更新站点"
#: ../../tips.rst:272 2e83c0c761c94f35ae3056634d8f1552
msgid ""
"To automatically update your Pelican site on each commit, you can create "
"a post-commit hook. For example, you can add the following to "
"``.git/hooks/post-commit``::"
msgstr ""
"要想在每次commit后自动更新Pelican站点，你可以创建一个post-commit钩子。例如，"
"可以将下面的内容保存为 ``.git/hooks/post-commit`` ："
#: ../../tips.rst:279 528589366e634f15bb0a702969715286
msgid "Copy static files to the root of your site"
msgstr "将静态文件拷贝到站点根目录"
#: ../../tips.rst:281 dc4267653ef04722a0583915c05b6c88
msgid ""
"To use a `custom domain <https://help.github.com/articles/setting-up-a"
"-custom-domain-with-pages>`_ with GitHub Pages, you need to put the "
"domain of your site (e.g., ``blog.example.com``) inside a ``CNAME`` file "
"at the root of your site. To do this, create the ``content/extra/`` "
"directory and add a ``CNAME`` file to it. Then use the ``STATIC_PATHS`` "
"setting to tell Pelican to copy this file to your output directory. For "
"example::"
msgstr ""
"要将 `自定义域名 <https://help.github.com/articles/setting-up-a-custom-domain-"
"with-pages>`_ 与GitHub Pages一起使用，需要将站点的域名（例如 ``blog.example.com`` "
"）添加到站点根目录的 ``CNAME`` 文件中。为此，请创建 ``content/extra/`` 目录，并在里面添加一个 ``CNAME`` "
"文件。然后使用Pelican的 ``STATIC_PATHS`` 来告诉Pelican将此文件复制到输出目录："
#: ../../tips.rst:292 5fcdc283f55f4d8ca121cb6438c67a36
msgid "Note: use forward slashes, ``/``, even on Windows."
msgstr "请注意：务必使用正斜杠 ``/`` ，在Windows上也是。"
#: ../../tips.rst:294 326a40a1536c462ea4974ce4b560f54c
msgid ""
"You can also use the ``EXTRA_PATH_METADATA`` mechanism to place a "
"``favicon.ico`` or ``robots.txt`` at the root of any site."
msgstr ""
"利用 ``EXTRA_PATH_METADATA`` 机制，你可以将 ``favicon.ico`` 或 ``robots.txt`` "
"也拷贝到站点的根目录下。"
#: ../../tips.rst:298 4e589caa6f17438aae1d1a12819c6ef2
msgid "How to add YouTube or Vimeo Videos"
msgstr "如何添加YouTube或Vimeo视频"
#: ../../tips.rst:300 5f60f033a7084739af5ef0dce5b91197
msgid ""
"The easiest way is to paste the embed code of the video from these sites "
"directly into your source content."
msgstr ""
"最简单的方法是将这些网站的视频嵌入代码直接粘贴到您的源内容文件中。"
#: ../../tips.rst:303 5446d02bebc241e88cc30b484799696c
msgid ""
"Alternatively, you can also use Pelican plugins like ``liquid_tags``, "
"``pelican_youtube``, or ``pelican_vimeo`` to embed videos in your "
"content."
msgstr ""
"或者，您还可以使用例如 ``liquid_tags`` 、``pelican_youtube`` 或 ``pelican_vimeo`` "
"等Pelican插件将视频嵌入。"
#: ../../tips.rst:306 c871fab4a3424b0dba84c1af24f6405f
msgid ""
"Moreover, markup languages like reST and Markdown have plugins that let "
"you embed videos in the markup. You can use `reST video directive "
"<https://gist.github.com/dbrgn/2922648>`_ for reST or `mdx_video plugin "
"<https://github.com/italomaia/mdx-video>`_ for Markdown."
msgstr ""
"此外，像reST和 Markdown这样的标记语言都有对应插件可以让你在其中嵌入视频。"
"可以使用 `reST的视频指令 <https://gist.github.com/dbrgn/2922648>`_ 或者 "
"`Markdown的mdx_video插件 <https://github.com/italomaia/mdx-video>`_ 。"
#: ../../tips.rst:313 569b7609cb9d412e942001da7c4a704c
msgid "Develop Locally Using SSL"
msgstr "在本地使用SSL进行开发"
#: ../../tips.rst:315 e66f6f1cacc4466682461d251aedb929
msgid "Here's how you can set up your local pelican server to support SSL."
msgstr "以下描述了如何在本地Pelican服务器上配置SSL。"
#: ../../tips.rst:317 138c34c1b6804246b79fda266a1fd937
msgid ""
"First, create a self-signed certificate and key using ``openssl`` (this "
"creates ``cert.pem`` and ``key.pem``)::"
msgstr ""
"首先，通过 ``openssl`` 创建自签名的证书和密钥，这会生成 ``cert.pem`` 和 "
"``key.pem`` 文件："
#: ../../tips.rst:321 ac189182bc694bcaa94cd935311f4492
msgid ""
"And use this command to launch the server (the server starts within your "
"``output`` directory)::"
msgstr ""
"接着使用下面的命令来开启服务器（此服务器会在 ``output`` 目录下开启）："
#: ../../tips.rst:325 88a33744d69f4f5bbc4a43024c43d3a0
msgid "If you are using ``develop-server.sh``, add this to the top::"
msgstr "如果你使用的是 ``develop-server.sh`` 脚本，在脚本的开头添加："
#: ../../tips.rst:330 9a783977fe814657b8590185af281b1e
msgid "and modify the ``pelican.server`` line as follows::"
msgstr "然后修改按照下述修改 ``pelican.server`` 一行："
#~ msgid ""
#~ "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 your "
#~ "``<username>.github.io`` repository on GitHub."
#~ msgstr ""
#~ msgid ""
#~ "The ``git push`` command pushes the "
#~ "local ``gh-pages`` branch (freshly "
#~ "updated by the ``ghp-import`` command)"
#~ " to the ``elemoine.github.io`` repository's "
#~ "``master`` branch on GitHub."
#~ msgstr ""
#~ msgid ""
#~ "Now you can push the whole project"
#~ " ``<username>.github.io`` to the master "
#~ "branch of your GitHub repository::"
#~ msgstr ""
#~ msgid ""
#~ "Pelican-powered sites can be published"
#~ " to GitHub Pages via a `custom "
#~ "workflow "
#~ "<https://github.com/getpelican/pelican/blob/master/.github/workflows/github_pages.yml>`_."
#~ " To use it:"
#~ msgstr ""
#~ msgid ""
#~ "You may want to replace the "
#~ "``@master`` with the ID of a "
#~ "specific commit in this repo in "
#~ "order to pin the version of the"
#~ " reusable workflow that you're using: "
#~ "``uses: "
#~ "getpelican/pelican/.github/workflows/github_pages.yml@<COMMIT_ID>``."
#~ " If you do this you might want"
#~ " to get Dependabot to send you "
#~ "automated pull requests to update that"
#~ " commit ID whenever new versions of"
#~ " this workflow are published, like "
#~ "so:"
#~ msgstr ""

170
docs/pelican-themes.rst
View file

@ -1,170 +0,0 @@
pelican-themes
##############
Description
===========
``pelican-themes`` is a command line tool for managing themes for Pelican. See
:ref:`settings/themes` for settings related to themes.
Usage
"""""
| pelican-themes [-h] [-l] [-i theme path [theme path ...]]
| [-r theme name [theme name ...]]
| [-s theme path [theme path ...]] [-v] [--version]
Optional arguments:
"""""""""""""""""""
-h, --help Show the help and exit
-l, --list Show the themes already installed
-i theme_path, --install theme_path One or more themes to install
-r theme_name, --remove theme_name One or more themes to remove
-s theme_path, --symlink theme_path Same as ``--install``, but create a symbolic link instead of copying the theme.
Useful for theme development
-v, --verbose Verbose output
--version Print the version of this script
Examples
========
Listing the installed themes
""""""""""""""""""""""""""""
With ``pelican-themes``, you can see the available themes by using the ``-l``
or ``--list`` option:
.. code-block:: console
$ pelican-themes -l
notmyidea
two-column@
simple
$ pelican-themes --list
notmyidea
two-column@
simple
In this example, we can see there are three themes available: ``notmyidea``,
``simple``, and ``two-column``.
``two-column`` is followed by an ``@`` because this theme is not copied to
the Pelican theme path, but is instead just linked to it (see `Creating
symbolic links`_ for details about creating symbolic links).
Note that you can combine the ``--list`` option with the ``-v`` or
``--verbose`` option to get more verbose output, like this:
.. code-block:: console
$ pelican-themes -v -l
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/simple
Installing themes
"""""""""""""""""
You can install one or more themes using the ``-i`` or ``--install`` option.
This option takes as argument the path(s) of the theme(s) you want to install,
and can be combined with the ``--verbose`` option:
.. code-block:: console
# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms --verbose
.. code-block:: console
# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms\
~/Dev/Python/pelican-themes/martyalchin \
--verbose
.. code-block:: console
# pelican-themes -vi ~/Dev/Python/pelican-themes/two-column
Removing themes
"""""""""""""""
The ``pelican-themes`` command can also remove themes from the Pelican themes
path. The ``-r`` or ``--remove`` option takes as argument the name(s) of the
theme(s) you want to remove, and can be combined with the ``--verbose`` option.
.. code-block:: console
# pelican-themes --remove two-column
.. code-block:: console
# pelican-themes -r martyachin notmyidea-cmd -v
Creating symbolic links
"""""""""""""""""""""""
``pelican-themes`` can also install themes by creating symbolic links instead
of copying entire themes into the Pelican themes path.
To symbolically link a theme, you can use the ``-s`` or ``--symlink``, which
works exactly as the ``--install`` option:
.. code-block:: console
# pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column
In this example, the ``two-column`` theme is now symbolically linked to the
Pelican themes path, so we can use it, but we can also modify it without having
to reinstall it after each modification.
This is useful for theme development:
.. code-block:: console
$ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ firefox /tmp/out/index.html
$ vim ~/Dev/Pelican/pelican-themes/two-column/static/css/main.css
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-column/static/img/bg.png
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ vim ~/Dev/Pelican/pelican-themes/two-column/templates/index.html
$ pelican ~/Blog/content -o /tmp/out -t two-column
Doing several things at once
""""""""""""""""""""""""""""
The ``--install``, ``--remove`` and ``--symlink`` options are not mutually
exclusive, so you can combine them in the same command line to do more than one
operation at time, like this:
.. code-block:: console
# pelican-themes --remove notmyidea-cms two-column \
--install ~/Dev/Python/pelican-themes/notmyidea-cms-fr \
--symlink ~/Dev/Python/pelican-themes/two-column \
--verbose
In this example, the theme ``notmyidea-cms`` is replaced by the theme
``notmyidea-cms-fr``

346
docs/plugins.rst
View file

@ -1,346 +0,0 @@
.. _plugins:
Plugins
#######
Beginning with version 3.0, Pelican supports plugins. Plugins are a way to add
features to Pelican without having to directly modify the Pelican core.
How to use plugins
==================
Starting with version 4.5, Pelican moved to a new plugin structure utilizing
namespace packages that can be easily installed via Pip_. Plugins supporting
this structure will install under the namespace package ``pelican.plugins`` and
can be automatically discovered by Pelican. To see a list of Pip-installed
namespace plugins that are active in your environment, run::
pelican-plugins
If you leave the ``PLUGINS`` setting as default (``None``), Pelican will
automatically discover namespace plugins and register them. If, on the other
hand, you specify a ``PLUGINS`` setting as a list of plugins, this
auto-discovery will be disabled. At that point, only the plugins you specify
will be registered, and you must explicitly list any namespace plugins as well.
If you are using the ``PLUGINS`` setting, you can specify plugins in two ways.
The first method specifies plugins as a list of strings. Namespace plugins can
be specified either by their full names (``pelican.plugins.myplugin``) or by
their short names (``myplugin``)::
PLUGINS = ['package.myplugin',
'namespace_plugin1',
'pelican.plugins.namespace_plugin2']
Alternatively, you can import them in your settings file and pass the modules::
from package import myplugin
from pelican.plugins import namespace_plugin1, namespace_plugin2
PLUGINS = [myplugin, namespace_plugin1, namespace_plugin2]
.. note::
When experimenting with different plugins (especially the ones that deal
with metadata and content) caching may interfere and the changes may not be
visible. In such cases disable caching with ``LOAD_CONTENT_CACHE = False``
or use the ``--ignore-cache`` command-line switch.
If your plugins are not in an importable path, you can specify a list of paths
via the ``PLUGIN_PATHS`` setting. As shown in the following example, paths in
the ``PLUGIN_PATHS`` list can be absolute or relative to the settings file::
PLUGIN_PATHS = ["plugins", "/srv/pelican/plugins"]
PLUGINS = ["assets", "liquid_tags", "sitemap"]
Where to find plugins
=====================
Namespace plugins can be found in the `pelican-plugins organization`_ as
individual repositories. Legacy plugins are located in the `pelican-plugins
repository`_ and will be gradually phased out in favor of the namespace
versions.
.. _pelican-plugins organization: https://github.com/pelican-plugins
.. _pelican-plugins repository: https://github.com/getpelican/pelican-plugins
Please note that while we do our best to review and maintain these plugins,
they are submitted by the Pelican community and thus may have varying levels of
support and interoperability.
How to create plugins
=====================
Plugins are based on the concept of signals. Pelican sends signals, and plugins
subscribe to those signals. The list of available signals is documented in a
subsequent section.
The only rule to follow for plugins is to define a ``register`` callable, in
which you map the signals to your plugin logic. Let's take a simple example::
import logging
from pelican import signals
log = logging.getLogger(__name__)
def test(sender):
log.debug("%s initialized !!", sender)
def register():
signals.initialized.connect(test)
.. note::
Signal receivers are weakly-referenced and thus must not be defined within
your ``register`` callable or they will be garbage-collected before the
signal is emitted.
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
--------------------------
Namespace plugins must adhere to a certain structure in order to function
properly. They need to be installable (i.e. contain ``setup.py`` or equivalent)
and have a folder structure as follows::
myplugin
├── pelican
│   └── plugins
│   └── myplugin
│   ├── __init__.py
│   └── ...
├── ...
└── setup.py
It is crucial that ``pelican`` or ``pelican/plugins`` folder **not**
contain an ``__init__.py`` file. In fact, it is best to have those folders
empty besides the listed folders in the above structure and keep your
plugin related files contained solely in the ``pelican/plugins/myplugin``
folder to avoid any issues.
To easily set up the proper structure, a `cookiecutter template for plugins`_
is provided. Refer to that project's README for instructions on how to use it.
.. _cookiecutter template for plugins: https://github.com/getpelican/cookiecutter-pelican-plugin
List of signals
===============
Here is the list of currently implemented signals:
================================= ============================ ===========================================================================
Signal Arguments Description
================================= ============================ ===========================================================================
initialized pelican object
finalized pelican object invoked after all the generators are executed and just before pelican exits
useful for custom post processing actions, such as:
- minifying js/css assets.
- notify/ping search engines with an updated sitemap.
generator_init generator invoked in the Generator.__init__
all_generators_finalized generators invoked after all the generators are executed and before writing output
readers_init readers invoked in the Readers.__init__
article_generator_context article_generator, metadata
article_generator_preread article_generator invoked before a article is read in ArticlesGenerator.generate_context;
use if code needs to do something before every article is parsed
article_generator_init article_generator invoked in the ArticlesGenerator.__init__
article_generator_pretaxonomy article_generator invoked before categories and tags lists are created
useful when e.g. modifying the list of articles to be generated
so that removed articles are not leaked in categories or tags
article_generator_finalized article_generator invoked at the end of ArticlesGenerator.generate_context
article_generator_write_article article_generator, content invoked before writing each article, the article is passed as content
article_writer_finalized article_generator, writer invoked after all articles and related pages have been written, but before
the article generator is closed.
get_generators pelican object invoked in Pelican.get_generator_classes,
can return a Generator, or several
generators in a tuple or in a list.
get_writer pelican object invoked in Pelican.get_writer,
can return a custom Writer.
page_generator_context page_generator, metadata
page_generator_preread page_generator invoked before a page is read in PageGenerator.generate_context;
use if code needs to do something before every page is parsed.
page_generator_init page_generator invoked in the PagesGenerator.__init__
page_generator_finalized page_generator invoked at the end of PagesGenerator.generate_context
page_generator_write_page page_generator, content invoked before writing each page, the page is passed as content
page_writer_finalized page_generator, writer invoked after all pages have been written, but before the page generator
is closed.
static_generator_context static_generator, metadata
static_generator_preread static_generator invoked before a static file is read in StaticGenerator.generate_context;
use if code needs to do something before every static file is added to the
staticfiles list.
static_generator_init static_generator invoked in the StaticGenerator.__init__
static_generator_finalized static_generator invoked at the end of StaticGenerator.generate_context
content_object_init content_object invoked at the end of Content.__init__
content_written path, context invoked each time a content file is written.
feed_generated context, feed invoked each time a feed gets generated. Can be used to modify a feed
object before it gets written.
feed_written path, context, feed invoked each time a feed file is written.
================================= ============================ ===========================================================================
.. warning::
Avoid ``content_object_init`` signal if you intend to read ``summary`` or
``content`` properties of the content object. That combination can result in
unresolved links when :ref:`ref-linking-to-internal-content` (see
`pelican-plugins bug #314`_). Use ``_summary`` and ``_content`` properties
instead, or, alternatively, run your plugin at a later stage (e.g.
``all_generators_finalized``).
.. note::
After Pelican 3.2, signal names were standardized. Older plugins may need
to be updated to use the new names:
========================== ===========================
Old name New name
========================== ===========================
article_generate_context article_generator_context
article_generate_finalized article_generator_finalized
article_generate_preread article_generator_preread
pages_generate_context page_generator_context
pages_generate_preread page_generator_preread
pages_generator_finalized page_generator_finalized
pages_generator_init page_generator_init
static_generate_context static_generator_context
static_generate_preread static_generator_preread
========================== ===========================
Recipes
=======
We eventually realised some of the recipes to create plugins would be best
shared in the documentation somewhere, so here they are!
How to create a new reader
--------------------------
One thing you might want is to add support for your very own input format.
While it might make sense to add this feature in Pelican core, we wisely chose
to avoid this situation and instead have the different readers defined via
plugins.
The rationale behind this choice is mainly that plugins are really easy to
write and don't slow down Pelican itself when they're not active.
No more talking — here is an example::
from pelican import signals
from pelican.readers import BaseReader
# Create a new reader class, inheriting from the pelican.reader.BaseReader
class NewReader(BaseReader):
enabled = True # Yeah, you probably want that :-)
# The list of file extensions you want this reader to match with.
# If multiple readers were to use the same extension, the latest will
# win (so the one you're defining here, most probably).
file_extensions = ['yeah']
# You need to have a read method, which takes a filename and returns
# some content and the associated metadata.
def read(self, filename):
metadata = {'title': 'Oh yeah',
'category': 'Foo',
'date': '2012-12-01'}
parsed = {}
for key, value in metadata.items():
parsed[key] = self.process_metadata(key, value)
return "Some content", parsed
def add_reader(readers):
readers.reader_classes['yeah'] = NewReader
# This is how pelican works.
def register():
signals.readers_init.connect(add_reader)
Adding a new generator
----------------------
Adding a new generator is also really easy. You might want to have a look at
:doc:`internals` for more information on how to create your own generator.
::
def get_generators(pelican_object):
# define a new generator here if you need to
return MyGenerator
def register():
signals.get_generators.connect(get_generators)
Adding a new writer
-------------------
Adding a writer will allow you to output additional file formats to disk, or
change how the existing formats are written to disk. Note that only one writer
will be active at a time, so be sure to either subclass the built-in Writer, or
completely re-implement it.
Here is a basic example of how to set up your own writer::
from pelican.writers import Writer
from pelican import signals
class MyWriter(Writer):
# define new writer functionality
pass
def add_writer(pelican_object):
# use pelican_instance to setup stuff if needed
return MyWriter
def register():
signals.get_writer.connect(add_writer)
Using Plugins to Inject Content
-------------------------------
You can programmatically inject articles or pages using plugins. This can be
useful if you plan to fetch articles from an API, for example.
Following is a simple example of how one can build a plugin that injects a
custom article, using the ``article_generator_pretaxonomy`` signal::
import datetime
from pelican import signals
from pelican.contents import Article
from pelican.readers import BaseReader
def addArticle(articleGenerator):
settings = articleGenerator.settings
# Author, category, and tags are objects, not strings, so they need to
# be handled using BaseReader's process_metadata() function.
baseReader = BaseReader(settings)
content = "I am the body of an injected article!"
newArticle = Article(content, {
"title": "Injected Article!",
"date": datetime.datetime.now(),
"category": baseReader.process_metadata("category", "fromAPI"),
"tags": baseReader.process_metadata("tags", "tagA, tagB")
})
articleGenerator.articles.insert(0, newArticle)
def register():
signals.article_generator_pretaxonomy.connect(addArticle)
.. _Pip: https://pip.pypa.io/
.. _pelican-plugins bug #314: https://github.com/getpelican/pelican-plugins/issues/314

198
docs/publish.rst
View file

@ -1,198 +0,0 @@
Publish your site
#################
.. _site_generation:
Site generation
===============
Once Pelican is installed and you have some content (e.g., in Markdown or reST
format), you can convert your content into HTML via the ``pelican`` command,
specifying the path to your content and (optionally) the path to your
:doc:`settings<settings>` file::
pelican /path/to/your/content/ [-s path/to/your/settings.py]
The above command will generate your site and save it in the ``output/``
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.
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
environments, this option can also be combined with the ``-l`` or ``--listen``
option to simultaneously both auto-regenerate *and* serve the output at
http://localhost:8000::
pelican --autoreload --listen
Pelican has other command-line switches available. Have a look at the help to
see all the options you can use::
pelican --help
Viewing the generated files
---------------------------
The files generated by Pelican are static files, so you don't actually need
anything special to view them. You can use your browser to open the generated
HTML files directly::
firefox output/index.html
Because the above method may have trouble locating your CSS and other linked
assets, running Pelican's simple built-in web server will often provide a more
reliable previewing experience::
pelican --listen
Once the web server has been started, you can preview your site at:
http://localhost:8000/
Deployment
==========
After you have generated your site, previewed it in your local development
environment, and are ready to deploy it to production, you might first
re-generate your site with any production-specific settings (e.g., analytics,
feeds, etc.) that you may have defined::
pelican content -s publishconf.py
To base your publish configuration on top of your ``pelicanconf.py``, you can
import your ``pelicanconf`` settings by including the following line in your
``publishconf.py``::
from pelicanconf import *
If you have generated a ``publishconf.py`` using ``pelican-quickstart``, this
line is included by default.
The steps for deploying your site will depend on where it will be hosted. If
you have SSH access to a server running Nginx or Apache, you might use the
``rsync`` tool to transmit your site files::
rsync -avc --delete output/ host.example.com:/var/www/your-site/
There are many other deployment options, some of which can be configured when
first setting up your site via the ``pelican-quickstart`` command. See the
:doc:`Tips<tips>` page for detail on publishing via GitHub Pages.
Automation
==========
While the ``pelican`` command is the canonical way to generate your site,
automation tools can be used to streamline the generation and publication flow.
One of the questions asked during the ``pelican-quickstart`` process pertains
to whether you want to automate site generation and publication. If you
answered "yes" to that question, a ``tasks.py`` and ``Makefile`` will be
generated in the root of your project. These files, pre-populated with certain
information gleaned from other answers provided during the
``pelican-quickstart`` process, are meant as a starting point and should be
customized to fit your particular needs and usage patterns. If you find one or
both of these automation tools to be of limited utility, these files can
be deleted at any time and will not affect usage of the canonical ``pelican``
command.
Following are automation tools that "wrap" the ``pelican`` command and can
simplify the process of generating, previewing, and uploading your site.
Invoke
------
The advantage of Invoke_ is that it is written in Python and thus can be used
in a wide range of environments. The downside is that it must be installed
separately. Use the following command to install Invoke, prefixing with
``sudo`` if your environment requires it::
python -m pip install invoke
Take a moment to open the ``tasks.py`` file that was generated in your project
root. You will see a number of commands, any one of which can be renamed,
removed, and/or customized to your liking. Using the out-of-the-box
configuration, you can generate your site via::
invoke build
If you'd prefer to have Pelican automatically regenerate your site every time a
change is detected (which is handy when testing locally), use the following
command instead::
invoke regenerate
To serve the generated site so it can be previewed in your browser at
http://localhost:8000/::
invoke serve
To serve the generated site with automatic browser reloading every time a
change is detected, first ``python -m pip install livereload``, then use the
following command::
invoke livereload
If during the ``pelican-quickstart`` process you answered "yes" when asked
whether you want to upload your site via SSH, you can use the following command
to publish your site via rsync over SSH::
invoke publish
These are just a few of the commands available by default, so feel free to
explore ``tasks.py`` and see what other commands are available. More
importantly, don't hesitate to customize ``tasks.py`` to suit your specific
needs and preferences.
Make
----
A ``Makefile`` is also automatically created for you when you say "yes" to the
relevant question during the ``pelican-quickstart`` process. The advantage of
this method is that the ``make`` command is built into most POSIX systems and
thus doesn't require installing anything else in order to use it. The downside
is that non-POSIX systems (e.g., Windows) do not include ``make``, and
installing it on those systems can be a non-trivial task.
If you want to use ``make`` to generate your site using the settings in
``pelicanconf.py``, run::
make html
To generate the site for production, using the settings in ``publishconf.py``,
run::
make publish
If you'd prefer to have Pelican automatically regenerate your site every time a
change is detected (which is handy when testing locally), use the following
command instead::
make regenerate
To serve the generated site so it can be previewed in your browser at
http://localhost:8000/::
make serve
Normally you would need to run ``make regenerate`` and ``make serve`` in two
separate terminal sessions, but you can run both at once via::
make devserver
The above command will simultaneously run Pelican in regeneration mode as well
as serve the output at http://localhost:8000.
When you're ready to publish your site, you can upload it via the method(s) you
chose during the ``pelican-quickstart`` questionnaire. For this example, we'll
use rsync over ssh::
make rsync_upload
That's it! Your site should now be live.
(The default ``Makefile`` and ``devserver.sh`` scripts use the ``python`` and
``pelican`` executables to complete its tasks. If you want to use different
executables, such as ``python3``, you can set the ``PY`` and ``PELICAN``
environment variables, respectively, to override the default executable names.)
.. _Invoke: https://www.pyinvoke.org/

82
docs/quickstart.rst
View file

@ -1,82 +0,0 @@
Quickstart
##########
Reading through all the documentation is highly recommended, but for the truly
impatient, following are some quick steps to get started.
Installation
------------
Install Pelican (and optionally Markdown if you intend to use it) on Python
|min_python| by running the following command in your preferred terminal, prefixing
with ``sudo`` if permissions warrant::
python -m pip install "pelican[markdown]"
Create a project
----------------
First, choose a name for your project, create an appropriately-named directory
for your site, and switch to that directory::
mkdir -p ~/projects/yoursite
cd ~/projects/yoursite
Create a skeleton project via the ``pelican-quickstart`` command, which begins
by asking some questions about your site::
pelican-quickstart
For questions that have default values denoted in brackets, feel free to use
the Return key to accept those default values [#tzlocal_fn]_. When asked for
your URL prefix, enter your domain name as indicated (e.g.,
``https://example.com``).
Create an article
-----------------
You cannot run Pelican until you have created some content. Use your preferred
text editor to create your first article with the following content::
Title: My First Review
Date: 2010-12-03 10:20
Category: Review
Following is a review of my favorite mechanical keyboard.
Given that this example article is in Markdown format, save it as
``~/projects/yoursite/content/keyboard-review.md``.
Generate your site
------------------
From your project root directory, run the ``pelican`` command to generate your site::
pelican content
Your site has now been generated inside the ``output/`` directory. (You may see
a warning related to feeds, but that is normal when developing locally and can
be ignored for now.)
Preview your site
-----------------
Open a new terminal session, navigate to your project root directory, and
run the following command to launch Pelican's web server::
pelican --listen
Preview your site by navigating to http://localhost:8000/ in your browser.
Continue reading the other documentation sections for more detail, and check
out the Pelican wiki's Tutorials_ page for links to community-published
tutorials.
.. _Tutorials: https://github.com/getpelican/pelican/wiki/Tutorials
Footnotes
---------
.. [#tzlocal_fn] You can help localize default fields by installing the
optional `tzlocal <https://pypi.org/project/tzlocal/>`_
module.

114
docs/report.rst
View file

@ -1,114 +0,0 @@
Some history about Pelican
##########################
.. warning::
This page comes from a report the original author (Alexis Métaireau) wrote
right after writing Pelican, in December 2010. The information may not be
up-to-date.
Pelican is a simple static blog generator. It parses markup files (Markdown or
reStructuredText for now) and generates an HTML folder with all the files in
it. I've chosen to use Python to implement Pelican because it seemed to be
simple and to fit to my needs. I did not wanted to define a class for each
thing, but still wanted to keep my things loosely coupled. It turns out that it
was exactly what I wanted. From time to time, thanks to the feedback of some
users, it took me a very few time to provide fixes on it. So far, I've
re-factored the Pelican code by two
times; each time took less than 30 minutes.
Use case
========
I was previously using WordPress, a solution you can host on a web server to
manage your blog. Most of the time, I prefer using markup languages such as
Markdown or reStructuredText to type my articles. To do so, I use vim. I think
it is important to let the people choose the tool they want to write the
articles. In my opinion, a blog manager should just allow you to take any kind
of input and transform it to a weblog. That's what Pelican does. You can write
your articles using the tool you want, and the markup language you want, and
then generate a static HTML weblog.
.. image:: _static/overall.png
To be flexible enough, Pelican has template support, so you can easily write
your own themes if you want to.
Design process
==============
Pelican came from a need I have. I started by creating a single file
application, and I have make it grow to support what it does by now. To start,
I wrote a piece of documentation about what I wanted to do. Then, I created the
content I wanted to parse (the reStructuredText files) and started
experimenting with the code. Pelican was 200 lines long and contained almost
ten functions and one class when it was first usable.
I have been facing different problems all over the time and wanted to add
features to Pelican while using it. The first change I have done was to add the
support of a settings file. It is possible to pass the options to the command
line, but can be tedious if there is a lot of them. In the same way, I have
added the support of different things over time: Atom feeds, multiple themes,
multiple markup support, etc. At some point, it appears that the "only one
file" mantra was not good enough for Pelican, so I decided to rework a bit all
that, and split this in multiple different files.
I’ve separated the logic in different classes and concepts:
* *writers* are responsible of all the writing process of the files.
They are responsible of writing .html files, RSS feeds and so on. Since those
operations are commonly used, the object is created once, and then passed to
the generators.
* *readers* are used to read from various formats (Markdown and
reStructuredText for now, but the system is extensible). Given a file, they
return metadata (author, tags, category, etc) and content (HTML formatted).
* *generators* generate the different outputs. For instance, Pelican
comes with an ArticlesGenerator and PagesGenerator, into others. Given a
configuration, they can do whatever you want them to do. Most of the time
it's generating files from inputs (user inputs and files).
I also deal with contents objects. They can be ``Articles``, ``Pages``,
``Quotes``, or whatever you want. They are defined in the ``contents.py``
module and represent some content to be used by the program.
In more detail
==============
Here is an overview of the classes involved in Pelican.
.. image:: _static/uml.jpg
The interface does not really exist, and I have added it only to clarify the
whole picture. I do use duck typing and not interfaces.
Internally, the following process is followed:
* First of all, the command line is parsed, and some content from the user is
used to initialize the different generator objects.
* A ``context`` is created. It contains the settings from the command line and
a settings file if provided.
* The ``generate_context`` method of each generator is called, updating
the context.
* The writer is created and given to the ``generate_output`` method of each
generator.
I make two calls because it is important that when the output is generated by
the generators, the context will not change. In other words, the first method
``generate_context`` should modify the context, whereas the second
``generate_output`` method should not.
Then, it is up to the generators to do what the want, in the
``generate_context`` and ``generate_content`` method. Taking the
``ArticlesGenerator`` class will help to understand some others concepts. Here
is what happens when calling the ``generate_context`` method:
* Read the folder “path”, looking for restructured text files, load each of
them, and construct a content object (``Article``) with it. To do so, use
``Reader`` objects.
* Update the ``context`` with all those articles.
Then, the ``generate_content`` method uses the ``context`` and the ``writer``
to generate the wanted output.

1418
docs/settings.rst
View file

File diff suppressed because it is too large Load diff

668
docs/themes.rst
View file

@ -1,668 +0,0 @@
.. _theming-pelican:
Themes
######
There is a community-managed repository of `Pelican Themes`_ for people to share
and use.
Please note that while we do our best to review and merge theme contributions,
they are submitted by the Pelican community and thus may have varying levels of
support and interoperability.
Creating Themes
~~~~~~~~~~~~~~~
To generate its HTML output, Pelican uses the `Jinja
<https://palletsprojects.com/p/jinja/>`_ templating engine due to its flexibility and
straightforward syntax. If you want to create your own theme, feel free to take
inspiration from the `"simple" theme
<https://github.com/getpelican/pelican/tree/main/pelican/themes/simple/templates>`_.
To generate your site using a theme you have created (or downloaded manually
and then modified), you can specify that theme via the ``-t`` flag::
pelican content -s pelicanconf.py -t /projects/your-site/themes/your-theme
If you'd rather not specify the theme on every invocation, you can define
``THEME`` in your settings to point to the location of your preferred theme.
Structure
=========
To make your own theme, you must follow the following structure::
├── static
│ ├── css
│ └── images
└── templates
├── archives.html // to display archives
├── article.html // processed for each article
├── author.html // processed for each author
├── authors.html // must list all the authors
├── categories.html // must list all the categories
├── category.html // processed for each category
├── index.html // the index (list all the articles)
├── page.html // processed for each page
├── period_archives.html // to display time-period archives
├── tag.html // processed for each tag
└── tags.html // must list all the tags. Can be a tag cloud.
* `static` contains all the static assets, which will be copied to the output
`theme` folder. The above filesystem layout includes CSS and image folders,
but those are just examples. Put what you need here.
* `templates` contains all the templates that will be used to generate the
content. The template files listed above are mandatory; you can add your own
templates if it helps you keep things organized while creating your theme.
.. _templates-variables:
Templates and Variables
=======================
The idea is to use a simple syntax that you can embed into your HTML pages.
This document describes which templates should exist in a theme, and which
variables will be passed to each template at generation time.
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
----------------
All of these settings will be available to all templates.
=============== ===================================================
Variable Description
=============== ===================================================
output_file The name of the file currently being generated. For
instance, when Pelican is rendering the home page,
output_file will be "index.html".
articles The list of articles, ordered descending by date.
All the elements are `Article` objects, so you can
access their attributes (e.g. title, summary, author
etc.). Sometimes this is shadowed (for instance, in
the tags page). You will then find info about it
in the `all_articles` variable.
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
all the categories and corresponding articles (values)
tags A list of (tag, articles) tuples, containing all
the tags and corresponding articles (values)
pages The list of pages
hidden_pages The list of hidden pages
draft_pages The list of draft pages
=============== ===================================================
Sorting
-------
URL wrappers (currently categories, tags, and authors), have comparison methods
that allow them to be easily sorted by name::
{% for tag, articles in tags|sort %}
If you want to sort based on different criteria, `Jinja's sort command`__ has a
number of options.
__ https://jinja.palletsprojects.com/en/latest/templates/#sort
Date Formatting
---------------
Pelican formats the date according to your settings and locale
(``DATE_FORMATS``/``DEFAULT_DATE_FORMAT``) and provides a ``locale_date``
attribute. On the other hand, the ``date`` attribute will be a `datetime`_
object. If you need custom formatting for a date different than your settings,
use the Jinja filter ``strftime`` that comes with Pelican. Usage is same as
Python `strftime`_ format, but the filter will do the right thing and format
your date according to the locale given in your settings::
{{ article.date|strftime('%d %B %Y') }}
.. _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
----------
This is the home page or index of your blog, generated at ``index.html``.
If pagination is active, subsequent pages will reside in
``index{number}.html``.
====================== ===================================================
Variable Description
====================== ===================================================
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (``None`` if page does
not exist)
articles_next_page The next page of articles (``None`` if page does
not exist)
dates_paginator A paginator object for the article list, ordered by
date, ascending.
dates_page The current page of articles, ordered by date,
ascending.
dates_previous_page The previous page of articles, ordered by date,
ascending (``None`` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (``None`` if page does not exist)
page_name 'index' -- useful for pagination links
====================== ===================================================
author.html
-------------
This template will be processed for each of the existing authors, with output
generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:`
``author/{slug}.html``). If pagination is active, subsequent pages will by
default reside at ``author/{slug}{number}.html``.
====================== ===================================================
Variable Description
====================== ===================================================
author The name of the author being processed
articles Articles by this author
dates Articles by this author, but ordered by date,
ascending
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (``None`` if page does
not exist)
articles_next_page The next page of articles (``None`` if page does
not exist)
dates_paginator A paginator object for the article list, ordered by
date, ascending.
dates_page The current page of articles, ordered by date,
ascending.
dates_previous_page The previous page of articles, ordered by date,
ascending (``None`` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (``None`` if page does not exist)
page_name AUTHOR_URL where everything after `{slug}` is
removed -- useful for pagination links
====================== ===================================================
category.html
-------------
This template will be processed for each of the existing categories, with
output generated according to the ``CATEGORY_SAVE_AS`` setting (`Default:`
``category/{slug}.html``). If pagination is active, subsequent pages will by
default reside at ``category/{slug}{number}.html``.
====================== ===================================================
Variable Description
====================== ===================================================
category The name of the category being processed
articles Articles for this category
dates Articles for this category, but ordered by date,
ascending
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (``None`` if page does
not exist)
articles_next_page The next page of articles (``None`` if page does
not exist)
dates_paginator A paginator object for the list of articles,
ordered by date, ascending
dates_page The current page of articles, ordered by date,
ascending
dates_previous_page The previous page of articles, ordered by date,
ascending (``None`` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (``None`` if page does not exist)
page_name CATEGORY_URL where everything after `{slug}` is
removed -- useful for pagination links
====================== ===================================================
article.html
-------------
This template will be processed for each article, with output generated
according to the ``ARTICLE_SAVE_AS`` setting (`Default:` ``{slug}.html``). The
following variables are available when rendering.
============= ===================================================
Variable Description
============= ===================================================
article The article object to be displayed
category The name of the category for the current article
============= ===================================================
Any metadata that you put in the header of the article source file will be
available as fields on the ``article`` object. The field name will be the same
as the name of the metadata field, except in all-lowercase characters.
For example, you could add a field called `FacebookImage` to your article
metadata, as shown below:
.. code-block:: md
Title: I love Python more than music
Date: 2013-11-06 10:06
Tags: personal, python
Category: Tech
Slug: python-je-l-aime-a-mourir
Author: Francis Cabrel
FacebookImage: http://franciscabrel.com/images/pythonlove.png
This new metadata will be made available as `article.facebookimage` in your
`article.html` template. This would allow you, for example, to specify an image
for the Facebook open graph tags that will change for each article:
.. code-block:: html+jinja
<meta property="og:image" content="{{ article.facebookimage }}"/>
page.html
---------
This template will be processed for each page, with output generated according
to the ``PAGE_SAVE_AS`` setting (`Default:` ``pages/{slug}.html``). The
following variables are available when rendering.
============= ===================================================
Variable Description
============= ===================================================
page The page object to be displayed. You can access its
title, slug, and content.
============= ===================================================
tag.html
--------
This template will be processed for each tag, with output generated according
to the ``TAG_SAVE_AS`` setting (`Default:` ``tag/{slug}.html``). If pagination
is active, subsequent pages will by default reside at
``tag/{slug}{number}.html``.
====================== ===================================================
Variable Description
====================== ===================================================
tag The name of the tag being processed
articles Articles related to this tag
dates Articles related to this tag, but ordered by date,
ascending
articles_paginator A paginator object for the list of articles
articles_page The current page of articles
articles_previous_page The previous page of articles (``None`` if page does
not exist)
articles_next_page The next page of articles (``None`` if page does
not exist)
dates_paginator A paginator object for the list of articles,
ordered by date, ascending
dates_page The current page of articles, ordered by date,
ascending
dates_previous_page The previous page of articles, ordered by date,
ascending (``None`` if page does not exist)
dates_next_page The next page of articles, ordered by date,
ascending (``None`` if page does not exist)
page_name TAG_URL where everything after `{slug}` is removed
-- useful for pagination links
====================== ===================================================
period_archives.html
--------------------
This template will be processed for each year of your posts if a path for
``YEAR_ARCHIVE_SAVE_AS`` is defined, each month if ``MONTH_ARCHIVE_SAVE_AS`` is
defined, and each day if ``DAY_ARCHIVE_SAVE_AS`` is defined.
=================== ===================================================
Variable Description
=================== ===================================================
period A tuple of the form (`year`, `month`, `day`) that
indicates the current time period. `year` and `day`
are numbers while `month` is a string. This tuple
only contains `year` if the time period is a
given year. It contains both `year` and `month`
if the time period is over years and months and
so on.
period_num A tuple of the form (``year``, ``month``, ``day``),
as in ``period``, except all values are numbers.
=================== ===================================================
You can see an example of how to use `period` in the `"simple" theme
period_archives.html template
<https://github.com/getpelican/pelican/blob/main/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
=======
Detail objects attributes that are available and useful in templates. Not all
attributes are listed here, this is a selection of attributes considered useful
in a template.
.. _object-article:
Article
-------
The string representation of an Article is the `source_path` attribute.
====================== ===================================================
Attribute Description
====================== ===================================================
author The :ref:`Author <object-author_cat_tag>` of
this article.
authors A list of :ref:`Authors <object-author_cat_tag>`
of this article.
category The :ref:`Category <object-author_cat_tag>`
of this article.
content The rendered content of the article.
date Datetime object representing the article date.
date_format Either default date format or locale date format.
default_template Default template name.
in_default_lang Boolean representing if the article is written
in the default language.
lang Language of the article.
locale_date Date formatted by the `date_format`.
metadata Article header metadata `dict`.
save_as Location to save the article page.
slug Page slug.
source_path Full system path of the article source file.
relative_source_path Relative path from PATH_ to the article source file.
status The article status, can be any of 'published' or
'draft'.
summary Rendered summary content.
tags List of :ref:`Tag <object-author_cat_tag>`
objects.
template Template name to use for rendering.
title Title of the article.
translations List of translations
:ref:`Article <object-article>` objects.
url URL to the article page.
====================== ===================================================
.. _PATH: settings.html#PATH
.. _object-author_cat_tag:
Author / Category / Tag
-----------------------
The string representation of those objects is the `name` attribute.
=================== ===================================================
Attribute Description
=================== ===================================================
name Name of this object [1]_.
page_name Author page name.
save_as Location to save the author page.
slug Page slug.
url URL to the author page.
=================== ===================================================
.. [1] for Author object, coming from `:authors:` or `AUTHOR`.
.. _object-page:
Page
----
The string representation of a Page is the `source_path` attribute.
===================== ===================================================
Attribute Description
===================== ===================================================
author The :ref:`Author <object-author_cat_tag>` of
this page.
content The rendered content of the page.
date Datetime object representing the page date.
date_format Either default date format or locale date format.
default_template Default template name.
in_default_lang Boolean representing if the article is written
in the default language.
lang Language of the article.
locale_date Date formatted by the `date_format`.
metadata Page header metadata `dict`.
save_as Location to save the page.
slug Page slug.
source_path Full system path of the page source file.
relative_source_path Relative path from PATH_ to the page source file.
status The page status, can be any of 'published', 'hidden' or
'draft'.
summary Rendered summary content.
tags List of :ref:`Tag <object-author_cat_tag>`
objects.
template Template name to use for rendering.
title Title of the page.
translations List of translations
:ref:`Article <object-article>` objects.
url URL to the page.
===================== ===================================================
.. _PATH: settings.html#PATH
Feeds
=====
The feed variables changed in 3.0. Each variable now explicitly lists ATOM or
RSS in the name. ATOM is still the default. Old themes will need to be updated.
Here is a complete list of the feed variables::
AUTHOR_FEED_ATOM
AUTHOR_FEED_RSS
CATEGORY_FEED_ATOM
CATEGORY_FEED_RSS
FEED_ALL_ATOM
FEED_ALL_RSS
FEED_ATOM
FEED_RSS
TAG_FEED_ATOM
TAG_FEED_RSS
TRANSLATION_FEED_ATOM
TRANSLATION_FEED_RSS
Inheritance
===========
Since version 3.0, Pelican supports inheritance from the ``simple`` theme, so
you can re-use the ``simple`` theme templates in your own themes.
If one of the mandatory files in the ``templates/`` directory of your theme is
missing, it will be replaced by the matching template from the ``simple``
theme. So if the HTML structure of a template in the ``simple`` theme is right
for you, you don't have to write a new template from scratch.
You can also extend templates from the ``simple`` theme in your own themes by
using the ``{% extends %}`` directive as in the following example:
.. code-block:: html+jinja
{% extends "!simple/index.html" %} <!-- extends the ``index.html`` template from the ``simple`` theme -->
{% extends "index.html" %} <!-- "regular" extending -->
Example
-------
With this system, it is possible to create a theme with just two files.
base.html
"""""""""
The first file is the ``templates/base.html`` template:
.. code-block:: html+jinja
{% extends "!simple/base.html" %}
{% block head %}
{{ super() }}
<link rel="stylesheet" type="text/css" href="{{ SITEURL }}/theme/css/style.css" />
{% endblock %}
1. On the first line, we extend the ``base.html`` template from the ``simple``
theme, so we don't have to rewrite the entire file.
2. On the third line, we open the ``head`` block which has already been defined
in the ``simple`` theme.
3. On the fourth line, the function ``super()`` keeps the content previously
inserted in the ``head`` block.
4. On the fifth line, we append a stylesheet to the page.
5. On the last line, we close the ``head`` block.
This file will be extended by all the other templates, so the stylesheet will
be linked from all pages.
style.css
"""""""""
The second file is the ``static/css/style.css`` CSS stylesheet:
.. code-block:: css
body {
font-family : monospace ;
font-size : 100% ;
background-color : white ;
color : #111 ;
width : 80% ;
min-width : 400px ;
min-height : 200px ;
padding : 1em ;
margin : 5% 10% ;
border : thin solid gray ;
border-radius : 5px ;
display : block ;
}
a:link { color : blue ; text-decoration : none ; }
a:hover { color : blue ; text-decoration : underline ; }
a:visited { color : blue ; }
h1 a { color : inherit !important }
h2 a { color : inherit !important }
h3 a { color : inherit !important }
h4 a { color : inherit !important }
h5 a { color : inherit !important }
h6 a { color : inherit !important }
pre {
margin : 2em 1em 2em 4em ;
}
#menu li {
display : inline ;
}
#post-list {
margin-bottom : 1em ;
margin-top : 1em ;
}
Download
""""""""
You can download this example theme :download:`here <_static/theme-basic.zip>`.
.. Links
.. _`Pelican Themes`: https://github.com/getpelican/pelican-themes

332
docs/tips.rst
View file

@ -1,332 +0,0 @@
Tips
####
Here are some tips about Pelican that you might find useful.
Custom 404 Pages
================
When a browser requests a resource that the web server cannot find, the web
server usually displays a generic "File not found" (404) error page that can be
stark and unsightly. One way to provide an error page that matches the theme of
your site is to create a custom 404 page (*not* an article), such as this
Markdown-formatted example stored in ``content/pages/404.md``::
Title: Not Found
Status: hidden
Save_as: 404.html
The requested item could not be located. Perhaps you might want to check
the [Archives](/archives.html)?
The next step is to configure your web server to display this custom page
instead of its default 404 page. For Nginx, add the following to your
configuration file's ``location`` block::
error_page 404 /404.html;
For Apache::
ErrorDocument 404 /404.html
For Amazon S3, first navigate to the ``Static Site Hosting`` menu in the bucket
settings on your AWS console. From there::
Error Document: 404.html
Publishing to GitHub 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>`_.
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
on GitHub.
The excellent `ghp-import <https://github.com/davisp/ghp-import>`_, which can
be installed with ``pip``, makes this process really easy.
For example, if the source of your Pelican site is contained in a GitHub
repository, and if you want to publish that Pelican site in the form of Project
Pages to this repository, you can then use the following::
$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push origin gh-pages
The ``ghp-import output`` command updates the local ``gh-pages`` branch with
the content of the ``output`` directory (creating the branch if it doesn't
already exist). The ``git push origin gh-pages`` command updates the remote
``gh-pages`` branch, effectively publishing the Pelican site.
.. note::
The ``github`` target of the Makefile (and the ``gh_pages`` task of
``tasks.py``) created by the ``pelican-quickstart`` command publishes the
Pelican site as Project Pages, as described above.
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 ``main`` branch of
your ``<username>.github.io`` repository on GitHub.
Again, you can take advantage of ``ghp-import``::
$ pelican content -o output -s pelicanconf.py
$ ghp-import output -b gh-pages
$ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:main
The ``git push`` command pushes the local ``gh-pages`` branch (freshly updated
by the ``ghp-import`` command) to the ``elemoine.github.io`` repository's
``main`` branch on GitHub.
.. note::
To publish your Pelican site as User Pages, feel free to adjust the
``github`` target of the Makefile.
Another option for publishing to User Pages is to generate the output files in
the root directory of the project.
For example, your main project folder is ``<username>.github.io`` and you can
create the Pelican project in a subdirectory called ``Pelican``. Then from
inside the ``Pelican`` folder you can run::
$ pelican content -o .. -s pelicanconf.py
Now you can push the whole project ``<username>.github.io`` to the main
branch of your GitHub repository::
$ git push origin main
(assuming origin is set to your remote repository).
Publishing to GitHub Pages Using a Custom GitHub Actions Workflow
-----------------------------------------------------------------
Pelican-powered sites can be published to GitHub Pages via a `custom workflow
<https://github.com/getpelican/pelican/blob/main/.github/workflows/github_pages.yml>`_.
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@main"
permissions:
contents: "read"
pages: "write"
id-token: "write"
with:
settings: "publishconf.py"
You may want to replace the ``@main`` with the ID of a specific commit in
this repo in order to pin the version of the reusable workflow that you're using:
``uses: getpelican/pelican/.github/workflows/github_pages.yml@<COMMIT_ID>``.
If you do this you might want to get Dependabot to send you automated pull
requests to update that commit ID whenever new versions of this workflow are
published, like so:
.. code-block:: yaml
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "monthly"
See `GitHub's docs about using Dependabot to keep your actions up to date <https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot>`_.
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`` or ``FEED_DOMAIN`` in your Pelican
settings: the workflow will set them correctly 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, for example:
.. code-block:: yaml
with:
settings: "publishconf.py"
requirements: "pelican[markdown] typogrify"
theme: "https://github.com/seanh/sidecar.git"
python: "3.12"
Here's the complete list of workflow inputs:
+------------------+----------+--------------------------------------------+--------+---------------+
| 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) | | |
+------------------+----------+--------------------------------------------+--------+---------------+
| ``theme`` | No | The GitHub repo URL of a custom | string | ``""`` |
| | | theme to use, for example: | | |
| | | ``"https://github.com/seanh/sidecar.git"`` | | |
+------------------+----------+--------------------------------------------+--------+---------------+
| ``python`` | No | The version of Python to use to build the | string | ``"3.12"`` |
| | | site, 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) | | |
+------------------+----------+--------------------------------------------+--------+---------------+
| ``siteurl`` | No | The base URL of your web site (Pelican's | string | The URL of |
| | | ``SITEURL`` setting). If not passed this | | your GitHub |
| | | will default to the URL of your GitHub | | Pages site. |
| | | Pages site, which is correct in most | | |
| | | cases. | | |
+------------------+----------+--------------------------------------------+--------+---------------+
| ``feed_domain`` | No | The domain to be prepended to feed URLs | string | The URL of |
| | | (Pelican's ``FEED_DOMAIN`` setting). If | | your GitHub |
| | | not passed this will default to the URL of | | Pages site. |
| | | your GitHub Pages site, which is correct | | |
| | | in most cases. | | |
+------------------+----------+--------------------------------------------+--------+---------------+
"Insecure content" warnings from browsers
"""""""""""""""""""""""""""""""""""""""""
If your site uses ``https://`` and is broken because the browser is blocking
network requests (for example for CSS files) due to "insecure content" this
may be because GitHub Pages is generating ``http://`` URLs for your site.
To fix this go into your site repo's settings and enable the **Enforce HTTPS** setting:
go to **Settings → Pages** and check **Enforce HTTPS**.
Then re-run the workflow to re-deploy your site.
Alternatively, you can use the workflow's ``siteurl`` and ``feed_domain`` settings.
Custom 404 Pages
----------------
GitHub Pages will display the custom 404 page described above, as noted in the
relevant `GitHub docs <https://help.github.com/articles/custom-404-pages/>`_.
Update your site on each commit
-------------------------------
To automatically update your Pelican site on each commit, you can create a
post-commit hook. For example, you can add the following to
``.git/hooks/post-commit``::
pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages
Copy static files to the root of your site
------------------------------------------
To use a `custom domain
<https://help.github.com/articles/setting-up-a-custom-domain-with-pages>`_ with
GitHub Pages, you need to put the domain of your site (e.g.,
``blog.example.com``) inside a ``CNAME`` file at the root of your site. To do
this, create the ``content/extra/`` directory and add a ``CNAME`` file to it.
Then use the ``STATIC_PATHS`` setting to tell Pelican to copy this file to your
output directory. For example::
STATIC_PATHS = ['images', 'extra/CNAME']
EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},}
Note: use forward slashes, ``/``, even on Windows.
You can also use the ``EXTRA_PATH_METADATA`` mechanism to place a
``favicon.ico`` or ``robots.txt`` at the root of any site.
How to add YouTube or Vimeo Videos
==================================
The easiest way is to paste the embed code of the video from these sites
directly into your source content.
Alternatively, you can also use Pelican plugins like ``liquid_tags``,
``pelican_youtube``, or ``pelican_vimeo`` to embed videos in your content.
Moreover, markup languages like reST and Markdown have plugins that let you
embed videos in the markup. You can use `reST video directive
<https://gist.github.com/dbrgn/2922648>`_ for reST or `mdx_video plugin
<https://github.com/italomaia/mdx-video>`_ for Markdown.
Develop Locally Using SSL
==================================
Here's how you can set up your local pelican server to support SSL.
First, create a self-signed certificate and key using ``openssl`` (this creates ``cert.pem`` and ``key.pem``)::
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
And use this command to launch the server (the server starts within your ``output`` directory)::
python -m pelican.server 8443 --key=../key.pem --cert=../cert.pem
If you are using ``develop-server.sh``, add this to the top::
CERT="$BASEDIR/cert.pem"
KEY="$BASEDIR/key.pem"
and modify the ``pelican.server`` line as follows::
$PY -m pelican.server $port --ssl --cert="$CERT" --key="$KEY" &

216
pyproject.toml
View file

@ -1,216 +0,0 @@
[project]
name = "pelican"
authors = [{ name = "Justin Mayer", email = "authors@getpelican.com" }]
description = "Static site generator supporting Markdown and reStructuredText"
version = "4.10.0"
license = { text = "AGPLv3" }
readme = "README.rst"
keywords = ["static site generator", "static sites", "ssg"]
classifiers = [
"Development Status :: 5 - Production/Stable",
"Environment :: Console",
"Framework :: Pelican",
"Intended Audience :: End Users/Desktop",
"License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: Implementation :: CPython",
"Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System",
"Topic :: Internet :: WWW/HTTP :: Site Management",
"Topic :: Software Development :: Libraries :: Python Modules",
"Topic :: Text Processing :: Markup :: Markdown",
"Topic :: Text Processing :: Markup :: HTML",
"Topic :: Text Processing :: Markup :: reStructuredText",
]
requires-python = ">=3.8.1,<4.0"
dependencies = [
"blinker>=1.7.0",
"docutils>=0.20.1",
"feedgenerator>=2.1.0",
"jinja2>=3.1.2",
"ordered-set>=4.1.0",
"pygments>=2.16.1",
"python-dateutil>=2.8.2",
"rich>=13.6.0",
"unidecode>=1.3.7",
"backports-zoneinfo>=0.2.1; python_version < \"3.9\"",
"watchfiles>=0.21.0",
"tzdata; sys_platform == 'win32'",
]
[project.optional-dependencies]
markdown = ["markdown>=3.1"]
[project.urls]
Homepage = "https://getpelican.com"
Funding = "https://donate.getpelican.com/"
"Issue Tracker" = "https://github.com/getpelican/pelican/issues"
Repository = "https://github.com/getpelican/pelican"
Documentation = "https://docs.getpelican.com"
[project.scripts]
pelican = "pelican.__main__:main"
pelican-import = "pelican.tools.pelican_import:main"
pelican-plugins = "pelican.plugins._utils:list_plugins"
pelican-quickstart = "pelican.tools.pelican_quickstart:main"
pelican-themes = "pelican.tools.pelican_themes:main"
[tool.autopub]
project-name = "Pelican"
git-username = "botpub"
git-email = "52496925+botpub@users.noreply.github.com"
changelog-file = "docs/changelog.rst"
changelog-header = "###############"
version-header = "="
[tool.pdm]
ignore_package_warnings = ["sphinx"]
[tool.pdm.scripts]
docbuild = "invoke docbuild"
docserve = "invoke docserve"
lint = "invoke lint"
test = "invoke tests"
[tool.pdm.dev-dependencies]
dev = [
"BeautifulSoup4>=4.12.2",
"jinja2>=3.1.2",
"lxml>=4.9.3",
"markdown>=3.5.1",
"typogrify>=2.0.7",
"sphinx>=7.1.2",
"sphinxext-opengraph>=0.9.0",
"furo==2023.9.10",
"livereload>=2.6.3",
"psutil>=5.9.6",
"pygments>=2.16.1",
"pytest>=7.4.3",
"pytest-cov>=4.1.0",
"pytest-sugar>=0.9.7",
"pytest-xdist>=3.4.0",
"tox>=4.11.3",
"invoke>=2.2.0",
# ruff version should match the one in .pre-commit-config.yaml
"ruff==0.4.10",
"tomli>=2.0.1; python_version < \"3.11\"",
]
[tool.pdm.build]
source-includes = [
"CONTRIBUTING.rst",
"THANKS",
"docs/changelog.rst",
"samples/",
]
[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"
[tool.ruff.lint]
# see https://docs.astral.sh/ruff/configuration/#using-pyprojecttoml
# "F" contains autoflake, see https://github.com/astral-sh/ruff/issues/1647
# add more rules
select = [
# default Ruff checkers as of ruff 0.1.3: E4, E7, E9, F
"E4",
"E7",
"E9",
"F", # pyflakes
# the rest in alphabetical order:
# TODO: "A", # flake8-builtins
# TODO: "ARG", # flake8-unused-arguments
"B", # flake8-bugbear
# TODO: "BLE", # flake8-blind-except
# TODO: Do I want "COM", # flake8-commas
"C4", # flake8-comprehensions
# TODO: "DJ", # flake8-django
# TODO: "DTZ", # flake8-datetimez
# TODO: "EM", # flake8-errmsg
"EXE", # flake8-executable
# TODO: "FURB", # refurb
# TODO: "FBT", # flake8-boolean-trap
# TODO: "G", # flake8-logging-format
"I", # isort
"ICN", # flake8-import-conventions
"INP", # flake8-no-pep420
# TODO: "INT", # flake8-gettext
"ISC", # flake8-implicit-str-concat
# TODO: "LOG", # flake8-logging
"PERF", # perflint
"PIE", # flake8-pie
"PL", # pylint
"PYI", # flake8-pyi
# TODO: "RET", # flake8-return
"RSE", # flake8-raise
"RUF",
# TODO: "SIM", # flake8-simplify
"SLF", # flake8-self
"SLOT", # flake8-slots
"TID", # flake8-tidy-imports
"UP", # pyupgrade
"Q", # flake8-quotes
"TCH", # flake8-type-checking
"T10", # flake8-debugger
"T20", # flake8-print
# TODO: "S", # flake8-bandit
"YTT", # flake8-2020
# TODO: add more flake8 rules
]
ignore = [
# suppression in order of # of violations in Dec 2023:
"PLW2901", # redefined-loop-name
"SLF001", # private-member-access
"PLR0912", # too-many-branches
"PLR0913", # too-many-arguments
# RUF005: this is a different style of concatenating literals. It perhaps performs
# a bit better, but doesn't seem any more readable to me. So, ignore it.
"RUF005", # collection-literal-concatenation
# TODO: several classes have class variables. If that is correct, we should
# annotate them with ClassVar.
# See https://docs.astral.sh/ruff/rules/mutable-class-default/
"RUF012", # mutable-class-default
"PLR0915", # too-many-statements
# Note: we have a couple of "namespace packages" (i.e. missing __init__.py)
# Not sure if we should add __init__.py to them, or they really need to be
# namespace packages.
"INP001", # implicit-namespace-package
# ruff-format wants us to ignore ISC001. I don't love that, but okay.
# "warning: The following rules may cause conflicts when used with the formatter:
# `ISC001`. To avoid unexpected behavior, we recommend disabling these rules,
# either by removing them from the `select` or `extend-select` configuration,
# or adding them to the `ignore` configuration."
"ISC001", # single-line-implicit-string-concatenation
# PERF203 has minimal performance impact, and you have to catch the exception
# inside the loop if you want to ignore it, so let's ignore PERF203.
"PERF203", # try-except-in-loop
]
[tool.ruff.lint.extend-per-file-ignores]
"pelican/__init__.py" = [
# allow imports after a call to a function, see the file
"E402"
]
"pelican/tests/test_utils.py" = [
# the tests have a bunch of unicode characters
"RUF001"
]
"pelican/tests/test_generators.py" = [
# the tests have a bunch of constants, why not
"PLR2004"
]
"pelican/tools/*.py}" = [
# this is a command-line utility, prints are fine
"T201"
]

2
requirements/developer.pip
View file

@ -1,2 +0,0 @@
-r test.pip
-r docs.pip

6
requirements/docs.pip
View file

@ -1,6 +0,0 @@
sphinx
sphinxext-opengraph
furo==2023.9.10
livereload
matplotlib
tomli;python_version<"3.11"

5
requirements/owner.pip
View file

@ -1,5 +0,0 @@
-r developer.pip
# Release issuance
tox
wheel

11
requirements/test.pip
View file

@ -1,11 +0,0 @@
# Tests
Pygments>=2.16.1
pytest
pytest-cov
pytest-xdist[psutil]
# Optional Packages
Markdown>=3.5.1
BeautifulSoup4
lxml
typogrify

4
samples/content/2012-11-30_filename-metadata.rst
View file

@ -1,4 +0,0 @@
FILENAME_METADATA example
#########################
Some cool stuff!

8
samples/content/another_super_article-fr.rst
View file

@ -1,8 +0,0 @@
Trop bien !
###########
:date: 2010-10-20 10:14
:lang: fr
:slug: oh-yeah
Et voila du contenu en français

21
samples/content/another_super_article.rst
View file

@ -1,21 +0,0 @@
Oh yeah !
#########
:tags: oh, bar, yeah
:date: 2010-10-20 10:14
:category: bar
:author: Alexis Métaireau
:lang: en
:slug: oh-yeah
:license: WTFPL
Why not ?
=========
After all, why not ? It's pretty simple to do it, and it will allow me to write my blogposts in rst !
YEAH !
.. image:: |static|/pictures/Sushi.jpg
:height: 450 px
:width: 600 px
:alt: alternate text

9
samples/content/article2-fr.rst
View file

@ -1,9 +0,0 @@
Deuxième article
################
:tags: foo, bar, baz
:date: 2012-02-29
:lang: fr
:slug: second-article
Ceci est un article, en français.

9
samples/content/article2.rst
View file

@ -1,9 +0,0 @@
Second article
##############
:tags: foo, bar, baz
:date: 2012-02-29
:lang: en
:slug: second-article
This is some article, in english

8
samples/content/article_tag_baz.rst
View file

@ -1,8 +0,0 @@
The baz tag
###########
:date: 2010-03-14
:url: tag/baz.html
:save_as: tag/baz.html
This article overrides the listening of the articles under the *baz* tag.

7
samples/content/cat1/article1.rst
View file

@ -1,7 +0,0 @@
Article 1
#########
:date: 2011-02-17
:yeah: oh yeah !
Article 1

6
samples/content/cat1/article2.rst
View file

@ -1,6 +0,0 @@
Article 2
#########
:date: 2011-02-17
Article 2

6
samples/content/cat1/article3.rst
View file

@ -1,6 +0,0 @@
Article 3
#########
:date: 2011-02-17
Article 3

7
samples/content/cat1/markdown-article.md
View file

@ -1,7 +0,0 @@
Title: A markdown powered article
Date: 2011-04-20
You're mutually oblivious.
[a root-relative link to unbelievable](|filename|/unbelievable.rst)
[a file-relative link to unbelievable](|filename|../unbelievable.rst)

7
samples/content/draft_article without_date.rst
View file

@ -1,7 +0,0 @@
A draft article without date
############################
:status: draft
This is a draft article, it should live under the /drafts/ folder and not be
listed anywhere else.

8
samples/content/draft_article.rst
View file

@ -1,8 +0,0 @@
A draft article
###############
:date: 2011-05-08 15:58
:status: draft
This is a draft article, it should live under the /drafts/ folder and not be
listed anywhere else.

2
samples/content/extra/robots.txt
View file

@ -1,2 +0,0 @@
User-agent: *
Disallow: /pictures

8
samples/content/pages/hidden_page.rst
View file

@ -1,8 +0,0 @@
This is a test hidden page
##########################
:category: test
:status: hidden
This is great for things like error(404) pages
Anyone can see this page but it's not linked to anywhere!

6
samples/content/pages/jinja2_template.html
View file

@ -1,6 +0,0 @@
{% extends "base.html" %}
{% block content %}
Some text
{% endblock %}

8
samples/content/pages/override_tag_oh.rst
View file

@ -1,8 +0,0 @@
Oh Oh Oh
########
:date: 2010-03-14
:url: tag/oh.html
:save_as: tag/oh.html
This page overrides the listening of the articles under the *oh* tag.

9
samples/content/pages/override_url_saveas.rst
View file

@ -1,9 +0,0 @@
Override url/save_as
####################
:date: 2012-12-07
:url: override/
:save_as: override/index.html
Test page which overrides save_as and url so that this page will be generated
at a custom location.

16
samples/content/pages/test_page.rst
View file

@ -1,16 +0,0 @@
This is a test page
###################
:category: test
Just an image.
.. image:: {static}/pictures/Fat_Cat.jpg
:height: 450 px
:width: 600 px
:alt: alternate text
.. image:: |filename|/images/Fat_Cat.jpg
:height: 450 px
:width: 600 px
:alt: wrong path since 'images' folder does not exist

BIN
samples/content/pictures/Fat_Cat.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 61 KiB

BIN
samples/content/pictures/Sushi.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 28 KiB

BIN
samples/content/pictures/Sushi_Macro.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 38 KiB

37
samples/content/super_article.rst
View file

@ -1,37 +0,0 @@
This is a super article !
#########################
:tags: foo, bar, foobar
:date: 2010-12-02 10:14
:modified: 2013-11-17 23:29
:category: yeah
:author: Alexis Métaireau
:summary:
Multi-line metadata should be supported
as well as **inline markup**.
Some content here !
This is a simple title
======================
And here comes the cool stuff_.
.. image:: |static|/pictures/Sushi.jpg
:height: 450 px
:width: 600 px
:alt: alternate text
.. image:: |static|/pictures/Sushi_Macro.jpg
:height: 450 px
:width: 600 px
:alt: alternate text
::
>>> from ipdb import set_trace
>>> set_trace()
→ And now try with some utf8 hell: ééé
.. _stuff: http://books.couchdb.org/relax/design-documents/views

98
samples/content/unbelievable.rst
View file

@ -1,98 +0,0 @@
Unbelievable !
##############
:date: 2010-10-15 20:30
Or completely awesome. Depends the needs.
`a root-relative link to markdown-article <|filename|/cat1/markdown-article.md>`_
`a file-relative link to markdown-article <|filename|cat1/markdown-article.md>`_
Testing sourcecode directive
----------------------------
.. sourcecode:: python
:linenos:
formatter = self.options and VARIANTS[self.options.keys()[0]]
Testing another case
--------------------
This will now have a line number in 'custom' since it's the default in
pelican.conf, it will have nothing in default.
.. sourcecode:: python
formatter = self.options and VARIANTS[self.options.keys()[0]]
Lovely.
Testing more sourcecode directives
----------------------------------
.. sourcecode:: python
:anchorlinenos:
:classprefix: testing
:hl_lines: 10,11,12
:lineanchors: foo
:linenos: inline
:linenospecial: 2
:linenostart: 8
:linenostep: 2
:lineseparator: <br>
:linespans: foo
:nobackground:
def run(self):
self.assert_has_content()
try:
lexer = get_lexer_by_name(self.arguments[0])
except ValueError:
# no lexer found - use the text one instead of an exception
lexer = TextLexer()
if ('linenos' in self.options and
self.options['linenos'] not in ('table', 'inline')):
self.options['linenos'] = 'table'
for flag in ('nowrap', 'nobackground', 'anchorlinenos'):
if flag in self.options:
self.options[flag] = True
# noclasses should already default to False, but just in case...
formatter = HtmlFormatter(noclasses=False, **self.options)
parsed = highlight('\n'.join(self.content), lexer, formatter)
return [nodes.raw('', parsed, format='html')]
Lovely.
Testing even more sourcecode directives
---------------------------------------
.. sourcecode:: python
:linenos: table
:nowrap:
formatter = self.options and VARIANTS[self.options.keys()[0]]
Lovely.
Testing overriding config defaults
----------------------------------
Even if the default is line numbers, we can override it here
.. sourcecode:: python
:linenos: none
formatter = self.options and VARIANTS[self.options.keys()[0]]
Lovely.

1
samples/content/unwanted_file
View file

@ -1 +0,0 @@
not to be parsed

0
samples/kinda/exciting/new/files/zap!
View file

0
samples/kinda/exciting/old
View file

60
samples/pelican.conf.py
View file

@ -1,60 +0,0 @@
AUTHOR = "Alexis Métaireau"
SITENAME = "Alexis' log"
SITESUBTITLE = "A personal blog."
SITEURL = "http://blog.notmyidea.org"
TIMEZONE = "Europe/Paris"
# can be useful in development, but set to False when you're ready to publish
RELATIVE_URLS = True
GITHUB_URL = "http://github.com/ametaireau/"
DISQUS_SITENAME = "blog-notmyidea"
REVERSE_CATEGORY_ORDER = True
LOCALE = "C"
DEFAULT_PAGINATION = 4
DEFAULT_DATE = (2012, 3, 2, 14, 1, 1)
FEED_ALL_RSS = "feeds/all.rss.xml"
CATEGORY_FEED_RSS = "feeds/{slug}.rss.xml"
LINKS = (
("Biologeek", "http://biologeek.org"),
("Filyb", "http://filyb.info/"),
("Libert-fr", "http://www.libert-fr.com"),
("N1k0", "http://prendreuncafe.com/blog/"),
("Tarek Ziadé", "http://ziade.org/blog"),
("Zubin Mithra", "http://zubin71.wordpress.com/"),
)
SOCIAL = (
("twitter", "http://twitter.com/ametaireau"),
("lastfm", "http://lastfm.com/user/akounet"),
("github", "http://github.com/ametaireau"),
)
# global metadata to all the contents
DEFAULT_METADATA = {"yeah": "it is"}
# path-specific metadata
EXTRA_PATH_METADATA = {
"extra/robots.txt": {"path": "robots.txt"},
}
# static paths will be copied without parsing their contents
STATIC_PATHS = [
"images",
"extra/robots.txt",
]
# custom page generated with a jinja2 template
TEMPLATE_PAGES = {"pages/jinja2_template.html": "jinja2_template.html"}
# there is no other HTML content
READERS = {"html": None}
# code blocks with line numbers
PYGMENTS_RST_OPTIONS = {"linenos": "table"}
# foobar will not be used, because it's not in caps. All configuration keys
# have to be in caps
foobar = "barbaz"

61
samples/pelican.conf_FR.py
View file

@ -1,61 +0,0 @@
AUTHOR = "Alexis Métaireau"
SITENAME = "Alexis' log"
SITEURL = "http://blog.notmyidea.org"
TIMEZONE = "Europe/Paris"
# can be useful in development, but set to False when you're ready to publish
RELATIVE_URLS = True
GITHUB_URL = "http://github.com/ametaireau/"
DISQUS_SITENAME = "blog-notmyidea"
PDF_GENERATOR = False
REVERSE_CATEGORY_ORDER = True
LOCALE = "fr_FR.UTF-8"
DEFAULT_PAGINATION = 4
DEFAULT_DATE = (2012, 3, 2, 14, 1, 1)
DEFAULT_DATE_FORMAT = "%d %B %Y"
ARTICLE_URL = "posts/{date:%Y}/{date:%B}/{date:%d}/{slug}/"
ARTICLE_SAVE_AS = ARTICLE_URL + "index.html"
FEED_ALL_RSS = "feeds/all.rss.xml"
CATEGORY_FEED_RSS = "feeds/{slug}.rss.xml"
LINKS = (
("Biologeek", "http://biologeek.org"),
("Filyb", "http://filyb.info/"),
("Libert-fr", "http://www.libert-fr.com"),
("N1k0", "http://prendreuncafe.com/blog/"),
("Tarek Ziadé", "http://ziade.org/blog"),
("Zubin Mithra", "http://zubin71.wordpress.com/"),
)
SOCIAL = (
("twitter", "http://twitter.com/ametaireau"),
("lastfm", "http://lastfm.com/user/akounet"),
("github", "http://github.com/ametaireau"),
)
# global metadata to all the contents
DEFAULT_METADATA = {"yeah": "it is"}
# path-specific metadata
EXTRA_PATH_METADATA = {
"extra/robots.txt": {"path": "robots.txt"},
}
# static paths will be copied without parsing their contents
STATIC_PATHS = [
"pictures",
"extra/robots.txt",
]
# custom page generated with a jinja2 template
TEMPLATE_PAGES = {"pages/jinja2_template.html": "jinja2_template.html"}
# code blocks with line numbers
PYGMENTS_RST_OPTIONS = {"linenos": "table"}
# foobar will not be used, because it's not in caps. All configuration keys
# have to be in caps
foobar = "barbaz"

0
samples/theme_standard/a_stylesheet
View file

0
samples/theme_standard/a_template
View file

0
samples/very/exciting/new/files/bap!
View file

Some files were not shown because too many files have changed in this diff Show more