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

Merge branch 'master' of github.com:ametaireau/pelican into fix-functional-tests

Browse source
This commit is contained in:
Alexis Metaireau 2012-07-10 13:51:34 +02:00
commit 4ce5adb2a0
15 changed files with 338 additions and 123 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/faq.rst
View file

@ -49,3 +49,14 @@ install it. You can do so by typing::
In case you don't have pip installed, consider installing it via::
$ (sudo) easy_install pip
How do I assign custom templates on a per page basis?
=====================================================
It's as simple as adding an extra line of metadata to any pages or articles you
want to have it's own template.
:template: template_name
Then just make sure to have the template installed in to your theme as
``template_name.html``.

106
docs/getting_started.rst
View file

@ -1,15 +1,15 @@
Getting started
###############
Installing
==========
Installing Pelican
==================
You're ready? Let's go! 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::
If you don't have ``pip`` installed, an alternative method is ``easy_install``::
$ easy_install pelican
@ -18,12 +18,13 @@ a virtual environment for Pelican via `virtualenv <http://www.virtualenv.org/>`_
and `virtualenvwrapper <http://www.doughellmann.com/projects/virtualenvwrapper/>`_
before installing Pelican::
$ pip install virtualenvwrapper
$ sudo pip install --upgrade virtualenv virtualenvwrapper
$ mkvirtualenv pelican
$ pip install pelican
Once the virtual environment has been created and activated, Pelican can be
be installed via pip or easy_install as noted above. Alternatively, if you
have the project source, you can install Pelican using the distutils
be installed via ``pip`` or ``easy_install`` as noted above. Alternatively, if
you have the project source, you can install Pelican using the distutils
method::
$ cd path-to-Pelican-source
@ -34,6 +35,11 @@ version of Pelican rather than a stable release, use the following command::
$ pip install -e git://github.com/ametaireau/pelican#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
Upgrading
---------
@ -62,6 +68,59 @@ Optionally:
* pygments, for syntax highlighting
* Markdown, for supporting Markdown as an input format
Kickstart a blog
================
Following is a brief tutorial for those who want to get started right away.
We're going to assume Pelican was installed in a virtual environment via the
following steps (if you're not using a virtual environment for Pelican, you can
skip to the ``pelican-quickstart`` command)::
$ sudo pip install --upgrade virtualenv virtualenvwrapper
$ mkvirtualenv pelican
$ pip install pelican Markdown
Next we'll create a directory to house our site content and configuration files,
which can be located any place you prefer, and associate this new project with
the currently-active virtual environment::
$ mkdir ~/code/yoursitename
$ cd ~/code/yoursitename
$ setvirtualenvproject
Now we can run the ``pelican-quickstart`` command, which will ask some questions
about your site::
$ pelican-quickstart
Once you finish answering all the questions, you can begin adding content to the
*content* folder that has been created for you. (See *Writing articles using
Pelican* section below for more information about how to format your content.)
Once you have some content to generate, you can convert it to HTML via the
following command::
$ make html
If you'd prefer to have Pelican automatically regenerate your site every time a
change is detected (handy when testing locally), use the following command
instead::
$ make regenerate
To serve the site so it can be previewed in your browser::
$ make serve
Visit http://localhost:8000 in your browser to see your site.
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.
Writing articles using Pelican
==============================
@ -83,7 +142,6 @@ following syntax (give your file the ``.rst`` extension)::
:category: yeah
:author: Alexis Metaireau
You can also use Markdown syntax (with a file ending in ``.md``).
Markdown generation will not work until you explicitly install the ``Markdown``
package, which can be done via ``pip install Markdown``. Metadata syntax for
@ -105,27 +163,28 @@ example, a file located at ``python/foobar/myfoobar.rst`` will have a category o
Generate your blog
------------------
To launch Pelican, just use the ``pelican`` command::
The ``make`` shortcut commands mentioned in the ``Kickstart a blog`` section
are mostly wrappers around the ``pelican`` command that generates the HTML from
the content. The ``pelican`` command can also be run directly::
$ pelican /path/to/your/content/ [-s path/to/your/settings.py]
And… that's all! Your weblog will be generated and saved in the ``content/``
folder.
The above command will generate your weblog and save it in the ``content/``
folder, using the default theme to produce a simple site. The default theme is
simple HTML without styling and is provided so folks may use it as a basis for
creating their own themes.
The above command will use the default theme to produce a simple site. It's not
very sexy, as it's just simple HTML output (without any style).
You can create your own style if you want. Have a look at the help to see all
the options you can use::
Pelican has other command-line switches available. Have a look at the help to
see all the options you can use::
$ pelican --help
Kickstart a blog
----------------
Auto-reload
-----------
You also can use the ``pelican-quickstart`` script to start a new blog in
seconds by just answering a few questions. Just run ``pelican-quickstart`` and
you're done! (Added in Pelican 3.0)
It's possible to 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.
Pages
-----
@ -209,13 +268,6 @@ For Markdown, format your code blocks thusly::
The specified identifier should be one that appears on the
`list of available lexers <http://pygments.org/docs/lexers/>`_.
Auto-reload
-----------
It's possible to 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.
Publishing drafts
-----------------

25
docs/settings.rst
View file

@ -63,18 +63,16 @@ Setting name (default value) What doe
`PDF_GENERATOR` (``False``) Set to True if you want to have PDF versions
of your documents. You will need to install
`rst2pdf`.
`RELATIVE_URLS` (``True``) Defines whether Pelican should use relative URLs or
not.
`RELATIVE_URLS` (``True``) Defines whether Pelican should use document-relative URLs or
not. If set to ``False``, Pelican will use the SITEURL
setting to construct absolute URLs.
`PLUGINS` (``[]``) The list of plugins to load. See :ref:`plugins`.
`SITENAME` (``'A Pelican Blog'``) Your site name
`SITEURL` Base URL of your website. Not defined by default,
which means the base URL is assumed to be "/" with a
root-relative URL structure. If `SITEURL` is specified
explicitly, there should be no trailing slash at the end,
and URLs will be generated with an absolute URL structure
(including the domain). If you want to use relative URLs
instead of root-relative or absolute URLs, you should
instead use the `RELATIVE_URL` setting.
so it is best to specify your SITEURL; if you do not, feeds
will not be generated with properly-formed URLs. You should
include ``http://`` and your domain, with no trailing
slash at the end. Example: ``SITEURL = 'http://mydomain.com'``
`STATIC_PATHS` (``['images']``) The static paths you want to have accessible
on the output path "static". By default,
Pelican will copy the 'images' folder to the
@ -111,6 +109,15 @@ Setting name (default value) What doe
URL settings
------------
The first thing to understand is that there are currently two supported methods
for URL formation: *relative* and *absolute*. Document-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
configuration files for local development and publishing, respectively.
You can customize the URLs and locations where files will be saved. The URLs and
SAVE_AS variables use Python's format strings. These variables allow you to place
your articles in a location such as '{slug}/index.html' and link to them as