# How to Structure the Table of Contents in an Awesome List: A Complete Guide

> Learn how to structure the table of contents in an awesome list. Follow these simple steps to organize your awesome list for maximum clarity and impact.

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

---

**Name the section exactly `## Contents`, place it immediately after the description, use a flat list of top-level categories only, and exclude auxiliary sections like Contributing or Footnotes.**

The sindresorhus/awesome repository maintains strict guidelines for curating high-quality resource lists. According to the official [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) and manifesto, the **table of contents** serves as the navigational backbone that determines whether your list meets community standards. Following the exact formatting rules ensures your README passes `awesome-lint` checks and provides a consistent experience for readers.

## Core Requirements for the Table of Contents

### Name the Section Exactly "Contents"

The section header must be precisely `## Contents` (or `# Contents` if you prefer a top-level header). According to [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) lines 80-82, this specific naming convention is mandatory to maintain uniformity across all Awesome lists in the repository.

### Position It as the First Content Section

Your table of contents must appear immediately after the brief description or logo at the top of the README. As specified in [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) line 82, placing the Contents section first ensures readers can instantly navigate to relevant categories without scrolling through extensive introductions.

### Use a Flat List Structure

Only one level of nesting is permitted—preferably none. The guidelines in [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) line 83 mandate a flat list structure to keep the TOC scannable and avoid deep indentation that complicates navigation. Each entry should represent a top-level category such as **Platforms**, **Programming Languages**, or **Tools & Utilities**.

### Exclude Non-Essential Sections

The TOC must **not** contain entries for `Contributing`, `Footnotes`, or other auxiliary sections. According to [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) lines 84-85, these entries are considered clutter that distracts from the actual curated content. The manifesto in [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md) lines 81-82 further emphasizes keeping the structure minimal and focused on resource categories only.

## Implementation Example

Here is a compliant table of contents structure based on the source guidelines:

```markdown

# Awesome My-Topic

[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)

A concise, one-sentence description of what the list covers.

## Contents

- [Platforms](#platforms)
- [Programming Languages](#programming-languages)
- [Front-End Development](#front-end-development)
- [Back-End Development](#back-end-development)
- [Databases](#databases)
- [Tools & Utilities](#tools--utilities)

## Platforms

- ...

## Programming Languages

- ...

```

Notice that each entry links to the corresponding heading using standard Markdown anchor syntax, and no auxiliary sections appear in the list.

## Validation and Automated Checking

Following these structural rules is essential for passing `awesome-lint`, the automated tool that validates list submissions against the sindresorhus/awesome standards. The manifesto in [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md) recommends using a TOC generator to maintain consistency, ensuring that your table of contents stays synchronized with your actual headings as the list grows.

## Summary

- Name the section exactly `## Contents` to match the required format specified in [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md).

- Place it immediately after your description or logo as the first content section.
- Use a flat list with only top-level categories—no nested sub-lists or excessive indentation.
- Exclude `Contributing`, `Footnotes`, and other auxiliary sections from the TOC.
- Link to standard Markdown anchors generated automatically from your headings.

## Frequently Asked Questions

### Can I use a different name like "Table of Contents" for the section?

No. The guidelines in [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) explicitly require the header to be exactly `## Contents` (or `# Contents`). Using alternative names like "Table of Contents" or "TOC" will cause your submission to fail the automated linting checks required for inclusion in the main repository.

### Are nested sub-categories allowed in the Contents section?

No. The rules specify a flat list structure with only one level of nesting allowed, preferably none. Deeply indented sub-categories in the TOC violate the scannability principle outlined in [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) line 83 and should be avoided. Sub-categories should appear only within the body sections, not in the table of contents.

### Should I include the Contributing section in my table of contents?

No. You must exclude auxiliary sections such as `Contributing`, `Footnotes`, and similar meta-sections from the table of contents. These sections typically appear at the end of your README but should not be listed in the Contents section according to lines 84-85 of [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md).

### Do I need to manually create anchor links for the TOC entries?

No. Standard Markdown automatically generates anchor links from your headings based on the text content. Simply use the format `[Category Name](#category-name)` where the anchor matches the heading text in lowercase with hyphens replacing spaces. The [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md) manifesto recommends using generators to handle this automatically and ensure consistency.