From db304911472bc34914a6a51380677cd1a3fa5ac4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Quiroz?= Date: Wed, 4 Jan 2023 18:25:20 -0300 Subject: [PATCH 1/5] docs: README improvements PR to add a couple of suggested improvements for **Adding a new documentation page** section --- README.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index bc3d5014b9..d346908392 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,10 @@ This is the repository for the `go-ethereum` website. All the website code is he 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. - - ## 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. - ### The geth.ethereum.org stack 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: @@ -28,26 +25,33 @@ geth.ethereum.org is a [Next.js](https://nextjs.org/) project bootstrapped with 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. -Notes in documentation pages are highlighted in pale blue boxes. To add a note, wrap the note text in `` tage as follows: +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. + +#### Adding notes to a doc + +Notes in documentation pages are highlighted boxes (color depend on the current set dark/light theme). To add a note, wrap the note text in `` tage as follows: ```markdown text to include in note ``` +Screen Shot 2023-01-04 at 18 22 06 + +> Example Note from [Account Management with Clef +](https://geth.ethereum.org/docs/fundamentals/account-management) doc + +#### Images + Images should be saved to `public/images/docs` and included in the markdown as follows: ```markdown ![alt-text](/images/docs/image-title.png) ``` -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: @@ -64,4 +68,4 @@ You can start editing the page by modifying `pages/index.tsx`. The page auto-upd ### Review and merge -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 +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. From 5bf99f3c0650eafb43a29f8d740618287f3b68bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Quiroz?= Date: Wed, 4 Jan 2023 18:33:43 -0300 Subject: [PATCH 2/5] docs: add frontmatter metadata example --- README.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d346908392..8bfc986ac5 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 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. -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 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. ## Contributing @@ -29,7 +29,7 @@ The website code is organized with a top-level `docs` folder that contains all t 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. +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**. Take into account that if you update the `/docs` structure or remove a doc, you should also update this file to avoid navigation issues. #### Adding notes to a doc @@ -41,8 +41,7 @@ Notes in documentation pages are highlighted boxes (color depend on the current Screen Shot 2023-01-04 at 18 22 06 -> Example Note from [Account Management with Clef -](https://geth.ethereum.org/docs/fundamentals/account-management) doc +> Example Note from [Account Management with Clef](https://geth.ethereum.org/docs/fundamentals/account-management) doc. #### Images @@ -52,6 +51,19 @@ Images should be saved to `public/images/docs` and included in the markdown as f ![alt-text](/images/docs/image-title.png) ``` +#### Metadata + +`title` and `description` are **required** metadata props for a post: `title` will generate the main heading on the doc page and `description` is used for SEO purposes, to serve as a concise and appropiate description of the content. + +``` +--- +title: Go API +description: Introduction to the Go packages that allow Geth to be used in Go native applications. +--- +``` + +> Example of the metadata for a sample post. + ### 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: From e52b44a09e518747c867160cc3da2302ab623158 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Quiroz?= Date: Wed, 4 Jan 2023 18:38:42 -0300 Subject: [PATCH 3/5] docs: update frontmatter section title --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8bfc986ac5..99909aceaf 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ Images should be saved to `public/images/docs` and included in the markdown as f ![alt-text](/images/docs/image-title.png) ``` -#### Metadata +#### Frontmatter metadata `title` and `description` are **required** metadata props for a post: `title` will generate the main heading on the doc page and `description` is used for SEO purposes, to serve as a concise and appropiate description of the content. From cb1a4b655001d7d42356738208a0356f558547fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Quiroz?= Date: Thu, 5 Jan 2023 13:48:44 -0300 Subject: [PATCH 4/5] docs: add tutorials to README --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 99909aceaf..15bc5d2329 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,6 @@ Contributions from the community are very welcome. Please contribute by cloning 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) @@ -21,6 +20,11 @@ geth.ethereum.org is a [Next.js](https://nextjs.org/) project bootstrapped with - Primary implementation: `/src/components/Search/index.ts` - [Netlify](https://www.netlify.com/) - DNS management and primary host for `master` build. +#### Resources + +- Official [NextJS tutorial](https://nextjs.org/learn/foundations/about-nextjs) +- Recommended [free tutorial to learn ChakraUI](https://egghead.io/courses/build-a-modern-user-interface-with-chakra-ui-fac68106). + ### 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`. From 5dbd2e88ea885d2f4f62e7c2cd29bb22583470a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Quiroz?= Date: Thu, 5 Jan 2023 13:56:38 -0300 Subject: [PATCH 5/5] docs: update README --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 15bc5d2329..bcf23463b1 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,12 @@ geth.ethereum.org is a [Next.js](https://nextjs.org/) project bootstrapped with - Primary implementation: `/src/components/Search/index.ts` - [Netlify](https://www.netlify.com/) - DNS management and primary host for `master` build. -#### Resources +#### Learn more -- Official [NextJS tutorial](https://nextjs.org/learn/foundations/about-nextjs) +To learn more about the stack, take a look at the following resources: + +- [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. - Recommended [free tutorial to learn ChakraUI](https://egghead.io/courses/build-a-modern-user-interface-with-chakra-ui-fac68106). ### Repository structure