forked from github/pelican
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/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue