axel22/scala-lang

The Scala Website

SCALA-LANG.ORG

This repository contains the static source of scala-lang.org. It does not contain the source of any content found under the docs.scala-lang.org subdomain (instead, visit the scala.github.com repo for that source).

It's a static site generated by Jekyll, and uses a whole host of open-source tools including a touch of Twitter's Bootstrap.

Dependencies

You'll need Jekyll installed to generate and test the site. To get it, most people can install via RubyGems:

gem install jekyll

OSX users might have to update RubyGems:

sudo gem update --system

If in doubt, head over to the Jekyll wiki for installation instructions.

Building

After cloning, cd into the scala/scala-lang directory and run:

jekyll serve

To see the generated site, just visit http://localhost:4000.

YAML Front Matter

The "YAML Front Matter" is nothing more than the header on each page that you intend for Jekyll to parse. It contains information such as the name of the HTML template (layout) chosen for the specific document, and the title of the document. An example YAML front matter might look like:

---
layout: page
title: My page title
---

You can use these fields in the YAML front matter later in your document. For example, to make a header with the title of the document, in markdown you would write:

---
layout: page
title: My page title
---

# {{ page.title }}

Body text here...

# {{ page.title }} would be rendered in HTML as, <h1>My page title</h1>.

Markdown

There are dozens of guides and cheatsheets that cover markdown syntax out there, though this screenshot from the free OSX markdown editor, Mou, is an excellent and concise reference:

Linking to internal pages

The least error-prone way to link between documents, to link to local images, or anything else: [link text]({{ site.baseurl }}/path/to/page/page.html)

Here, {{ site.baseurl }} is a site-wide variable that represents the root directory of the static site. So, to display the Scala logo image, located in img/scala-logo.png, one must simply write: ![Img alt text]({{ site.baseurl }}/resources/img/scala-logo.png)

Resources and Workflow

On every commit to the scala/scala-lang repository a jenkins job will generate the site using jekyll and copy the resulting files to the webserver. NOTE: the rsync of this job also deletes whatever is in the webserver directory with explicit exceptions: we need to keep the files listed below. Kind of a hack.

There are additional files on the webserver:

• Subdirectory scala-lang.org/old is a static copy of the old website. It was generated once and copied there, and it stays like that.
• Most of the files in /home/linuxsoft/archives/scala/ (on chara, accessible through ssh with your LAMP account) are synchronized to the subdirectory scala-lang.org/files/archive by another hourly jenkins job. This folder is used by the nightly and release jenkins jobs to publish scala releases:
  • distribution files (tarballs etc) in /
    • older distribution files, RCs in /old/ (not sure how exactly this is split up..)
  • api docs for distributions in /api/
  • nightly builds in /nightly/distributions/
  • nightly api builds in /nightly/docs-xxx/
  • nightly pdf builds (spec etc) in /nightly/pdfs

Templates

We have the following (general) templates: (Note that this is not an exhaustive list.)

page.html

Example YAML front matter with all possible fields:

---
layout: page
title: I Haz Build: An Autobiography of the Build Kitten
by: Scala Jenkins (Build Kitty)
---