Makefolio

A simple static site generator for image-heavy, project-based portfolios.

Usage

Commands

makefolio init Create skeleton image metadata files for your projects (will not overwrite exisiting images.yaml files).

makefolio gen Generate your final html files and images in the ./dist directory.

Folder Structure

Makefolio expects a specific folder structure of projects, with a directory for each project containing a markdown description file and a subdirectory of project images. An additional YAML file is used to record metadata for the images, but makefolio will generate a skeleton of this file for you.

Your project files should be organized like this (explanatory notes in italics):

• Root directory
  • _src [your site content]
    • projects
      • project_one
        • img
          • image1.jpg
          • image1-lg.jpg
          • image2.jpg
          • image2-lg.jpg
          • [...]
        • project_one.md [markdown-formatted project decription]
        • images.yaml [automatically generated by makefolio]
      • project two
        • ...
      • project three
        • ...
    • templates
      • layout.html.erb
      • _project.html.erb
      • _index.html.erb
  • dist
    • [makefolio will create this directory and generate your site files here]

Project Description Files

Each project directory should contain a markdown file containing the project description, using the same filename as the directory name (so the project_one directory should contain project_one.md). This markdown file can also contain YAML front matter. The front matter data will be added to the hash of project data available for use in the template files.

The title property of a project is automatically set to its directory name, but this can be overridden by setting title in the front matter. The sort property can be set to specify a display order of projects, in ascending order. (Projects with no sort property will appear last.)

Project Images

Makefolio will not generate thumbnail images for you, but it will automatically associate thumbnails and large images if you follow its naming convention.

To do this, add the suffix -lg to your image filename. For example, if you have an image file with the name my-image.jpg, the corresponding large image should be named my-image-lg.jpg.

Image Metadata

Running makefolio init will generate images.yaml metadata files for each of your projects. If the file already exists, makefolio will not overwrite it. (So if you add an additional image to your project you will have to add it to images.yaml yourself.)

Whatever properties you set in this file will be available in your templates. The sort property can be set to specify a display order of images, in ascending order. (Images with no sort property will appear last.)

Other Site Resources

Makefolio will copy the _src/resources directory and all of its contents, including subdirectories, to the dist directory unchanged. A file saved at _src/resources/myfile.gif will be copied to dist/myfile.gif.

Templates

Makefolio creates a very simple website structure: a site index containing a list of all of your projects, and an individual page for each project.

It uses three ERB template files:

layout.html.erb

The basic html structure of your site. Place the <%= content %> tag where makefolio should insert the project index/individual project information.

_project.html.erb

The template for individual product pages. title, desc and images are automatically available, as well as anything defined in the YAML front matter.

images is array of the images associated with a project. Each image's information is a hash that contains path (relative to index.html), path_large (the same, for the large version of an image, if it exists), filename and filename_large. Additional information defined in images.yaml is also included.

_index.html.erb

The variable projects is available in this template. It contains an array of project data hashes identical to the one available on the individual project page.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request