Design.Liferay

About

The online presence of Liferay's Design Teams!

Designed in Figma, built with Gatsby, powered by Netlify.

Table of Contents

• Design.Liferay
  • About
  • 👾 Getting started
    • If you don't have a dev environment
    • Tech Stack & Requirements
    • Quick Start
  • ⛩ Structure
    • 🌳 Branches
      • Master
      • Dev
      • vN
    • 📂 Folders
      • Deploy
      • src
        • components
        • markdown
          • Using React Components Within a Markdown file
        • pages
        • theme
        • utils
      • static/images
  • 💁 What do all these files do?
  • 🎓 Learning Gatsby
  • Starting Phresh
    • Step 1: Create a Github Account (3 min)
    • Step 2: Familiarize yourself with Git and Github (20 min)
    • Step 3: Let's git it started™ (20 min)
    • Step 4: The Clone Wars (2 min)
    • Notes

👾 Getting started

If you don't have a dev environment

Skip down to Starting Phresh for a step-by-step guide.

Tech Stack & Requirements

Tool	Version	Notes
Node	18.x (18.20.8)	Pinned in .nvmrc — run nvm use inside the repo. Gatsby 5 needs Node ≥18
npm	10.x (bundled with Node 18)	package-lock.json is lockfileVersion 3; .npmrc sets legacy-peer-deps=true for React 18 peer ranges
Gatsby	5.16	Migrated from Gatsby 2 → 3 → 4 → 5 (webpack 5, LMDB datastore, MDX v2)
React	18.3	Do not apply React 16 patterns
MDX	v2	Page content renders via {children}; stricter CommonMark+JSX (see notes below)
Sass	sass (dart-sass) ~1.32	Replaced node-sass — no more native bindings to compile

A few conventions to keep in mind when touching code:

• CSS modules are imported with default exports (import styles from './styles.module.scss'). Gatsby 3+ changed the default to named exports, but this repo restores the classic behavior through cssLoaderOptions in the gatsby-plugin-sass entry of gatsby-config.js — don't migrate imports file by file.
• MDX v2: templates render the page body with {children} (the old MDXRenderer + body field were removed in Gatsby 5). Pages are created with component: \${template}?__contentFilePath=${node.internal.contentFilePath}`. The parser is stricter — HTML comments are invalid (use {/* */}), a literal < must be escaped (<), inline JSX elements can't break across lines, and style="..." must be an object (style={{ ... }}`).
• GraphQL sort uses the Gatsby 5 shape: sort: { date: DESC }, not sort: { fields: [date], order: DESC }.
• timeToRead is a custom field resolver in gatsby-node.js (Gatsby 5 removed the built-in) — it reads the source file and counts words at ~200 wpm to power the "X Min Read" badges.
• theme-ui 0.17: use Themed (from @theme-ui/mdx) instead of the removed Styled, ThemeUIProvider instead of ThemeProvider, and @emotion/react instead of @emotion/core.
• YAML/JSON id is exposed as yamlId/jsonId (Gatsby 4 change). The gatsby-config.js mapping block and any GraphQL query reading a data file's own id use yamlId (often aliased back as id: yamlId). Keep this in mind for queries against AuthorsYaml, OfficesYaml, ChangelogYaml, etc.
• Coming from an older Node setup? Delete your old install first: rm -rf node_modules && nvm use && npm install.
• Deployment runs on Netlify with NODE_VERSION = "18" pinned in netlify.toml.

Quick Start

Warning: This project requires Node v18 (see .nvmrc). You can use NVM to install it by nvm install v18.20.8 (or just nvm use inside the repo), then you can follow these steps:

1. Install Dependencies

   • open Terminal and type:

   npm install

   • hit Enter, then do the same for the command below

2. Start up the dev server

   npm run dev

3. Your favorite browser should open automatically showing the site at http://0.0.0.0:localhost:7777!

   • It will also be accessible on your network at your.local.ip:7777 — usually this will be something like 192.168.1.160:7777 — the command line prompt will specify your address.
   • This makes mobile development easier, since you can check the site out on any device that's on your network.

4. See the Contributing Guidelines for what to do after you make some improvements!

