Octopress/Non-blog Octopress Site
From charlesreid1
This is a guide to using Octopress for a (mostly) non-blog site. See an example of this workflow in action here: http://charlesreid1.github.io/cantera-book
NOTE: This does not prevent you from using the blog features of Octopress. Fixed content can be served by Octopress alongside blog content. It just describes how to reorganize content to be less blog-centric.
Non-Blog Landing Page
The first thing to do when deploying a non-blog site with Octopress is fixing the landing page so that it doesn't try and show the latest blog posts. This is straightforward to do.
Move Blog Index
First, we don't want to blow away our existing blog index, because we may want to keep using the blog feature. Assuming you're in your project's octopress directory,
cd cantera-source/octopress/
you can move the existing blog index from source to source/blog:
mv source/index.html source/blog/index.html
Make New Index
We can either make a new index page with Markdown, or we can make an HTML page by hand.
The first way looks like this:
touch source/index.markdown
and index.markdown should look like this:
--- layout: default --- # Howdy Welcome to the index.
(Or you can use whatever layout you want.)
If you have your own HTML file, you can just put it there:
cp /path/to/my/index.html source/.
The navbar "blog" button will still point to the index, so update it to point to the new blog index (or get rid of the blog button altogether, if you don't want it). Edit the file source/_includes/custom/navigation.html and add a "Home" button to point to /. Update "Blog" to point to /blog.
Update Config
One last thing you'll have to do is tell Octopress that you've moved the blog index. Edit the Rakefile and change:
blog_index_dir = 'source'
to:
blog_index_dir = 'source/blog'
Populating Your Non-Blog Content
To populate your non-blog content, you'll probably want to make a bunch of pages that link to each other. We'll tackle this in two steps, the first step being making your pages.
Pages
To make a new Markdown file to be rendered into an HTML page, simply edit a markdown file wherever in the source directory you want it to reside. Let's say we want to have a file at the location charlesreid1.github.io/cantera-book/test.html. Then we would edit the file test.markdown:
cd cantera-book/octopress/source vim test.markdown
And as long as our test.markdown contains the following header,
--- layout: default --- (Your content goes here)
then our Markdown page will be rendered into HTML.
NOTE: If your Markdown pages are NOT being turned into HTML, make sure that you have the header. Otherwise, Jekyll will not know what to do with the Markdown and will deploy it as raw Markdown.
Page Directories
To make a directory containing a bundle of Markdown files to be rendered into HTML pages, navigate to the source directory:
cd cantera-book/octopress/source
Now simply make your directory:
mkdir section1
and populate the directory with an index.markdown, which will be the section index, as well as any other Markdown files for section1, like chapter1.markdown, etc...
As before, make sure that all Markdown files have the following header:
--- layout: default --- (Your content goes here)
Otherwise they will not be turned into HTML pages!
Inter-Octopress Links
The second step in populating our non-blog content is to make our pages (most of all our index page) more useful by linking to some other pages.
The way we link to a file depends on where it resides in the source/ directory.
For Content in Base Source Directory
If a file like index.markdown resides in the source directory, i.e.,
cantera-book/octopress/source
then it can link to other markdown files in the source directory by linking to the HTML file that the Markdown will turn into (once Jekyll is run via rake generate).
Link to Content in Same Directory
To link to content in the same directory, e.g., to link from index.html to test.html,
| Location (project repo) | cantera-book/octopress/source/test.markdown |
| Location (URL) | charlesreid1.github.io/cantera-book/test.html |
| Corresponding Markdown code | [This links to our test](test.html) |
Link to Content in Subdirectory
To link to content in a subdirectory, e.g., to link from index.html to section1/chapter1.html,
| Location (project repo) | cantera-book/octopress/source/section1/chapter1.markdown |
| Location (URL) | charlesreid1.github.io/cantera-book/section1/chapter1.html |
| Corresponding Markdown code | [This links to chapter one](section1/chapter1.html) |
For Files in Subdirectory of Source Directory
Link to Content in Same Directory
To link to content in the same directory, we can use a relative Markdown link, and Jekyll will take care of filling out the path to the current directory. Thus if we are in source/section1 and we have the following Markdown:
[Relative link to chapter one](chapter1.html)
this would be rendered as a link to:
charlesreid1.github.io/cantera-book/section1/chapter.html
Link to Content in Parent Directories
If you are trying to link to another file in a parent directory of the current directory, you'll need to modify the link schema a bit.
Let's say we're trying to add a link in source/section1/chapter1.markdown to the file sources/test.html, one directory up. Then our link schema would look like:
| Location (project repo) | cantera-book/octopress/source/test.markdown |
| Location (URL) | charlesreid1.github.io/cantera-book/test.html |
| Corresponding Markdown code | [This links to our test](../test.html) |