In the vast landscape of website creation tools, Pelican stands out as a powerful and flexible static site generator. Whether you're a seasoned developer or a beginner looking to establish an online presence, Pelican offers a straightforward way to build and deploy a website. Coupled with Visual Studio Code (VSCode) for development and Cloudflare Pages for hosting, you can create and manage your site efficiently. In this guide, we'll walk you through deploying your very first website using Pelican, leveraging VSCode for development, and hosting it on Cloudflare Pages.

What is Pelican?

Pelican is a static site generator written in Python. Unlike dynamic websites that rely on databases and server-side processing, static sites are composed of pre-rendered HTML, CSS, and JavaScript files. This approach offers benefits like improved security, faster load times, and easier deployment.

Why Choose Pelican?

  • Simplicity: Write your content in Markdown or reStructuredText, and Pelican handles the rest.
  • Flexibility: Customize themes, plugins, and configurations to suit your needs.
  • Performance: Static sites are inherently fast and require minimal server resources.
  • Version Control Friendly: Since the site is composed of text files, integrating with version control systems like Git is seamless.

Prerequisites

Before diving into Pelican, ensure you have the following:

  • Python Installed: Pelican is a Python-based tool. Make sure you have Python 3.6 or later installed. We shall be using Python 3.12. You can download it from the official website.
  • Basic Command-Line Knowledge: Familiarity with terminal or command prompt operations will be beneficial.
  • Visual Studio Code (VSCode): A powerful and versatile code editor. Download it from the official website.
  • Git Installed: For version control and integration with Cloudflare Pages. Download it from the official website.

Step 1: Set Up Your Development Environment with VSCode

Using Visual Studio Code (VSCode) enhances your development workflow by providing a robust environment with features like a sidebar for easy file navigation, an integrated terminal, and a plethora of extensions to streamline your workflow.

Install VSCode Extensions

To optimize VSCode for Pelican development, install the following extensions: - Python: Provides rich support for Python development. - Markdown All in One: Enhances Markdown editing with shortcuts and previews. - Pelican Snippets: Speeds up writing Pelican-specific code. - GitLens: Enhances Git capabilities within VSCode. - Live Server: Allows you to preview your site locally in real-time.

You can install these extensions by clicking on the Extensions icon in the sidebar or pressing Ctrl+Shift+X and searching for each extension by name.

Create a New Project Directory

Open VSCode and use the integrated terminal to create a new project directory. 

mkdir my-first-pelican-site
cd my-first-pelican-site

Alternatively, you can use the File > Open Folder option in VSCode to open the newly created directory.

Open the Workspace in VSCode

By opening the workspace in VSCode, you'll have access to all your project files in the sidebar, allowing for easy navigation and editing.

Step 2: Install Pelican and Dependencies

First, let's set up a virtual environment to keep Pelican and its dependencies isolated.

Create a Virtual Environment

python3 -m venv .venv

Activate the Virtual Environment

On macOS/Linux:

source .venv/bin/activate

On Windows:

.venv\Scripts\activate

Install Pelican and Markdown (optional)

pip install pelican markdown

Pelican supports various markup languages. Here, we're installing Markdown for content creation.

Step 3: Create a New Pelican Project

With Pelican installed, you can now create a new project.

Initialize a New Pelican Site

pelican-quickstart

Answer the Prompts

You'll be guided through a series of questions to set up your site configuration. Here's an example:

(.venv) abdy@abdy-pc:~/my-first-pelican-site$ pelican-quickstart
Welcome to pelican-quickstart v4.10.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.] 
> What will be the title of this web site? My First Pelican Site
> Who will be the author of this web site? Abhyuday
> What will be the default language of this web site? [en] 
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Rome] Asia/Kolkata
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) n
> Do you want to upload your website using FTP? (y/N) n
> Do you want to upload your website using SSH? (y/N) n
> Do you want to upload your website using Dropbox? (y/N) n
> Do you want to upload your website using S3? (y/N) n
> Do you want to upload your website using Rackspace Cloud Files? (y/N) n
> Do you want to upload your website using GitHub Pages? (y/N) n
Done. Your new project is available at ~/my-first-pelican-site

For the theme, you can press Enter to use the default theme or specify one later.

Directory Structure

After completion, your project directory will look like this:

my-first-pelican-site/
├── content/
│   ├── pages/
│   └── articles/
├── output/
├── pelicanconf.py
└── publishconf.py

If you don't see pages and articles directory, you can go ahead and create the same as pelican uses the pages directory for static pages like about us, contact etc. and articles directory for the blog posts.

Step 4: Create Your First Post

Create a Markdown File

Now, let's add content to your site.

In VSCode's Explorer terminal, right click the articles directory and create a new file named welcome.md and add the following content to the file:

Title: Welcome to My Pelican Site
Date: 2024-11-9
Category: Introduction
Tags: pelican, static site, blog
Slug: welcome
Author: Abhyuday
Summary: This is my first post using Pelican. Excited to share more!
Publish: True

# Hello World!

This is my first post on my new Pelican-powered website. Stay tuned for more updates!

Pelican uses metadata at the top of the file to manage posts.

Save the File

Save the welcome.md file in VSCode. The live preview from the Markdown All in One extension can help visualize the content as you write.

Step 5: Generate the Static Site

With your content in place, it's time to generate the static files using Pelican's command-line flags instead of a Makefile.

Generate and Render the Site Using Pelican Commands

Cloudflare Pages supports Pelican natively, so you can use Pelican's flags for content generation and rendering.

pelican content -r -l

*-r flag or --recursive flag: Recursively process content files.

*-l flag or --listen flag: Serve the site locally for preview.

This command processes your content and creates the static site in the output/ directory. Additionally, it serves the site locally so you can preview it in your browser.

Preview Locally

After running the above command, open your browser and navigate to http://127.0.0.1:8000 to see your site in action. You can make changes in VSCode, and the live server will automatically refresh the preview.

Step 6: Choose a Hosting Platform

Pelican-generated static sites can be hosted on various platforms. Here are some popular choices:

  • Cloudflare Pages: Offers seamless integration with Pelican, continuous deployment, custom domains, and a global CDN for fast content delivery.
  • GitHub Pages: Free and integrates seamlessly with GitHub repositories.
  • Netlify: Provides continuous deployment, custom domains, and a range of build options.
  • Amazon S3: Scalable storage solution for hosting static sites.
  • DigitalOcean: Flexible VPS hosting for more control.

For this guide, we'll use Cloudflare Pages due to its native support for Pelican and its robust feature set.

Step 7: Deploying to Cloudflare Pages

Cloudflare Pages simplifies the deployment process by natively supporting Pelican. Here's how to deploy your site:

Push Your Code to a Git Repository

Cloudflare Pages integrates with GitHub, GitLab, and Bitbucket. We'll use GitHub in this example.

  • Initialize a Git Repository:

If you haven't already, initialize Git in your project:

git init
git add .
git commit -m "Initial commit"
  • Create a GitHub Repository:
  • Go to GitHub and create a new repository named my-first-pelican-site.
  • Push Your Code to GitHub:
git remote add origin https://github.com/yourusername/my-first-pelican-site.git
git branch -M main
git push -u origin main

Set Up Cloudflare Pages

Log in to Cloudflare:

If you don't have an account, sign up at Cloudflare.

Create a New Project:

  • Navigate to the Pages section in the Cloudflare dashboard.
  • Click on Create a Project.
  • Connect your GitHub account and select the my-first-pelican-site repository.

Configure the Build Settings:

Cloudflare Pages automatically detects Pelican as the framework. Ensure the following settings:

  • Build Command: pelican content -o output -s pelicanconf.py
  • Output Directory: output

Since Cloudflare Pages supports Pelican natively, you don't need to use a Makefile.

Deploy the Site:

Click Save and Deploy. Cloudflare Pages will start the build process. This might take a few minutes. Once deployed, your site will be accessible at

https://your-subdomain.pages.dev/.

Configure Custom Domain (Optional):

Add a Custom Domain:

  • In your Cloudflare Pages project, navigate to the Settings.
  • Under Custom Domains, add your desired domain.
  • Follow the instructions to update your DNS settings.

Enable HTTPS:

Cloudflare Pages provides free SSL certificates. Ensure HTTPS is enabled for secure access.

Automate Deployment:

Every time you push changes to the main branch on GitHub, Cloudflare Pages will automatically rebuild and deploy your site. This continuous deployment ensures your website is always up-to-date with your latest content.

Conclusion

Deploying your first website with Pelican is a rewarding experience that combines the power of Python with the simplicity of static site generation. By leveraging Visual Studio Code (VSCode) for development, you benefit from a robust and efficient coding environment that enhances productivity. Hosting your site on Cloudflare Pages provides seamless integration, automated deployments, and a global CDN that ensures your site is fast and reliable. As you become more comfortable with Pelican, you can explore advanced features, integrate with other tools, and scale your site to meet your growing needs.

Appendices

Appendix A: Key Code Snippets

Pelican Configuration (pelicanconf.py)

AUTHOR = 'Abhyuday'
SITENAME = 'My First Pelican Site'
SITEURL = ""

PATH = "content"

TIMEZONE = 'Asia/Kolkata'

DEFAULT_LANG = 'en'

# Feed generation is usually not desired when developing
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None

# Blogroll
LINKS = (
    ("Pelican", "https://getpelican.com/"),
    ("Python.org", "https://www.python.org/"),
    ("Jinja2", "https://palletsprojects.com/p/jinja/"),
    ("You can modify those links in your config file", "#"),
)

# Social widget
SOCIAL = (
    ("You can add links in your config file", "#"),
    ("Another social link", "#"),
)

DEFAULT_PAGINATION = 10

# Uncomment following line if you want document-relative URLs when developing
RELATIVE_URLS = True

First Post (welcome.md)

Title: Welcome to My Pelican Site
Date: 2024-11-9
Category: Introduction
Tags: pelican, static site, blog
Slug: welcome
Author: Abhyuday
Summary: This is my first post using Pelican. Excited to share more!
Publish: True

# Hello World!

This is my first post on my new Pelican-powered website. Stay tuned for more updates!