This article describes how to clone the MindFLow website and create your own content. The site structure is separate from the content. You get to use the power of the mindflow site design and create all your own content.

First, setup your dev environment with virtualenv with virtualenvwrapper and python (at least 3.5).

My dev env uses WSL (Windows Subsystem for Linux) so there may be a few details you will want to change if you are in a pure linux environment.

Clone The Git Repos

First make sure your current folder is a project folder where you want the website repositories to exist.

/home/rick/projects

That is where I create all my website repos. At least that is where it is from the linux (ubuntu) point of view. My setup is a bit more complex as I am using WSL. When I actually create the repos they are created on a hard drive in my Windows filesystem and mounted on linux as an external drive. So what I actually have at /home/rick/projects in ubuntu will be symlinks to the mount points in Windows. This works out really well and there are only a few times you need to use the mount paths rather than the symlinks.

Clone the two repos that make up the mindflow site. Let’s call the first one the site repo and the second one the content repo.

git clone https://gitlab.com/ubiquity/mindflow.git /mnt/d/dev/yoursite
git clone https://gitlab.com/ubiquity/mindflow_content.git /mnt/d/dev/yoursite_content

You will need the current username and password for each clone.
TODO: Setup gitlab with access levels for users to clone and pull.

This clones the repos into my projects folder (called dev) on Windows (drive d)

If I was working in a pure linux environment I would go to my projects folder and do this:

git clone https://gitlab.com/ubiquity/mindflow.git yoursite
git clone https://gitlab.com/ubiquity/mindflow_content.git yoursite_content

It is important to name the content repo the exact same as the site repo with ‘_content’ appended. The site requires this. So the folder names become ‘yoursite’ and ‘yoursite_content’.

Now I create symlinks to the repository folders (again, not required if in pure linux and the repos are right there):

ln -s /mnt/d/dev/yoursite yoursite
ln -s /mnt/d/dev/yoursite_content yoursite_content

Or, if you are using WSL with docker and have modified the wsl.conf to mount volumes on / rather than /mnt use this:

ln -s /d/dev/yoursite yoursite
ln -s /d/dev/yoursite_content yoursite_content

See Nick J’s blog for more info on using WSL and Docker: https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly

Or you can use shorter symlink names if you like. Short names make typing easier!

From a linux point of view you end up with either a real or symlinked environment that looks like this

/home/rick/projects/yoursite
/home/rick/projects/yoursite_content

In the next step we will create a virtualenv that also has ‘yoursite’ embedded in it’s path. The site requires this.

/home/rick/.virtualenvs/yoursite/lib/python3.5/site-packages/pelican

Disconnect the Mindflow Content

Now cd into the content folder (yoursite_content) and del the .git repo folder. We are going to create our own repo for the content. This is what makes the new site different from the mindflow site. Mindflow content is just a model for getting started with the new site. Do this now just so there is no accidental push to the mindflow repo after making changes to any local files.

cd yoursite_content
rm -r .git

When done this, return to the projects folder.

cd ..

Do NOT delete the .git repo in the ‘yoursite’ source folder! All the code for running the site is in there and updates from mindflow are just a merge away. Unless, of course, you want to use mindflow as a starting point and modify the source. Then you can delete repo and start your own.

Create a Virtual Environment

Now create a python3 virtualenv for the project. The virtualenv name must be the same as the folder name of the site repo: in this case it is ‘yoursite’.

mkvirtualenv -p python3 yoursite

Creating the virtualenv should activate it. You will see the linux command line prompt change to include the name of the virtualenv. To deactivate type:

deactivate

To activate again type:

workon yoursite

Build the Requirements

Now cd into the site repo folder

cd yoursite

Now you are in the site repo folder and the virtualenv is active. It is time to install the project requirements.

pip3 install -r requirements.txt

Private Data

Now create an env.py file in the root folder of the project (yoursite). This is where private data goes that is NOT tracked in git. This is for account numbers or passwords - stuff you want to keep very private. Keep this backed up somehwere else.

In this file add the following line of code:

_GOOGLE_ANALYTICS = ''

It is just an empty string for now, but still required. When your site is up and has some content then you can get you google analytics id and turn on that feature by assigning the id to this variable.

Compile and Run the Site

Now you should be able to compile the site. It’s a good idea to compile and run the site to make sure it all works before customizing it for your needs. And compiling the site at least once customizes things a bit so it is good to compile before creating the content folder’s git repo.

pelican --debug
cd output
python -m http.server

If it all works, it is time to customize!

Make Your Own Content Repo

First, lets initialize a git repo for the content folder. If git is not installed check the article on doing that cd into the content folder (or you could open a separate command window for each folder).

cd ..
cd yoursite_content
git init

Create an online repo at your favorite git host. I use gitlab.com because you can have unlimited private repos with a free account. I think github.com allows just one for free.

Make the name of your online repo the same as your local content folder name: yoursite_content

git remote add origin https://gitlab.com/ubiquity/yoursite_content.git
git add .
git commit -m "Initial commit"
git push -u origin master

You will be prompted for your usename and password to do the push to the remote repo.

You could also use:

git remote add origin [email protected]:ubiquity/yoursite_content.git

If you are setup to use ssh.

Install Visual Studio Code

Install Microsoft’s Visual Studio Code editor (vscode). It’s awesome! Best thing Microsoft ever created.

Open vscode and go to ‘File > Open Folder…’ and open the folder ‘yoursite’. Now go to ‘File > Add Folder to Workspace…’ and add the content folder ‘yoursite_content’. Then ‘File > Save Workspace As…’ and save it as ‘yoursite.code-workspace’.

After that you can open both folders as a workspace by going to ‘File > Open Workspace…’

Configuring Your Site

Open the siteconfig.py file from the content folder.

Update the stuff that’s obvious, do the other stuff later.

To start with make sure this variable:

UNSPLASH_COLLECTION_ID = ''

is set to an empty string.

With an empty string it will grab random images from all over the unsplash site. If you use a collection id they will narrow it down to random images from a particular subject matter that might suite your site better. Go to unsplash to check it out.

Customize Your Site Pages

Now is the time to edit the site pages and create the content you want. In vscode go to the content folder:

yoursite_content/content/pages

This folder contains all the site pages like about, contact, privacy, legal, etc. The home page is called index.md and is a good place to start making the site content yours. These are all text files in markdown format (extension .md). Markdown is a simple format that separates the content from the structure of a webpage. You could also use reStructuredText (extension .rst) if you prefer that format. This pages folder is where all webpages go that are not articles.

Once the main site pages are created, it is time to create some articles.

Create Content for Your Readers

More detailed docs for this are comming soon.

For now just browse the content to see how articles are created in folders (and folder names become categories) and how the images are organized in the media folder. The yoursite_content/content/images folder is used for site design imagery - not for articles. All images and videos for article content are in the yoursite_content/media folder. More content examples are coming…