Erlang.org

This is the repository for the erlang.org website.

We use ruby /w jekyll, nodejs /w bootstrap 5 and Erlang to build this website.

To launch a local copy, install the correct prerequisites and do make serve and navigate to http://localhost:4000.

You can view the deployed version here: https://www.erlang.org

Makefile

The makefile supports these targets

• build (default) - depeds on setup
  • Builds the entire site under _site for exporting
• serve - depends on setup
  • start jekyll to serve the erlang.org site at http://localhost:4000
• setup
  • Download and generate all Auto-generated Content.
• test - depends on setup
  • Runs linting and all testcases

Devcontainer / gitpod.io

This project can be run as a vscode devcontainer and/or in gitpod.io.

To work with this project in gitpod go to: https://gitpod.io/#https://github.com/erlang/erlang-org/

For instructions on how to run with vscode devcontainers see: https://code.visualstudio.com/docs/remote/containers

Adding content

Most pages are either html or markdown pages so they can be edited directly. They are located in the at the same place as the URL. So, for instance, the /about URL is implemented by /about.md and /community/euc is implemented in /community/euc.

There are three major collections that you can add new items to: News, Blog and Release. Each of these are markdown files found in _news, _posts and _releases respectively. There is a README file in each of those folders that describe the mandatory front matter for each item.

The markdown dialect used is github flavored markdown.

There are also two yaml data files that contain the documentation and community links.

Auto-generated content

When doing make setup the auto-generated content is created. All auto-generated content is cached on github in order to speed up the netlify build.

EEPs

This is placed under _eeps.

Clone https://github.com/erlang/eep then parse using format-eeps.erl. We do not use the perl markdown formatter for EEPs as the html produced does not look very nice.

FAQ

This is placed under faq.

Clone https://github.com/matthiasl/Erlang-FAQ and then build it.

Patches

This is placed under _data/release.json and _patches.

We fetch the latest otp_versions.table and from there use the Github API and use erlang.org rsync to fetch information about each patch released since OTP-17.0.

The files in _patches and _data/release.json contain a lot of duplicate information. We could have kept the _data/release.json as the only place to keep the data, but we didn't as doing lookups in it turned out to be too slow for jekyll.

Documentation

This is placed under docs.

The latest documentation for each release since OTP-17 is downloaded+flattened and put into the docs folder. The documentation is not built from scratch but rather fetched from github releases or erlang.org.

The documentation in docs/doc is modified to have the algolia search functionality inserted into it.

Algolia

We have an agreement with algolia that they run a scraper that goes through our documentation and provides search results from that. We use a customized [Algolia Crawler] that crawls the documentation at www.erlang.org/doc once every week.

For the search widget we use docsearch v3, which is a small react widget.

At the moment there is (as far as I know) no good way for a anybody else to optimize the search results as the crawler and index config is inside my (@garazdawi) account and not available outside. So if you want to attempt to make the search better results, you should contact me and we'll have to work together to improve things.

Getting good results from the search is hard, so maybe we should implement a way to make sure that lists:map is recognized as a module and function. However, our react skills are not there yet so this will have to do for now.

Prerequisites

You need to have the following tools installed to build the erlang.org site:

• GNU make 4.1 or later
• ruby 2.6.5 or later
• bundler 1.16 or later
• nodejs 14 or later
• erlang 24 or later
• xsltproc

Most likely earlier versions of these tools will work, but they have not been tested.

If you want to be sure that you use the correct version of the dependencies you can either use the devcontainer or asdf.

Development

Layout

erlang.org uses a combination of CSS Grid layout and Bootstrap 5 Grid layout. The goal is to use CSS Grid for all responsive layouts and then use Bootstrap Grid for all the non-responsive things.

Using CSS Grid to do the responsive layout instead of Bootstrap removes a lot of extra divs and order classes that are needed otherwise. However, it removes the layout from the html, so it sometimes becomes less obvious what is going on.

The HTML for a normal page looks something like this:

<body>
    <header class="container header">
        <nav></nav>
    </header>
    <div class="container body">
      <aside class="sidebar"></aside>
      <main class="main">
          <div class="top"></div>
          <div class="content"></div>
      </main>
    </div>
    <footer class="container footer"></footer>
</body>

In the above the container class is part of bootstrap and is used for styling and then we use CSS grid to place the content of the body and main classes responsively:

@include media-breakpoint-up(lg) {
    .body {
        display: grid;
        /* 2 columns on > lg screens */
        grid-template-columns: 1fr auto;
    }
    .main {
        display: grid;
    }
}
@include media-breakpoint-down(lg) {
    .body {
        display: grid;
        /* Hide the sidebar on small screens */
        .sidebar {
            display: none;
        }
    }
    .main {
        display: grid;
    }
}

Manipulating CSS

Bootstrap 5 comes with a lot of css entities built in. You should have a look around in the bootstrap docs to see what you can use.

If you want to change the color of a specific component there is a list of the sass variable that you need to change in the specific page. For example if you want to change the font-size in badges you can lookup the variable here: https://getbootstrap.com/docs/5.0/components/badge/#sass. And then set $badge-font-size: 0.80em in _variables.scss.

A full list of all the variables can be found in node_modules/bootstrap/scss/_variables.scss.

You can of course also create your own styles, but we try to stay with the bootstrap styles as much as possible.

Architecture

Things to do when switching

• Change www.erlang.org to point to new cdn.

Redirection fixes

• Redirect blog.erlang.org/* to www.erlang.org/blog
• Redirect bugs.erlang.org/browse/* to www.erlang.org/bugs/
• Redirect bugs.erlang.org to github.com/erlang/otp/issues
• Redirect erlang.org/faq/* to www.erlang.org/faq
• Redirect erlang.org/eep/* to www.erlang.org/eep
• Redirect erlang.org/eeps/* to www.erlang.org/eeps
• Redirect erlang.org/doc/* to www.erlang.org/doc
• Redirect erlang.org/workshop/* to www.erlang.org/workshop
• Redirect www.erlang.org/download/* to erlang.org/download
• Redirect www.erlang.org/* to erlang.org/*
• Redirect www.erlang.org/course/* to erlang.org/course
• Redirect www.erlang.org/documentation/* to erlang.org/documentation
• Redirect www.erlang.org/mailman/* to erlang.org/mailman
• Redirect www.erlang.org/mailman-icons/* to erlang.org/mailman-icons
• Redirect www.erlang.org/pipermail/* to erlang.org/pipermail

Things that have been removed

• The course (this is actually on erlang.org)
• The events (redirect to EEF?)
• Documentation version index page (redirect to erlang.org/documentation)

Ideas

• Add plausable.io tracking
• Add https://search.google.com/search-console/ support?
• Add visual testing
  • Use BackstopJS for regression testing
  • https://applitools.com/
• Rework /community to not just be a bunch of links. Maybe the rust page can give some inspiration? https://www.rust-lang.org/community
• Add markdownlint? https://www.npmjs.com/package/markdownlint
• Add paginated docsearch results. See https://discourse.algolia.com/t/dedicated-search-page/583 and https://jsfiddle.net/maxiloc/oemnhuv4/
• /docs
  • Other sections? Learning/Developing/References
• /community
  • Beam Languages
  • Other projects