Skip to main content
Maintainers -ImageDr. Fabrizio Finozzi, ImageAkshat Mittal

Editing the handbook

This is a controlled document

In line with Open Energy Transition regulatory obligations, changes to Controlled documents must be approved and merged by a code maintainer. All contributions are welcome and encouraged.

Introduction​

The handbook uses Docusaurus's documentation functionality as the foundation for its folder and content structure. You can learn more about Docusaurus at Docusaurus Docs.

  • Every folder must contain an index.mdx file. This file will be rendered as the homepage for that section of the handbook.
  • Refer to this template for the index page: Index Template.
  • Although Docusaurus supports both .md and .mdx file extensions, we recommend using .mdx to maintain uniformity across the project.
  • Maintainer tags should be present on every page. See all available team members here: Team. We use email as a unique identifier.
  • All pages must include the following metadata:
sidebar_position: 3.7
sidebar_label: "Contribution Guide"
  • The sidebar position is determined by the parent folder's index page. It should be a single digit for index pages and two digits for other pages in the same directory.
  • sidebar_label is the name that will appear in the sidebar and other navigation elements. It is best practice to keep it the same as the main heading on the page.
  • For best practices, folders should be named using camelCase. For example, the folder for this page should be named ContributionGuide.mdx.
  • Documents that fall under the controlled category should have the Controlled Document Banner present.
  • For implementing navigation, refer to Docusaurus Navigation.
  • Here is also a link to the template for non-index pages: Page Template.

Editing the handbook locally​

There are two possibilities to modify the Open Energy Transition (OET) Handbook. This section covers how to modify it locally. The README details how to install and fetch locally the necessary dependencies, generate the JSON for the handbook structure and run a local development server.

Open Energy Transition (internal) contributors​

If you belong to the Open Energy Transition team, you can contribute by following these steps:

  • Clone the repository.
  • Create a new branch for your feature or bug fix.
  • Make your changes and commit them.
  • Push your changes to your branch.
  • Open a pull request.

External contributors​

Open Energy Transition welcomes contributions also from the wider community. If you are external to Open Energy Transition, you can contribute as detailed below:

  • Fork the repository.
  • Create a new branch for your feature or bug fix.
  • Make your changes and commit them.
  • Push your changes to your branch.
  • Open a pull request to the upstream repository.

Editing the handbook with the Web IDE​

There are two possibilities to modify the Open Energy Transition (OET) Handbook. This section covers how to modify it by means of the Web IDE.

Editing existing pages​

Navigate to the handbook website and search for the page you would like to contribute to. In this example, the modifications are applied to the About the Handbook page.

img from static

Edit this page​

Navigate to the bottom of the page and click on Edit this page.

img from static

Start the edit​

Click on Edit this page.

img from static

Commit the changes​

Modify the page and then click on Commit changes.... The Propose changes window opens. Add a Commit message and an Extended description. Choose a branch name. Click then on Propose changes.

img from static

Open a pull request​

Insert a title under Add a title, that briefly summarises the proposed changes. Insert a description under Add a description and finally click on Create pull request.

img from static

Adding a new page​

Navigate to the handbook website and click on Github.

img from static

Create a new branch​

Click on the branches.

img from static

Click then on New Branch, give an appropriate name to the branch and click on Create new branch.

img from static

Open the Web IDE​

To open the Web IDE, copy the name of the branch you just created and paste it in the following url

https://github.dev/open-energy-transition/handbook/tree/<branch-name>

Place the url in your browser and navigate to the Web IDE. To create a new handbook page, select the folder docs in the EXPLORER and then click on the left button. To add a new folder, click instead on the button on the right.

img from static

Commit the changes​

Click on the Source Control button. Add a commit message and click on Commit & Push.

img from static

Open a pull request​

Click on Create pull request.

img from static

Insert a pull request title and click on Create.

img from static