Learn to build a lean & flexible blogging platform
Setting Up the Project
In this step, we'll perform the last housekeeping tasks before we start actual development.
The “Starterkit” project provides us with two things:
a) A boilerplate structure for our new project.
b) Kirby’s core code parts.
The latter could be seen as “libraries”; and, as clean coders, we know that library type of code should not be modified by us (because, if you did, you would have a hard time updating to new versions of the library).
Here’s where Git’s “Submodule” concept comes in handy: it allows you to import library code as a sub-repository into your main project. This allows you to keep your code cleanly separated.
The “Starterkit” includes two Submodules in its “kirby” and “panel” folders. Let’s initialize them properly:
In Tower, expand the “Submodules” area in the sidebar. Then, select a submodule item - and you’ll instantly see that we have to perform an “Update” to initialize it.
After having initialized these two submodules, double-click the “kirby” submodule to open it in Tower: as it contains another submodule itself (the “toolkit” library), you’ll have to initialize this one, too.
Initializing submodules instructs Git to clone the necessary files for these libraries into your project structure. Now, it’s finally time for a little test drive.
On the command line, make sure you are in the root folder of the Starterkit project. There, enter the following command:
$ git submodule update --init --recursive
This instructs Git to clone the necessary files for these libraries into your project structure. Now, it’s finally time for a little test drive.
Testing Our Kirby Installation
Since it includes a boilerplate structure, the “Starterkit” automatically provides us with a fully functional demo site. Start up a server in your MAMP or XAMPP app to take this for a spin. Alternatively, if you have PHP 5.4 (or newer) installed, you can open your Command Line and simply type the following in the root folder of your project:
php -S localhost:8888
Open your browser on localhost to have a look at the demo site.
Now that we know that the system is running, let's remove all dummy content from the sample project:
All subfolders in the "assets” directory should be empty.
The content folder should contain only the "home", "error", and "site.txt" items.
In "site", make sure the "snippets" and "templates" folders are empty.
Be sure to commit our cleaned up project structure:
In Tower, make sure the project is open and “Working Copy” is the active item in the sidebar. Then simply hit the “Stage All” button, enter a commit message like “Clean up dummy content”, and confirm by clicking “Commit”.
On the command line, execute the following commands:
After cleaning up the project, we should make sure that it stays clean - by ignoring unnecessary files from version control. Thankfully, the boilerplate project already comes with a simple text file named .gitignore in the root of the project. Open this in your favorite editor and replace its contents with the following lines:
You will only need the .DS_Store rule if you're on a Mac (like I am). You'll also notice that we included a rule specific to Sass. This is because we'll be using Sass for our HTML/CSS template.
Each of these rules fulfills a simple task: it prevents files from being included in version control that should not be.
Just like before, we stage and commit this change to the local repository.
Connecting Our Own Remote Repo
With our first two commits made, Git informs you that we’re “2 commits ahead”:
This means we have two commits locally that haven’t been published to the remote repository, yet.
With our current setup, however, we cannot publish (or, in Git lingo: “push”) these changes: at the moment, the only remote repository that is connected is the “Starterkit” repository from which we initially cloned. And we don’t have write access to this remote repository.
Therefore, if we want to collaborate with others on the project, we’ll need to connect a remote repository of our own. For this example, I have created a blank repository on GitHub.com and will now connect it with our local repository:
Note that the URL that I used here will again not be writable for you. If you want to follow along, you’ll need to enter a URL to a blank remote repo of your own.
We can then publish our local “master” branch on this new remote repository:
$ git push -u origin master
For the sake of brevity and clarity, I won’t list all code changes in every situation. However, I will often reference the corresponding commit on GitHub when explaining a certain step. You can then inspect these step's changes in detail.
Now that we have our project set up, let's import our HTML template.
Get our popular Git Cheat Sheet for free!
You'll find the most important commands on the front and helpful best practice tips on the back. Over 100,000 developers have downloaded it to make Git a little bit easier.
As the makers of Tower, the best Git client for Mac and Windows, we help over 100,000 users in companies like Apple, Google, Amazon, Twitter, and Ebay get the most out of Git.
Just like with Tower, our mission with this platform is to help people become better professionals.
That's why we provide our guides, videos, and cheat sheets (about version control with Git and lots of other topics) for free.