mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Merge branch 'getpelican:master' into Chinese-translation
This commit is contained in:
GeorgeHu
GitHub
commit
2cf90ccc0c
27 changed files with 266 additions and 182 deletions
|
|
@ -25,7 +25,7 @@ rst_prolog = '''
|
|||
'''.format(last_stable)
|
||||
|
||||
extlinks = {
|
||||
'pelican-doc': ('https://docs.getpelican.com/%s/', '%s')
|
||||
'pelican-doc': ('https://docs.getpelican.com/en/latest/%s.html', '%s')
|
||||
}
|
||||
|
||||
# -- Options for HTML output --------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -95,8 +95,9 @@ contains a list of reserved metadata keywords:
|
|||
``url`` URL to use for this article/page
|
||||
=============== ===============================================================
|
||||
|
||||
Readers for additional formats (such as AsciiDoc_) are available via plugins.
|
||||
Refer to `pelican-plugins`_ repository for those.
|
||||
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
|
||||
|
|
@ -183,7 +184,7 @@ files in it will be used to generate static pages, such as **About** or
|
|||
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
|
||||
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.
|
||||
|
||||
|
|
@ -234,7 +235,7 @@ 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``
|
||||
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.
|
||||
|
|
@ -306,7 +307,7 @@ 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
|
||||
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
|
||||
|
|
@ -538,12 +539,12 @@ 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:
|
||||
`code-block` directive:
|
||||
|
||||
============= ============ =========================================
|
||||
Option Valid values Description
|
||||
============= ============ =========================================
|
||||
anchorlinenos N/A If present wrap line numbers in <a> tags.
|
||||
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
|
||||
|
|
@ -554,22 +555,22 @@ hl_lines numbers List of lines to be highlighted, where
|
|||
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
|
||||
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.
|
||||
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
|
||||
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.
|
||||
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.
|
||||
============= ============ =========================================
|
||||
|
|
@ -595,7 +596,7 @@ 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::
|
||||
and a CSS prefix, you would set this variable to::
|
||||
|
||||
PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'}
|
||||
|
||||
|
|
@ -611,7 +612,7 @@ 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
|
||||
accidentally publish an article before it is finished), include the status in
|
||||
the ``DEFAULT_METADATA``::
|
||||
|
||||
DEFAULT_METADATA = {
|
||||
|
|
@ -626,11 +627,12 @@ 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
|
||||
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.
|
||||
|
||||
.. _W3C ISO 8601: https://www.w3.org/TR/NOTE-datetime
|
||||
.. _AsciiDoc: https://www.methods.co.nz/asciidoc/
|
||||
.. _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/
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ suggestions or problems you might have via `Pelican Discussions
|
|||
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
|
||||
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>`
|
||||
|
|
@ -68,7 +68,7 @@ I want to use Markdown, but I got an error.
|
|||
===========================================
|
||||
|
||||
If you try to generate Markdown content without first installing the Markdown
|
||||
library, may see a message that says ``No valid files found in content``.
|
||||
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
|
||||
|
|
@ -128,7 +128,7 @@ to override the generated URL. Here is an example page in reST format::
|
|||
:save_as: override/url/index.html
|
||||
|
||||
With this metadata, the page will be written to ``override/url/index.html``
|
||||
and Pelican will use url ``override/url/`` to link to this page.
|
||||
and Pelican will use the URL ``override/url/`` to link to this page.
|
||||
|
||||
How can I use a static page as my home page?
|
||||
============================================
|
||||
|
|
@ -229,7 +229,7 @@ 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
|
||||
My tag cloud is missing/broken since I upgraded Pelican
|
||||
=======================================================
|
||||
|
||||
In an ongoing effort to streamline Pelican, tag cloud generation has been
|
||||
|
|
|
|||
|
|
@ -64,7 +64,6 @@ automatically installed without any action on your part:
|
|||
* `pygments <https://pypi.org/project/Pygments/>`_, for syntax highlighting
|
||||
* `docutils <https://pypi.org/project/docutils/>`_, for supporting
|
||||
reStructuredText as an input format
|
||||
* `pytz <https://pypi.org/project/pytz/>`_, for timezone definitions
|
||||
* `blinker <https://pypi.org/project/blinker/>`_, an object-to-object and
|
||||
broadcast signaling system
|
||||
* `unidecode <https://pypi.org/project/Unidecode/>`_, for ASCII
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ Optional arguments:
|
|||
"""""""""""""""""""
|
||||
|
||||
|
||||
-h, --help Show the help an exit
|
||||
-h, --help Show the help and exit
|
||||
|
||||
-l, --list Show the themes already installed
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ Optional arguments:
|
|||
|
||||
-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.
|
||||
-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
|
||||
|
|
@ -62,7 +62,7 @@ or ``--list`` option:
|
|||
In this example, we can see there are three themes available: ``notmyidea``,
|
||||
``simple``, and ``two-column``.
|
||||
|
||||
``two-column`` is prefixed with an ``@`` because this theme is not copied to
|
||||
``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).
|
||||
|
||||
|
|
@ -82,7 +82,7 @@ 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:
|
||||
and can be combined with the ``--verbose`` option:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
@ -154,7 +154,7 @@ This is useful for theme development:
|
|||
Doing several things at once
|
||||
""""""""""""""""""""""""""""
|
||||
|
||||
The ``--install``, ``--remove`` and ``--symlink`` option are not mutually
|
||||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -67,7 +67,7 @@ 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
|
||||
re-generate your site with any production-specific settings (e.g., analytics,
|
||||
feeds, etc.) that you may have defined::
|
||||
|
||||
pelican content -s publishconf.py
|
||||
|
|
|
|||
|
|
@ -15,6 +15,9 @@ setting file. Note that values must follow JSON notation::
|
|||
|
||||
pelican content -e SITENAME='"A site"' READERS='{"html": null}' CACHE_CONTENT=true
|
||||
|
||||
Environment variables can also be used here but must be escaped appropriately::
|
||||
|
||||
pelican content -e API_KEY=''\"$API_KEY\"''
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -1242,18 +1245,19 @@ Feel free to use them in your themes as well.
|
|||
Your GitHub URL (if you have one). It will then use this information to
|
||||
create a GitHub ribbon.
|
||||
|
||||
.. data:: GOOGLE_ANALYTICS
|
||||
.. data:: ANALYTICS
|
||||
|
||||
Set to ``UA-XXXXX-Y`` Property's tracking ID to activate Google Analytics.
|
||||
Put any desired analytics scripts in this setting in ``publishconf.py``.
|
||||
Example:
|
||||
|
||||
.. data:: GA_COOKIE_DOMAIN
|
||||
.. parsed-literal::
|
||||
|
||||
Set cookie domain field of Google Analytics tracking code. Defaults to
|
||||
``auto``.
|
||||
|
||||
.. data:: GOSQUARED_SITENAME
|
||||
|
||||
Set to 'XXX-YYYYYY-X' to activate GoSquared.
|
||||
ANALYTICS = """
|
||||
<script src="/theme/js/primary-analytics.js"></script>
|
||||
<script>
|
||||
[ … in-line Javascript code for secondary analytics … ]
|
||||
</script>
|
||||
"""
|
||||
|
||||
.. data:: MENUITEMS
|
||||
|
||||
|
|
|
|||
|
|
@ -34,11 +34,10 @@ Structure
|
|||
To make your own theme, you must follow the following structure::
|
||||
|
||||
├── static
|
||||
│ ├── css
|
||||
│ └── images
|
||||
│ ├── css
|
||||
│ └── images
|
||||
└── templates
|
||||
├── archives.html // to display archives
|
||||
├── period_archives.html // to display time-period archives
|
||||
├── article.html // processed for each article
|
||||
├── author.html // processed for each author
|
||||
├── authors.html // must list all the authors
|
||||
|
|
@ -46,6 +45,7 @@ To make your own theme, you must follow the following structure::
|
|||
├── 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.
|
||||
|
||||
|
|
@ -465,14 +465,14 @@ 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::
|
||||
|
||||
FEED_ATOM
|
||||
FEED_RSS
|
||||
FEED_ALL_ATOM
|
||||
FEED_ALL_RSS
|
||||
CATEGORY_FEED_ATOM
|
||||
CATEGORY_FEED_RSS
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue