From 8bbc3caf3ebfe290b2c5912f37018fa164b46ca0 Mon Sep 17 00:00:00 2001 From: Addison <42930383+addisonschultz@users.noreply.github.com> Date: Mon, 9 Sep 2024 15:28:19 +0200 Subject: [PATCH] Update Readme & Contributing Guide (#2459) --- .github/CONTRIBUTING.md | 28 +++++++++++++++++++++------- README.md | 23 ++++++++++++++++------- 2 files changed, 37 insertions(+), 14 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f125c3500..a65357a23 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,6 +1,8 @@ # Welcome to GitBook's contributing guide! -Thank you for investing your time in contributing to GitBook. Any contribution you make will be reviewed by our team.In this guide, you'll learn the different ways you can contribute. +> _For help, support, feature requests, and product questions - head to our [GitHub Community](https://github.com/orgs/GitbookIO/discussions) ๐Ÿค–_ + +Thank you for investing your time in contributing to GitBook. Any contribution you make will be reviewed by our team. In this guide, you'll learn the different ways you can contribute. ## Types of Contributions @@ -45,13 +47,25 @@ Any contribution you make can be made to the code located in this repository. In - [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them. -##### GitHub Codespaces: - -- [Fork, edit, and preview](https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/creating-a-codespace) using [GitHub Codespaces](https://github.com/features/codespaces) without having to install and run the project locally. - #### 2. Create a working branch and start with your changes -After forking this repository, you'll want to [create a branch](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue) to work off of. After creating the branch, you can start making changes! +After forking this repository, you'll want to [create a branch](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue) to work off of. + +#### 3. Install dependencies and run the project locally + +GitBook uses [Bun](https://bun.sh/) to run the project. Make sure you're using the specified version of `node` before running any of the development commands to ensure a smooth development experience. + +You can easily do this by running the command `nvm use`. + +To start your local version of GitBook, run the command `bun dev`. + +#### 4. Preview your changes + +When running the development server, published GitBook sites can be rendered through your local version at `http://localhost:3000/`. + +For example, our published docs can be viewed using the local version by visiting `http://localhost:3000/docs.gitbook.com` after running the development server. + +You can visit any published GitBook site behind your development server. Please make sure your site is [published publicly](https://docs.gitbook.com/published-documentation/publish-your-content-as-a-docs-site) to ensure you can view the site correctly in your development version. ### Commit your update @@ -71,4 +85,4 @@ When you're finished with the changes, [create a pull request](https://docs.gith ### Your PR is merged -Congratulations ๐ŸŽ‰Thank you for your contribution! Once your PR is merged, your contributions will be publicly visible on the relevant repository. +Congratulations ๐ŸŽ‰ Thank you for your contribution! Once your PR is merged, your contributions will be publicly visible on the relevant repository. diff --git a/README.md b/README.md index bcb565c35..f3748de92 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@

Welcome to GitBook, the platform for managing technical knowledge for teams.

-

This repository contains the open-source code used to render GitBook's published content.

+

This repository contains the open source code used to render GitBook's published content.

GitBook Open Published Site @@ -46,19 +46,28 @@ To run a local version of this project, please follow these simple steps. git clone https://github.com/gitbookIO/gitbook.git ``` -2. Install the project's dependencies through Bun. +2. Ensure you are using the project's version of `node`. Running `nvm use` will change your local version to the correct one. + +3. Install the project's dependencies through Bun. ``` bun install ``` -3. Start your local development server. +4. Start your local development server. ``` bun dev ``` -Then open the space in your web browser, using http://localhost:3000// (example: http://localhost:3000/docs.gitbook.com). +5. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/`. + +examples: + +- http://localhost:3000/docs.gitbook.com +- http://localhost:3000/open-source.gitbook.io/midjourney + +Any published GitBook site can be accessed through your local development instance, and any updates you make to the codebase will be reflected in your browser. ### Other development commands @@ -71,7 +80,7 @@ All pull-requests will be tested against both visual and performances testing to ## Contributing -GitBook's rendering engine is fully open-source and built on top of [Next.js](https://nextjs.org/). Head to our [contributing guide](https://github.com/GitbookIO/gitbook/.github/CONTRIBUTING.md) to learn more about the workflow on adding your first Pull Request. +GitBook's rendering engine is fully open source and built on top of [Next.js](https://nextjs.org/). Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to learn more about the workflow on adding your first Pull Request. ### Types of contributions @@ -79,7 +88,7 @@ We encourage you to contribute to GitBook to help us build the best tool for doc #### Translations -The GitBook UI is rendered using a set of translation files found in [`src/intl/translations`](/src/intl/translations/). We welcome all additional translations for the UI. +The GitBook UI is rendered using a set of translation files found in [`packages/gitbook/src/intl/translations`](/packages/gitbook/src/intl/translations/). We welcome all additional translations for the UI. #### Bugs @@ -90,7 +99,7 @@ Encounter a bug or find an issue you'd like to fix? Helping us fix issues relate > [!WARNING] > While it is possible to self-host this project, we do not recommend this unless you are certain this option fits your need. > -> _Looking to add a specific feature in GitBook? Head to our [contributing guide](/.github/CONTRIBUTING.md) to get started._ +> _Looking to add a specific feature in GitBook? Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to get started._ > > Self-hosting this project puts the responsibility of maintaining and merging future updates on **you**. We cannot guarantee support, maintenance, or updates to forked and self-hosted instances of this project. >