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

Merge pull request #1345 from justinmayer/docs34

Browse source 
Split "Getting Started" docs into separate sections
This commit is contained in:
Justin Mayer 2014-05-13 09:01:57 -07:00
commit 33e9ce1ddf
11 changed files with 785 additions and 696 deletions
Download patch file Download diff file Expand all files Collapse all files

307
docs/getting_started.rst → docs/content.rst
View file

@ -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 Articles and pages
------------------ ==================
Pelican considers "articles" to be chronological content, such as posts on a Pelican considers "articles" to be chronological content, such as posts on a
blog, and thus associated with a date. blog, and thus associated with a date.
@ -295,7 +14,7 @@ pages).
.. _internal_metadata: .. _internal_metadata:
File metadata File metadata
------------- =============
Pelican tries to be smart enough to get the information it needs from the 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 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. the metadata extracted from the filename.
Pages Pages
----- =====
If you create a folder named ``pages`` inside the content folder, all the 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 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: .. _ref-linking-to-internal-content:
Linking to internal content Linking to internal content
--------------------------- ===========================
From Pelican 3.1 onwards, it is now possible to specify intra-site links to 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* 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 ``|tag|tagname``, ``|category|foobar``. The syntax was changed from ``||`` to
``{}`` to avoid collision with Markdown extensions or reST directives. ``{}`` 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 It is possible to import your site from WordPress, Tumblr, Dotclear, and RSS
a simple script. See :ref:`import`. feeds using a simple script. See :ref:`import`.
Translations Translations
------------ ============
It is possible to translate articles. To do so, you need to add a ``lang`` meta 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 attribute to your articles/pages and set a ``DEFAULT_LANG`` setting (which is
@ -559,7 +278,7 @@ which posts are translations::
.. _internal_pygments_options: .. _internal_pygments_options:
Syntax highlighting Syntax highlighting
------------------- ===================
Pelican is able to provide colorized syntax highlighting for your code blocks. 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. 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. your settings file.
Publishing drafts Publishing drafts
----------------- =================
If you want to publish an article as a draft (for friends to review before 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 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 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. 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 .. _W3C ISO 8601: http://www.w3.org/TR/NOTE-datetime
.. _Fabric: http://fabfile.org/
.. _AsciiDoc: http://www.methods.co.nz/asciidoc/ .. _AsciiDoc: http://www.methods.co.nz/asciidoc/

12
docs/faq.rst
View file

@ -65,9 +65,11 @@ How do I create my own theme?
Please refer to :ref:`theming-pelican`. 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 is not a hard dependency for Pelican, so if you have content in
Markdown format, you will need to explicitly install the Markdown library. Markdown format, you will need to explicitly install the Markdown library.
You can do so by typing the following command, prepending ``sudo`` if You can do so by typing the following command, prepending ``sudo`` if
@ -75,10 +77,6 @@ permissions require it::
pip install markdown 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? 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 CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None TRANSLATION_FEED_ATOM = None
Please note that ``None`` and ``''`` are not the same thing. The word ``None`` The word ``None`` should not be surrounded by quotes. Please note that ``None``
should not be surrounded by quotes. and ``''`` are not the same thing.
I'm getting a warning about feeds generated without SITEURL being set properly I'm getting a warning about feeds generated without SITEURL being set properly
============================================================================== ==============================================================================

6
docs/importer.rst
View file

@ -1,9 +1,7 @@
.. _import: .. _import:
================================= Importing an existing site
Import from other blog software ##########################
=================================
Description Description
=========== ===========

22
docs/index.rst
View file

@ -10,30 +10,32 @@ Pelican |release|
Were you looking for version |last_stable| documentation? 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 in reStructuredText_, Markdown_, or AsciiDoc_ formats
* Includes a simple CLI tool to (re)generate your site * Includes a simple CLI tool to (re)generate your site
* Easy to interface with distributed version control systems and web hooks * Easy to interface with distributed version control systems and web hooks
* Completely static output is easy to host anywhere * Completely static output is easy to host anywhere
Ready to get started? Check out the :doc:`Quickstart<quickstart>` guide.
Features Features
-------- --------
Pelican |version| currently supports: Pelican |version| currently supports:
* Articles (e.g., blog posts) and pages (e.g., "About", "Projects", "Contact") * Articles (e.g., blog posts) and pages (e.g., "About", "Projects", "Contact")
* Comments, via an external service (Disqus). (Please note that while * Comments, via an external service (Disqus). If you prefer to have more
useful, Disqus is an external service, and thus the comment data will be control over your comment data, self-hosted comments are another option.
somewhat outside of your control and potentially subject to data loss.) Check out the `Pelican Plugins`_ repository for more details.
* Theming support (themes are created using Jinja2_ templates) * Theming support (themes are created using Jinja2_ templates)
* Publication of articles in multiple languages * Publication of articles in multiple languages
* Atom/RSS feeds * Atom/RSS feeds
* Code syntax highlighting * Code syntax highlighting
* Import from WordPress, Dotclear, or RSS feeds * Import from WordPress, Dotclear, or RSS feeds
* Integration with external tools: Twitter, Google Analytics, etc. (optional) * 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"? Why the name "Pelican"?
----------------------- -----------------------
@ -66,16 +68,19 @@ Documentation
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
getting_started quickstart
install
content
publish
settings settings
themes themes
plugins plugins
internals
pelican-themes pelican-themes
importer importer
faq faq
tips tips
contribute contribute
internals
report report
changelog changelog
@ -88,5 +93,6 @@ Documentation
.. _Jinja2: http://jinja.pocoo.org/ .. _Jinja2: http://jinja.pocoo.org/
.. _`Pelican documentation`: http://docs.getpelican.com/latest/ .. _`Pelican documentation`: http://docs.getpelican.com/latest/
.. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html .. _`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 .. _`#pelican on Freenode`: irc://irc.freenode.net/pelican
.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4 .. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4

122
docs/install.rst Normal file
View 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/

9
docs/pelican-themes.rst
View file

@ -153,12 +153,3 @@ The ``--install``, ``--remove`` and ``--symlink`` option are not mutually exclus
--verbose --verbose
In this example, the theme ``notmyidea-cms`` is replaced by the theme ``notmyidea-cms-fr`` 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
View 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
View 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

20
docs/settings.rst
View file

@ -1,10 +1,10 @@
Settings 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:: 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 (If you used the ``pelican-quickstart`` command, your primary settings file will
be named ``pelicanconf.py`` by default.) be named ``pelicanconf.py`` by default.)
@ -94,7 +94,7 @@ Setting name (followed by default value, if any)
``READERS = {}`` A dictionary of file extensions / Reader classes for Pelican to ``READERS = {}`` A dictionary of file extensions / Reader classes for Pelican to
process or ignore. For example, to avoid processing .html files, process or ignore. For example, to avoid processing .html files,
set: ``READERS = {'html': None}``. To add a custom reader for the set: ``READERS = {'html': None}``. To add a custom reader for the
`foo` extension, set: ``READERS = {'foo': FooReader}`` ``foo`` extension, set: ``READERS = {'foo': FooReader}``
``IGNORE_FILES = ['.#*']`` A list of file globbing patterns to match against the ``IGNORE_FILES = ['.#*']`` A list of file globbing patterns to match against the
source files to be ignored by the processor. For example, source files to be ignored by the processor. For example,
the default ``['.#*']`` will ignore emacs lock files. the default ``['.#*']`` will ignore emacs lock files.
@ -108,10 +108,12 @@ Setting name (followed by default value, if any)
include them explicitly and enumerate the full list of include them explicitly and enumerate the full list of
desired Markdown extensions.) desired Markdown extensions.)
``OUTPUT_PATH = 'output/'`` Where to output the generated files. ``OUTPUT_PATH = 'output/'`` Where to output the generated files.
``PATH = None`` Path to content directory to be processed by Pelican. ``PATH`` Path to content directory to be processed by Pelican. If undefined,
``PAGE_DIR = 'pages'`` Directory to look at for pages, relative to `PATH`. and content path is not specified via an argument to the ``pelican``
command, Pelican will use the current working directory.
``PAGE_DIR = 'pages'`` Directory to look at for pages, relative to ``PATH``.
``PAGE_EXCLUDES = ()`` A list of directories to exclude when looking for pages. ``PAGE_EXCLUDES = ()`` A list of directories to exclude when looking for pages.
``ARTICLE_DIR = ''`` Directory to look at for articles, relative to `PATH`. ``ARTICLE_DIR = ''`` Directory to look at for articles, relative to ``PATH``.
``ARTICLE_EXCLUDES = ('pages',)`` A list of directories to exclude when looking for articles. ``ARTICLE_EXCLUDES = ('pages',)`` A list of directories to exclude when looking for articles.
``OUTPUT_SOURCES = False`` Set to True if you want to copy the articles and pages in their ``OUTPUT_SOURCES = False`` Set to True if you want to copy the articles and pages in their
original format (e.g. Markdown or reStructuredText) to the original format (e.g. Markdown or reStructuredText) to the
@ -201,8 +203,8 @@ for URL formation: *relative* and *absolute*. Relative URLs are useful
when testing locally, and absolute URLs are reliable and most useful when when testing locally, and absolute URLs are reliable and most useful when
publishing. One method of supporting both is to have one Pelican configuration 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 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 type of setup, use the ``pelican-quickstart`` script as described in the
the :doc:`Getting Started <getting_started>` page, which will produce two separate :doc:`Installation <install>` section, which will produce two separate
configuration files for local development and publishing, respectively. configuration files for local development and publishing, respectively.
You can customize the URLs and locations where files will be saved. The You can customize the URLs and locations where files will be saved. The
@ -603,7 +605,7 @@ For example::
Translations 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. more information.
======================================================== ===================================================== ======================================================== =====================================================

18
docs/themes.rst
View file

@ -1,13 +1,21 @@
.. _theming-pelican: .. _theming-pelican:
How to create themes for Pelican Creating themes
################################ ###############
Pelican uses the great `Jinja2 <http://jinja.pocoo.org/>`_ templating engine to To generate its HTML output, Pelican uses the `Jinja <http://jinja.pocoo.org/>`_
generate its HTML output. Jinja2 syntax is really simple. If you want to templating engine due to its flexibility and straightforward syntax. If you want
create your own theme, feel free to take inspiration from the `"simple" theme 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>`_. <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 Structure
========= =========