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

Improve English documentation with enhanced clarity, grammar, and spelling

Browse source
This commit is contained in:
Justin Mayer 2012-03-06 06:13:17 -08:00
commit bde06c4011
11 changed files with 429 additions and 403 deletions
Download patch file Download diff file Expand all files Collapse all files

140
docs/getting_started.rst
View file

@ -4,13 +4,12 @@ Getting started
Installing
==========
You're ready? Let's go ! You can install pelican in a lot of different ways,
the simpler one is via `pip <http://pip.openplans.org/>`_::
You're ready? Let's go! You can install Pelican via several different methods. The simplest is via `pip <http://pip.openplans.org/>`_::
$ pip install pelican
If you have the sources, you can install pelican using the distutils command
install. I recommend to do so in a virtualenv::
If you have the project source, you can install Pelican using the distutils
method. I recommend doing so in a virtualenv::
$ virtualenv pelican_venv
$ source bin/activate
@ -19,30 +18,30 @@ install. I recommend to do so in a virtualenv::
Dependencies
------------
At this time, pelican is dependent of the following python packages:
At this time, Pelican is dependent on the following Python packages:
* feedgenerator, to generate the ATOM feeds.
* jinja2, for templating support.
* feedgenerator, to generate the Atom feeds
* jinja2, for templating support
If you're not using python 2.7, you will also need `argparse`.
If you're not using Python 2.7, you will also need `argparse`.
Optionally:
* docutils, for reST support
* pygments, to have syntactic colorization with resT input
* Markdown, for Markdown as an input format
* pygments, for syntax highlighting
* docutils, for supporting reStructuredText as an input format
* Markdown, for supporting Markdown as an input format
Writing articles using pelican
Writing articles using Pelican
==============================
Files metadata
File metadata
--------------
Pelican tries to be smart enough to get the informations it needs from the
file system (for instance, about the category of your articles), but you need to
provide by hand some of those informations in your files.
Pelican tries to be smart enough to get the information it needs from the
file system (for instance, about the category of your articles), but some
information you need to provide in the form of metadata inside your files.
You could provide the metadata in the restructured text files, using the
You can provide this metadata in reStructuredText text files via the
following syntax (give your file the `.rst` extension)::
My super title
@ -54,31 +53,35 @@ following syntax (give your file the `.rst` extension)::
:author: Alexis Metaireau
You can also use a markdown syntax (with a file ending in `.md`)::
You can also use Markdown syntax (with a file ending in `.md`)::
Date: 2010-12-03
Title: My super title
Tags: thats, awesome
Slug: my-super-post
Put you content here.
This is the content of my super blog post.
Note that none of those are mandatory: if the date is not specified, pelican will
rely on the mtime of your file, and the category can also be determined by the
directory where the rst file is. For instance, the category of
`python/foobar/myfoobar.rst` is `foobar`.
Note that, aside from the title, none of this metadata is mandatory: if the date
is not specified, Pelican will rely on the file's "mtime" timestamp, and the
category can be determined by the directory in which the file resides. For
example, a file located at `python/foobar/myfoobar.rst` will have a category of
`foobar`.
Generate your blog
------------------
To launch pelican, just use the `pelican` command::
To launch Pelican, just use the `pelican` command::
$ pelican /path/to/your/content/ [-s path/to/your/settings.py]
And… that's all! You can see your weblog generated on the `content/` folder.
And… that's all! Your weblog will be generated and saved in the `content/`
folder.
This one will just generate a simple output, with the default theme. It's not
really sexy, as it's a simple HTML output (without any style).
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 to the help to see all
You can create your own style if you want. Have a look at the help to see all
the options you can use::
$ pelican --help
@ -88,7 +91,7 @@ Kickstart a blog
You also can use the `pelican-quickstart` script to start a new blog in
seconds, by just answering few questions. Just run `pelican-quickstart` and
you're done! (Added in pelican 3)
you're done! (Added in Pelican 3.0)
Pages
-----
@ -102,26 +105,26 @@ the menu.
Importing an existing blog
--------------------------
It is possible to import your blog from dotclear, wordpress and an RSS feed using
It is possible to import your blog from Dotclear, WordPress, 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
in your articles/pages, and to set a `DEFAULT_LANG` setting (which is en by
default).
Then, only articles with this default language will be listed, and
each article will have a translation list.
attribute to your articles/pages and set a `DEFAULT_LANG` setting (which is
English [en] by default). With those settings in place, only articles with the
default language will be listed, and each article will be accompanied by a list
of available translations for that article.
Pelican uses the "slug" of two articles to compare if they are translations of
each others. So it's possible to define (in restructured text) the slug
directly.
Pelican uses the article's URL "slug" to determine if two or more articles are
translations of one another. The slug can be set manually in the file's
metadata; if not set explicitly, Pelican will auto-generate the slug from the
title of the article.
Here is an exemple of two articles (one in english and the other one in
french).
Here is an example of two articles, one in English and the other in French.
The english one::
The English article::
Foobar is not dead
##################
@ -129,9 +132,9 @@ The english one::
:slug: foobar-is-not-dead
:lang: en
That's true, foobar is still alive !
That's true, foobar is still alive!
And the french one::
And the French version::
Foobar n'est pas mort !
#######################
@ -141,56 +144,67 @@ And the french one::
Oui oui, foobar est toujours vivant !
Despite the text quality, you can see that only the slug is the same here.
You're not forced to define the slug that way, and it's completely possible to
have two translations with the same title (which defines the slug)
Post content quality notwithstanding, you can see that only item in common
between the two articles is the slug, which is functioning here as an
identifier. If you'd rather not explicitly define the slug this way, you must
then instead ensure that the translated article titles are identical, since the
slug will be auto-generated from the article title.
Syntactic recognition
Syntax highlighting
---------------------
Pelican is able to regognise the syntax you are using, and to colorize the
right way your block codes. To do so, you have to use the following syntax::
Pelican is able to provide colorized syntax highlighting for your code blocks.
To do so, you have to use the following convention for reStructuredText::
.. code-block:: identifier
your code goes here
The identifier is one of the lexers available `here
<http://pygments.org/docs/lexers/>`_.
For Markdown, format your code blocks thusly:
You also can use the default `::` syntax::
::identifier
your code goes here
The specified identifier should be one that appears on the
`list of available lexers <http://pygments.org/docs/lexers/>`_.
You also can use the default `::` syntax, in which case it will be assumed
that your code is written in Python. For reStructuredText::
::
your code goes here
It will be assumed that your code is witten in python.
For Markdown:
::
your code goes here
Autoreload
----------
It's possible to tell pelican to watch for your modifications, instead of
manually launching it each time you need. Use the `-r` option, or
`--autoreload`.
It's possible to tell Pelican to watch for your modifications, instead of
manually launching it every time you want to see your changes. To enable this,
run the `pelican` command with the `-r` or `--autoreload` options.
Publishing drafts
-----------------
If you want to publish an article as a draft, for friends to review it for
instance, you can add a ``status: draft`` to its metadata, it will then be
available under the ``drafts`` folder, and not be listed under the index page nor
any category page.
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 page.
Viewing the generated files
---------------------------
The files generated by pelican are static files, so you don't actually need
something special to see what's hapenning with the generated files.
The files generated by Pelican are static files, so you don't actually need
anything special to see what's happening with the generated files.
You can either run your browser on the files on your disk::
You can either use your browser to open the files on your disk::
$ firefox output/index.html
Or run a simple web server using python::
Or run a simple web server using Python::
cd output && python -m SimpleHTTPServer