Driving-By Dirty Octopress

and getting started with Octopress 2.0!

If you drove off here to know about the Octopress framework and get started rapidly over in a hour, this could be your best bet or you could always research and end up in thousand more blogs and end up on the same thing except only after having lost hours linking one solution to another problem and vice versa.

##Why migrate to Octopress?

Why would a chap like me want to migrate from Wordpress to Octopress? For that I would first need to answer problems with the basic setup and i.e: PHP/MySQL stack - a complete stupid stack with needs to update plugins/code, etc. in a long run, generate more dynamic pages, parameters, etc in order to exhale more security loopholes.

####Pointers:

• I never wanted to maintain security updates
• Being in Security, I know the pain
• A nice attempt to keep it clean
• Not at all for novice users
• Above gives heartache

##In a Nutshell

##Deploying to Github:

• create a new repository at Github, this is fairly self explanatory.
• the host machine must have Ruby, Github and Octopress downloaded via Git.
• Now that, everything is ready, move to octopress folder and run: rake setup_github_pages
• set the repository URL from Github when asked.
• run rake generate via rake generate
• run deployment. This might ask username and SSH keys password from Github; Use rake deploy
• check git status to look if anything is uncommited; Use git status
• to push any changes into the remote github repository, use below:

1
2
3

git add .
git commit -m "any message here, a conventional one"
git push origin source

.. after this one might deploy using below:

1

rake deploy

##Before you commit to Octopress

There are basics if one really would need to customize and initiate the power of octopress to the next level. One does not simply limit himself to understanding of markdown but there’s a lot under-the-hood in the octopress framework (not really, take time reading!).

Octopress 3.0 makes it more simpler but here I would be using Octopress 2.0 in it’s truest and meanest form possible since it’s easy and isn’t tough for one from a developer background. That been said, here are some pre-requisities suggested (although not mandatory, but it is!)

• Octopress documentation could be a great place to start with. Here’s the web documentation.

• Markdown basics and additional markdown cheatsheets could be a benifit. Start with DaringBall Markdown Basics. A good amount of pointers on markup summarization has been done by Jesse Herrick. Take time going through them as well.

• Before you do down deeper, know what are different parsers which are used with octopress installation and take liberty to understand rDiscount, Kramdown and Shopify Templates or one can also read through the documentation covered here in Jekyll. Jekyll go hand-in-hand with Octopress 2.0 and Octopress relies on it’s support, however this has come to an drastic change since release of Octopress 3.0.

##Octopress Plugins and Support

Octopress Image Plugin:

1
2
3
4

