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.
This site uses a Jekyll, a Ruby framework. The required Jekyll version is 3.4.0.
There are two ways to run Jekyll to build the site:
- Using Bundler, so Jekyll and accompanying gems are installed only inside this directory.
- Using globally-installed Jekyll and accompanying gems.
The latter method is the one currently actually used on scala-lang.org. The former method is likely most convenient for users who already have a different version of Jekyll installed, or who are comfortable using Bundler and who don't want anything else installed system-wide.
cd
into the directory where you cloned this repository, then install the
required gems with bundle install
. This will automatically put the gems into
./bundle-vendor/bundle
.
Start the server in the context of the bundle:
bundle exec jekyll serve
That's it.
If that doesn't work, to guarantee that your version of Ruby, etc, completely
matches the production environment, you can also use rbenv
. Start by cd
ing
into the directory where you cloned this repository, then execute the following:
rbenv install 2.3.1
rbenv local 2.3.1
rbenv rehash
gem install bundle
bundle install # This will automatically put the gems into `./bundle-vendor/bundle`
bundle exec jekyll serve # Start the server in the context of the bundle
From this point, everything else should be the same, regardless of which method you used to run Jekyll.
Install Jekyll 3.4.0 on your system using RubyGems:
gem install jekyll -v 3.4.0
After cloning, cd
ing into the directory where you cloned this repository and
run:
jekyll serve
and watch the output. You should see something like:
Configuration file: /Users/ben/src/scala.github.com/_config.yml
Source: /Users/ben/src/scala.github.com
Destination: /Users/ben/src/scala.github.com/_site
Incremental build: enabled
Generating... done.
Auto-regeneration: enabled for '/Users/ben/src/scala-lang'
If you get incompatible encoding
errors when generating the site under Windows, then ensure that the
console in which you are running jekyll can work with UTF-8 characters. As described in the blog
Solving UTF problem with Jekyll on Windows
you have to execute chcp 65001
. This command is best added to the jekyll.bat
-script.
Regardless of your method of running Jekyll, the generated site is available at http://localhost:4000
.
If you add --watch
to your Jekyll command line, Jekyll will automatically watch for changes on the filesystem. When you change a file, the console will show that jekyll is regenerating. Wait until it says done
to refresh your browser.
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>
.
There are dozens of guides and cheatsheets that cover Markdown syntax out there, though this screenshot from the free OS X Markdown editor, Mou, is an excellent and concise reference:
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)
## Permalinks
In this new version of the scala-lang site we've tried to follow a pretty permalink
style, so that any generated page will have an permalink finishing in a slash character (/
). This will tell Jekyll to build that particular page as an index.html
inside a folder with a name as specified in the provided permalink. i.e.: if a page has a permalink as follows:
permalink: /what-is-scala/
This will tell Jekyll to create a what-is-scala
folder, with an index.html
file inside. Links to this page will refer to the {{site.baseurl}}/what-is-scala/
.
## Custom collections and data
In the previous version of the site, data used in different pages was contained in categorized blogs. This has been changed to use custom collections. Every custom collection is a folder starting with an underscore character (_
), containing a markdown
file for each member of the collection. As any markdown containing a page in the site, it starts with a YAML front matter containing the data for this item, and can optionally contain markdown text to be rendered as html.
Right now there are no collections being rendered as specific pages in the site (they're only consumed internally as static data), but in the future this can be changed by specifying the global output: true
variable in the _config.yml
custom collections section. You'll also need to specify a layout by using the defaults
settings in the _config.yml
file. i.e.:
defaults:
- scope:
path: ""
type: collection_name
values:
layout: layout_name
To access data from a custom collection just refer to site.<collection_name>
. The collection's name will be the name of its folder sans the underscore character. i.e.: to access the data inside _downloads
, you can do it as follows:
site.downloads
Some of the data has been also modelled as YAML files inside the _data
folder. Generally for data that is used throughout the site (i.e: the navigation bar links).
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 subdirectoryscala-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..)
- older distribution files, RCs in
- 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
- distribution files (tarballs etc) in
We have the following (general) templates: (Note that this is not an exhaustive list.)
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)
---