Skip to content
This repository was archived by the owner on Dec 10, 2024. It is now read-only.

Commit 55e0288

Browse files
jonnysmilliejonnysmillie
committed
update readme with more details
1 parent 16e1912 commit 55e0288

File tree

1 file changed

+219
-8
lines changed

1 file changed

+219
-8
lines changed

‎README.md

Lines changed: 219 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,229 @@
1-
# Haskell Foundation
1+
# Haskell Foundation website
22

3-
# Gatsby based website
3+
## Based on the IOHK Gatsby Starter
4+
5+
If you use VisualStudio Code then it's recommended that you download the [code tour](https://github.com/vsls-contrib/code-tour) extension to make use of the guided tours of the codebase. Otherwise the documentation below should be sufficient. The tours will be setup on `npm install`.
6+
7+
## Features
8+
9+
* Localization
10+
* [Client side routing](#client-side-routing)
11+
* Theming - multiple themes
12+
* Netlify CMS
13+
* Material UI
14+
* Styled components
15+
* Configured for Netlify hosting, compatible with other hosting options
16+
* Fully configurable
17+
18+
## Scripts
19+
20+
* `npm run build` - runs a full static build
21+
* `npm run build:netlify` - webpack build of Netlify CMS bundle in `netlify/index.js`
22+
* `npm run build:netlify-prod` - production build of Netlify CMS bundle
23+
* `npm run build:netlify-toml` - builds the `netlify.toml` configuration, generating config as well as combining with `.netlify.toml`
24+
* `npm run ci` - CI task to perform for building, will run linter as well
25+
* `npm run clean` - `gatsby clean`, the same as running `./node_modules/.bin/gatsby clean`
26+
* `npm run create-pages` - custom script to create pages see [creating pages](#creating-pages)
27+
* `npm run delete-pages` - custom script to delete pages see [deleting pages](#deleting-pages)
28+
* `npm run develop` - `gatsby develop`, the same as running `./node_modules/.bin/gatsby develop`
29+
* `npm run lint` - runs eslint on all `.js` files
30+
* `npm run lint:changed` - used by git hook on pre-commit to detect bad code changes which fail linting
31+
* `npm start` - proxy to `npm run develop`
32+
* `npm run serve` - serves the static build in public and replicates server hosting on Netlify
33+
* `npm run watch:netlify` - watches the Netlify folder and regenerates the Netlify bundle, useful for development on Netlify CMS configuration
34+
35+
## Configuration
36+
37+
The starter can be configured through the `package.json` file under the `gatsby-starter-iohk-default` key. All configuration is safe to delete. The configuration shipped with the starter is the default configuration that is used for missing configuration.
38+
39+
| Option | Notes |
40+
| ------ | ----- |
41+
| availableLanguages | Array of languages available on the site, used to build localized pages and content. |
42+
| availableLanguages[].key | Language key, e.g. `en`, `en-us`, `fr`, `ja`, `zh-cn` etc. Corresponds with resource naming and URL construction. |
43+
| availableLanguages[].label | Label for the language e.g. `English`, `English (US)`, `Français`, `日本語`, `简体中文`. |
44+
| availableLanguages[].flag | Optional emoji flag for the language e.g. 🇺🇸, 🇫🇷, 🇯🇵, 🇨🇳 |
45+
| availableLanguages[].locale | Locale for the language e.g. `en_US`, `fr_FR`, `zh_CN` etc. |
46+
| alternativeLanguages | Array of alternative languages which resolve to an available language. |
47+
| alternativeLanguages[].key | The language of the alternative language e.g. `en-gb`, `fr-fr` etc. |
48+
| alternativeLanguages[].languageKey | The language to resolve to from availableLanguages e.g. `en`, `fr` |
49+
| themes | List of themes, used in `src/themes.js` to resolve themes from [@input-output-hk/front-end-themes](https://npmjs.com/package/@input-output-hk/front-end-themes) by default and consumed by [@input-output-hk/front-end-core-components/components/Theme](https://github.com/input-output-hk/front-end-core-components/blob/master/docs/components/Theme.md). Behaviour can be changes in `src/themes.js` and `src/App.js`. |
50+
| ga | Google Analytics. |
51+
| ga.trackingID | Tracking ID for GA property. Setup on [@input-output-hk/front-end-core-libraries analytics](https://github.com/input-output-hk/front-end-core-libraries/blob/master/docs/libraries/analytics.md). Analytics setup in `gatsby-browser.js`. |
52+
| localization | Localization related configuration. |
53+
| localization.createLocalizedPages | Boolean, whether to create localized pages or not on build. |
54+
| localization.ignore | List of pages to ignore on build when creating localized pages |
55+
| localization.createDefaultPages | Boolean, should default pages be created? For example the first language in `availableLanguages` being `en` - `/en/` and `/` will be created for the index page when createDefaultPages is true. |
56+
| localization.useURL | Boolean, use the URL to store and read localization state? Used in `src/App.js` passed to [@input-output-hk/front-end-core-components/components/Language](https://github.com/input-output-hk/front-end-core-components/blob/master/docs/components/Language.md). |
57+
| localization.useNavigator | Boolean, use the users OS language? Used in `src/App.js` passed to [@input-output-hk/front-end-core-components/components/Language](https://github.com/input-output-hk/front-end-core-components/blob/master/docs/components/Language.md). |
58+
| localization.persistLang | Boolean, persist the language to local storage? Used in `src/App.js` passed to [@input-output-hk/front-end-core-components/components/Language](https://github.com/input-output-hk/front-end-core-components/blob/master/docs/components/Language.md). |
59+
| routes | Array, list of client only routes handled by [@reach/router](https://www.npmjs.com/package/@reach/router). Netlify and Gatsby are automatically configured based on this configuration. |
60+
| routes[].path | String, the path used by [@reach/router](https://reach.tech/router/tutorial/05-url-parameters). |
61+
| routes[].component | String, the relative path to the component used to render the route from `src/routes/` minus the `.js` extension. For example `MyRoute` would resolve to `src/routes/MyRoute.js`. |
62+
63+
## Environment variables
64+
65+
* `UPLOADCARE_PUBLIC_KEY` - Required for Netlify CMS to interface with Uploadcare. If you don't want to use Uploadcare then you can edit the Netlify configuration in `netlify/index.js` to use something else or static files instead.
66+
* `NODE_ENV` - Handled by default, set to `production` on `npm run build:netlify-prod` to configure Netlify CMS correctly on production/development environments. Limited testing can be carried out on Netlify CMS locally.
67+
* `HEAD` - Taken from Netlify's build environment. `HEAD` points to the branch currently being built. Will integrate seamlessly with Netlify's hosting, but should you wish to host elsewhere then you will need to setup the `HEAD` environment variable in your choice of CI.
68+
* `GATSBY_IOHK_STARTER_CONFIG` - Handled automatically, populated from the site configuration in `package.json`.
69+
* `GATSBY_URL` - The URL the site is being served on. Resolved via Netlify's environment variables and `NODE_ENV`. It can also take a value from `static/CNAME`. For logic see `node/gatsby/onPreInit.js`. Explicitly setting this value will bypass any logic to resolve the value.
70+
* `CONTEXT` - From Netlify's build environment. Used when resolving `GATSBY_URL`. When a Netlify build is detected the `GATSBY_URL` value is taken from `DEPLOY_URL`, also a Netlify environment variable.
71+
72+
## Templates
73+
74+
By default there is one template `src/templates/Main.js`. This will be the default template used by `src/components/Layout.js`. It is possible to create additional templates in `src/templates/` then utilize them in the existing `src/components/Layout.js` Layout.
75+
76+
For example a new template `src/templates/Blog.js`
77+
78+
```JavaScript
79+
import React from 'react'
80+
import PropTypes from 'prop-types'
81+
82+
const Blog = ({ children }) => (
83+
<div>
84+
<p>Blog template</p>
85+
...
86+
<div>
87+
{children}
88+
</div>
89+
</div>
90+
)
91+
92+
Blog.propTypes = {
93+
children: PropTypes.node.isRequired
94+
}
95+
96+
export default Blog
497

5-
### Install
698
```
7-
npm i
99+
100+
Then utilizing this template in a new page `src/pages/blog.js`.
101+
102+
```JavaScript
103+
import React from 'react'
104+
import Box from '@material-ui/core/Box'
105+
import Container from '@material-ui/core/Container'
106+
import Grid from '@material-ui/core/Grid'
107+
import Layout from '../components/Layout'
108+
import Blog from '../templates/Blog'
109+
import BlogPageQuery from '../queries/BlogPageQuery'
110+
111+
export default () => (
112+
<BlogPageQuery
113+
render={(content) => (
114+
<Layout template={Blog}>
115+
<Container maxWidth='lg'>
116+
<Box marginTop={6} marginBottom={10}>
117+
<Grid container spacing={2}>
118+
<Grid item xs={12}>
119+
<p>{content.default_content}</p>
120+
</Grid>
121+
</Grid>
122+
</Box>
123+
</Container>
124+
</Layout>
125+
)}
126+
/>
127+
)
128+
8129
```
9130

10-
### Run
131+
## Creating pages
132+
133+
Creating pages with localized content and Netlify CMS configuration can be a chore, there's several files to create with boilerplate style code. In order to make it a bit simpler there is a script to allow you to create pages:
134+
135+
```bash
136+
npm run create-pages -- /about/ /contact-us/ /projects/ /projects/project-a/ projects/project-a/additional-information/
11137
```
12-
npm start
138+
139+
The script accepts any amount of arguments with each argument treated as a path for the new page. The script is safe to run for pages that have already been created, it will not overwrite any existing files. The above command will create boilerplate content for each available language, a static query inside `src/queries/`, a page file inside `src/pages/` mapped to the path, a netlify collection in `netlify/collections/pages/` as well as updating the `netlify/collections/pages/index.js`, the relevant markdown files in `resources/content/pages/` and meta data markdown files in `resources/content/meta/` - for each page. The only thing left to do is write the code and map the content as required.
140+
141+
## Deleting pages
142+
143+
Deleting pages is just as easy as creating pages with the `npm run delete-pages` script. It will undo the work done in `npm run create-pages`. It accepts the same arguments as well:
144+
145+
```bash
146+
npm run delete-pages -- /about/ /contact-us/ /projects/ /projects/project-a/ projects/project-a/additional-information/
13147
```
14148

15-
### Build
149+
## Global content
150+
151+
For content that isn't restricted to a single page, for example footer, header and navigation content there is a global content system in place. If you have a large site or large amount of global content then it may make sense to break up the content into multiple static queries for performance benefits.
152+
153+
The global content is located in `resources/content/global/` with a file for each language. The content is retrieved through the `GlobalContentQuery` in `src/queries/GlobalContentQuery.js` file.
154+
155+
There is a Netlify CMS collection for the global content within `netlify/collections/globalContent.js`.
156+
157+
## Meta data
158+
159+
Pages can optionally have a corresponding meta data content file for each language inside `resources/content/meta/`. When using the `npm run create-pages` script meta files for each language will be created. The naming convention is as follows (assuming a language of `en`):
160+
161+
* `/` -> `resources/content/meta/index-en.md`
162+
* `/about/` -> `resources/content/meta/about-en.md`
163+
* `/projects/project-a/additional-information/` -> `resources/content/meta/projects___project-a___additional-information-en.md`
164+
165+
The `/` is replaced with `___` except for the trailing and leading `/`.
166+
167+
The meta data is consumed inside the `Layout` component in `src/components/Layout/` and is forwarded to [@input-output-hk/front-end-core-components Head](https://github.com/input-output-hk/front-end-core-components/blob/master/docs/components/Head.md) using [react-helmet-async](https://npmjs.com/package/react-helmet-async).
168+
169+
## Netlify
170+
171+
To setup with Netlify hosting simply link your repository to Netlify creating a new site and set the build command to `npm run ci` and the publish directory to `public/`. The `ci` script will run linting as well as building the site and can be extended to run tests etc. should you wish to add automated testing.
172+
173+
To access the CMS go to `/admin/` and you will be redirected to the login/CMS page depending on your Netlify configuration.
174+
175+
## Uploadcare
176+
177+
The starter has integration with [Uploadcare](https://uploadcare.com/), but can be used without Uploadcare. To use Netlify CMS without Uploadcare edit the `netlify/index.js` config to replace the Uploadcare config with something else. For example choosing to host images locally:
178+
179+
```JavaScript
180+
import backend from './backend'
181+
import collections from './collections'
182+
import { getBranch } from './helpers'
183+
184+
const init = window.initCMS
185+
const config = {
186+
load_config_file: false,
187+
backend,
188+
public_folder: '/images/uploads',
189+
logo_url: 'https://ucarecdn.com/0a28215f-a3f0-40e2-ac7e-d7dc93288d16/-/resize/150/-/progressive/yes/',
190+
show_preview_links: true,
191+
collections
192+
}
193+
194+
if (getBranch() === 'staging') config.publish_mode = 'editorial_workflow'
195+
196+
console.log('CMS config', config)
197+
198+
init({ config })
199+
200+
```
201+
202+
Uploaded images in Netlify will be stored at `static/images/uploads`.
203+
204+
## Client side routing
205+
206+
Optionally you can implement client side routing through the configuration on `routes`. This will enable client only routes for your application. For example you have thousands of data points which change often and dynamically, you may want to create a client side route as it could perform better than SSR. The main issue with client only routes on statically generated sites is letting the server know the client handles specific "glob" paths. This is taken care of for Netlify hosting, the `netlify.toml` file is generated on build using the `routes` configuration as well as the static `.netlify.toml` file for custom Netlify toml configuration.
207+
208+
When a client side route is requested the server will rewrite the URL to the "static" part of the path, for example `/my-data/:id/` would have a rewrite to `/my-data/` with a corresponding static file which uses the `src/routes/Fallback.js` component. The `Fallback` component determines whether or not the URL matches the path of the client side route and displays the 404 page when the route does not match. Of course the drawback here is the server responds with a 200 status regardless of whether or not there is any content present, there's no way of getting around this.
209+
210+
Using the above example for `/my-data/:id/` the expected build output would be to create a static file under `public/my-data/index.html` using the `Fallback` component. In `netlify.toml` we'd expect to see something like this: (note each available language is supported when configured to do so)
211+
16212
```
17-
npm run build
213+
[[redirects]]
214+
from = "/my-data/*"
215+
to = "/my-data/index.html"
216+
status = 200
217+
218+
[[redirects]]
219+
from = "/en/my-data/*"
220+
to = "/en/my-data/index.html"
221+
status = 200
18222
```
223+
224+
This means when navigating to:
225+
226+
* `/my-data/` you will be served with the `Fallback` component rendering a 404 page with a 200 status code. Client side routing will not match the route and only the 404 page will be visible.
227+
* `/my-data/123/` you will be served with the `Fallback` component rendering nothing, at which point client side routing will render the corresponding component for the route and the `:id` parameter can be handled there.
228+
229+
Server behaviour cannot be easily tested through `gatsby serve` or `gatsby develop`, there is a script `npm run serve` which will spin up an [express](https://www.npmjs.com/package/express) server which will replicate the hosting configuration on Netlify to assist with testing server behaviour locally.

0 commit comments

Comments
 (0)