{% img [class name] /path/to/image [width] [height] [title text [alt text]] %}
{% img http://localhost:4000/assets/img.png %}
 

Sample Image Example using Liquid Markup:

Note: This image was not set for heights and widths, the raw source code is as follows:

1
2
3

{% img http://s17.postimg.org/wvwql2atr/sample.png %}
 

Octopress Blockquote Plugin:

1
2
3
4
5
6

{% blockquote [author [, source ]] [link] [source link title] %} {% endblockquote %}
{% blockquote Shritam Bhowmick, His Portfolio %}
To the mind that is still, the whole world surrenders.
{% endblockquote %}
 

Sample Quote Example:

To the mind that is still, the whole world surrenders.

Octopress Code Plugin:

Markdown Method: tab (indent) in your code.

1
2
3

var framework = "octopress";
 

Sample Code Example Block using tab indenting:

var framework = "octopress";

Backtick Method: open and close with three backticks.

Sample Code Example using Backtick method for a codeblock:

1
2

js Variable Assignment http://www.localhost:4000/ Link
var framework = "octopress";

CodeBlock Method: more like blockquote method.

1
2
3
4
5

{% codeblock Variable Assignment lang:js http://www.localhost:4000/ Link %}
var framework = "octopress";
{% endcodeblock %}
 

Sample Code Example using codeblock method with lang:js i.e. language set to it’s intended type:

1

var framework = "octopress";

Include Code: file is stored in the octopress source directory, and one can include the code from the file. The user needs to use the /config.yml and there would be code_dir set to the default one.

1
2
3

{% include_code JS lang:js file.js %}
 

Sample Code Example of an included .js file which has it’code content:

Gist Method: The sample code below can used to pull out code from Gist from Github

1
2
3

{% gist gist_id [filename] %}
 

Sample Code Example to illustrate a random gist taken from Github:

JSFiddle Method: Pull JavaScript code from JSFiddle

1
2
3
4

{% jsfiddle shorttag [tabs] {skin} [height] [width] %}
{% jsfiddle fATe6 %}
 

Sample Code Example with a random jsfiddle ID:

To split a page into ‘read more’ styling, use:

1
2
3

<!-- more -->
 

The sample for this was illustrated when you chose to click on continue reading ..

Fixes and Work-Arounds!

These are some of the fixes which I though might be just helpful when not using any automation for markdown via editors such as Atom, etc .. if you are writing in raw text and believe it’s going to be all easy - trust me it’s not going to be!

• Fix “Liquid Exceptions” - common symptoms are ‘tags not closed’ etc .. Here’s a hint for you - always close tags in proper syntax such as for blockquote:

1
2
3
4
5

{% blockquote Octopress, It's Documentation %}
has to end with endblockquotes
{% endblockquote %}
 

• Fix color compatibility with proper liquid code block usage. This one, I needed documentation help and also existing Kramdown userbase help. I had a friend who suggested me to use the below code for all octopress documentation code in liquid since it’s markdown support with color is amazing and Rdiscount parser which ships with octopress does not cry about it!

Note: you’ll notice I have had used include code method instead of codeblock to illustrate my example in the above code snippet. The reason is I would had to iterate the raw and endraw liquid markup and escape opening liquid markup. This is however possible using assign operators; however I have had not done the research on it and it somehow rendered the entire code bad.

• Having been into security, I would really need to illustrate code snippets which carry special information and thos which deal with non-ASCII, such as &#x3c and such. Special Characters in Octopress could be used using the method as shown above i.e via using raw and endraw. Have a look at the Sample code below!

1
2
3
4
5
6
7

<ul id="beers-list">
    {{#beers}}
        <li>{{name}} - {{color}} - {{alcohol}}%</li>
    {{/beers}}
</ul>
 

• Fix liquid exception undefined method [] on octopress might just be a time consuming research. I have it before-hand for you. So, the ground fact is here’s what you might end up sometime while doing a rake generate and hence the parser not being able to completely generate the markdown files (e.g. below)

To solve this, goto the .pygments-cache and rm .pygments-cache directory as a whole as shown below in your octopress installation.

Note: ignore The system cannot find the path specified. since they are generic custom cmd environment errors and not related to octopress, it’s ruby dependency or python pygments highlighter dependencies.

This issue persists with Windows installations and haven’t been found in linux installations. I had however tried re-installing python 2.7.x, re-installing ruby 2.2.x, and everything else which were possible but all solution ended up to this working method.

• To fix and be choosy of your markdown processor not being able to provide with you with good alternatives for code block, you do know it’s customizable and you can always have a GitHub Style combination here.

• To fix bullet/numbered styling which ships as default and indents to cornering left of the actual article body, you will require to add below lines to sass/custom/_style.scss:

1
2
3
4
5

article {
  ol, ul {
    padding-left: 3em;
  }
}

Conclusions

That was a short but a devasting ride for a start with the Octopress Framework. My recommendations would be to stick to the Octopress documentation, and research a lot in order to get a perfect working shape of your work.

Feel free to drop your queries below and I could test them to get a new rake post task for you under the octopress category section - laters!

Updates

Please keep referencing these which might be very useful from time to time ..

• How to setup Octopress Cloned Blog & keeping accessing from different machines, also - the basic working of Octopress

• How to fix Error: Pygments can’t parse unknown language: rake:

  • use /plugins/pygments_code.rb file
  • change raise "Pygments can't parse unknown language: #{lang}# to raise "Pygments can't parse unknown language: #{lang}#{code}
  • next time a rake generate is issued, the location is shown which wouldn’t before.
  • fix the syntax. This probably triggers by using backticks without a proper line-feed.