Introducing org: A site generation tool for open source organizations

• by Alejandro Gomez
• •
• January 31, 2017
• •
• clojure• open source
• |
• 8 minutes to read.

We’ve recently developed a website to showcase some of our open source projects. Aside from listing many of our projects, it also shows statistics regarding their audiences, stars, and contributors. Instead of building a one-off website, we decided that it would be a fun exercise to write an open source project site generator (much like our project to generate sites for individual libraries sbt-microsites. This way, we’re not the only ones benefiting from having this type of directory, any GitHub organization can create their own by simply tweaking a couple of lines from a config file. We’ve entitled this project org, and you can find it in the org GitHub repo.

org is written in Clojure and ClojureScript. We’ll discuss how it works in more depth in an upcoming post, but for now, we’re going to focus on teaching you how you can easily create this site for your organization by leveraging org.

Setup

Ensure you have Leiningen and Sass installed.

Clone the repository

First and foremost, grab org from the official repository with git:

$ git clone https://github.com/47deg/org.git site
$ cd site

We’ll now have a site directory with org’s repository contents, let’s get started!

You’ll want to remove the default git origin and add your organization’s site repo instead, this is how it looks like for the 47deg organization:

$ git remote rm origin
$ git remote add origin https://github.com/47deg/47deg.github.io.git

Create a branch to host the “raw,” uncompiled version of the site, since your organization’s site files must be in the master branch. We’ll push to master shortly, for now, we’ll create a raw branch and push that instead:

$ git checkout -b raw
$ git branch -d master
$ git push -u origin raw

Compile Sass files

The styles are written using Sass instead of CSS, so you’ll need to compile the Sass files to CSS with the following command:

$ sass sass/style.scss:resources/public/style.css

Configure the site

Now that we’ve cloned the repository its time to edit the config file located in resources/config.edn.

Before doing anything else, create a GitHub token since org will need to use it for fetching GitHub data. Once you have the token, make sure to add it to the :token entry in the configuration file.

We’ll start by making "47deg" the name of the GitHub organization and listing a few projects: fetch and mvessel. Next, we’ll add a human-readable, capitalized name to the organization. We’re also interested in showing and being able to filter by Scala and Java, since those are the languages used to write these libraries.

This is our config file after adding the settings mentioned above:

{:token "your-token-here"
 :organization "47deg"
 :organization-name "47 Degrees"
 :languages #{"Scala" "Java"}
 :included-projects #{"fetch" "mvessel"}}

We’ll want to configure the logo to point to 47 Degrees’ main site and to include the logo image:

{; ...
 :logo {:href "https://www.47deg.com"
        :src "img/nav-brand.png"}}

The initial version of our site will look like the following:

Optionally, we can customize the styles applied to the img tag by configuring the :style map. If we want to invert the logo image we could do the following:

{; ...
 :logo {:href "https://www.47deg.com"
        :src "img/nav-brand.png"
        :style {:filter "invert(1)"}}}

Project logos

Since most projects don’t have logos, a placeholder is shown by default, but we can include logos on a per-project basis in the configuration. The :project-logos allows us to map project names to their logo’s URL:

{;...
 :project-logos {"fetch" "https://rawgit.com/47deg/microsites/cdn//fetch/navbar_brand.png"
                 "mvessel" "https://rawgit.com/47deg/microsites/cdn//mvessel/navbar_brand.png"}
}

Now the project cards look much better:

Links

You may want to include a series of links at the top of the page, the :links setting allows you to add any links you want to the navigation bar and footer.

On the 47 Degrees open source site, we link to our blog and contact page, so the :links settings appears as the following:

{;...
 :links [{:text "Blog" :href "https://www.47deg.com/blog"}
         {:text "Contact" :href "mailto:[email protected]"}]}

You can see the links to the blog and contact in the top of the page:

As well as the footer:

Social media

Social media links are also supported, so if you want to link to other social sites outside of GitHub, you can do so by tweaking the :social setting. You can include entries for :twitter and :facebook with your respective handles:

{;...
 :social {:twitter "47deg"
          :facebook "47degreesLLC"}}

The links to social media sites will appear in the footer:

Styles

There are a few style settings that can be changed, such as the primary color, header, and main font.

• :primary-color allows users to customize the main color used in the website.
• :header allows users to adjust header styles.
• :font allows users to customize the webfont they want to use for the headings and the overall text, as well as the sizes for the light, regular, semi-bold, and bold variants.

This is how our configuration looks for the 47 Degrees site:

{;...
 :style {:primary-color "#F44336"
         :header {:background "linear-gradient(0deg, rgba(30, 39, 53, 0.88), rgba(30, 39, 53, 0.88)), url(\"img/header-background.jpg\") no-repeat center center"
		          :background-size "cover"}
         :font {:url "https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700|Poppins:300,400&display=swap"
                :base "'Open sans', sans-serif"
                :headings "'Poppins', sans-serif"
                :sizes {:light 300
                        :regular 400
                        :semi-bold 600
                        :bold 700}}}}

The site looks much better with a background image in the header:

Developer preview

Once you’ve configured org, you can preview the site by running:

$ lein figwheel

and pointing your browser to locahost:3449. You can update the configuration and reload the site to see the latest changes.

Build a static site

After adjusting the configuration to your satisfaction, run the following command for generating a static version of the site in the docs directory:

$ lein run

After compiling the site you’ll be able to serve it from the docs directory.

Publish to GitHub

After successfully building the site, we can push the docs directory directly to the master branch to publish our site. We do so by adding the contents of the docs folder to the repo in the raw branch and then pushing the docs subdirectory to the master branch:

$ git add docs/
$ git commit -m "Generate site"
$ git subtree push --prefix docs origin master

Conclusion

org lets you build a website to showcase your GitHub organization’s open source projects by simply editing a configuration file. Most of the website can be adjusted by editing a config file, take a look at the README for an explanation of every configuration option. The resulting site is prerendered with your content so it’s easily indexed by search engines, and will update its information when users visit it. Take a look at 47 Degree’s open source site or Funcool’s open source site,both built with org!

Stay tuned for a follow-up post containing a few details on how org works! We’ll also discuss how the technology choices have enabled us to run the same data-fetching and rendering code in both the users’ browsers and the JVM. In the meantime, you can ask us any questions regarding this project, or any others here: @47deg.