N.B. Our site requires API keys to be fully built — while we're working on making it easy for anyone to contribute to, there are some technical limitations that we've run into. As a result, either you won't be able to build the site locally or some sections of the site will be missing. This should not affect your ability to make edits to content. Please reach out to Paul Hanaoka if you need keys.

⛩ Structure

🌳 Branches

Master

Work and submit pull requests from the master branch.

Production

Currently live on design.liferay.com, don't work on Production as your pull request typically won't get accepted.

vN

We save "versions" of the site as branches — v1 (for example) was the first ever version of the site.

TODO: deploy old versions on subdomains.

---

📂 Folders

Deploy

This contains the scripts that make the site magically appear when new work gets pulled into the repo — real developers made this for us, and we generally don't touch it.

src

The src folder is where all the code is that gets compiled into a public folder which gets rendered onto the interwebs at our domain. We roughly follow atomic design principles.

components

Where all of our react components live — atoms, molecules, organisms, templates, and theme.

markdown

This is where 98.3% of the site content lives — markdown is a lot easier to write than html 🤓.

Using React Components Within a Markdown file

This is new experimental territory to render react components in md files, so you will propbably run into some quirks!

1. Rename the file extension from .md to .mdx
2. If you have markup in the file, you will now have to make it React friendly (change class to className and style="" to style={{}})
3. Import the component as normal and use it as normal :)

---
title: 'Markdown File Title'
---

<div className="aspect-ratio card-item-first" style={{background: "url('/images/logos/liferay-logo.png') center/cover"}}>
  <Icon name="keyboardArrowDown" />
</div>

• Notes: - For .mdx file syntax highlighting you can download the "Mdx" extension and follow their instructions - Don't put an extra line break between markup as it will think it will print out the literal markup for some reason

pages

Surprise surprise, this is where the code for the main pages of design.liferay.com lives.

theme

Stylesheets and other theme-related files.

utils

generateIcons.js will take any svg in the static / images / icons folder and add it to the icons component.

static/images

This is where we store all the... you guessed it, images! There's probably a better way to do this, so please help us out.

---

💁 What do all these files do?

A quick look at the top-level files and directories you'll see in a Gatsby project.

.
├── node_modules
├── src
├── .env.development
├── .gitignore
├── .prettierrc
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── LICENSE
├── package-lock.json
├── package.json
├── README.md

1. /node_modules: The directory where all of the modules of code that your project depends on (npm packages) are automatically installed.
2. /src: This directory will contain all of the code related to what you will see on the front-end of your site (what you see in the browser), like your site header, or a page template. “Src” is a convention for “source code”.
3. .env.development: This is where we keep tokens, API keys, and other secret stuff that is needed to build certain areas of the site. For the time being, please reach out to Paul and he will share any keys with you manually.
4. .gitignore: This file tells git which files it should not track / not maintain a version history for. You most likely won't need to edit it.
5. .prettierrc: This is a configuration file for a tool called Prettier, which is a tool to help keep the formatting of your code consistent.
6. gatsby-browser.js: This file is where Gatsby expects to find any usage of the Gatsby browser APIs (if any). These allow customization/extension of default Gatsby settings affecting the browser.
7. gatsby-config.js: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. (Check out the config docs for more detail).
8. gatsby-node.js: This file is where Gatsby expects to find any usage of the Gatsby node APIs (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.
9. LICENSE: Gatsby is licensed under the MIT license.
10. package-lock.json (See package.json below, first). This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. (You won’t change this file directly).
11. package.json: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.
12. README.md: A text file containing useful reference information about your project.

🎓 Learning Gatsby

Looking for more guidance? Full documentation for Gatsby lives on the website. Here are some places to start:

• For most developers, we recommend starting with our in-depth tutorial for creating a site with Gatsby. It starts with zero assumptions about your level of ability and walks through every step of the process.

• To dive straight into code samples head to our documentation. In particular, check out the “Guides”, API reference, and “Advanced Tutorials” sections in the sidebar.

Starting Phresh

See our GitHub Setup Guide

Notes

1. Pushing work to any of the branches will automagically build the site

2. You can check the progress of current and past builds by checking our Netlify Deploys page.