Procedure for creating a Pelican website from source developed by Mind Flow Productions.
To create a pelican website from the current mindflow source follow the steps below.
Preliminary System Check
First you need access to a computer running Ubuntu. I am using the Ubuntu 16.04 release. The pelican website is created with Python3.5 so make sure it (or a more recent version) is installed. Both python2.7+ and python3.5+ should be installed on Ubuntu. To check for python3 run:
python3 -V
Also make sure pip is installed
pip3 -V
Install Git (if not installed)
To see if it is installed type ‘git —version’ in the terminal.
For detailed install instructions go to these links:
Installing-Git
First-Time-Git-Setup
Install virtualenv and virtualenvwrapper
Clone the sitedev repo
All references to ‘grokthis’ or ‘grok’ are just by example, name this whatever makes sense for your project. It is best to use a name that could be considered a short name for your website or company. The name of your website (or the domain name) might long. Make a short version.
i.e. ‘Mind Flow’ is a good short name for ‘Mind Flow Productions’ (mindflowproductions.com) and for the foldername would become ‘mindflow’ without spaces.
This short name for the repo folder is automatically created from the short name ‘Mind Flow’ in Pelican siteconfig.py. The short name is used in Pelican to find the content folder. The form is ‘shortname’ for the code repo and ‘shortname_content’ for the content repo. You can easily override this in the siteconfig.py file.
git clone https://gitlab.com/ubiquity/sitedev.git /mnt/d/dev/grokthis
You will be prompted for the git username and password.
This will create the target folder ‘/mnt/d/dev/grokthis’ and clone the repo there. In this example it is mounted from the Windows file system as I am using the Windows Subsystem for Linux. Thats why the path starts with /mnt/d/dev where /mnt is the ubuntu mount location, /d is the drive on Windows, and /dev is the root folder for the all the development folders and files.
Now create a symlink to the new repo folder. For website source symlinks, I shorten the name as much as possible and still have it make sense.
ln -s /mnt/d/dev/grokthis grok
install the project requirements
cd grok pip3 install -r requirements.txt
Setup your Site configuration
Rename siteconfig_example.py to siteconfig.py and edit it to configure with your details.
TODO: create an example repo for the website content - call it sitedev_content. This should clarify the way content is organized by categories (folders) and how to use markdown to create content.
Clone the sitedev_content repo
cd .. (make sure you are in the projects folder - the folder that contains grokthis)
git clone https://gitlab.com/ubiquity/sitedev_content.git /mnt/d/dev/grokthis_content
Create a symlink to the new content folder. For the content symlinks I just add a ‘c’ to the symlink name I used for the site source repo folder. The source symlink is grok so the content becomes grokc. This just keeps it organized and makes typing easier.
ln -s /mnt/d/dev/grokthis_content grokc
You can name the symlink whatever you want, just make it easy to remember what it is for.
Now enter the grokthis_content folder and delete the .git repo folder from the grokthis_content folder. NOTE: Deleting the .git folder and recreating it is only done for the content folder, not the website source code folder. This is because there is one source for all the website code (sitedev) and each website has it’s own unique content (with an initial start from sitedev_content).
cd grokc (using the symlink to go to mnt/d/dev/grokthis_content)
rm -r .git
Now create a new repo for the content. This is so it becomes your repo and not the initial repo from sitedev. You will need an account at gitlab.com to push your files.
TODO: docs for account creation and getting your username and password for pushing your repos to gitlab.
Make sure a .gitignore file exists and make sure media/downloads/ is in that file. It should be there from cloning sitedev_content. The media/downloads/ folder is where raw image downloads are kept before being cropped and placed in the appropriate media folder for further processing (when the site is compiled).
You might want to edit the default readme.md file for the content repo. Or just leave it as is.
Then create the git repo with the git init command
git init
You can check the status anytime with this command
git status
Add all the files to the repo with this
git add .
Commit all the added files to the local repo
git commit -m "Initial commit for grokthis_content"
The next step is to add the origin address to your local repo. The origin address is the online repo where you push files from your local repo. You need to create an account at gitlab.com and create a repository in your online account to go any further. You get this address from the GitLab site where you created your online repository.
git remote add origin https://gitlab.com/ubiquity/grokthis_content.git
This will be different for you based on this pattern
git remote add origin https://gitlab.com/your_username/your_repository_name.git
And finally push to the origin to put the content online
git push -u origin master
You will be prompted to enter the username and password for the push to complete
Extra info
Just in case you need to reinstall pelican this will force a reinstall
pip3 install —upgrade —no-deps —force-reinstall pelican
Individual files (or a list of files) can be added to a git repo like so
git add readme.md