Repository files navigation

This repository contains the source for thescala-lang.org web site.

It does not contain the source for thedocs.scala-lang.org subdomain. You can visit thedocs.scala-lang repository if you are interested in contributing to the Scala documentation site.

The repository for Scala 3 itself ishttps://github.com/scala/scala3 .

Scala 2 is athttps://github.com/scala/scala. Scala 2 bug reports are athttps://github.com/scala/bug.

To build the site you can either useCompose orBundler. Compose is a good option if you are just gettingstarted and want something simple. If you are already familiar with the Ruby ecosystem then Bundlermight be the most comfortable for you.

Either way the site is built withJekyll and is typeset mostly inMarkdown.

Make sure you are in the root directory of the cloned repository.

You need to haveDocker Engine andDocker Compose installed on your machine.Under macOS (Intel or Apple silicon), instead of installingDocker Desktop you can also useHomeBrew withColima:brew install colima docker docker-compose.
UID and GID environment variables are needed to avoid docker from writing files as root in your directory.By default, docker-compose will use the file docker-compose.yml which will build the website and serve it on 0.0.0.0:4000 .If you just need to build the website, add-f docker-compose_build-only.yml

env UID="$(id -u)" GID="$(id -g)" docker-compose up

The generated site is available athttp://localhost:4000.

When the website dependencies change (the content of theGemfile),you have to re-build the Docker image:

env UID="$(id -u)" GID="$(id -g)" docker-compose up --build

If you have problems with the Docker image or want to force the rebuild of the Docker image:

env UID="$(id -u)" GID="$(id -g)" docker-compose build --no-cache

Install bundler first:

sudo gem install bundler

Then:

bundle installbundle exec jekyll serve --incremental

Regardless of your method of running Jekyll, the generated site is available athttp://localhost:4000.

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: pagetitle: 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: pagetitle: My page title---# {{ page.title }}Body text here...

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

Visual Studio Code has great support for Scala, Git, and Markdown.

The least error-prone way to make links is to use this format:[link text]({{ site.baseurl }}/path/to/page/page.html)

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

We try to follow apretty permalink style, so that any generated page will have a link finishing in a slash character (/). This will tell Jekyll to build that particular page as anindex.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 awhat-is-scala directory, with anindex.html file inside. Links to this page will refer to the{{site.baseurl}}/what-is-scala/.

Everycollection is a directory starting with an underscore character (_), containing a Markdown file for each member of the collection. These Markdown files start 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 are only consumed internally as data. In the future this can be changed by specifying the globaloutput: true variable in the_config.yml custom collections section. You will also need to specify a layout by using thedefaults 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 refer tosite.<collection-name>. The collection's name will be the name of it's directory without the underscore character. i.e.: to access the data inside_downloads, usesite.downloads.

Some of our data has been modelled as YAML files inside the_data folder. We generally do this for data that is used throughout the whole site. For example we do this for the navigation bar links.

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

There are additional files on the webserver:

• Subdirectoryscala-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 anotherhourly 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