Contributing

If you’re interested in supporting the Hub’s development and are familiar with Markdown and MDX, read on to learn how to contribute to the project.

Contributions are very welcome and appreciated. Be sure to review CONTRIBUTING.md before getting started with your contribution!

Project Structure

This is not the entire project structure, but it’s the most important part of the project structure which we recommend you limit your contributions to.

Web-only Contribution

While this method is limited in terms of what you should contribute, you can still contribute to the project by adding new text content on existing pages, fixing typos, or improving existing text content.

Requirements

• Good understanding of Markdown and MDX
• Basic understanding of how to use GitHub
• A brain and patience
• A computer and an internet connection

Setting up the project

IDE-based Contribution

This method is more advanced and allows you to contribute to the project in a more flexible way. You can add new pages, edit existing pages, and add new components to the Hub. This also allows you to preview your changes locally before submitting a pull request.

Requirements

• Basic understanding of Markdown and MDX and the local components exported by @components/docs
• Basic understanding of how to use GitHub
• Git installed on your machine
• A brain and patience
• A computer and an internet connection
• A code editor like VSCode or a GitHub’s Codespace
• Optional: Socket.dev CLI for supply chain security

Setting up the project

Socket.dev Firewall (Optional)

The Hub uses Socket.dev to detect supply chain attacks in npm packages. Setting up aliases lets you use pnpm as normal while scanning every install automatically.

First, install the Socket CLI globally:

npm i -g sfw

Then configure shell aliases for your platform:

macOS / Linux (Bash / Zsh)

Add to ~/.bashrc or ~/.zshrc:

alias npm="sfw npm"
alias yarn="sfw yarn"
alias pnpm="sfw pnpm"
alias npx="sfw npx"

Then run source ~/.bashrc (or ~/.zshrc) to apply.

Windows (PowerShell)

Add to your PowerShell profile ($PROFILE):

function pnpm { sfw pnpm @args }
function npm { sfw npm @args }
function npx { sfw npx @args }

Restart PowerShell to apply. Now pnpm install runs through Socket automatically.

GitHub Codespaces (browser-based editing with live preview)

The repo ships with a pre-configured devcontainer so you can contribute entirely from your browser with a live preview — no local setup required.

This approach is equivalent to visual editing — you see the rendered result of every change in real time, without needing to install anything locally.

Scaffolding a new exam page

Instead of copying an existing page and editing it manually, use the scaffold script to generate a correctly-structured starting point:

node scripts/new-exam.mjs --code AZ-999 --name "Microsoft Azure Whatever"

Optional flags:

The script:

• Validates the exam code format and determines the correct content area
• Creates src/content/docs/<area>/<CODE>.mdx with all five required tabs
• Prints a checklist of what to fill in next (exam URL description, training course link, etc.)

The new page is automatically picked up by the sidebar — no manual astro.config.mjs edits needed.

VSCode Support

We recommend using VSCode or GitHub Codespaces for contributing. The repo includes a pre-configured .vscode/settings.json with Markdown paste and drop settings, and a .devcontainer configuration for a one-click Codespaces setup.

Recommended extensions:

• Astro VSCode Extension
• MDX Extension

Where to begin?

If you’re new to the project, you can start by fixing typos, adding new studying resources, or improving existing guides. This will help you get familiar with the project structure and the way content is written.

Here are some resources that will help you understand how the Hub works better:

• Astro Markdown and MDX Guide
• Astro Content Collections
• Astro Documentation