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

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 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 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 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 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 lines 84-85, these entries are considered clutter that distracts from the actual curated content. The manifesto in 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:

# 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 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.

• 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 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 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.

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 manifesto recommends using generators to handle this automatically and ensure consistency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}