mirror of
https://github.com/getpelican/pelican.git
synced 2025-10-15 20:28:56 +02:00
Split Getting Started docs into separate sections
The "Getting Started" docs became overly long and unwieldy over time. This splits it into separate sections, including: * Quickstart * Installation * Writing content * Publish your site
This commit is contained in:
Justin Mayer
parent
7313d327fb
commit
86e11c619d
10 changed files with 420 additions and 333 deletions
307
docs/content.rst
307
docs/content.rst
|
|
@ -1,289 +1,8 @@
|
|||
Getting started
|
||||
Writing content
|
||||
###############
|
||||
|
||||
Installing Pelican
|
||||
==================
|
||||
|
||||
Pelican currently runs best on Python 2.7.x; earlier versions of Python are
|
||||
not supported. There is provisional support for Python 3.3, although there may
|
||||
be rough edges, particularly with regards to optional 3rd-party components.
|
||||
|
||||
You can install Pelican via several different methods. The simplest is via
|
||||
`pip <http://www.pip-installer.org/>`_::
|
||||
|
||||
$ pip install pelican
|
||||
|
||||
If you don't have ``pip`` installed, an alternative method is
|
||||
``easy_install``::
|
||||
|
||||
$ easy_install pelican
|
||||
|
||||
(Keep in mind that operating systems will often require you to prefix the above
|
||||
commands 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
|
||||
$ . bin/activate
|
||||
|
||||
Once the virtual environment has been created and activated, Pelican can be
|
||||
be installed via ``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::
|
||||
|
||||
$ pip install -e git+https://github.com/getpelican/pelican.git#egg=pelican
|
||||
|
||||
If you plan on using Markdown as a markup format, you'll need to install the
|
||||
Markdown library as well::
|
||||
|
||||
$ pip install Markdown
|
||||
|
||||
If you want to use AsciiDoc_ you need to install it from `source
|
||||
<http://www.methods.co.nz/asciidoc/INSTALL.html>`_ or use your operating
|
||||
system's package manager.
|
||||
|
||||
Basic usage
|
||||
-----------
|
||||
|
||||
Once Pelican is installed, you can use it to convert your Markdown or reST
|
||||
content into HTML via the ``pelican`` command, specifying the path to your
|
||||
content and (optionally) the path to your 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.
|
||||
|
||||
Pelican has other command-line switches available. Have a look at the help to
|
||||
see all the options you can use::
|
||||
|
||||
$ pelican --help
|
||||
|
||||
Continue reading below for more detail, and check out the Pelican wiki's
|
||||
`Tutorials <https://github.com/getpelican/pelican/wiki/Tutorials>`_ page for
|
||||
links to community-published tutorials.
|
||||
|
||||
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 a simple web server using Python will often provide a more
|
||||
reliable previewing experience::
|
||||
|
||||
cd output && python -m SimpleHTTPServer
|
||||
|
||||
Once the ``SimpleHTTPServer`` has been started, you can preview your site at
|
||||
http://localhost:8000/
|
||||
|
||||
Upgrading
|
||||
---------
|
||||
|
||||
If you installed a stable Pelican release via ``pip`` or ``easy_install`` and
|
||||
wish to upgrade to the latest stable release, you can do so by adding
|
||||
``--upgrade`` to the relevant command. For pip, that would be::
|
||||
|
||||
$ 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.
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
When Pelican is installed, the following dependent Python packages should be
|
||||
automatically installed without any action on your part:
|
||||
|
||||
* `feedgenerator <http://pypi.python.org/pypi/feedgenerator>`_, to generate the
|
||||
Atom feeds
|
||||
* `jinja2 <http://pypi.python.org/pypi/Jinja2>`_, for templating support
|
||||
* `pygments <http://pypi.python.org/pypi/Pygments>`_, for syntax highlighting
|
||||
* `docutils <http://pypi.python.org/pypi/docutils>`_, for supporting
|
||||
reStructuredText as an input format
|
||||
* `pytz <http://pypi.python.org/pypi/pytz>`_, for timezone definitions
|
||||
* `blinker <http://pypi.python.org/pypi/blinker>`_, an object-to-object and
|
||||
broadcast signaling system
|
||||
* `unidecode <http://pypi.python.org/pypi/Unidecode>`_, for ASCII
|
||||
transliterations of Unicode text
|
||||
* `six <http://pypi.python.org/pypi/six>`_, for Python 2 and 3 compatibility
|
||||
utilities
|
||||
* `MarkupSafe <http://pypi.python.org/pypi/MarkupSafe>`_, for a markup safe
|
||||
string implementation
|
||||
* `python-dateutil <https://pypi.python.org/pypi/python-dateutil>`_, to read
|
||||
the date metadata
|
||||
|
||||
If you want the following optional packages, you will need to install them
|
||||
manually via ``pip``:
|
||||
|
||||
* `markdown <http://pypi.python.org/pypi/Markdown>`_, for supporting Markdown as
|
||||
an input format
|
||||
* `typogrify <http://pypi.python.org/pypi/typogrify>`_, for
|
||||
typographical enhancements
|
||||
|
||||
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
|
||||
|
||||
Once you finish answering all the questions, your project will consist of the
|
||||
following hierarchy (except for "pages", which you can optionally add yourself
|
||||
if you plan to create non-chronological content)::
|
||||
|
||||
yourproject/
|
||||
├── content
|
||||
│ └── (pages)
|
||||
├── output
|
||||
├── develop_server.sh
|
||||
├── fabfile.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. (See the **Writing content using Pelican** section below
|
||||
for more information about how to format your content.)
|
||||
|
||||
Once you have written some content to generate, you can use the ``pelican``
|
||||
command to generate your site, which will be placed in the output folder.
|
||||
|
||||
Automation tools
|
||||
================
|
||||
|
||||
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
|
||||
described above pertains to whether you want to automate site generation and
|
||||
publication. If you answered "yes" to that question, a ``fabfile.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 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.
|
||||
|
||||
Fabric
|
||||
------
|
||||
|
||||
The advantage of Fabric_ 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 Fabric, prefixing with
|
||||
``sudo`` if your environment requires it::
|
||||
|
||||
$ pip install Fabric
|
||||
|
||||
Take a moment to open the ``fabfile.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::
|
||||
|
||||
$ fab 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::
|
||||
|
||||
$ fab regenerate
|
||||
|
||||
To serve the generated site so it can be previewed in your browser at
|
||||
http://localhost:8000/::
|
||||
|
||||
$ fab serve
|
||||
|
||||
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::
|
||||
|
||||
$ fab publish
|
||||
|
||||
These are just a few of the commands available by default, so feel free to
|
||||
explore ``fabfile.py`` and see what other commands are available. More
|
||||
importantly, don't hesitate to customize ``fabfile.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, run::
|
||||
|
||||
$ make html
|
||||
|
||||
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. Once you are done testing your
|
||||
changes, you should stop the development server via::
|
||||
|
||||
$ ./develop_server.sh stop
|
||||
|
||||
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.)
|
||||
|
||||
|
||||
Writing content using Pelican
|
||||
=============================
|
||||
|
||||
Articles and pages
|
||||
------------------
|
||||
==================
|
||||
|
||||
Pelican considers "articles" to be chronological content, such as posts on a
|
||||
blog, and thus associated with a date.
|
||||
|
|
@ -295,7 +14,7 @@ pages).
|
|||
.. _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
|
||||
|
|
@ -400,7 +119,7 @@ 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
|
||||
|
|
@ -416,7 +135,7 @@ things like making error pages that fit the generated theme of your site.
|
|||
.. _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*
|
||||
|
|
@ -494,14 +213,14 @@ curly braces (``{}``). 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.
|
||||
|
||||
Importing an existing blog
|
||||
--------------------------
|
||||
Importing an existing site
|
||||
==========================
|
||||
|
||||
It is possible to import your blog from Dotclear, WordPress, and RSS feeds using
|
||||
a simple script. See :ref:`import`.
|
||||
It is possible to import your site from WordPress, Tumblr, Dotclear, and RSS
|
||||
feeds 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
|
||||
|
|
@ -559,7 +278,7 @@ which posts are translations::
|
|||
.. _internal_pygments_options:
|
||||
|
||||
Syntax highlighting
|
||||
-------------------
|
||||
===================
|
||||
|
||||
Pelican is able to provide colorized syntax highlighting for your code blocks.
|
||||
To do so, you have to use the following conventions inside your content files.
|
||||
|
|
@ -641,14 +360,12 @@ If specified, settings for individual code blocks will override the defaults in
|
|||
your settings file.
|
||||
|
||||
Publishing drafts
|
||||
-----------------
|
||||
=================
|
||||
|
||||
If you want to publish an article 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.
|
||||
|
||||
.. _virtualenv: http://www.virtualenv.org/
|
||||
.. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime
|
||||
.. _Fabric: http://fabfile.org/
|
||||
.. _AsciiDoc: http://www.methods.co.nz/asciidoc/
|
||||
|
|
|
|||
12
docs/faq.rst
12
docs/faq.rst
|
|
@ -65,9 +65,11 @@ How do I create my own theme?
|
|||
|
||||
Please refer to :ref:`theming-pelican`.
|
||||
|
||||
I'm using Markdown and getting ``No valid files found in content`` errors.
|
||||
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``.
|
||||
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
|
||||
|
|
@ -75,10 +77,6 @@ permissions require it::
|
|||
|
||||
pip install markdown
|
||||
|
||||
If you don't have ``pip`` installed, consider installing it via::
|
||||
|
||||
easy_install pip
|
||||
|
||||
Can I use arbitrary metadata in my templates?
|
||||
==============================================
|
||||
|
||||
|
|
@ -157,8 +155,8 @@ disable all feed generation, you only need to specify the following settings::
|
|||
CATEGORY_FEED_ATOM = None
|
||||
TRANSLATION_FEED_ATOM = None
|
||||
|
||||
Please note that ``None`` and ``''`` are not the same thing. The word ``None``
|
||||
should not be surrounded by quotes.
|
||||
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
|
||||
==============================================================================
|
||||
|
|
|
|||
|
|
@ -1,9 +1,7 @@
|
|||
.. _import:
|
||||
|
||||
=================================
|
||||
Import from other blog software
|
||||
=================================
|
||||
|
||||
Importing an existing site
|
||||
##########################
|
||||
|
||||
Description
|
||||
===========
|
||||
|
|
|
|||
|
|
@ -10,30 +10,32 @@ Pelican |release|
|
|||
Were you looking for version |last_stable| documentation?
|
||||
|
||||
|
||||
Pelican is a static site generator, written in Python_.
|
||||
Pelican is a static site generator, written in Python_. Highlights include:
|
||||
|
||||
* Write your content directly with your editor of choice (vim!)
|
||||
* Write your content directly with your editor of choice
|
||||
in reStructuredText_, Markdown_, or AsciiDoc_ 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 |version| currently supports:
|
||||
|
||||
* Articles (e.g., blog posts) and pages (e.g., "About", "Projects", "Contact")
|
||||
* Comments, via an external service (Disqus). (Please note that while
|
||||
useful, Disqus is an external service, and thus the comment data will be
|
||||
somewhat outside of your control and potentially subject to data loss.)
|
||||
* Comments, via an external service (Disqus). If you prefer to have more
|
||||
control over your comment data, self-hosted comments are another option.
|
||||
Check out the `Pelican Plugins`_ repository for more details.
|
||||
* Theming support (themes are created using Jinja2_ templates)
|
||||
* Publication of articles in multiple languages
|
||||
* Atom/RSS feeds
|
||||
* Code syntax highlighting
|
||||
* Import from WordPress, Dotclear, or RSS feeds
|
||||
* Integration with external tools: Twitter, Google Analytics, etc. (optional)
|
||||
* Fast rebuild times thanks to content caching and selective output writing.
|
||||
* Fast rebuild times thanks to content caching and selective output writing
|
||||
|
||||
Why the name "Pelican"?
|
||||
-----------------------
|
||||
|
|
@ -66,16 +68,19 @@ Documentation
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
getting_started
|
||||
quickstart
|
||||
install
|
||||
content
|
||||
publish
|
||||
settings
|
||||
themes
|
||||
plugins
|
||||
internals
|
||||
pelican-themes
|
||||
importer
|
||||
faq
|
||||
tips
|
||||
contribute
|
||||
internals
|
||||
report
|
||||
changelog
|
||||
|
||||
|
|
@ -88,5 +93,6 @@ Documentation
|
|||
.. _Jinja2: http://jinja.pocoo.org/
|
||||
.. _`Pelican documentation`: http://docs.getpelican.com/latest/
|
||||
.. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html
|
||||
.. _`Pelican plugins`: https://github.com/getpelican/pelican-plugins
|
||||
.. _`#pelican on Freenode`: irc://irc.freenode.net/pelican
|
||||
.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4
|
||||
|
|
|
|||
122
docs/install.rst
Normal file
122
docs/install.rst
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
Installing Pelican
|
||||
##################
|
||||
|
||||
Pelican currently runs best on Python 2.7.x; earlier versions of Python are
|
||||
not supported. There is provisional support for Python 3.3+, although there may
|
||||
be rough edges, particularly with regards to optional 3rd-party components.
|
||||
|
||||
You can install Pelican via several different methods. The simplest is via
|
||||
`pip <http://www.pip-installer.org/>`_::
|
||||
|
||||
pip install pelican
|
||||
|
||||
(Keep in mind that operating systems will often 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
|
||||
be installed via ``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::
|
||||
|
||||
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 <http://pypi.python.org/pypi/Markdown>`_ as a
|
||||
markup format, you'll need to install the Markdown library::
|
||||
|
||||
pip install Markdown
|
||||
|
||||
Typographical enhancements can be enabled in your settings file, but first the
|
||||
requisite `Typogrify <http://pypi.python.org/pypi/typogrify>`_ library must be
|
||||
installed::
|
||||
|
||||
pip install typogrify
|
||||
|
||||
If you want to use AsciiDoc_ you need to install it from `source
|
||||
<http://www.methods.co.nz/asciidoc/INSTALL.html>`_ or use your operating
|
||||
system's package manager.
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
When Pelican is installed, the following dependent Python packages should be
|
||||
automatically installed without any action on your part:
|
||||
|
||||
* `feedgenerator <http://pypi.python.org/pypi/feedgenerator>`_, to generate the
|
||||
Atom feeds
|
||||
* `jinja2 <http://pypi.python.org/pypi/Jinja2>`_, for templating support
|
||||
* `pygments <http://pypi.python.org/pypi/Pygments>`_, for syntax highlighting
|
||||
* `docutils <http://pypi.python.org/pypi/docutils>`_, for supporting
|
||||
reStructuredText as an input format
|
||||
* `pytz <http://pypi.python.org/pypi/pytz>`_, for timezone definitions
|
||||
* `blinker <http://pypi.python.org/pypi/blinker>`_, an object-to-object and
|
||||
broadcast signaling system
|
||||
* `unidecode <http://pypi.python.org/pypi/Unidecode>`_, for ASCII
|
||||
transliterations of Unicode text
|
||||
* `six <http://pypi.python.org/pypi/six>`_, for Python 2 and 3 compatibility
|
||||
utilities
|
||||
* `MarkupSafe <http://pypi.python.org/pypi/MarkupSafe>`_, for a markup safe
|
||||
string implementation
|
||||
* `python-dateutil <https://pypi.python.org/pypi/python-dateutil>`_, to read
|
||||
the date metadata
|
||||
|
||||
Upgrading
|
||||
---------
|
||||
|
||||
If you installed a stable Pelican release via ``pip`` or ``easy_install`` and
|
||||
wish to upgrade to the latest stable release, you can do so by adding
|
||||
``--upgrade`` to the relevant command. For pip, that would be::
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
├── develop_server.sh
|
||||
├── fabfile.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.
|
||||
|
||||
.. _virtualenv: http://www.virtualenv.org/
|
||||
.. _AsciiDoc: http://www.methods.co.nz/asciidoc/
|
||||
|
|
@ -153,12 +153,3 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus
|
|||
--verbose
|
||||
|
||||
In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr``
|
||||
|
||||
|
||||
|
||||
|
||||
See also
|
||||
========
|
||||
|
||||
- http://docs.notmyidea.org/alexis/pelican/
|
||||
- ``/usr/share/doc/pelican/`` if you have installed Pelican using the `APT repository <http://skami18.github.com/pelican-packages/>`_
|
||||
|
|
|
|||
174
docs/publish.rst
Normal file
174
docs/publish.rst
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
Publish your site
|
||||
#################
|
||||
|
||||
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.
|
||||
|
||||
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 a simple web server using Python will often provide a more
|
||||
reliable previewing experience::
|
||||
|
||||
cd output
|
||||
python -m SimpleHTTPServer
|
||||
|
||||
Once the ``SimpleHTTPServer`` 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
|
||||
|
||||
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 ``fabfile.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 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.
|
||||
|
||||
Fabric
|
||||
------
|
||||
|
||||
The advantage of Fabric_ 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 Fabric, prefixing with
|
||||
``sudo`` if your environment requires it::
|
||||
|
||||
pip install Fabric
|
||||
|
||||
Take a moment to open the ``fabfile.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::
|
||||
|
||||
fab 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::
|
||||
|
||||
fab regenerate
|
||||
|
||||
To serve the generated site so it can be previewed in your browser at
|
||||
http://localhost:8000/::
|
||||
|
||||
fab serve
|
||||
|
||||
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::
|
||||
|
||||
fab publish
|
||||
|
||||
These are just a few of the commands available by default, so feel free to
|
||||
explore ``fabfile.py`` and see what other commands are available. More
|
||||
importantly, don't hesitate to customize ``fabfile.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, run::
|
||||
|
||||
make html
|
||||
|
||||
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. Once you are done testing your
|
||||
changes, you should stop the development server via::
|
||||
|
||||
./develop_server.sh stop
|
||||
|
||||
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.)
|
||||
|
||||
.. _Fabric: http://fabfile.org/
|
||||
73
docs/quickstart.rst
Normal file
73
docs/quickstart.rst
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
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 on Python 2.7.x or Python 3.3+ by running the following command
|
||||
in your preferred terminal, prefixing with ``sudo`` if permissions warrant::
|
||||
|
||||
pip install pelican markdown
|
||||
|
||||
Create a project
|
||||
----------------
|
||||
|
||||
First, choose a name for your project, create an appropriately-named directory
|
||||
for your it, 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. When asked for your URL prefix,
|
||||
enter your domain name as indicated (e.g., ``http://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 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 and run the following commands to switch to your
|
||||
``output`` directory and launch Python's built-in web server::
|
||||
|
||||
cd ~/projects/yoursite/output
|
||||
python -m SimpleHTTPServer
|
||||
|
||||
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
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
Settings
|
||||
########
|
||||
|
||||
Pelican is configurable thanks to a configuration file you can pass to
|
||||
Pelican is configurable thanks to a settings file you can pass to
|
||||
the command line::
|
||||
|
||||
$ pelican content -s path/to/your/settingsfile.py
|
||||
pelican content -s path/to/your/settingsfile.py
|
||||
|
||||
(If you used the ``pelican-quickstart`` command, your primary settings file will
|
||||
be named ``pelicanconf.py`` by default.)
|
||||
|
|
@ -201,8 +201,8 @@ for URL formation: *relative* and *absolute*. Relative URLs are useful
|
|||
when testing locally, and absolute URLs are reliable and most useful when
|
||||
publishing. One method of supporting both is to have one Pelican configuration
|
||||
file for local development and another for publishing. To see an example of this
|
||||
type of setup, use the ``pelican-quickstart`` script as described at the top of
|
||||
the :doc:`Getting Started <getting_started>` page, which will produce two separate
|
||||
type of setup, use the ``pelican-quickstart`` script as described in the
|
||||
:doc:`Installation <install>` section, which will produce two separate
|
||||
configuration files for local development and publishing, respectively.
|
||||
|
||||
You can customize the URLs and locations where files will be saved. The
|
||||
|
|
@ -603,7 +603,7 @@ For example::
|
|||
Translations
|
||||
============
|
||||
|
||||
Pelican offers a way to translate articles. See the :doc:`Getting Started <getting_started>` section for
|
||||
Pelican offers a way to translate articles. See the :doc:`Content <content>` section for
|
||||
more information.
|
||||
|
||||
======================================================== =====================================================
|
||||
|
|
|
|||
|
|
@ -1,13 +1,21 @@
|
|||
.. _theming-pelican:
|
||||
|
||||
How to create themes for Pelican
|
||||
################################
|
||||
Creating themes
|
||||
###############
|
||||
|
||||
Pelican uses the great `Jinja2 <http://jinja.pocoo.org/>`_ templating engine to
|
||||
generate its HTML output. Jinja2 syntax is really simple. If you want to
|
||||
create your own theme, feel free to take inspiration from the `"simple" theme
|
||||
To generate its HTML output, Pelican uses the `Jinja <http://jinja.pocoo.org/>`_
|
||||
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/master/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
|
||||
=========
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue