This tutorial follows
a similar tutorial from the web.
I tested that tutorial to see if it works.
This tutorial is focused on GitHub but can also be used independently on another python platform.
You need a
GitHub Pro, your personal account:
With GitHub Pro, your personal account gets unlimited public and private repositories with unlimited collaborators.
In addition to the features available with GitHub Free, private repositories on GitHub Pro include advanced tools and insights:
Unlimited collaborators
GitHub Pages
Wikis
Protected branches
Code owners
Repository insights graphs: Pulse, contributors, traffic, commits, code frequency, network, and forks
Let's start with pip install tool:
C:\Python373>cd Scripts
C:\Python373\Scripts>pip install pelican ghp-import
...
Installing collected packages: unidecode, blinker, feedgenerator, pelican, ghp-import
Successfully installed blinker-1.4 feedgenerator-1.9 ghp-import-0.5.5 pelican-4.0.1
unidecode-1.0.23
Now you can create a new repository with your name into the GitHub website.
I create a repository named
catafest:
C:\Python373\Scripts>git clone https://github.com/catafest/catafest.git blog
Cloning into 'blog'...
warning: You appear to have cloned an empty repository.
C:\Python373\Scripts>cd blog
C:\Python373\Scripts\blog>git checkout -b content
Switched to a new branch 'content'
C:\Python373\Scripts\blog>pelican-quickstart
Welcome to pelican-quickstart v4.0.1.
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? catafest
> Who will be the author of this web site? Catalin George Festila
> What will be the default language of this web site? [English]
> 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)
> How many articles per page do you want? [10]
> What is your time zone? [Europe/Paris] Europe/Bucharest
> Do you want to generate a tasks.py/Makefile to automate generation and publish
ing? (Y/n) y
> 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) y
> Is this your personal page (username.github.io)? (y/N) y
Done. Your new project is available at C:\Python373\Scripts\blog
The content of the blog file:
[.] [..] [content] Makefile
[output] pelicanconf.py publishconf.py tasks.py
4 File(s) 6,496 bytes
4 Dir(s) 333,558,878,208 bytes free
The quickstart created five files and one new directory:
- Makefile: make command convenience tasks for common operations such as running a development server, building a site and cleaning extraneous build files;
- fabfile.py: A Fabric file that has some of the same types of commands as the Makefile. Fabric is a wonderful code library but for now I recommend skipping the Fabric file because unfortunately Fabric does not yet support Python 3;
- develop_server.sh: shell script for running the development server;
- pelicanconf.py: settings file for your Pelican project. If you are used to earlier versions of Pelican this file was instead named settings.py;
- publishconf.py: another (optional) settings file that can be considered as a "production" settings file when you move past the development phase and want to deploy your site;
- content: location for your markup files, which should be stored under pages and posts directories
Now we can use the local Git repo, commit the changes, and push the local changes to the remote repo hosted on GitHub:
C:\Python373\Scripts\blog>git add .
warning: LF will be replaced by CRLF in Makefile.
This can be fixed with:
git config core.autocrlf true
Check the first commit:
C:\Python373\Scripts\blog>git commit -m "first commit"
*** Please tell me who you are.
Run
git config --global user.email "you@example.com"
git config --global user.name "Your Name"
to set your account's default identity.
Omit --global to set the identity only in this repository.
fatal: unable to auto-detect email address (got 'catal_000@catafest.(none)')
Add the mail and name to your git settings:
C:\Python373\Scripts\blog>git config --global user.email "catafest@yahoo.com"
C:\Python373\Scripts\blog>git config --global user.name "catafest"
Use the git for the first commit
C:\Python373\Scripts\blog>git commit -m "first commit"
[content (root-commit) 85814f7] first commit
6 files changed, 230 insertions(+)
create mode 100644 Makefile
create mode 100644 README.md
create mode 100644 git
create mode 100644 pelicanconf.py
create mode 100644 publishconf.py
create mode 100644 tasks.py
C:\Python373\Scripts\blog>git push origin content
Enumerating objects: 8, done.
Counting objects: 100% (8/8), done.
Delta compression using up to 2 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 2.91 KiB | 994.00 KiB/s, done.
Total 8 (delta 0), reused 0 (delta 0)
To https://github.com/catafest/catafest.git
* [new branch] content -> content
Create folders
pages and
images and create the first post with new file
first-post.md.
C:\Python373\Scripts\blog>cd content
C:\Python373\Scripts\blog\content>mkdir pages images
C:\Python373\Scripts\blog\content>notepad first-post.md
Add content to the first post:
title: First Post on My Sweet New Blog
date:
author: Your Name Here
#I am On My Way To Internet Fame and Fortune!
This is my first post on my new blog. While not super informative it
should convey my sense of excitement and eagerness to engage with you,
the reader!
Copy an image file into folder
images.
I used the
catafest.jpg image.
Create a new file into
pages and named this file
about.md.
C:\Python373\Scripts\blog\content>cd pages
C:\Python373\Scripts\blog\content\pages>notepad about.md
The content of
about.md file is:
title: About
date:
![So Schmexy][my_sweet_photo]
Hi, I am and I wrote this epic collection of Interweb
wisdom. In days of yore, much of this would have been deemed sorcery
and I would probably have been burned at the stake.
😆
[my_sweet_photo]: {filename}/images/catafest.jpg
C:\Python373\Scripts\blog\content>cd pages
C:\Python373\Scripts\blog\content\pages>notepad about.md
Run Pelican to generate the static HTML files in the output:
C:\Python373\Scripts\blog\content\pages>notepad about.md
C:\Python373\Scripts\blog\content\pages>cd ..
C:\Python373\Scripts\blog\content>cd ..
C:\Python373\Scripts\blog>pelican content -o output -s publishconf.py
WARNING: Feeds generated without SITEURL set properly may not be valid
WARNING: Docutils has no localization for 'english'. Using 'en' instead.
WARNING: No valid files found in content for the active readers:
| BaseReader (static)
| HTMLReader (htm, html)
| RstReader (rst)
Done: Processed 0 articles, 0 drafts, 0 pages, 0 hidden pages and 0 draft pages
in 0.23 seconds.
C:\Python373\Scripts\blog>ghp-import -m "Generate Pelican site" --no-jekyll -b m
aster output
C:\Python373\Scripts\blog>git push origin master
Enumerating objects: 49, done.
Counting objects: 100% (49/49), done.
Delta compression using up to 2 threads
Compressing objects: 100% (45/45), done.
Writing objects: 100% (49/49), 149.15 KiB | 2.98 MiB/s, done.
Total 49 (delta 5), reused 0 (delta 0)
remote: Resolving deltas: 100% (5/5), done.
remote:
remote: Create a pull request for 'master' on GitHub by visiting:
remote: https://github.com/catafest/catafest/pull/new/master
remote:
To https://github.com/catafest/catafest.git
* [new branch] master -> master
C:\Python373\Scripts\blog>git add content
C:\Python373\Scripts\blog>git commit -m "added a first post, a photo and an abou
t page"
[content 4b036fd] added a first post, a photo and an about page
3 files changed, 21 insertions(+)
create mode 100644 content/first-post.md
create mode 100644 content/images/catafest.jpg
create mode 100644 content/pages/about.md
C:\Python373\Scripts\blog>git push origin content
Enumerating objects: 9, done.
Counting objects: 100% (9/9), done.
Delta compression using up to 2 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 20.28 KiB | 5.07 MiB/s, done.
Total 8 (delta 1), reused 0 (delta 0)
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To https://github.com/catafest/catafest.git
85814f7..4b036fd content -> content
Open your browser and enter:
https://username.github.io
If you want to test it without Github, then use this:
C:\Python373\Scripts\blog>pelican -s pelicanconf.py -o output content
WARNING: Docutils has no localization for 'english'. Using 'en' instead.
WARNING: No valid files found in content for the active readers:
| BaseReader (static)
| HTMLReader (htm, html)
| RstReader (rst)
Done: Processed 0 articles, 0 drafts, 0 pages, 0 hidden pages and 0 draft pages
in 0.19 seconds.
C:\Python373\Scripts\blog>cd output
C:\Python373\Scripts\blog\output>python -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
Open your browser with the
http://localhost:8000 URL.
You need to understand the difference between these two commands and how this make changes into output:
C:\Python373\Scripts\blog>pelican -s pelicanconf.py -o output content
WARNING: Docutils has no localization for 'english'. Using 'en' instead.
WARNING: No valid files found in content for the active readers:
| BaseReader (static)
| HTMLReader (htm, html)
| RstReader (rst)
Done: Processed 0 articles, 0 drafts, 0 pages, 0 hidden pages and 0 draft pages
in 0.19 seconds.
C:\Python373\Scripts\blog>pelican content -o output -s publishconf.py
WARNING: Feeds generated without SITEURL set properly may not be valid
WARNING: Docutils has no localization for 'english'. Using 'en' instead.
WARNING: No valid files found in content for the active readers:
| BaseReader (static)
| HTMLReader (htm, html)
| RstReader (rst)
Done: Processed 0 articles, 0 drafts, 0 pages, 0 hidden pages and 0 draft pages
in 0.23 seconds.
You can create themes and used into similar way like django with this command:
pelican -s pelicanconf.py -o output -t theme content
I do not want to extend this tutorial, but I can tell you that this python module is very versatile.