How to Contribute to COLIB

contribution
quarto
qmd
template
guide
Author

COLIB Team

Welcome to the COLIB contribution guide! This page will help you understand how to contribute models and test cases to the COLIB library using our standardized templates and tools.

What is QMD format?

COLIB uses Quarto Markdown (QMD) format for all documentation pages. QMD is an extension of standard Markdown that allows you to:

  • Write scientific documentation with LaTeX math equations
  • Include executable code blocks
  • Create interactive plots and figures
  • Generate citations and references automatically
  • Produce high-quality HTML, PDF, and other output formats
QMD Benefits for Scientific Documentation:
  • Native support for mathematical equations using LaTeX syntax
  • Automatic cross-referencing of figures, tables, and equations
  • Bibliography management with BibTeX
  • Code execution and result embedding
  • Professional formatting and styling

Choosing Your Template

COLIB provides two main contribution templates depending on what you want to add:

Model Template

Use the Model Template when you want to contribute on:

  • Mathematical models of power system components
  • Control system descriptions
  • Algorithm implementations
  • Component behavior models

Download model template

Model template includes:
  • Context (mandatory)
  • Model use, assumptions, validity domain and limitations (mandatory)
  • Model description (mandatory)
  • Source code (optional)
  • Open source implementations (if any)
  • Table of references & license

Test Case Template

Use the Test Case Template when you want to contribute on:

  • Validation scenarios
  • Benchmark test systems
  • Simulation examples
  • Performance comparisons

Download test case template

Test case template includes:
  • Use case purpose​ and context (mandatory)
  • Network ​description (mandatory)
  • Static and Dynamic models​ description (mandatory)
  • Input Data (mandatory)
  • Scenarios (at least one mandatory)
  • Simulation parameters (optional)
  • Outputs (mandatory)
  • Open source implementations (if any)
  • Table of references & license

Existing page improvements

You can also contribute enhance the current COLIB content by:

  • Refining and enriching existing documentation quality
  • Supplementing current model or test case descriptions with missing details
  • Fixing inaccuracies, typos, or outdated information
  • Adding practical examples, clarifications, or better explanations
  • Updating references, citations, or technical specifications
  • Improving formatting, structure, or readability
  • And much more!
Steps for page improvement contributions:
  1. Browse and select the specific page you wish to enhance from the COLIB repository
  2. Document your improvements by creating a detailed GitHub issue explaining what changes you propose and why
  3. Provide your modifications either as an updated QMD file attachment or as specific textual changes in the issue
  4. Submit for review - your contribution will go through the same quality review process as new content submissions

Installing and Using Quarto

Installation

1. Install Quarto

Visit the official Quarto website and download the installer for your operating system:

  • Windows: Download the .msi installer
  • macOS: Download the .pkg installer
  • Linux: Use the appropriate package manager or download the .deb/.rpm package

2. Verify Installation

Open a terminal/command prompt and run:

quarto --version

3. Install a Text Editor (Recommended)

While you can edit QMD files with any text editor, we recommend:

  • VS Code with the Quarto extension
Note

You can install the Quarto extension from within the Extensions tab in VS Code, from the Extension Marketplace, the Open VSX Registry or directly from a VISX extension file.

  • RStudio (built-in Quarto support)

  • Jupyter Lab (built-in Quarto support)

Key QMD Syntax for COLIB

See Quarto Basics

Basic Quarto Workflow

1. Clone the repository

git clone https://github.com/CRESYM/Colib_Quarto.github.io.git
cd colib_quarto

2. Create Your Contribution

  1. Download the appropriate template (model or test case)
  2. Open the index.qmd file in your preferred editor

3. Edit Your Content

Replace the content of the index.qmd file with your own, following the guidelines in the template.

Tip

4. Preview Your Work

To see how your page will look, run in your terminal:

quarto preview index.qmd

This opens a live preview in your browser that updates as you edit.

5. Render Final Output

To generate the final HTML file:

quarto render index.qmd

Submission Process

  1. Open a new issue through GitHub before starting your contribution.(create an issue)
  2. Prepare your contribution using the appropriate template (model/ test case) available in the repository
  3. Test your QMD file by rendering it locally
  4. Submit via GitHub to the same issue you created
  5. Compress your QMD file and related resources into a .zip archive, as GitHub does not support .qmd uploads directly
  6. Review process - our team will review your contribution
  7. Publication - approved contributions are merged and published
Pro Tips for Contributors
  • Start with the template and modify incrementally
  • Preview frequently to catch formatting issues early
  • Use descriptive file names and organize your assets
  • Follow the existing naming conventions in COLIB
  • Include comprehensive references and citations

Thank you for contributing to COLIB and advancing open-source power system modeling!

Back to top