├── .gitignore
├── portfolio-generator.gemspec
├── portfolio-generator.rb
└── README.md


/.gitignore:
--------------------------------------------------------------------------------
1 | test
2 | 


--------------------------------------------------------------------------------
/portfolio-generator.gemspec:
--------------------------------------------------------------------------------
 1 | Gem::Specification.new do |s|
 2 |   s.name        = 'portfolio-generator'
 3 |   s.version     = '1.0.0'
 4 |   s.date        = '2015-09-25'
 5 |   s.summary     = "Portfolio generator for Jekyll"
 6 |   s.description = "Generates a portfolio/project pages (including related projects) out of data files"
 7 |   s.authors     = ["Shannon Babincsak"]
 8 |   s.files       = ["portfolio-generator.rb"]
 9 |   s.homepage    = 'https://github.com/codeinpink/jekyll-portfolio-generator'
10 | end
11 | 


--------------------------------------------------------------------------------
/portfolio-generator.rb:
--------------------------------------------------------------------------------
  1 | module Jekyll
  2 |     class ProjectPage < Page
  3 |         def initialize(site, base, dir, project_data)
  4 |             @site = site
  5 |             @base = base
  6 |             @dir = dir
  7 |             @name = "index.html"
  8 | 
  9 |             self.process(@name)
 10 |             self.read_yaml(File.join(base, "_layouts"), "project.html")
 11 | 
 12 |             project_data.each { |key, value| self.data[key] = value }
 13 |         end
 14 |     end
 15 | 
 16 |     class PortfolioGenerator < Generator
 17 |         safe true
 18 | 
 19 |         def generate(site)
 20 |             dir = site.config["portfolio_dir"] || "portfolio"
 21 | 
 22 |             # First get the related projects and add them to each project
 23 |             unless site.config["skip_related_projects"] == true
 24 |                 raise ArgumentError.new "Missing related_project_keys in config file" unless site.config["related_project_keys"]
 25 |                 compute_related_projects(site)
 26 |             end
 27 | 
 28 |             # Then generate the project pages
 29 |             site.data["projects"].each do |project_file|
 30 |                 project = project_file[1]
 31 | 
 32 |                 # I Love Cats -> i-love-cats
 33 |                 file_name_slug = slugify(project["title"])
 34 | 
 35 |                 # portfolio/i-love-cats/
 36 |                 path = File.join(dir, file_name_slug)
 37 |                 project["dir"] = path
 38 | 
 39 |                 site.pages << ProjectPage.new(site, site.source, path, project)
 40 |             end
 41 |         end
 42 | 
 43 |         def compute_related_projects(site)
 44 |             projects = []
 45 |             site.data["projects"].each { |project| projects.push(project[1]) }
 46 | 
 47 |             keys = site.config["related_project_keys"]
 48 | 
 49 |             projects.each do |project|
 50 |                 project["related_projects"] = []
 51 |                 min = site.config["related_min_common"] || 0.6
 52 | 
 53 |                 projects_copy = []
 54 | 
 55 |                 projects.clone.each do |copy_project|
 56 |                     projects_copy.push([copy_project, get_matches(project, copy_project, keys)])
 57 |                 end
 58 | 
 59 |                 related = projects_copy.keep_if { |project2| project2[1] >= min }
 60 |                 related = related.sort { |related_project, related_project2| related_project[1] <=> related_project2[1] }
 61 |                 related.reverse!.each { |related_project| project["related_projects"].push(related_project[0]) }
 62 |             end
 63 |         end
 64 | 
 65 |         def get_matches(project1, project2, keys)
 66 |             total = 0
 67 |             total_possible_matches = get_total_possible_matches(project1, keys)
 68 | 
 69 |             if project1.to_a == project2.to_a || total_possible_matches == 0
 70 |                 return total
 71 |             else
 72 |                 keys.each { |key| total += get_num_matches_for_key(project1, project2, key) }
 73 |             end
 74 | 
 75 |             result = total.fdiv(total_possible_matches).round(2)
 76 | 
 77 |             # Uncomment to see info about the matches for each project
 78 |             #puts "Matches between #{project1["title"]} and #{project2["title"]}: #{total} (#{result})"
 79 | 
 80 |             return result
 81 |         end
 82 | 
 83 |         def get_total_possible_matches(project, keys)
 84 |             total = 0
 85 | 
 86 |             keys.each do |key|
 87 |                 if project[key].class == String
 88 |                     total += 1
 89 |                 else
 90 |                     total += project[key].to_a.length()
 91 |                 end
 92 |             end
 93 | 
 94 |             return total
 95 |         end
 96 | 
 97 |         def get_num_matches_for_key(project1, project2, key)
 98 |             matches = 0
 99 | 
