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