Octopress is a Ruby-based framework for generating static blog sites. This post will show the most basics of Octopress to get started on blogging quickly.
In summary, the workflow for writing blog in Octopress is as follows:
rake new_post["Post title"]
- Edit & Preview:
- After this step, the published artifacts are generated in the “public” directory.
- Published pages will be served locally at “localhost:4000”. Preview it in any browser.
- Updated Markdown files will be regenerated automatically.
- This step makes sure latest changes are added.
- After this step, the content in the “public” directory is copied into “_deploy” directory and git add/commit/push to the remote Github branch.
Setting up on a new machine
This section discusses installing basic Ruby packages and their requirements to use Octopress.
For Octopress 2, we have to use Ruby 2.3.x since one of its packages
yajl-ruby 1.2.1 requires
ruby < 2.4.
The instructions for installing different Ruby versions on different Mac OSX versions are in this page.
In summary, to install Ruby 2.3.6 on OSX High Sierra (10.13):
1 2 3 4 5 6 7 8 9 10
Then follow Octopress instructions to run
gem install bundler and
Do NOT install
ruby from Homebrew directly.
If you already installed the latest Ruby via Homebrew
brew install ruby, Bundler may not pick up the older Ruby version.
Check for it by using the command
If that is the case, force Bundler to use the other Ruby version by these commands:
1 2 3 4 5 6 7 8 9 10 11
Setting up new blog
This section assumes that we will publish in
gh-pages branch which is more common (publishing in
master branch only works for
In general, any project that we work in a repo
foo (with main development in branches
develop) on Github can have associated documentation HTML site in
Such documentation site can be accessed publicly at “username.github.io/foo/”.
Octopress allows easy generation of such static HTML sites.
One can arrange such that each blog post is a tutorial or a documentation page, written in Markdown and “compiled” into HTML.
The process of setting up such a static “documentation” site is as follows:
- Download the zip file from octopress master branch here. Note that this link is version 3, which is different.
- Unzip the zip file into the repo. Rename it to “docs” or “octopress”.
- Commit it to
rake installto generate files. Check in the generated files.
_deployfolder for deployment. For new static site,
- Start blogging/writing documentation. Use the workflow in the last section:
- For layout editing, check out one of early commits in this repo.
NOTE: when previewing the one published in
gh-pages, you need to edit “destination: public” in
_config.yml file to “destination: public/repo_name”.
Add a new page
This section is about adding a new page, opposed to a new post. The common examples of such page in an Octopress-based blog is “About” page or “Resume” page. To create a new page, use the following command:
This will create a new file at “source/about/index.markdown” and you can edit that file to add content.
rake generate command, the “source/about/index.markdown” will “compiled” into “public/about/index.html” that is displayed in the web browser.
After the page content is ready, you may want to add an “About” link in the navigation bar to that page.
To do that, edit the file “source/_includes/custom/navigation.html”.
Octopress deploys latest changes with the command
deploy step, it copies all the latest changes to the generated static HTML site into a
_deploy folder which is a clone of one of the public branches (
gh-pages) of the same repository.
_deploy folder by using this command.
With Git 1.7.10 and later, add
--single-branch to prevent fetching of all branches.
Make sure you use the SSH URL for the Github repo since the HTTPS URL will prompt for password for every deployment. In addition, SSH public/private key pair must be generated and added to the Github accordingly. Otherwise, you might get the following errorr:
1 2 3 4 5 6
If you get the above message even though the public key is already added to Github, check if you are using the right private key. Make sure it is added to SSH authentication agent.
1 2 3 4 5 6 7 8
ssh-add -l -E md5 can be used to find if there is a matching public key on Github.
See here for more information.
Make Google searchable
After the blog is deployed to
github.com, make it searchable by Google will allow the top search field working.
The usual way is to either resubmit your site in your Google Webmaster Tools or submit it here.
See this Stackoverflow thread for more options.
- Latex for Math formulas
- New page:
rake new_page["Resume"]and add link (example).
- Include code from file
- rake isolate/integrate
- Table (implemented): Markdown example.
Markdown editing tips:
- Cheat sheet
<!-- more —>to specify Excerpt.
- Internal link:
(/2012/01/05/hello-world)gives the link “http://userName.github.io/repoName/blog/2012/01/05/hello-world”