1Installing Pelican
2##################
3
4Pelican currently runs best on 3.6+; earlier versions of Python are not supported.
5
6You can install Pelican via several different methods. The simplest is via Pip_::
7
8    python -m pip install pelican
9
10Or, if you plan on using Markdown::
11
12    python -m pip install "pelican[markdown]"
13
14(Keep in mind that some operating systems will require you to prefix the above
15command with ``sudo`` in order to install Pelican system-wide.)
16
17While the above is the simplest method, the recommended approach is to create a
18virtual environment for Pelican via virtualenv_ before installing Pelican.
19Assuming you have virtualenv_ installed, you can then open a new terminal
20session and create a new virtual environment for Pelican::
21
22    virtualenv ~/virtualenvs/pelican
23    cd ~/virtualenvs/pelican
24    source bin/activate
25
26Once the virtual environment has been created and activated, Pelican can be
27installed via ``python -m pip install pelican`` as noted above. Alternatively, if you
28have the project source, you can install Pelican using the distutils method::
29
30    cd path-to-Pelican-source
31    python setup.py install
32
33If you have Git installed and prefer to install the latest bleeding-edge
34version of Pelican rather than a stable release, use the following command::
35
36    python -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"
37
38Once Pelican is installed, you can run ``pelican --help`` to see basic usage
39options. For more detail, refer to the :doc:`Publish<publish>` section.
40
41Optional packages
42-----------------
43
44If you plan on using `Markdown <https://pypi.org/project/Markdown/>`_ as a
45markup format, you can install Pelican with Markdown support::
46
47    python -m pip install "pelican[markdown]"
48
49Typographical enhancements can be enabled in your settings file, but first the
50requisite `Typogrify <https://pypi.org/project/typogrify/>`_ library must be
51installed::
52
53    python -m pip install typogrify
54
55Dependencies
56------------
57
58When Pelican is installed, the following dependent Python packages should be
59automatically installed without any action on your part:
60
61* `feedgenerator <https://pypi.org/project/feedgenerator/>`_, to generate the
62  Atom feeds
63* `jinja2 <https://pypi.org/project/Jinja2/>`_, for templating support
64* `pygments <https://pypi.org/project/Pygments/>`_, for syntax highlighting
65* `docutils <https://pypi.org/project/docutils/>`_, for supporting
66  reStructuredText as an input format
67* `pytz <https://pypi.org/project/pytz/>`_, for timezone definitions
68* `blinker <https://pypi.org/project/blinker/>`_, an object-to-object and
69  broadcast signaling system
70* `unidecode <https://pypi.org/project/Unidecode/>`_, for ASCII
71  transliterations of Unicode text
72  utilities
73* `MarkupSafe <https://pypi.org/project/MarkupSafe/>`_, for a markup-safe
74  string implementation
75* `python-dateutil <https://pypi.org/project/python-dateutil/>`_, to read
76  the date metadata
77
78Upgrading
79---------
80
81If you installed a stable Pelican release via Pip_ and wish to upgrade to
82the latest stable release, you can do so by adding ``--upgrade``::
83
84    python -m pip install --upgrade pelican
85
86If you installed Pelican via distutils or the bleeding-edge method, simply
87perform the same step to install the most recent version.
88
89Kickstart your site
90-------------------
91
92Once Pelican has been installed, you can create a skeleton project via the
93``pelican-quickstart`` command, which begins by asking some questions about
94your site::
95
96    pelican-quickstart
97
98If run inside an activated virtual environment, ``pelican-quickstart`` will
99look for an associated project path inside ``$VIRTUAL_ENV/.project``. If that
100file exists and contains a valid directory path, the new Pelican project will
101be saved at that location. Otherwise, the default is the current working
102directory. To set the new project path on initial invocation, use:
103``pelican-quickstart --path /your/desired/directory``
104
105Once you finish answering all the questions, your project will consist of the
106following hierarchy (except for *pages* — shown in parentheses below — which
107you can optionally add yourself if you plan to create non-chronological
108content)::
109
110    yourproject/
111    ├── content
112    │   └── (pages)
113    ├── output
114    ├── tasks.py
115    ├── Makefile
116    ├── pelicanconf.py       # Main settings file
117    └── publishconf.py       # Settings to use when ready to publish
118
119The next step is to begin to adding content to the *content* folder that has
120been created for you.
121
122.. _Pip: https://pip.pypa.io/
123.. _virtualenv: https://virtualenv.pypa.io/en/latest/
124