Skip to content
Doras.to

Contributing to the docs

Introduction

First off, thanks for considering contributing to the docs! We’re always looking for people to help improve the docs, whether that’s by fixing a typo, adding additional information, or writing a new article. We really appreciate it! We’ll just need to get a few things set up first!

Updating VS creating a new article

  • Updating an existing article
    • If you’re looking to update an existing article, the simplest solution would to click the ”Edit page” link at the bottom of the article. It’s available on every page of the docs. This will take you to the GitHub repository where the docs are stored. You can then make your changes and submit a pull request, in which we’ll review your changes and merge them into the docs once approved. We may ask you to make some changes before we merge your pull request!
  • Creating a new article
    • If you’re looking to create a new article, you’ll need to follow the steps below to get a firm understanding.

Creating a new article

What you’ll need

  • A GitHub account
  • A basic understanding of markdown
  • Some development tools (optional)

Development tools

Download the following software:

NOTE: You may need to restart your computer after installing these tools.

Getting started

  1. Head over to GitHub and fork the docs repository. There’s a button to do this in the top right of the repository. This will create a copy of the docs repository in your own GitHub account. You can call it whatever you want!
  2. Once you’ve created the fork head over to your forked repo (https://github.com/YOURUSERNAME/docs most likely), and you can clone your forked repository to your computer. The easiest way to do this would be using GitHub Desktop, but you can also use the command line if you prefer.
  3. Once you’ve cloned it, open the repo in your code editor of choice. We use Visual Studio Code, but you can use any code editor you like.
  4. Open a terminal in your code editor and run the following commands:
Terminal window
pnpm install

This will install all the dependencies required to build the docs.

Terminal window
pnpm run dev

This will start a development server, which will allow you to preview the docs. You can access this by going to http://localhost:4321 in your browser.

File structure

The docs are built as simply as possible. All the articles are stored in src/content/docs. Each article is a markdown file, with the extension .mdx. The file name is the URL of the article. For example, if you create a file called my-new-article.mdx in the getting-started folder, the URL will be https://docs.doras.to/getting-started/my-new-article. A markdown file must be placed in the docs folder, but you can create sub-folders to sort your articles into categories. For example, you could create a folder called getting-started and place all your getting started articles in there.

Creating a new article

I’ve created a template that you can copy/paste to get started, just be sure to move it to the correct folder for the category, and change the file name to the name of your article. You can find the template in /content/docs/TEMPLATE.mdx. Copy/paste this file, and move it to the correct folder.

For example, if you’re creating a new article in the getting-started category, you’d move your copied file to /content/docs/getting-started and rename it to getting-started.mdx.

Formatting your article

We use Astro Starlight to build the docs, so you can use any of the components that Astro Starlight provides. You can find a list of components here. Another great resource would be the Authoring Content guide on the Astro Starlight website to help you with your formatting.

Adding your article to the sidebar

We will manage this for you should it not be automatically generated, so no need for concern here.

Submitting your changes

Once you’ve finished writing your article, you can submit your changes by creating a pull request. If you’re using GitHub Desktop, you can do this by clicking the ”Create Pull Request” button in the top right of the GitHub Desktop app after you’ve commited your changes.

Call your pull request whatever you want, and give a brief description of what you’ve changed. Once you’ve done that, click ”Create Pull Request” and you’re done! We’ll review your changes and merge them into the docs once approved. We may ask you to make some changes before we merge your pull request if we feel it’s necessary.

Don’t feel obligated or pressured to make it perfect, we’ll help you out if you need it, just let us know in the pull request comments and we’ll be more than happy to help! We really appreciate any help you can give us, no matter how small! Even submitting a pull request with some problems included is a huge help, as it gives us a starting point to work from!