Skip to content

Commit ab9c8cd

Browse files
authored
Merge pull request #1 from graphql/source
sync with main repo
2 parents 24f7de4 + 83094b8 commit ab9c8cd

File tree

147 files changed

+4177
-2934
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

147 files changed

+4177
-2934
lines changed

.github/workflows/CI.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
name: CI
2+
on: pull_request
3+
4+
jobs:
5+
tests:
6+
runs-on: ubuntu-latest
7+
8+
steps:
9+
- uses: actions/checkout@v1
10+
- uses: actions/setup-node@v1
11+
12+
- run: yarn install
13+
14+
# Verify it compiles
15+
- run: yarn build
16+
17+
# Doesn't pass ATM
18+
# - run: yarn tsc --noEmit

CONTRIBUTING.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Contributing to graphql.org
2+
3+
> This repository is governed by the [GraphQL Code of Conduct](https://graphql.org/codeofconduct/). By contributing, you agree to abide by its terms.
4+
5+
Thanks for taking the time to contribute! The GraphQL community is great because of people like you 🎉
6+
7+
There are many ways to get involved. Follow this guide and feel free to [reach out if you have questions](#asking-questions).
8+
9+
## What's in this document
10+
11+
- [Development guide](#development-guide)
12+
- [Running the site locally](#running-the-site-locally)
13+
- [Branching](#branching)
14+
- [Project structure](#project-structure)
15+
- [Publishing the updated site](#publishing-the-updated-site)
16+
- [Updating content](#updating-content)
17+
- [Fix a typo, code sample bug, or formatting](#fix-a-typo-code-sample-bug-or-formatting)
18+
- [Add a library or tool to the Code page](#add-a-library-or-tool-to-the-code-page)
19+
- [Add a resource to the Community page](#add-a-resource-to-the-community-page)
20+
- [Add a question to the FAQ](#add-a-question-to-the-faq)
21+
- [Write a new section or guide](#write-a-new-section-or-guide)
22+
- [Making changes to the code](#making-changes-to-the-code)
23+
- [Contributing something else](#contributing-something-else)
24+
- [Asking questions](#asking-questions)
25+
26+
## Development guide
27+
28+
### Running the site locally
29+
30+
First, clone this repository and move into the directory:
31+
32+
```bash
33+
git clone https://github.com/graphql/graphql.github.io.git
34+
cd graphql.github.io
35+
```
36+
37+
Then, use [Yarn](https://yarnpkg.com/getting-started/install) to install and load all the necessary dependencies:
38+
39+
```bash
40+
yarn
41+
```
42+
43+
> Note: [Yarn is currently the only way to run the site locally](https://github.com/graphql/graphql.github.io/issues/946).
44+
45+
Run the `start` script to launch the server:
46+
47+
```bash
48+
yarn start
49+
```
50+
51+
Finally, open [http://localhost:8000](http://localhost:8000) to view it in the browser.
52+
53+
The GraphQL website is built with [Gatsby](https://www.gatsbyjs.com/docs/). This means that a hot-reloading development environment will be accessible by default.
54+
55+
### Branching
56+
57+
Active development for graphql.org happens on the `source` branch. Be sure to create any new branches or direct any pull requests back to `source`.
58+
59+
### Project structure
60+
61+
- `static`: Files that will be copied directly to `public`.
62+
- `public`: Output files that will be served by a static HTTP server.
63+
- `src`: Markdown and the TypeScript/JavaScript files used to generate the website.
64+
- `assets`: All the [`less`](http://lesscss.org/) files that contain stylesheets.
65+
- `components` and `Containers`: React components used for layouts and pages.
66+
- `content`: Markdown files with the content of pages.
67+
- `templates`: Layout templates.
68+
- `utils`: Helper functions.
69+
70+
### Publishing the updated site
71+
72+
Your changes will be merged into the `source` branch. Then, the CI will automatically publish a new version of http://graphql.org via [Netlify](https://docs.netlify.com/).
73+
74+
## Updating content
75+
76+
### Fix a typo, code sample bug, or formatting
77+
78+
If you notice something wrong in the text or code samples, please follow our [development guide](#development-guide) to [open a pull request](https://github.com/graphql/graphql.github.io/pulls) with your fix.
79+
80+
All of the content on graphql.org is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/).
81+
82+
### Add a library or tool to the Code page
83+
84+
The [Code page](https://graphql.org/code/) is a collection of libraries, tools, and services built for GraphQL.
85+
86+
To add your resource to this page, follow our [development guide](#development-guide) to [open a pull request](https://github.com/graphql/graphql.github.io/pulls).
87+
88+
The content for this page is located in [various directories under `src/content/code`](./src/). Everything is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/).
89+
90+
### Add a resource to the Community page
91+
92+
The [Community page](https://graphql.org/community/) highlights resources and groups that help people get more involved with GraphQL.
93+
94+
To add something to this page, follow our [development guide](#development-guide) to [open a pull request](https://github.com/graphql/graphql.github.io/pulls).
95+
96+
The content for this page is located in a [directory under `src/content/community`](./src/). Everything is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/).
97+
98+
### Add a question to the FAQ
99+
100+
Our [Frequently Asked Questions (FAQ) page](https://graphql.org/faq/) is designed to help answer questions from the community. This page is still in development, so if you think there's a question missing - please [open an issue](https://github.com/graphql/graphql.github.io/issues/new)! It'd be great if you could include both the question and a proposed answer outline in the issue description.
101+
102+
Once you have approval from a maintainer, use the [development guide](#development-guide) to add your question and answer. The content for the FAQ is located in [`src/content/faq`](./src/content/faq/). Each section has its own [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/) file.
103+
104+
> Note: All answers in this section should be vendor-neutral and accessible to GraphQL users of all levels.
105+
106+
When your answer is ready, [open a pull request](https://github.com/graphql/graphql.github.io/pulls/).
107+
108+
### Write a new section or guide
109+
110+
There are still several [Best Practices guides that no one has written](https://github.com/graphql/graphql.github.io/issues/41) yet. If you want to take one of these, comment on [the original issue](https://github.com/graphql/graphql.github.io/issues/41) and mention which topic you'll work on.
111+
112+
Then, use our [development guide](#development-guide) to determine where your new page best fits. Our documentation is written and formatted in [Markdown](https://www.gatsbyjs.com/docs/mdx/markdown-syntax/).
113+
114+
Once it's ready for review, please [open a pull request](https://github.com/graphql/graphql.github.io/pulls/).
115+
116+
## Making changes to the code
117+
118+
Before diving into any code updates, please [open an issue](https://github.com/graphql/graphql.github.io/issues/new) describing the change(s) you'd like to make.
119+
120+
If you're working off an [existing issue](https://github.com/graphql/graphql.github.io/issues/), follow our [development guide](#development-guide) to make your changes. Once it's ready for review, please [open a pull request](https://github.com/graphql/graphql.github.io/pulls/) and reference the original issue.
121+
122+
## Contributing something else
123+
124+
Interested in adding something not covered in this guide? Please [open an issue](https://github.com/graphql/graphql.github.io/issues/new) and tell us all about your idea.
125+
126+
## Asking questions
127+
128+
If you run into any problems or have questions while contributing, you're always welcome to [open an issue](https://github.com/graphql/graphql.github.io/issues/new).
129+
130+
You can also ping our team in the [#website channel on the GraphQL Slack](https://graphql.slack.com/messages/website/). [Get your invite here!](https://graphql-slack.herokuapp.com/)

README.md

Lines changed: 3 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,7 @@
11
# Source Repository for graphql.org
2-
This repository contains the source code of https://graphql.org website.
3-
4-
# Contributing
5-
6-
Organization gh-pages deploy the `master` branch, so active development occurs
7-
on this `source` branch.
8-
9-
### Making changes
10-
11-
The first time, get all the dependencies loaded via
12-
13-
`$ npm install` or `$ yarn install`
142

15-
Then, run the server via
16-
17-
`$ npm start` or `$ yarn start`
18-
19-
Open [http://localhost:8000](http://localhost:8000) to view it in the browser.
20-
Anytime you make some changes, refresh the page to see the updates.
21-
22-
### Folder structure
23-
24-
- `static` folder contains the files that will be copied directly to `public` folder which will contain the output files to be served by a static HTTP server.
25-
26-
- `src` folder contains markdown and TypeScript/JavaScript files used to generate the website;
27-
- - `assets` folder contains `less` files and those files contain stylesheets
28-
- - `components` and `Containers` folders contains React components that are used in layouts and pages
29-
- - `content` folder contains markdown files for the content of pages
30-
- - `templates` contains the layout templates
31-
- - `utils` contains helper functions
3+
This repository contains the source code of https://graphql.org website.
324

33-
### Publish the Website
5+
## Contributing
346

35-
Once pushed to the `source` branch, CI will publish http://graphql.org
7+
Check out our [contributing guide](./CONTRIBUTING.md) for detailed instructions for how to make changes to graphql.org 🎉

gatsby-config.js

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@ module.exports = {
1414
options: {
1515
name: "content",
1616
path: `${__dirname}/src/content`,
17-
include: ["**/*.md"], // ignore files starting with a dot
1817
},
1918
},
2019
`gatsby-transformer-remark`,

gatsby-node.js

Lines changed: 128 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,120 @@
11
const path = require("path")
2+
const sortLibs = require("./scripts/sort-libraries")
3+
const globby = require('globby');
4+
const frontmatterParser = require('parser-front-matter');
5+
const { readFile } = require("fs-extra");
6+
const { promisify } = require('util');
27

38
exports.onCreatePage = async ({ page, actions }) => {
49
const { createPage, deletePage } = actions
510
deletePage(page)
11+
let context = {
12+
...page.context,
13+
sourcePath: path.relative(__dirname, page.componentPath),
14+
}
15+
if (page.path === "/code" || page.path === "/code/") {
16+
const markdownFilePaths = await globby('src/content/code/**/*.md');
17+
const codeData = {}
18+
const slugMap = require('./src/content/code/slug-map.json');
19+
const parse$ = promisify(frontmatterParser.parse);
20+
await Promise.all(markdownFilePaths.map(async markdownFilePath => {
21+
22+
const markdownFileContent = await readFile(markdownFilePath, "utf-8")
23+
let {
24+
data: { name, description, url, github, npm, gem },
25+
content: howto,
26+
} = await parse$(markdownFileContent, undefined)
27+
howto = howto.trim();
28+
const pathArr = markdownFilePath.split("/")
29+
if (markdownFilePath.includes("language-support")) {
30+
const languageSupportDirIndex = pathArr.indexOf("language-support")
31+
const languageNameSlugIndex = languageSupportDirIndex + 1
32+
const languageNameSlug = pathArr[languageNameSlugIndex]
33+
const languageName = slugMap[languageNameSlug]
34+
codeData.Languages = codeData.Languages || {}
35+
codeData.Languages[languageName] =
36+
codeData.Languages[languageName] || {}
37+
38+
const categoryNameSlugIndex = languageSupportDirIndex + 2
39+
const categoryNameSlug = pathArr[categoryNameSlugIndex]
40+
const categoryName = slugMap[categoryNameSlug]
41+
codeData.Languages[languageName][categoryName] =
42+
codeData.Languages[languageName][categoryName] || []
43+
codeData.Languages[languageName][categoryName].push({
44+
name,
45+
description,
46+
howto,
47+
url,
48+
github,
49+
npm,
50+
gem,
51+
sourcePath: markdownFilePath,
52+
})
53+
} else {
54+
const codeDirIndex = pathArr.indexOf("code")
55+
const categoryNameSlugIndex = codeDirIndex + 1
56+
const categoryNameSlug = pathArr[categoryNameSlugIndex]
57+
const categoryName = slugMap[categoryNameSlug]
58+
codeData[categoryName] = codeData[categoryName] || []
59+
codeData[categoryName].push({
60+
name,
61+
description,
62+
howto,
63+
url,
64+
github,
65+
npm,
66+
gem,
67+
sourcePath: markdownFilePath,
68+
})
69+
}
70+
}))
71+
const languageList = []
72+
let sortedTools = []
73+
await Promise.all([
74+
Promise.all(
75+
Object.keys(codeData.Languages).map(async languageName => {
76+
const libraryCategoryMap = codeData.Languages[languageName]
77+
let languageTotalStars = 0
78+
await Promise.all(
79+
Object.keys(libraryCategoryMap).map(async libraryCategoryName => {
80+
const libraries = libraryCategoryMap[libraryCategoryName]
81+
const { sortedLibs, totalStars } = await sortLibs(libraries)
82+
libraryCategoryMap[libraryCategoryName] = sortedLibs
83+
languageTotalStars += totalStars || 0
84+
})
85+
)
86+
languageList.push({
87+
name: languageName,
88+
totalStars: languageTotalStars,
89+
categoryMap: libraryCategoryMap,
90+
})
91+
})
92+
),
93+
sortLibs(codeData.Tools).then(({ sortedLibs }) => {
94+
sortedTools = sortedLibs
95+
}),
96+
])
97+
98+
context = {
99+
...context,
100+
otherLibraries: {
101+
Services: codeData.Services,
102+
Tools: sortedTools,
103+
"More Stuff": codeData["More Stuff"],
104+
},
105+
languageList: languageList.sort((a, b) => {
106+
if (a.totalStars > b.totalStars) {
107+
return -1
108+
} else if (a.totalStars < b.totalStars) {
109+
return 1
110+
}
111+
return 0
112+
}),
113+
}
114+
}
6115
createPage({
7116
...page,
8-
context: {
9-
...page.context,
10-
sourcePath: path.relative(__dirname, page.componentPath),
11-
},
117+
context,
12118
})
13119
}
14120

@@ -64,7 +170,10 @@ exports.createPages = async ({ graphql, actions }) => {
64170
parent: { relativeDirectory, sourceInstanceName },
65171
} = node
66172

67-
if (sourceInstanceName !== "content") {
173+
if (
174+
sourceInstanceName !== "content" ||
175+
relativeDirectory.includes("code/")
176+
) {
68177
return
69178
}
70179

@@ -138,17 +247,24 @@ exports.createPages = async ({ graphql, actions }) => {
138247
throw new Error(`First page not found in ${folder}`)
139248
}
140249

141-
let categories = []
250+
let categoriesMap = {}
142251
let currentCategory = null
143252

144253
let page = firstPage
145254
let i = 0
146255
while (page && i++ < 1000) {
147256
const { frontmatter } = page
148-
const { category: definedCategory, next: definedNextPageUrl } = frontmatter
257+
const {
258+
category: definedCategory,
259+
next: definedNextPageUrl,
260+
} = frontmatter
149261
let category = definedCategory || folder
150262
if (!currentCategory || category !== currentCategory.name) {
151-
currentCategory && categories.push(currentCategory)
263+
if (currentCategory) {
264+
if (!(currentCategory.name in categoriesMap)) {
265+
categoriesMap[currentCategory.name] = currentCategory
266+
}
267+
}
152268
currentCategory = {
153269
name: category,
154270
links: [],
@@ -165,9 +281,11 @@ exports.createPages = async ({ graphql, actions }) => {
165281
}
166282
}
167283

168-
categories.push(currentCategory)
284+
if (!(currentCategory.name in categoriesMap)) {
285+
categoriesMap[currentCategory.name] = currentCategory
286+
}
169287

170-
sideBardata[folder] = categories
288+
sideBardata[folder] = Object.values(categoriesMap)
171289
})
172290
)
173291

0 commit comments

Comments
 (0)