Contributing#

Check if there are issues related to your contribution, or post a new issue to discuss improvement to the documentation.

GitHub issues
Fork this repository

Otherwise you will need to first fork this repository, then send a pull request when your changes have been pushed.

Direct change if permission

If you are part of the MaastrichtU-IDS organization on GitHub you can directly create a new branch to make your change in the main repository.

⚡ Quick edit on GitHub#

You can really easily make quick changes directly on the GitHub website by clicking the Edit this page button at the bottom left of each documentation page. Or browsing to your forked repository.

For example to edit the introduction page you can go to https://github.com/MaastrichtU-IDS/d2s-docs/edit/master/website/docs/introduction.md

🏗️ Larger changes locally#

To edit the documentation it is easier to clone the repository on your laptop, and use a user-friendly markdown editor.

Use a Markdown editor

We strongly recommend you to use a markdown editor, such as Typora. It makes writing documentation much faster, and more enjoyable.

  1. Clone the repository on your machine:
git clone https://github.com/MaastrichtU-IDS/d2s-docs.git
cd d2s-docs
  1. Create a new branch from the master branch 🕊️
git checkout -b my-branch

  1. Add your changes in this branch ✒️

  2. Start the website on http://localhost:3000 to test it:

cd website
yarn install
yarn start
Send a pull request

Send a pull request to the master branch when your changes are done

Development documentation

Read more about running the API in development at https://github.com/MaastrichtU-IDS/d2s-docs#run-for-development

🔄 Automated deployment#

The documentation website is automatically updated and redeployed at each change to the main branch using a GitHub Actions workflow.

Publish to GitHub Pages

📝 Help#

Most pages of this website are written in Markdown, hence they are really easy to edit, especially when you are using a convenient markdown editor. Only the index.js page is written in React JavaScript.

🔎 Files locations#

  • Main DSRI documentation markdown files in website/docs
    • Left docs menu defined in website/sidebars.json
  • Blog articles as markdown files in website/docs
  • Index and contribute pages in website/src/pages
  • Images in website/src/static/img
  • Website configuration file in website/docusaurus.config.js
Blog specificities

Blog articles files name needs to include the date at the beginning, e.g. 2020-12-31-my-article.md

And the text can be truncated to use the first part as description for the article on the main blog page using <!--truncate-->

🦄 Markdown tip#

Colorful boxes

Use the following tags to create colorful boxes in markdown files:

:::note You can specify an optional title
Grey box
:::
:::tip Green box
The content and title *can* include markdown.
:::
:::info Blue box
Useful information.
:::
:::caution Be careful!
Yellow box
:::
:::danger Fire red box
Danger danger, mayday!
:::

✔️ Pull Request process#

  1. Before sending a pull request make sure the DSRI documentation website still work as expected with the new changes properly integrated:
cd website
yarn install
yarn start
  1. Send a pull request to the master branch.
  2. Project contributors will review your change as soon as they can!