100 |             if project1[key].kind_of?(Array)
101 |                 matches = (project1[key] & project2[key]).length()
102 |             else
103 |                 if project1[key] == project2[key]
104 |                     matches += 1
105 |                 end
106 |             end
107 | 
108 |             return matches
109 |         end
110 | 
111 |         def slugify(title)
112 |             title.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, '')
113 |         end
114 | 
115 |     end
116 | 
117 |     module ProjectFilter
118 |         def get_projects_from_files(input)
119 |             projects = []
120 |             input.each { |project| projects.push(project[1]) }
121 |             return projects
122 |         end
123 |     end
124 | 
125 | end
126 | 
127 | Liquid::Template.register_filter(Jekyll::ProjectFilter)
128 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Jekyll Portfolio Generator
  2 | 
  3 | ## Getting Started
  4 | 
  5 | ### Installation
  6 | Install `portfolio_generator.rb` in your plugins directory (`_plugins`).
  7 | 
  8 | ### Configuration
  9 | Set your config options:
 10 | 
 11 | * `portfolio_dir` - The directory in which the projects will be generated. Defaults
 12 | to `portfolio`.
 13 | 
 14 | * `skip_related_projects` - If `true`, it will not generate related projects for
 15 | each project. Defaults to `false`.
 16 | 
 17 | * `related_project_keys` - An array of project keys that will be used to compute
 18 | related projects. This is **required** *if* you want to generate related projects.
 19 | There is no default.
 20 | 
 21 | * `related_min_common` - As a decimal, the minimum percentage of keys that should
 22 | be common for a project to be considered related. Defaults to `0.6`.
 23 | 
 24 | #### Sample `_config.yml`:
 25 | 
 26 | ```
 27 | # ...
 28 | 
 29 | portfolio_dir: "projects"
 30 | 
 31 | related_project_keys: ["category", "technology"]
 32 | 
 33 | related_min_common: 0.7
 34 | 
 35 | # ...
 36 | ```
 37 | 
 38 | ### Layout
 39 | Create a layout file named `project.html` in your `_layouts` folder that will be used
 40 | for the project pages.
 41 | 
 42 | #### Sample `project.html`:
 43 | 
 44 | ```
 45 | <h2>{{ page.title }} <span>{{ page.category }}</span></h2>
 46 | 
 47 | <p>{{ page.description }}</p>
 48 | 
 49 | <ul>
 50 |     {% for technology in page.technology %}
 51 |     <li><a>{{ technology }}</a></li>
 52 |     {% endfor %}
 53 | </ul>
 54 | ```
 55 | 
 56 | The project page will have access to any keys you use in your project data files,
 57 | so to access them you just need to use the `page` variable (e.g. `{{ page.KEY }}`).
 58 | 
 59 | ### Data Files
 60 | This plugin assumes that the project data files will be inside a `projects` directory
 61 | inside of the `_data` directory. Each project **must** have its own file, and each
 62 | project **must** have a key named `title`.
 63 | 
 64 | #### Sample Project Data File
 65 | 
 66 | `Tokyo Drift Cats.yml`:
 67 | ```
 68 | title: Tokyo Drift Cats
 69 | description: An illegal street racing game but with cats.
 70 | category: game development
 71 | technology:
 72 |     - C++
 73 |     - Git
 74 | ```
 75 | 
 76 | ## Using Projects in Templates
 77 | If you want to include your projects in your `index.html` or `portfolio.html`,
 78 | you can access your projects like this:
 79 | 
 80 | ```
 81 | {% assign projects = site.data.projects | get_projects_from_files | sort:'date' %}
 82 | {% for project in projects reversed %}
 83 |     <!-- portfolio-item -->
 84 |     <h2>{{ project.title }} <span>{{ project.category | slugify }}</h2>
 85 | 
 86 |     <a href="/{{ project.dir }}">
 87 |         <img src="{{ project.image.url }}" alt="{{ project.image.alt }}" title="{{ project.image.title }}">
 88 |     </a>
 89 |     <!-- portfolio-item -->
 90 | {% endfor %}
 91 | ```
 92 | 
 93 | This will show your projects with the most-recent being first (if you include the date
 94 | in your project files). I recommend always using the `get_projects_from_files` filter.
 95 | Without it, you'll have to do this, and the projects won't be in reverse chronological
 96 | order:
 97 | 
 98 | ```
 99 | {% for project_file in site.data.projects %}
100 |     {% assign project = project_file[1] %}
101 |     <!-- portfolio-item -->
102 |     <h2>{{ project.title }} <span>{{ project.category | slugify }}</h2>
103 | 
104 |     <a href="/{{ project.dir }}">
105 |         <img src="{{ project.image.url }}" alt="{{ project.image.alt }}" title="{{ project.image.title }}">
106 |     </a>
107 |     <!-- portfolio-item -->
108 | {% endfor %}
109 | ```
110 | 
111 | ## Related Projects
112 | Related projects are generated for each project by computing the number of matches
113 | between the projects and adding the projects as related if they are greater than
114 | or equal to the minimum required. They are sorted such that the most related
115 | appear first.
116 | 
117 | ### Using Related Projects in Templates
118 | Assuming this is in the `project.html` layout file:
119 | 
120 | ```
121 | {% if page.related_projects.size > 0 %}
122 | <h3>Related Projects</h3>
123 | {% for project in page.related_projects %}
124 | <a href="/{{ project.dir }} ">
125 |     <img src="{{ project.image.url }}" alt="{{ project.image.alt }}" title="{{ project.image.title }}">
126 | </a>
127 | {% endfor %}
128 | {% endif %}
129 | ```
130 | 
131 | The plugin adds *all* related projects, so if a project has a lot of related projects,
132 | you might have to add a limit, like so:
133 | 
134 | ```
135 | {% if page.related_projects.size > 0 %}
136 | <h3>Related Projects</h3>
137 | {% for project in page.related_projects limit:3 %}
138 | <a href="/{{ project.dir }} ">
139 |     <img src="{{ project.image.url }}" alt="{{ project.image.alt }}" title="{{ project.image.title }}">
140 | </a>
141 | {% endfor %}
142 | {% endif %}
143 | ```
144 | 
145 | ## More Examples
146 | For more examples, check out the [repo](https://github.com/codeinpink/codeinpink.github.io)
147 | for [codeinpink.github.io](http://codeinpink.github.io/)! The source code is in
148 | the `source` branch and the generated content is in the `master` branch.
149 | 


--------------------------------------------------------------------------------