Liferay.Design

About

The online presence of Liferay's Design Teams!

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

Table of Contents

• Liferay.Design
  • About
  • 👾 Getting started
    • If you don't have a dev environment
    • 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.

Quick Start

Warning: This project only works with Node v12 (we could run v14, but we need 12 to install dependencies). You can use NVM to install Node v12.14.1 by nvm install v12.14.1, 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.

Dev

Note: The Dev branch is no longer being actively used — the use-case for it is no longer necessary thanks to Netlify's Deploy Previews.

Currently live on dev.liferay.design. This is our pre-production environment, best not to send pull requests to it unless there's a special scenario.

Production

Currently live on liferay.design, 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 liferay.design 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.