From 4464c02b89e6d478b76f46afef08bd94141fd2ba Mon Sep 17 00:00:00 2001 From: Joe Date: Wed, 4 Jan 2023 11:24:37 +0000 Subject: [PATCH] update README and contributing page --- README.md | 67 ++++++++++--------- .../developers/geth-developer/contributing.md | 2 +- 2 files changed, 35 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 7043b9cc02..a3f4577f4c 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,44 @@ -## Geth website +## Welcome to the go-ethereum website! -This repo will act as a shared workspace for the geth website team in developing new content, designs etc +This is the repository for the `go-ethereum` website. All the website code is held here in the `website` branch. If you are looking for `go-ethereum` source code you need to switch to the `master` branch. -Resources: +The purpose of the go-ethereum website is to provide the necessary documentation and supporting information to help users to get up to speed with using go-ethereum (aka "Geth"). The website is maintained by a team of developers but community contributions are also very welcome. -- the project management notes: https://www.notion.so/efdn/Build-new-Geth-website-bf35a46cfe5848db83ac3acb5191eb1c -- some draft figma files for design sketching: https://www.figma.com/file/ekzIgwyeVKLtFSAcnA0Q0D/geth-website?node-id=6%3A31 -- content planning notes: https://www.notion.so/efdn/Content-Strategy-3252234338814a749374fa7f11049083 -- meeting notes: https://www.notion.so/efdn/Call-notes-46aa0202810a402ebfda07b046761cbd -Notes: -**Dev note**: Remember that the fiules in `vulnerabilities` must be served at the same URLs as they are currently to avoid breaking some Geth functions related to security auditing. +## Contributing ---- +Contributions from the community are very welcome. Please contribute by cloning the `go-ethereum` repository, checking out the `website` branch and raising pull requests to be reviewed and merged by the repository maintainers. Issues can be raised in the main `go-ethereum` repository using the prefix `[website]: ` in the title. -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). -## Getting Started +### The geth.ethereum.org stack -First, run the development server: +geth.ethereum.org is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). The following tools were used to build the site: + +- [Node.js](https://nodejs.org/) +- [Yarn package manager](https://yarnpkg.com/cli/install) +- [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 +- [Chakra UI](https://chakra-ui.com/) - A UI library (Migration in progress) +- [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.ts` +- [Netlify](https://www.netlify.com/) - DNS management and primary host for `master` build. + +### Repository structure + +The website code is organized with a top-level `docs` folder that contains all the documentation pages as markdown files. Inside `docs` are subdirectories used to divide the docs by theme (e.g. `getting-started`,`fundamentals`, `developers` etc). Website code is in `src`, and assets including images are in `public`. + + +### Adding a new documentation page + +Documentation pages are located in the `/docs` folder in the root directory of the project. The docs pages are all markdown files. When you want to add a new page, add the new file in the appropriate folder in the `/docs` page. `index.md` files will be the default page for a directory, and `{pagename}.md` will define subpages for a directory. + +After adding a page, you will also need to list it in `/src/data/documentation-links.yaml`. This file defines the documentation structure which you will see on the left sidebar in the documentation pages. + + +### Building locally + +To check a new page it is helpful to build the site locally and see how it behaves in the browser. First, run the development server: ```bash npm run dev @@ -35,25 +54,7 @@ You can start editing the page by modifying `pages/index.tsx`. The page auto-upd The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages. -## Learn More -To learn more about Next.js, take a look at the following resources: +### Review and merge -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! - -## Deploy on Vercel - -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. - -Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. - -## Adding a new documentation page - -Documentation pages are located in the `/docs` folder in the root directory of the project. - -When you want to add a new page, add the new file in the appropriate folder in the `/docs` page. `index.md` files will be the default page for a directory, and `{pagename}.md` will define subpages for a directory. - -After adding this page, you will need to add it `/src/data/documentation-links.yaml` which adds documentation structure which you will see on the left sidebar in the documentation pages. +PRs will be reviewed by the website maintainers and merged if they improve the website. For substantial changes it is best to reach out to the team by raising a GH issue for discussion first. \ No newline at end of file diff --git a/docs/developers/geth-developer/contributing.md b/docs/developers/geth-developer/contributing.md index 3034b0c870..4b88cb9da9 100644 --- a/docs/developers/geth-developer/contributing.md +++ b/docs/developers/geth-developer/contributing.md @@ -25,7 +25,7 @@ We encourage an early pull request approach, meaning pull requests are created a ## Contributing to the Geth website {#contributing-to-website} -The Geth website is hosted separately from Geth itself. The contribution guidelines are the same. Please check out the [website repository](https://github.com/ethereum/geth-website) and raise pull requests for the maintainers to review and merge. +The Geth website is hosted on a separate branch of `go-ethereum` from the source code. To contribute, please check out the website branch and raise pull requests for the maintainers to review and merge. Please note that new pages added to the site must also be added to `/src/data/documentation-links.yaml` in order for it to be included in the navigation sidebar. Additional contributioon guidelines are available in the website [README](https://github.com/ethereum/go-ethereum/tree/website#readme). ## License {#license}