Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@pettinarip
pettinarip committed May 24, 2022
1 parent 014d3b2 commit 012d7c7
Show file tree
Hide file tree
Showing 4 changed files with 34 additions and 28 deletions.
4 changes: 4 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,10 @@ To create a new function, you will need to create two files:
- One in `src/lambdas` where the logic will live. These are the ones that will be deployed to Netlify. These functions follow [this format](https://docs.netlify.com/functions/build-with-javascript/#synchronous-function-format).
- One in `src/api` that will be just a wrapper around the previous one in order to be compatible with Gatsby functions. More on the [Gatbsy docs](https://www.gatsbyjs.com/docs/reference/functions/getting-started/) for the format they follow.

Typically, you will develop and test functions in the Gatsby context, by running `yarn start`.

In case you want to test them as if you were in a Netlify env, you can install the [Netlify CLI](https://docs.netlify.com/cli/get-started/) and run `netlify dev --framework=gatsby`.

### 6. Submit your PR

- After your changes are committed to your GitHub fork, submit a pull request (PR) to the `dev` branch of the `ethereum/ethereum-org-website` repo
Expand Down
40 changes: 20 additions & 20 deletions docs/best-practices.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Markdown will be translated as whole pages of content, so no specific action is
- This results in significant challenges during the translation process, as written syntax for each language will vary in terms of ordering subjects/verbs/etc.
- If you're wanting to link to something within your sentence, create a link at the end of the sentence or paragraph:
```jsx
```tsx
<p>
All Ethereum transactions require a fee, known as Gas, that gets paid to the
miner. <Link to="link">More on Gas</Link>
Expand All @@ -41,7 +41,7 @@ Markdown will be translated as whole pages of content, so no specific action is

Once, you've added your English content to the appropriate JSON file, the above code should look something more like:

```jsx
```tsx
<p>
<Translation id="page-transactions" />{" "}
<Link to="link">
Expand All @@ -52,11 +52,11 @@ Markdown will be translated as whole pages of content, so no specific action is

- _tl;dr Each individual JSON entry should be a complete phrase by itself_

- This is done using the `Translation` component. However there is an alternative method for regular JS: `gatsby-plugin-intl` with `/src/utils/translations.js`
- This is done using the `Translation` component. However there is an alternative method for regular JS: `gatsby-plugin-intl` with `/src/utils/translations.ts`

- **Method one: `<Translation />` component (preferred if only needed in JSX)**

```jsx
```tsx
import { Translation } from "src/components/Translation"

// Utilize in JSX using
Expand All @@ -65,7 +65,7 @@ Markdown will be translated as whole pages of content, so no specific action is

- **Method two: `translateMessageId()`**

```jsx
```tsx
import { useIntl } from "gatsby-plugin-intl"
import { translateMessageId } from "src/utils/translations"
Expand All @@ -74,19 +74,19 @@ Markdown will be translated as whole pages of content, so no specific action is
translateMessageId("language-json-key", intl)
```

```jsx
```tsx
const siteTitle = translateMessageId("site-title", intl)
```

## React Hooks

- Components and pages are written using arrow function syntax with React hooks in lieu of using class-based components

```jsx
```tsx
// Example
import React, { useState, useEffect } from "react"
const ComponentName = (props) => {
const ComponentName: React.FC = (props) => {
// useState hook for managing state variables
const [greeting, setGreeting] = useState("")
Expand All @@ -103,12 +103,12 @@ export default ComponentName

## Styling

- `src/theme.js` - Declares site color themes, breakpoints and other constants (try to utilize these colors first)
- `src/theme.ts` - Declares site color themes, breakpoints and other constants (try to utilize these colors first)
- We use [styled-components](https://styled-components.com/)

- Tagged template literals are used to style custom components

```jsx
```tsx
// Example of styling syntax using styled-components
import styled from "styled-components"
Expand All @@ -130,10 +130,10 @@ export default ComponentName

- Recommended VS Code Plugin: `vscode-styled-components` <br>To install: Open VS Code > `Ctrl+P` / `Cmd+P` > Run: <br>`ext install vscode-styled-components`

- Values from `src/theme.js` are automatically passed as a prop object to styled components
- Values from `src/theme.ts` are automatically passed as a prop object to styled components

```jsx
// Example of theme.js usage
```tsx
// Example of theme.ts usage

import styled from "styled-components"

Expand All @@ -148,7 +148,7 @@ export default ComponentName
- [Framer Motion](https://www.framer.com/motion/) - An open source and production-ready motion library for React on the web, used for our animated designs
- **Emojis**: We use [Twemoji](https://twemoji.twitter.com/), an open-source emoji set created by Twitter. These are hosted by us, and used to provide a consistent experience across operating systems.

```jsx
```tsx
// Example of emoji use
import Emoji from "./Emoji"

Expand All @@ -157,12 +157,12 @@ import Emoji from "./Emoji"
```

- **Icons**: We use [React Icons](https://react-icons.github.io/react-icons/)
- `src/components/Icon.js` is the component used to import icons to be used
- `src/components/Icon.ts` is the component used to import icons to be used
- If an icon you want to use is not listed you will need to add it to this file

`src/components/Icon.js`:
`src/components/Icon.ts`:

```jsx
```tsx
// Example of how to add new icon not listed
import { ZzIconName } from "react-icons/zz"

Expand All @@ -174,7 +174,7 @@ import { ZzIconName } from "react-icons/zz"

From React component:

```jsx
```tsx
// Example of icon use
import Icon from "./Icon"

Expand All @@ -187,7 +187,7 @@ import Icon from "./Icon"
- [Gatsby + GraphQL](https://www.gatsbyjs.com/docs/graphql/) used for loading of images and preferred for API calls (in lieu of REST, if possible/practical). Utilizes static page queries that run at build time, not at run time, optimizing performance.
- Image loading example:

```jsx
```tsx
import { graphql } from "gatsby"

export const query = graphql`
Expand All @@ -209,7 +209,7 @@ export const query = graphql`

- API call example:

```jsx
```tsx
import { graphql } from "gatsby"

export const repoInfo = graphql`
Expand Down
17 changes: 9 additions & 8 deletions docs/stack.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,14 @@
- [Yarn package manager](https://yarnpkg.com/cli/install)
- [Gatsby](https://www.gatsbyjs.org/)
- Manages page builds and deployment
- Configurable in `gatsby-node.js`, `gatsby-browser.js`, `gatsby-config.js`, and `gatsby-ssr.js`
- Configurable in `gatsby-node.ts`, `gatsby-browser.ts`, `gatsby-config.ts`, and `gatsby-ssr.ts`
- [Gatsby Tutorial](https://www.gatsbyjs.com/docs/tutorial/)
- [Gatsby Docs](https://www.gatsbyjs.org/docs/)
- [React](https://reactjs.org/) - A JavaScript library for building component-based user interfaces
- [Typescript](https://www.typescriptlang.org/) - TypeScript is a strongly typed programming language that builds on JavaScript
- [GraphQL](https://graphql.org/) - A query language for APIs
- [Algolia](https://www.algolia.com/) - Site indexing, rapid intra-site search results, and search analytics. [Learn more on how we implement Algolia for site search](./docs/ALGOLIA_DOCSEARCH.md).
- Primary implementation: `/src/components/Search/index.js`
- Primary implementation: `/src/components/Search/index.ts`
- [Crowdin](https://crowdin.com/) - crowdsourcing for our translation efforts (See "Translation initiative" below)
- [GitHub Actions](https://github.com/features/actions) - Manages CI/CD, and issue tracking
- [Netlify](https://www.netlify.com/) - DNS management and primary host for `master` build.
Expand All @@ -23,15 +24,15 @@
| `/src` | Main source folder for development |
| `/src/assets` | Image assets |
| `/src/components` | React components that do not function as standalone pages |
| `/src/content` | Markdown/MDX files for site content stored here. <br>For example: `ethereum.org/en/about/` is built from `src/content/about/index.md` <br>The markdown files are parsed and rendered by `src/templates/static.js`\* |
| `/src/content/developers/docs` | \*Markdown files in here use the Docs template: `src/templates/docs.js` |
| `/src/content/developers/tutorials` | \*Markdown files in here use the Tutorial template: `src/templates/tutorial.js` |
| `/src/content` | Markdown/MDX files for site content stored here. <br>For example: `ethereum.org/en/about/` is built from `src/content/about/index.md` <br>The markdown files are parsed and rendered by `src/templates/static.ts`\* |
| `/src/content/developers/docs` | \*Markdown files in here use the Docs template: `src/templates/docs.ts` |
| `/src/content/developers/tutorials` | \*Markdown files in here use the Tutorial template: `src/templates/tutorial.ts` |
| `/src/data` | General data files importable by components |
| `/src/hooks` | Custom React hooks |
| `/src/intl` | Language translation JSON files |
| `/src/lambda` | Lambda function scripts for API calls |
| `/src/pages`<br>`/src/pages-conditional` | React components that function as standalone pages. <br>For example: `ethereum.org/en/wallets/find-wallet` is built from `src/pages/wallets/find-wallet.js` |
| `/src/pages`<br>`/src/pages-conditional` | React components that function as standalone pages. <br>For example: `ethereum.org/en/wallets/find-wallet` is built from `src/pages/wallets/find-wallet.ts` |
| `/src/scripts`<br>`/src/utils` | Custom utility scripts |
| `/src/styles` | Stores `layout.css` which contains root level css styling |
| `/src/templates` | JSX templates that define layouts of different regions of the site |
| `/src/theme.js` | Declares site color themes, breakpoints and other constants (try to utilize these colors first) |
| `/src/templates` | TSX templates that define layouts of different regions of the site |
| `/src/theme.ts` | Declares site color themes, breakpoints and other constants (try to utilize these colors first) |
1 change: 1 addition & 0 deletions gatsby-config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,7 @@ const config: GatsbyConfig = {
`gatsby-plugin-gatsby-cloud`,
// Creates `_redirects` & `_headers` build files for Netlify
`gatsby-plugin-netlify`,
// Enables codegen for graphql queries
{
resolve: `gatsby-plugin-graphql-codegen`,
options: {
Expand Down

0 comments on commit 012d7c7

Please sign in to comment.