Getting Started With Blogging

Dec 2, 2012 00:00 · 996 words · 5 minutes read how-to blogging

Recently I completed the installation of this blog. As it is based on camendesign with a few customizations for rendering of content and display. This documents how the system works. Since the blogs’ system and ReMarkable are supposedly designed to let one focus on publishing content instead of system maintenance — I call it the WordPress tax — it should be provable if there is truth to that.

When it comes to blogging, some people are fine with using a plug and play solution that gets their ideas in front of their audience as quickly as possible. Others want to gain a deeper understanding of how their blog works, how it presents to their audience and anything that runs in the background that might impact how other elements of their website work.

This blog is built on ReMarkable and is designed to let the author focus on publishing content instead of having to maintain their website’s systems — which I call a “Wordpress Tax.” Depending on how this blog works out, I should be able to see if there is any truth to this claim.

Getting it

The code for this site is available for free on github without any license attached. Feel free to use what you like for your own blog!

Using git, the site can be pulled:

$ git clone git://github.com/danielsreichenbach/marenkay.com.git yourdomain.com
$ cd yourdomain.com
$ git submodule init
$ git submodule update

This will pull in a clone of the site’s source code and update the git submodule which contains the ReMarkable parser to the latest version.

Configuration

You will need to have a few items prepared prior to configuring your new site:

  • your personal SSH private/public key pair, uploaded to your web server so that you may connect via SSH
  • connection information for your web server, of course
  • at least read access to a git repository with your copy of the site. If you have non, fork away mine on github with a free github account.

Once you have everything prepared, we can configure our site. First, have a look at the configuration example in .system/config.php.dist:

<?php
define('APP_HOST', 'marenkay.dev');
define('APP_PREVIEW_SIZE', 640);
define('ANALYTICS_KEY', 'UA-12345678-1');
define('DEVELOPMENT', true);

Should you prefer to skip Google analytics just leave the define empty, and there will be no analytics snippet added to your site.

Setting DEVELOPMENT to true will change the behaviour of the code:

  • no external calls will be made
  • generated HTML markup for articles will not be cached

This is intended to ease local development.

Save the file to .system/config.php to make your site use it. Upon deployment, Capistrano will over to deploy this file, too.

To configure Capistrano deployment, you will need your web server’s access data, and path information. This is important as it regulates where your website’s files will be stored.

Edit the Capistrano configuration in .system/deploy.rb.dist:

# the source control ssh user
set :git_user, "git"

# the source control host
set :git_host, "github.com"

# the source control user id
set :git_account, "your-github-ccount"

# the source control repository name
set :git_repository, "your-domain.com"

# the git-clone url for your repository
set :repository, "#{git_user}@#{git_host}:#{git_account}/#{git_repository}.git"

# the branch you want to clone (default is master)
set :branch, "master"

# tell capistrano to init and update submodules
set :git_enable_submodules, 1

These settings control from which git repository your site will be pulled from and also if any specific branch shall be used. E.g. if you use a git plugin like git-flow, you might be deploying from a release branch.

Once done, the next section covers your target server. There will be differences depending on your provider.

# The name of the application.
set :application, "sUSERID.gridserver.com"

# The name of the user to use when logging into the remote host(s).
set :user, "your-domain.com"

# the user id of your (mt) account
set :mt_id, "USERID"

# The root of the directory tree on the remote host(s) that the
# application should be deployed to
set :deploy_to, "/home/#{mt_id}/domains/#{git_repository}"

# The directory under deploy_to that should contain each deployed revision.
set :version_dir, "releases"

# The name to use (relative to deploy_to) for the symlink that points at
# the current release
set :current_dir, "html"

The above example is customized for hosting at Media Temple but should be easily changed for other hosting providers.

One interesting bit here is the current_dir setting, as providers usually chose to use different names for the DOCUMENT_ROOT in the dozens. This refers to the directory from which the web server will serve files. Some providers use public_html, some html, and others www.

Be sure to take extra care here since Capistrano has no real document root, but creates a symbolic link from the document root to your last working deployment.

Crafting content

Try out Sublime Text for editing. It is awesome and available for Windows, Linux, and Mac OS.

Crafting Content in Sublime Text 2

I recommend to study ReMarkable syntax before beginning. It is basedon Markdown.

Since the structure is simple and does only include semantic elements, all you have to worry about is your creativity. Relax, and let the words flow. Once you feel like an article is done, add and commit it, and push it into your repository.

Publishing content

Get Ruby, RubyGems, and deploy your site with Capistrano.

In order to prepare deployment with Capistrano, you have to tell Capistrano to prepare your target server. You do so by executing

$ cap deploy:setup

This will ensure the required directory structure is present on your target server and enable subsequent deploys, rollbacks, etc.

Once this has run, you can deploy the site by executing

$ cap deploy

Congratulations! You now have a working blog site, powered by ReMarkable!

BTW: looking for awesome git recipes? Try out git immersion!

Personally, I write, git add, write, and git add until I am satisfied with an article. Then I just commit, push and execute cap deploy to push an article life. Just like I did with this one.

Feel free to contact me with questions!

Comments powered by Disqus