Contributing¶

Contributions are always welcome.

Guidelines¶

• Add resources to the appropriate markdown files in docs/en/ directory.
• Use the table format: | [Name](https://example.com) | Short description. |
• Keep descriptions concise and factual.
• Ensure links work and lead to legitimate resources.
• Use clean URLs without trailing slashes for homepages: https://example.com not https://example.com/
• Add new sections only when necessary.

Pull Requests¶

• Keep PR focused: one primary logical change per PR.
• Use a clear title, for example: Add Terraform to infrastructure tools.
• Test your changes locally if possible using just dev.

Content Organization¶

• Main content is in docs/en/ directory
• Website is built from these markdown files
• README.md serves as a landing page directing to the website
• Changes to docs/en/ automatically update the website

Issues¶

• Use issues to report broken links, errors, or suggestions.
• Provide a short and clear description.

Development Setup¶

Local setup is only required if you want to preview the site or work on larger changes.

Prerequisites¶

• Install uv (Python package manager):

curl -LsSf https://astral.sh/uv/install.sh | sh

• Install lychee (Link checker)

cargo install lychee

Note: You need to install cargo before: curl https://sh.rustup.rs -sSf | sh Or read the guidelines.

Setup¶

1. Fork and clone the repository:

git clone https://github.com/YOUR_USERNAME/awesome-cloud-computing.git && cd awesome-cloud-computing

2. Setup Python environment (Python 3.13):

Option A - Automatic (Recommended):

uv sync --extra dev

Option B - Manual virtual environment:

uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

3. Start development server:

uv run mkdocs serve

The site will be available at http://127.0.0.1:8000

Optional: Install justfile for easier commands¶

If you want to use the task runner for convenience:

# On macOS: brew install just
# On Linux: cargo install just
# Or visit: https://github.com/casey/just#installation

# Then you can use:
just dev              # Start development server
just lint             # Run quality checks (fast, no link checking)
just check-links      # Check for broken links only
just check-all        # Run all checks including links (slower)
just create-lang <code_lang> # Create new language structure
just install-hooks    # Install pre-commit hooks

Manual Commands¶

Without justfile, you can run commands directly:

# Start development server
uv run mkdocs serve

# Run all quality checks (includes markdown linting)
uv run pre-commit run --all-files

# Check for broken links only
lychee docs/en/**/*.md

# Create new language
uv run python scripts/create-language.py <code_lang>

Pre-commit Hooks (Optional)¶

To automatically run quality checks before each commit:

# Install pre-commit hooks
uv run pre-commit install

# Run all checks (excludes link checking for performance)
uv run pre-commit run --all-files

The pre-commit hooks will automatically:

• Fix trailing whitespace and end-of-file issues
• Check markdown formatting with markdownlint
• Format Python code with ruff
• Format other files with prettier

Note: Link checking is handled separately via just check-links for better performance.

Alternative Setup¶

If you don't want to use uv:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Start development server
mkdocs serve

Adding Translations¶

To add a new language:

just create-lang es
just sync-langs

# Or manually

python scripts/create-language.py es
python scripts/sync-languages.py

Quality Checks¶

just lint
just check-links

# Or manually

markdownlint README.md docs/**/*.md
lychee README.md docs/en/**/*.md