- Date of this document: July 2013
- Author and maintainer: Pito Salas
This tool is very much under development so things may change without warning. However right now it is already usable by a somewhat technical user who is willing to put up with ugliness. I am using it to create the web presence for Cosi235A and Brandeis University, and am evolving the features as I write the course.
- To create course curriculum web sites that look like http://cosi235a.courses.salas.com.s3-website-us-west-2.amazonaws.com
- Permit editing of content through a simple text editor, while not connected to web
- Permit the whole site and contennt to be managed on source control (such as github)
- Generate a static web site that can be hosted for free, for example on Amazon S3
- To allow a collection of building blocks (which are called topics) to be used and moved around between sections or not used at all but kept in a usable form for future courses
- To create a shared, open source, repository of curriculum building blocks, with proper handling of copyrights, version tracking and so on.
- To allow the curriculum to be rendered in different forms, e.g. a web site, a mobile app, a powerpoint presentation, a pdf
Nanoc is one of several static site building tools. It is built on top of Ruby and benefits from the large collection of libraries and tools. It's pretty easy to use and allows easy extension and customization for specific purposes.
You may be able to use Course without knowing Nanoc, I am not sure. It depends a little on how good my instructions are which for now still leave lots of room for improvement.
Nanoc is working finen for me for now, but there's no guarantee that I won't decide that another static site generator is better.
Extensions and new macros are written in Ruby because that is what Nanoc expects. You can find all the ruby customizations in the lib directory.
A well known and very easy to learn markup language to annotate your content to format it. This very file is a markdown document. You can recongize the markdown files because of the .md extension. You will also see many .md.erb files which represent a markdown file which has embedded ruby.
Pages are styled with Twitter Bootstrap. Right now the theme (such as it is) is hardwired. Bootstrap's files cann all be seen in the ./content/bootstrap directory
- ./content - the content directory contains all the .md files which form all the content that you will be writing
- ./layout - these are standard page layouts which are applied, as well as 'partials', bits of html that are used to build out the page. In particular you will see a layout called 'course' which is the overall html frame for all the ages. In there you will see the placement and layout of the page, the borders, the navigation and so on.
- ./output - this contains the complete collection of html, css, js, images and everything that forms the final site. It is generated by the $ nanoc compile command. To deploy you just need to ftp all of this directory to your favorite web server.
- topics - these are small bits of content corresponding maybe to a unit of teaching. Typically a lecture may contain zero or more included topics. The intent is that you may write and reuse topics between different courses. You could use someone else's topics in your courses, and so on.
- lectures - a nested set of .md files corresponding to your series of lectures however you chose to organize them. Today only one level of nesting is supported.
This is high level, for now, assuming you understand some of the jargon
-
How to view the current state of things
- Git clone the repository
- bundle _(assumes you have ruby and the bundler gem installed)
- nanoc view _(which runs the local server)
- In your browser, look at 0.0.0.0:3000
-
As you work on content you may need these commands
- nanoc compile _(which will generate the site, once)
- guard -i _(which will watch for file changes and recompile as needed)
- nanoc purge --yes _(which will reset the output directory for a full regen)
-
Biggest one: this is a work in progress. The paint is wet, everywhere. I am changing it every day. But it is usable if you are somewhat enterprising.
-
I have noticed that sometimes I see old pages, and nanoc purge --yes doesn't seem to clean up everything. You may try clearing your browser cache or any other witchcraft you can think of the get rid of the old page.
-
rake deploy is hardwired to deploy to my one and only server so far.
I haven't tested this sequence but I will, at some point.
- git clone
- delete all files in output/
- delete *.md and *.md.erb in content/ and its subdirectories.
- also delete the subdirectories that you see under content/lectures
- Your files should be called *.md or *.md.erb in all the available directories
- For now, only in the lectures/ directory will subdirectories be automatically reflected in the sidebar
- For now, only the existing top level directories under lectures/ will be used
- Run nanoc compile or guard -i to compile and remove errors from your content
- Whenever you are ready, deploy to a simple web server by copying ./output and all its directories and files.
- This is what I do:
- Create a free bucket on S3
- Mark it as a "static web site"
- Use a free app called S3CMD to copy all the files
- rake deploy to deploy
- Send me email at pitosalas@gmail.com with any feedback or suggestions
- Make your own improvements and send me a pull request when and if appropriate