Skip to content

install.rst

Latest commit

 

History

History
146 lines (102 loc) · 4.96 KB

install.rst

File metadata and controls

146 lines (102 loc) · 4.96 KB
Raw

Installing Pelican

Pelican currently runs best on |min_python|; earlier versions of Python are not supported.

You can install Pelican via several different methods. The simplest is via Pip:

python -m pip install pelican

Or, if you plan on using Markdown:

python -m pip install "pelican[markdown]"

(Keep in mind that some operating systems will require you to prefix the above command 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
source bin/activate

Once the virtual environment has been created and activated, Pelican can be installed via python -m pip install pelican as noted above. Alternatively, if you have the project source, you can install Pelican using the setuptools method:

cd path-to-Pelican-source
python -m pip 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:

python -m pip install -e "git+https://github.com/getpelican/pelican.git#egg=pelican"

Once Pelican is installed, you can run pelican --help to see basic usage options. For more detail, refer to the :doc:`Publish<publish>` section.

Optional packages

If you plan on using Markdown as a markup format, you can install Pelican with Markdown support:

python -m pip install "pelican[markdown]"

Typographical enhancements can be enabled in your settings file, but first the requisite Typogrify library must be installed:

python -m pip install typogrify

Dependencies

When Pelican is installed, the following dependent Python packages should be automatically installed without any action on your part:

Upgrading

If you installed a stable Pelican release via Pip and wish to upgrade to the latest stable release, you can do so by adding --upgrade:

python -m 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.

Windows notes

Git Bash users may encounter:

bash: pelican-quickstart: command not found

This occurs because Git Bash does not automatically include Python’s Scripts directory in PATH.

Recommended options:

  • Use PowerShell instead of Git Bash
  • Use WSL (Windows Subsystem for Linux) for a Linux-like environment

Alternative workarounds:

  • Ensure Python’s Scripts directory is in PATH

  • Run Pelican via:

    python -m pelican

See issue #3574 for discussion.

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

If run inside an activated virtual environment, pelican-quickstart will look for an associated project path inside $VIRTUAL_ENV/.project. If that file exists and contains a valid directory path, the new Pelican project will be saved at that location. Otherwise, the default is the current working directory. To set the new project path on initial invocation, use:

pelican-quickstart --path /your/desired/directory

Once you finish answering all the questions, your project will consist of the following hierarchy (except for pages — shown in parentheses below — which you can optionally add yourself if you plan to create non-chronological content):

yourproject/
├── content
│   └── (pages)
├── output
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

The next step is to begin adding content to the content folder that has been created for you.