Website & Documentation Development

The Resoto website and documentation are built with Docusaurus, a static-site generator. The source code lives in the someengineering/resoto.com repository on GitHub.

Contributions are made via pull requests to the GitHub repository. Changes can be authored via the GitHub web interface (easy) or in a local repository using your favorite git client (recommended).

note

If your changes modify non-Markdown files, it is strongly recommended to work on a local clone of the repository rather than within the GitHub web interface.

GitHub Web Interface

1. Click the "Edit this page" link at the bottom of a documentation page.

2. Make your changes in the GitHub web editor.

   tip

   For supported Markdown features, please refer to the Docusaurus documentation.

3. Select the "Create a new branch for this commit and start a pull request." option at the bottom of the page.

Local Git Repository

Prerequisites

• Git (the below instructions assume you are using the CLI, though GUI clients will also work!)
• Code editor (Visual Studio Code is recommended)
• Node.js
• Yarn

1. Clone the Repository

1. Fork the repository.

2. Create a local clone of the repository:

   git clone https://github.com/<your_github_username>/resoto.com.git

   This will create a directory named resoto.com in your current working directory.

3. Add a remote pointing to the upstream repository (as opposed to your fork) named upstream:

   git remote add upstream https://github.com/someengineering/resoto.com.git

4. Create a new branch from main (it is recommended to give your branch a meaningful, descriptive name):

   git checkout -b <branch_name> main

tip

If there are new commits to the main branch of the repository, you can update your branch by rebasing from your upstream remote:

git fetch upstream
git rebase upstream/main

2. Start the Development Server

Now, we are finally able to get to the fun stuff! 🥳

1. Install dependencies.

   yarn

2. Start a local development server:

   yarn start

   You will notice that http://localhost:3000 has been opened in your browser, where you can see your changes reflected live.

   note

   Older docs versions and some MDX plugins are disabled in development mode to improve performance.

   If you would like to test your changes with these enabled, you can run yarn build and then yarn serve to start a local server with the production build.

3. Test Your Changes

After you are done authoring your changes, you'll want to verify your changes will pass the required checks:

• Optimize SVG images with SVGO:

  yarn optimize

• Format your code with Prettier:

  yarn format

• Lint your code with ESLint:

  yarn lint

• Trigger a production build:

  yarn build

  This will create a build directory containing the static website. You can preview the build locally by running yarn serve.

  tip

  The build may take several minutes to complete. It is possible to perform a faster build with older docs versions and some MDX plugins disabled:

  yarn build:fast

4. Push Your Changes

Ready to submit your changes for review?

1. Commit them to your local repository:

   git commit

2. Push them to your fork:

   git push --set-upstream origin <branch_name>
   note

   To update your fork after a rebase, you may need to force push:

   git push -f origin <branch_name>

3. Submit your pull request on GitHub.

   You are welcome to open your pull request as a draft for early feedback and review.

   note

   Be sure to follow the pull request template!

   info

   Pull request titles should follow the Conventional Commits specification.

   However, do not worry too much about getting this right, as we will make any necessary adjustments prior to merging your changes.