Repository Conventions¶

This document defines the standard conventions for writing and organizing Markdown content in this repository.

File Naming¶

File names must be written in lowercase.
Use dash (-) to separate words.
Exclude common or filler words such as a, the, is, etc.
File names should directly reflect the content title.
Examples:
- Title: The Future of Quantum Security → future-of-quantum-security.md
- Title: OAI RAN Deployment → oai-ran.md

Directory Structure¶

Each main section (e.g., ai-ml, pqc, ebpf, tutorials) has:
- Its own index.md with a toctree directive
- An images/ directory for images used in that section
Each subsection has:
- Its own subdirectory
- Its own index.md
- Images in the parent images/ directory under a subdirectory
Do not mix images across sections or subsections.
If content belongs to a series or category, place it under a dedicated subdirectory.

Example Structure¶

section-name/
├── index.md
├── file-1.md
├── file-2.md
├── images/
│   ├── image-1.png
│   └── image-2.png
└── subsection/
    ├── index.md
    ├── file-1.md
    └── images/
        └── image-1.png

Metadata Format¶

Every Markdown file should include standardized metadata at the top:

# Document Title

**Author:** [Author Name](https://linkedin.com/in/username/)

**Published:** Month Day, Year

Brief introduction or description of the content.

For multiple authors:

**Author:** [Name 1](link), [Name 2](link) & [Name 3](link)

Repository Links¶

When referencing code repositories, implementation guides, or related projects, include them in a note block at the beginning of the document:

> **Note:**
> Follow this repository ([github/username/repo-name](https://github.com/username/repo-name)) for implementation details.

Tutorials¶

Replica Note Block¶

When a tutorial document is based on or mirrors a GitHub repository README, include the following note block immediately after the metadata header (title, author, published date, and intro paragraph):

> **Note:** This documentation is a replica of the README available at the [github/username/repo-name](https://github.com/username/repo-name). Please refer to the original repository for the most up-to-date information.

Example:

> **Note:** This documentation is a replica of the README available at the [github/ngkore/OAI-RAN](https://github.com/ngkore/OAI-RAN). Please refer to the original repository for the most up-to-date information.

Formatting and Style¶

General Guidelines¶

Use Prettier for consistent Markdown formatting.
Avoid unnecessary emoji or icons.
Keep language concise and technical.
Use code blocks for directory structures, code samples, or examples.
Do not use bold styling for headings.
Do not use em dash (—).

Header Hierarchy¶

Headers must follow consecutive levels - no jumps allowed:

Correct:

# Main Title (H1)

## Section (H2)

### Subsection (H3)

#### Detail (H4)

Incorrect:

# Main Title (H1)

### Subsection (H3) ← Skipped H2, will cause Sphinx warning

Rules:

# (H1) for document title - use once at the top
## (H2) for main sections
### (H3) for subsections
#### (H4) for detailed points
Never jump levels (H2 to H4 or H1 to H3)

Code Blocks¶

Use appropriate language identifiers for syntax highlighting:

```python
# Python code
```

```javascript
// JavaScript code
```

```yaml
# YAML configuration
```

```json
# JSON data
```

```groovy
// Gradle build files
```

```bash
# Shell commands/scripts
```

```console
# Terminal output with commands
```

```diff
# Patch/diff files
```

```c
# C code
```

```cpp
// C++ code
```

Important distinctions:

Use console for terminal output that includes commands and their output
Use bash for shell scripts or commands only
Use groovy for Gradle build files (not gradle)
Use diff for patch files (not patch)

Examples:

Terminal output:

ubuntu@server:~$ kubectl get pods
NAME                      READY   STATUS    RESTARTS   AGE
nginx-6d4cf56db6-xyz      1/1     Running   0          2d

Shell script:

#!/bin/bash
make clean
make all

Configuration file:

apiVersion: v1
kind: Pod
metadata:
  name: nginx

Horizontal Lines¶

Do not use horizontal lines (---) in Markdown files. They can cause rendering issues in Sphinx documentation.

Incorrect:

## Section 1

---

## Section 2

Correct:

## Section 1

Content here.

## Section 2

Git Commits and Sign-off¶

All commits must include a Developer Certificate of Origin (DCO) sign-off to certify that you have the right to submit the code under the project’s license.

Adding Sign-off¶

Add the -s or --signoff flag when creating commits:

git commit -s -m "Add new feature"

This automatically adds a Signed-off-by line with your name and email:

Signed-off-by: Your Name <[email protected]>

Commit Message Format¶

Use clear, descriptive commit messages
Start with a verb in imperative mood (add, fix, update, remove)
Keep the subject line under 72 characters
Add details in the commit body if needed