# How to Add a Logo to Your Awesome List README

> Learn how to add a logo to your Awesome list README. Store your image in a media directory and reference it using Markdown or HTML for a professional look.

- Repository: [Sindre Sorhus/awesome](https://github.com/sindresorhus/awesome)
- Tags: how-to-guide
- Published: 2026-07-07

---

**To add a logo to your Awesome list README, store the image file in a `media/` directory and reference it using Markdown or HTML syntax at the top of your README file.**

The `sindresorhus/awesome` repository treats each curated list as a standalone Markdown document, with visual assets organized in a dedicated `media/` folder. When creating your own Awesome list, you follow the same architectural pattern established in the main repository to ensure consistency across the ecosystem.

## Store Logo Assets in the media/ Directory

The repository architecture expects visual assets to live in a `media/` folder at the root level. In `sindresorhus/awesome`, the main Awesome logo resides at `media/logo.svg`, establishing this location as the standard for all image files.

When preparing your list:

- Create a `media/` directory in your repository root
- Place your logo file inside (e.g., `media/your-list-logo.svg`)
- Use **SVG format** for scalability, or PNG for raster graphics

This approach keeps assets organized and ensures GitHub's Markdown renderer can resolve relative paths correctly.

## Reference the Logo in Your README

You can embed the logo using either Markdown or HTML syntax. The main [`readme.md`](https://github.com/sindresorhus/awesome/blob/main/readme.md) demonstrates this pattern in the first few lines of the document.

**Markdown syntax** provides simple insertion but offers no size control:

```markdown
![Your List Logo](media/your-list-logo.svg)

```

**HTML syntax** allows precise alignment and sizing attributes:

```html
<div align="center">
  <img src="media/your-list-logo.svg" alt="Your List Logo" width="300"/>
</div>

```

The HTML method is recommended when you need to center the image or specify dimensions, as GitHub Flavored Markdown passes through raw HTML blocks.

## Match the Official Awesome Styling

To maintain visual consistency with the main Awesome list, wrap your logo in a center-aligned container. The official [`readme.md`](https://github.com/sindresorhus/awesome/blob/main/readme.md) uses this exact pattern to display the global Awesome logo at the top of the file.

Example implementation:

```markdown
<div align="center">
  <img src="media/your-list-logo.svg" alt="Your List Logo" width="300"/>
</div>

# Your Awesome List Title

```

This structure ensures your list header matches the established design conventions of the Awesome ecosystem.

## Follow the Creation Guidelines

Before committing your logo, verify compliance with the contribution standards outlined in [`create-list.md`](https://github.com/sindresorhus/awesome/blob/main/create-list.md). This checklist reminds contributors to follow the list guidelines and maintain repository quality standards.

Best practices for committing:

- Add the image file and README update in the same commit to keep history tidy
- Ensure the logo follows the Awesome manifesto regarding content and presentation
- Test that the image renders correctly on GitHub before submitting pull requests

## Summary

- **Store logo files** in a `media/` directory at the repository root, following the pattern established in `sindresorhus/awesome`
- **Use relative paths** like `media/your-list-logo.svg` to ensure GitHub renders images correctly
- **Use HTML syntax** (`<div align="center">` with `<img>` tags) for center alignment and size control, or standard Markdown for simple insertion
- **Verify compliance** with [`create-list.md`](https://github.com/sindresorhus/awesome/blob/main/create-list.md) guidelines before finalizing your list

## Frequently Asked Questions

### Should I use SVG or PNG format for my Awesome list logo?

SVG is the recommended format for logos in Awesome lists because it scales cleanly across all device resolutions without quality loss. The main Awesome repository uses `media/logo.svg` as its primary asset. However, PNG is acceptable if your logo requires complex raster effects or transparent backgrounds that don't render well in vector format.

### Can I use absolute URLs instead of relative paths for the logo?

While GitHub Markdown supports absolute URLs, **relative paths are strongly recommended** for Awesome lists. Relative paths ensure the logo remains accessible if the repository is forked or mirrored, and they keep the repository self-contained. Use `media/logo.svg` rather than `https://raw.githubusercontent.com/...` references.

### Where exactly should I place the logo reference in my README?

Position the logo reference at the **very top of your README file**, before the H1 title or description. According to the structure in [`readme.md`](https://github.com/sindresorhus/awesome/blob/main/readme.md), the logo appears in the first few lines of the document, typically wrapped in a center-aligned div block followed by the list title and description.

### Does adding a logo require updating the create-list.md checklist?

No, you do not need to modify [`create-list.md`](https://github.com/sindresorhus/awesome/blob/main/create-list.md) itself. Instead, ensure your list satisfies the guidelines described in that file. The checklist reminds you to follow general contribution standards, but logo placement is handled within your individual list repository following the patterns shown in the main [`readme.md`](https://github.com/sindresorhus/awesome/blob/main/readme.md).