How to contribute to the Colib project

Introduction

This guide demonstrates how to create rich, interactive content using Quarto. Quarto is a powerful publishing system that allows you to combine narrative text, executable code, equations, figures, tables, and citations into beautiful documents.

Each section below includes:

  • Code samples
  • Rendered results showing what the output looks like

Let’s explore the main features you’ll need for academic and technical writing.

Text Formatting and Markdown Basics

Basic Text Formatting

Here are the fundamental text formatting options:

*italic text*,
**bold text**,
***bold italic text***
~~strikethrough text~~
`inline code`
superscript^2^, subscript~2~

Rendered result:

  • italic text,
  • bold text,
  • bold italic text
  • strikethrough text
  • inline code
  • superscript2, subscript2

Headings and Structure

# Main Heading (Level 1)
## Section Heading (Level 2) 
### Subsection Heading (Level 3)
#### Sub-subsection Heading (Level 4)

Rendered result:

Main Heading (Level 1)

Section Heading (Level 2)

Subsection Heading (Level 3)

Sub-subsection Heading (Level 4)

Lists

Unordered Lists

* First item
  + Sub-item 1
  + Sub-item 2
    - Sub-sub-item
* Second item

Rendered result:

  • First item
    • Sub-item 1
    • Sub-item 2
      • Sub-sub-item
  • Second item

Ordered Lists

1. First numbered item
2. Second numbered item
   i. Sub-item with roman numerals
   ii. Another sub-item

Rendered result:

  1. First numbered item
  2. Second numbered item
    1. Sub-item with roman numerals
    2. Another sub-item

Mathematical Equations

Inline Math

You can include mathematical expressions inline using single dollar signs: \(E = mc^2\) and \(\alpha + \beta = \gamma\).

Display Equations

For larger equations, use double dollar signs:

\[ \frac{\partial^2 u}{\partial t^2} = c^2 \nabla^2 u \tag{1}\]

\[ P(X = k) = \frac{\lambda^k e^{-\lambda}}{k!} \tag{2}\]

Multi-line Equations

$$
\begin{align}
f(x) &= ax^2 + bx + c \\
f'(x) &= 2ax + b \\
f''(x) &= 2a
\end{align}
$$ {#eq-derivatives}

Rendered result: \[ \begin{align} f(x) &= ax^2 + bx + c \\ f'(x) &= 2ax + b \\ f''(x) &= 2a \end{align} \tag{3}\]

Figures and Images

Static Images

You can include static images using markdown syntax:

![Quarto Logo](../../assets/img/Logo_colib.svg){#fig-logo fig-alt="The Colib project logo" width="200px"}

Rendered result:

Cross-References

How Cross-References Work

Quarto automatically generates numbered cross-references for:

  • Equations: Use eq- prefix (e.g., #eq-wave)
  • Sections: Use sec- prefix (e.g., #sec-figures)
  • Figures: Use fig- prefix (e.g., #fig-logo)
  • Tables: Use tbl- prefix (e.g., #tbl-features)

Examples of Cross-References

  • Reference an equation: “Using the wave equation (Equation 1)…”
  • Reference a section: “Details are provided in Section 5…”
  • Reference a figure: “See Figure 1 for the Colib project logo…”
  • Reference a table: “The results in Table 1 indicate…”

Citations and References

Citation Syntax

Quarto uses BibTeX for managing references. Citations are created using @ followed by the citation key:

  • Author-date citation: @marrero2019 produces: Studies by Taylor (2010) show…
  • Parenthetical citation: [@marrero2019] produces: Previous research (Taylor 2010) indicates…

Adding References

References should be stored in a .bib file and specified in the YAML header:

bibliography: references.bib

Example Bibliography Entry

@article{example2024,
  title={An Example Article},
  author={Smith, John and Doe, Jane},
  journal={Journal of Examples},
  volume={42},
  number={1},
  pages={1--10},
  year={2024},
  publisher={Example Press}
}

Advanced Features

Callout Blocks

Quarto provides several types of callout blocks:

Note

This is a note callout. Use it for additional information.

Tip

This is a tip callout. Perfect for helpful suggestions.

Warning

This is a warning callout. Use for important caveats.

Important

This is an important callout. Use for critical information.

Code Blocks computation

Code blocks that use braces around the language name (e.g. ```{python}) are executable, and will be run by Quarto during render. Here is a simple example:

---
title: "matplotlib demo"
format:
  html:
    code-fold: true
jupyter: python3
---

For a demonstration of a line plot on a polar axis, see @fig-polar.

::: {#cell-fig-polar .cell execution_count=1}
``` {.python .cell-code}
import numpy as np
import matplotlib.pyplot as plt

r = np.arange(0, 2, 0.01)
theta = 2 * np.pi * r
fig, ax = plt.subplots(
  subplot_kw = {'projection': 'polar'} 
)
ax.plot(theta, r)
ax.set_rticks([0.5, 1, 1.5, 2])
ax.grid(True)
plt.show()
Figure 2: A line plot on a polar axis

:::

Tables

Markdown Tables

You can create tables using markdown syntax:

| Feature | Supported | Notes |
|---------|-----------|-------|
| Code execution | ✓ | Python, R, Julia |
| Math equations | ✓ | LaTeX syntax |
| Cross-references | ✓ | Figures, tables, sections |
| Citations | ✓ | BibTeX format |

Rendered result:

Table 1: Quarto features overview
Feature Supported Notes
Code execution ✓ Python, R, Julia
Math equations ✓ LaTeX syntax
Cross-references ✓ Figures, tables, sections
Citations ✓ BibTeX format

Tables from Code

Code sample:

#| label: tbl-data
#| tbl-cap: "Sample data analysis results"

import pandas as pd

# Create sample data
data = {
    'Method': ['Linear', 'Quadratic', 'Exponential', 'Logarithmic'],
    'R²': [0.65, 0.89, 0.94, 0.72],
    'RMSE': [2.3, 1.1, 0.8, 1.9],
    'Status': ['Fair', 'Good', 'Excellent', 'Good']
}

df = pd.DataFrame(data)
print(df.to_string(index=False))

Example output:

      Method   R²  RMSE    Status
      Linear 0.65   2.3      Fair
   Quadratic 0.89   1.1      Good
 Exponential 0.94   0.8 Excellent
 Logarithmic 0.72   1.9      Good

References

Taylor, Alan. 2010. “The Book with a Nice Title.” https://doi.org/10.1016/j.epsr.2020.112811.
Back to top