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

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!

⛩ 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
├── .gitignore
├── .prettierrc
├── gatsby-browser.js
├── gatsby-config.js
├── gatsby-node.js
├── gatsby-ssr.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. .gitignore: This file tells git which files it should not track / not maintain a version history for.

4. .prettierrc: This is a configuration file for a tool called Prettier, which is a tool to help keep the formatting of your code consistent.

5. 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.

6. 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).

7. 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.

8. gatsby-ssr.js: This file is where Gatsby expects to find any usage of the Gatsby server-side rendering APIs (if any). These allow customization of default Gatsby settings affecting server-side rendering.

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

This is written for people who generally try to avoid the terminal — it can be scary, but Liferay.Design is a lot like Zelda (you don't have to go alone 🥁)!

Any of the designers here can help you, or at least point you to someone who can.

Set aside about 45 — 60 min to get set up.

Step 1: Create a Github Account (3 min)

1. Set up a personal account
2. Choose the "free" plan
3. Tailor your experience — if you'd like, this can be helpful

Step 2: Familiarize yourself with Git and Github (20 min)

1. Read Hello World and complete the tutorial. (10 min)
   • If you really, really, really aren't interested in this "technical" stuff, then this tutorial covers everything you'll need to create your bio page.
2. Read Chris' post on Git Commit Messages — this will help you avoid Paul-like commit messages.
3. Read the Git Handbook (10 min) for a good overview on the theory behind Git and GitHub.
   • NB This is important and helpful information to understand at a high level because Liferay uses Git.
4. Check out the GitHub's resources, and the team's Trello cards on Git.

Step 3: Let's git it started™ (20 min)

1. Congratulate Paul on that amazing section title 👆
2. Visit our Phresh-N-Clean guide — this whole thing is pretty helpful for setting up your computer in a way that it can quickly and easily be reformatted and restored will help your computer stay faster, better, longer. (So you can work it.)
3. Complete steps 1, 2, 4, and 6 of the Set Up portion
4. Install a code editor — Sublime Text or VSCode.
   • brew cask install sublime-text or brew cask isntall visual-studio-code

Step 4: The Clone Wars (2 min)

1. Pat yourself on the back, you're almost done — the last thing to do is get a local copy (code on your computer) of the site repository (repo for short).
2. Orient yourself
   1. Open your Terminal and type ls and hit Enter — this command will list the files and folders of the current directory (folder)
   2. Type open . and hit Enter — this will open up Finder to the current directory.
   3. Type mkdir github and hit Enter — now look at your Finder, you should now see a new folder labeled 'github' in your Home directory (~/)
   4. Type cd github and hit Enter — you've now navigated to the github folder in your Terminal!
   • Note that this is our suggested method for organizing your repos, feel free to organize differently.
3. Now that your Terminal is open to your github folder, it's time to clone the repo!
4. Copy the url to your clipboard (there's a handy little button 📋)
5. Type git clone, paste the repo url and hit Enter — cloning should take about 10 seconds.
6. Now you need to navigate to the folder — type cd life and hit Tab, it should autocomplete to liferay.design — if it does, hit enter, if not, finish typing it out
7. Take your fingers off the keyboard, and give yourself a hand, you're now ready to begin development!

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.