Rakefiles are the Ruby equivalent of Makefiles. As detailed on the Octopress site, the Rakefile that ships with Octopress has a number of useful scripts (rake tasks) for generating new posts and deploying your site.
Generating a new post is as simple as
which creates a new Markdown file in your
source/_posts directory with filename given by the title, prepended by the date. This will already contain useful metadata that Octopress uses (see the YAML front matter section below). Simply edit this Markdown file to fill your post with content.
I haven’t added any new pages quite yet, but there is a rake task for creating new pages easily:
This will create the file
source/filename/index.markdown that will ultimately be served as
filename/index.html on your website.
Preview, Generate, and Deploy
To use a local webserver to serve all your posts (including ones with the
published: false flag), simply run
and point your browser to
http://localhost:4000. One trick that made using this server a bit easier is to use Fluid to create an
If you’re satisifed with your site, you can generate the html files and deploy it to GitHub Pages by running
rake generate rake deploy
Don’t forget to commit and push your source!
Lastly, the beauty of having your site as the
master branch, and everything else as the
source branch is that you can modify your website and use version control without having to publish all your changes. Once you’ve made a new post or page, or some other tweaks to your page source, simply run
git add . git commit -m 'your message' git push origin source
and your progress will be saved on GitHub.
YAML front matter
The special YAML Ain’t Markup Language front matter tells Octopress how to process your Markdown files. The
new_post script generates this for you. By default the
published: line is omitted. Including
published: false will prevent the post from being deployed, but will show when you preview your site locally with
rake preview. This is useful if you like to preview your post in a browser before deploying.
Below the fold
If you want to restrict the amount of a post that is shown in your blog index, simply insert the
<!-- more -->
tag into your post. The remainder of the post will not be shown in the blog index.
plugins directory contains some usful scripts. Here I’ll show a few examples.
Standard Markdown blockquotes, coded as
> Don't Panic. > **Douglas Adams** - The Hitchhiker's Guide to the Galaxy
Douglas Adams - The Hitchhiker’s Guide to the Galaxy
which is perfectly fine. However, using the
blockquote script, they appear a bit more fancy:
This was created using
<blockquote><p>Don't Panic.</p><footer><strong>Douglas Adams</strong> <cite>The Hitchhiker's Guide to the Galaxy</cite></footer></blockquote>
This environment is especially nice for linking to quotes in articles. See the documentation for usage details.
Internal post linking
Thanks to Xi Wang’s post about internal post linking, I was able to use his linked
post_url script to more easily make internal links to posts in this blog. Simply download post_url.rb and place it into your
I used this code at the beginning of the post to generate the URL:
2012-12-19-blogging-with-octopress is the name of the Markdown file (sans extension, of course) that I used to generate the previous post. Full disclosure, I used the Markdown syntax:
[Last time][BloggingWithOctopress] [BloggingWithOctopress]: /2012/12/19/blogging-with-octopress/ "Blogging With Octopress"