Contributing to Awesome Ads¶

We welcome contributions from the community! Follow these guidelines to help us improve the Awesome Ads repository.

Repository structure¶

├── docs/
│   ├── channels/     # One guide per advertising channel
│   ├── resources/    # Cross-cutting topics (analytics, legal, FAQ, …)
│   ├── ad-ad-templates/    # Template and design resources
│   └── meta/         # Repo documentation
├── .github/          # CI, Dependabot, issue/PR templates
└── scripts/          # Maintenance scripts (link checker)

Add new channel guides under docs/channels/. Add cross-cutting topics under docs/resources/. Update docs/README.md and the root README.md when adding pages.

How to contribute¶

Fork the repository — TMHSDigital/Awesome-Ads

Clone your fork

git clone https://github.com/your-username/Awesome-Ads.git
cd Awesome-Ads

Create a branch
```
git checkout -b your-branch-name
```
Make your changes — follow existing markdown style; keep links relative.

Verify locally

npx markdownlint-cli2 "**/*.md"
python scripts/check-public-repo-hygiene.py
python scripts/check-internal-links.py
python scripts/prepare-mkdocs.py
mkdocs build --strict

Commit and push

git commit -m "Description of your changes"
git push origin your-branch-name

Open a pull request against main.

Preview the site locally¶

Install MkDocs Material and serve the docs site:

pip install -r requirements-docs.txt
python scripts/prepare-mkdocs.py
mkdocs serve

Open the local URL printed by mkdocs serve (typically port 8000).

Standards¶

Write clear, accurate prose aimed at small-business readers.
Use relative links so pages work on GitHub and GitHub Pages.
End markdown files with a single trailing newline.
Update the table of contents when adding or renaming pages.

Issues and bug reports¶

Use Issues for bugs and content gaps. Reference issue numbers in commits when fixing them:

git commit -m "Fixes #123: Description of the fix"

Community guidelines¶

Follow our Community Guidelines.