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

Octopress Wordpress
Markdown Powered Driven by UI Interface
Parse Engine Choice WP Engine Default
Novice Unfriendly Novice Userbase Recommended

##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.

Shritam BhowmickHis Portfolio.

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:

Variable AssignmentLink
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:

# OSX for Pentesting (Mavericks/Yosemite)
# macOS Sierra shall be updated;
# This's a fork, folks - suck in the caffeine!
# http://pwntoken.github.io/
#!/bin/sh
# Ask for the administrator password upfront
echo "Have you read through the script prior to running this? (y or n)"
read bcareful
if [ $bcareful == "y" ]
then
echo "Alright, lets get started. First, you'll need to give this script admin privileges (however, do not run as root)"
else
echo "Goodbye"
exit
fi
sudo -v
echo "and away we go!"
###############################################################################
# Add useful aliases to .bash_profile
###############################################################################
echo "Adding useful aliases to your .bash_profile..."
echo "alias chrome='open -a \"Google Chrome\"'" >> ~/.bash_profile
echo "alias atom='open -a \"Atom\"'" >> ~/.bash_profile # alternative to sublime
echo "alias attach=\"hdiutil attach\"" >> ~/.bash_profile # attach volume (useful for attaching an encrypted volume)
echo "alias listen=\"lsof -i TCP -n -P | grep LISTEN\"" >> ~/.bash_profile # show listening ports
###############################################################################
# Install osx command line tools
###############################################################################
xcode-select --install
###############################################################################
# Install Homebrew
###############################################################################
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
###############################################################################
# Install pentesting binaries with homebrew
###############################################################################
echo "Installing a few useful binaries"
bins=(
python # Update your python
nmap
hydra # Great tool for password attacks
ncrack # Alternative to hydra, supports RDP
john-jumbo
the_silver_searcher # A code searching tool similar to ack, with a focus on speed.
git # Update to a newer version of git
autojump # Great little tool for navigating directories via the command line, see https://github.com/joelthelion/autojump
)
brew install ${bins[@]}
###############################################################################
# Install useful apps with homebrew cask
###############################################################################
brew install caskroom/cask/brew-cask
apps=(
alfred
google-chrome
qlcolorcode # Quicklook plugin that handles source code with syntax highlighting
appcleaner
firefox
qlmarkdown # QuickLook generator for Markdown files
spotify # Everybody loves Spotify
flash # :D
iterm2
caffeine # Keep your mac from going to sleep (when needed)
virtualbox
limechat
atom # Sublime-text alt
flux # Go easy on your eyes
qlstephen # Quicklook plugin for files without extensions (README, etc)
vlc
nvalt # Nice free note taking app
quicklook-json # Quicklook plugin for JSON files
)
echo "Installing apps via brew-cask..."
brew cask install --appdir="/Applications" ${apps[@]}
brew cask alfred link
brew cleanup
###############################################################################
# Install RVM to update and manage your version of ruby
###############################################################################
echo "Installing RVM, updating Ruby, and installing Bundler to manage gems"
curl -L https://get.rvm.io | bash -s stable
source ~/.bash_profile
rvm use ruby --install --default
gem install bundler
###############################################################################
# General UI/UX
###############################################################################
echo ""
echo "Hide the Time Machine, Volume, User, and Bluetooth icons"
for domain in ~/Library/Preferences/ByHost/com.apple.systemuiserver.*; do
defaults write "${domain}" dontAutoLoad -array \
"/System/Library/CoreServices/Menu Extras/TimeMachine.menu" \
"/System/Library/CoreServices/Menu Extras/Volume.menu" \
"/System/Library/CoreServices/Menu Extras/User.menu"
done
defaults write com.apple.systemuiserver menuExtras -array \
"/System/Library/CoreServices/Menu Extras/Bluetooth.menu" \
"/System/Library/CoreServices/Menu Extras/AirPort.menu" \
"/System/Library/CoreServices/Menu Extras/Battery.menu" \
"/System/Library/CoreServices/Menu Extras/Clock.menu"
sudo chmod 600 /System/Library/CoreServices/Search.bundle/Contents/MacOS/Search
echo ""
echo "Disabling OS X Gate Keeper"
echo "(You'll be able to install any app you want from here on, not just Mac App Store apps)"
sudo spctl --master-disable
sudo defaults write /var/db/SystemPolicy-prefs.plist enabled -string no
defaults write com.apple.LaunchServices LSQuarantine -bool false
echo ""
echo "Increasing the window resize speed for Cocoa applications"
defaults write NSGlobalDomain NSWindowResizeTime -float 0.001
echo ""
echo "Expanding the save panel by default"
defaults write NSGlobalDomain NSNavPanelExpandedStateForSaveMode -bool true
defaults write NSGlobalDomain PMPrintingExpandedStateForPrint -bool true
defaults write NSGlobalDomain PMPrintingExpandedStateForPrint2 -bool true
echo ""
echo "Automatically quit printer app once the print jobs complete"
defaults write com.apple.print.PrintingPrefs "Quit When Finished" -bool true
echo ""
echo "Disabling automatic termination of inactive apps"
defaults write NSGlobalDomain NSDisableAutomaticTermination -bool true
echo ""
echo "Saving to disk (not to iCloud) by default"
defaults write NSGlobalDomain NSDocumentSaveNewDocumentsToCloud -bool false
echo ""
echo "Reveal IP address, hostname, OS version, etc. when clicking the clock in the login window"
sudo defaults write /Library/Preferences/com.apple.loginwindow AdminHostInfo HostName
echo ""
echo "Check for software updates daily, not just once per week"
defaults write com.apple.SoftwareUpdate ScheduleFrequency -int 1
echo ""
echo "Disable smart quotes and smart dashes as they’re annoying when typing code"
defaults write NSGlobalDomain NSAutomaticQuoteSubstitutionEnabled -bool false
defaults write NSGlobalDomain NSAutomaticDashSubstitutionEnabled -bool false
###############################################################################
# Trackpad, mouse, keyboard, Bluetooth accessories, and input
###############################################################################
echo ""
echo "Increasing sound quality for Bluetooth headphones/headsets"
defaults write com.apple.BluetoothAudioAgent "Apple Bitpool Min (editable)" -int 40
echo ""
echo "Enabling full keyboard access for all controls (e.g. enable Tab in modal dialogs)"
defaults write NSGlobalDomain AppleKeyboardUIMode -int 3
echo ""
echo "Disabling press-and-hold for keys in favor of a key repeat"
defaults write NSGlobalDomain ApplePressAndHoldEnabled -bool false
echo ""
echo "Setting a blazingly fast keyboard repeat rate (ain't nobody got time fo special chars while coding!)"
defaults write NSGlobalDomain KeyRepeat -int 0
echo ""
echo "Disabling auto-correct"
defaults write NSGlobalDomain NSAutomaticSpellingCorrectionEnabled -bool false
echo ""
echo "Setting trackpad & mouse speed to a reasonable number"
defaults write -g com.apple.trackpad.scaling 2
defaults write -g com.apple.mouse.scaling 2.5
echo ""
echo "Turn off keyboard illumination when computer is not used for 5 minutes"
defaults write com.apple.BezelServices kDimTime -int 300
###############################################################################
# Screen
###############################################################################
echo ""
echo "Requiring password immediately after sleep or screen saver begins"
defaults write com.apple.screensaver askForPassword -int 1
defaults write com.apple.screensaver askForPasswordDelay -int 0
echo ""
echo "Enabling subpixel font rendering on non-Apple LCDs"
defaults write NSGlobalDomain AppleFontSmoothing -int 2
echo ""
echo "Enable HiDPI display modes (requires restart)"
sudo defaults write /Library/Preferences/com.apple.windowserver DisplayResolutionEnabled -bool true
###############################################################################
# Finder
###############################################################################
echo ""
echo "Showing icons for hard drives, servers, and removable media on the desktop"
defaults write com.apple.finder ShowExternalHardDrivesOnDesktop -bool true
echo ""
echo "Showing all filename extensions in Finder by default"
defaults write NSGlobalDomain AppleShowAllExtensions -bool true
echo ""
echo "Showing status bar in Finder by default"
defaults write com.apple.finder ShowStatusBar -bool true
echo ""
echo "Allowing text selection in Quick Look/Preview in Finder by default"
defaults write com.apple.finder QLEnableTextSelection -bool true
echo ""
echo "Displaying full POSIX path as Finder window title"
defaults write com.apple.finder _FXShowPosixPathInTitle -bool true
echo ""
echo "Disabling the warning when changing a file extension"
defaults write com.apple.finder FXEnableExtensionChangeWarning -bool false
echo ""
echo "Use column view in all Finder windows by default"
defaults write com.apple.finder FXPreferredViewStyle Clmv
echo ""
echo "Avoiding the creation of .DS_Store files on network volumes"
defaults write com.apple.desktopservices DSDontWriteNetworkStores -bool true
echo ""
echo "Disabling disk image verification"
defaults write com.apple.frameworks.diskimages skip-verify -bool true
defaults write com.apple.frameworks.diskimages skip-verify-locked -bool true
defaults write com.apple.frameworks.diskimages skip-verify-remote -bool true
echo ""
echo "Enabling snap-to-grid for icons on the desktop and in other icon views"
/usr/libexec/PlistBuddy -c "Set :DesktopViewSettings:IconViewSettings:arrangeBy grid" ~/Library/Preferences/com.apple.finder.plist
/usr/libexec/PlistBuddy -c "Set :FK_StandardViewSettings:IconViewSettings:arrangeBy grid" ~/Library/Preferences/com.apple.finder.plist
/usr/libexec/PlistBuddy -c "Set :StandardViewSettings:IconViewSettings:arrangeBy grid" ~/Library/Preferences/com.apple.finder.plist
###############################################################################
# Dock & Mission Control
###############################################################################
echo ""
echo "Setting the icon size of Dock items to 36 pixels for optimal size/screen-realestate"
defaults write com.apple.dock tilesize -int 36
echo ""
echo "Speeding up Mission Control animations and grouping windows by application"
defaults write com.apple.dock expose-animation-duration -float 0.1
defaults write com.apple.dock "expose-group-by-app" -bool true
echo ""
echo "Setting Dock to auto-hide and removing the auto-hiding delay"
defaults write com.apple.dock autohide -bool true
defaults write com.apple.dock autohide-delay -float 0
defaults write com.apple.dock autohide-time-modifier -float 0
###############################################################################
# Safari & WebKit
###############################################################################
echo ""
echo "Hiding Safari bookmarks bar by default"
defaults write com.apple.Safari ShowFavoritesBar -bool false
echo ""
echo "Hiding Safari sidebar in Top Sites"
defaults write com.apple.Safari ShowSidebarInTopSites -bool false
echo ""
echo "Disabling Safari thumbnail cache for History and Top Sites"
defaults write com.apple.Safari DebugSnapshotsUpdatePolicy -int 2
echo ""
echo "Enabling Safari debug menu"
defaults write com.apple.Safari IncludeInternalDebugMenu -bool true
echo ""
echo "Making Safari search banners default to Contains instead of Starts With"
defaults write com.apple.Safari FindOnPageMatchesWordStartsOnly -bool false
echo ""
echo "Removing useless icons from Safari bookmarks bar"
defaults write com.apple.Safari ProxiesInBookmarksBar "()"
echo ""
echo "Allow hitting the Backspace key to go to the previous page in history"
defaults write com.apple.Safari com.apple.Safari.ContentPageGroupIdentifier.WebKit2BackspaceKeyNavigationEnabled -bool true
echo ""
echo "Enabling the Develop menu and the Web Inspector in Safari"
defaults write com.apple.Safari IncludeDevelopMenu -bool true
defaults write com.apple.Safari WebKitDeveloperExtrasEnabledPreferenceKey -bool true
defaults write com.apple.Safari "com.apple.Safari.ContentPageGroupIdentifier.WebKit2DeveloperExtrasEnabled" -bool true
echo ""
echo "Adding a context menu item for showing the Web Inspector in web views"
defaults write NSGlobalDomain WebKitDeveloperExtras -bool true
###############################################################################
# Terminal
###############################################################################
echo ""
echo "Enabling UTF-8 ONLY in Terminal.app and setting the Pro theme by default"
defaults write com.apple.terminal StringEncodings -array 4
defaults write com.apple.Terminal "Default Window Settings" -string "Pro"
defaults write com.apple.Terminal "Startup Window Settings" -string "Pro"
###############################################################################
# Time Machine
###############################################################################
echo ""
echo "Preventing Time Machine from prompting to use new hard drives as backup volume"
defaults write com.apple.TimeMachine DoNotOfferNewDisksForBackup -bool true
echo ""
echo "Disabling local Time Machine backups"
hash tmutil &> /dev/null && sudo tmutil disablelocal
###############################################################################
# Messages #
###############################################################################
echo ""
echo "Disable smart quotes"
defaults write com.apple.messageshelper.MessageController SOInputLineSettings -dict-add "automaticQuoteSubstitutionEnabled" -bool false
echo ""
echo "Disable continuous spell checking"
defaults write com.apple.messageshelper.MessageController SOInputLineSettings -dict-add "continuousSpellCheckingEnabled" -bool false
###############################################################################
# Misc Additions
###############################################################################
echo ""
echo "Disable hibernation (speeds up entering sleep mode)"
sudo pmset -a hibernatemode 0
echo ""
echo "Remove the sleep image file to save disk space"
sudo rm /Private/var/vm/sleepimage
echo "Creating a zero-byte file instead"
sudo touch /Private/var/vm/sleepimage
echo "and make sure it can't be rewritten"
sudo chflags uchg /Private/var/vm/sleepimage
echo ""
echo "Disable the sudden motion sensor as its not useful for SSDs"
sudo pmset -a sms 0
echo ""
echo "Speeding up wake from sleep to 24 hours from an hour"
# http://www.cultofmac.com/221392/quick-hack-speeds-up-retina-macbooks-wake-from-sleep-os-x-tips/
sudo pmset -a standbydelay 86400
echo ""
echo "Disable annoying backswipe in Chrome"
defaults write com.google.Chrome AppleEnableSwipeNavigateWithScrolls -bool false
echo ""
echo "Generating db for the locate command"
sudo launchctl load -w /System/Library/LaunchDaemons/com.apple.locate.plist
source ~/.bash_profile
echo "Done!"

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

&#x3C;ul id=&#x22;beers-list&#x22;&#x3E;
{{#beers}}
&#x3C;li&#x3E;{{name}} - {{color}} - {{alcohol}}%&#x3C;/li&#x3E;
{{/beers}}
&#x3C;/ul&#x3E;

  • 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 ..

Powered By Valine
v1.5.2
2015-07-14

⬆︎TOP