repo-toc

Easily generate a markdown Table of Contents (TOC) for your GitHub repository. Automatically respects .gitignore files and excludes ignored files and directories from the TOC.

Installation

Install the package using npm:

npm install -g repo-toc

Usage

repo-toc provides a simple way to generate a markdown Table of Contents for all files in your GitHub repository.

Example

Input:

Your directory structure:

.
├── TestFile3.md
├── test-files/
│   ├── TestFile1.md
│   └── TextFile.txt

Output:

The generated Table of Contents:

    <!---TOC-START--->
    * [TestFile3](./TestFile3.md)
    * **test-files**
      * [Test File 1 Title](./test-files/TestFile1.md)

    <!---TOC-END--->

CLI

repo-toc [options]

Options:
      --version  Show version number                                   [boolean]
  -d, --dir      Directory path to generate TOC for
                [string] [default: process.cwd()]
  -e, --ext      File extensions to include (comma-separated)
                                                       [string] [default: ".md"]
  -o, --output   File path to save the TOC     [string] [default: "./README.md"]
  -x, --exclude  Directories to exclude (comma-separated)              [string]
  -h, --help     Show help                                             [boolean]

**Important**: Files and directories listed in `.gitignore` files are automatically excluded from the TOC generation. This includes:
- Files and directories specified in `.gitignore` at any level in your repository
- Common ignored patterns like `node_modules/`, `dist/`, `build/`, `.git/`, etc.
- You can still use the `--exclude` option to exclude additional directories beyond what's in `.gitignore`

repo-toc

.gitignore Support

repo-toc automatically respects .gitignore files throughout your repository:

• Automatic exclusion: Files and directories listed in .gitignore are automatically excluded from TOC generation
• Multi-level support: Respects .gitignore files at any directory level in your repository
• Common patterns: Automatically excludes common ignored patterns like node_modules/, dist/, build/, .git/, etc.
• Additional exclusions: You can still use the --exclude option to exclude additional directories beyond what's in .gitignore

This ensures your TOC only includes files that are actually tracked in your repository, keeping it clean and relevant.

Usage Examples

Generate TOC excluding specific directories:

repo-toc --exclude node_modules,dist,build

Generate TOC for only JavaScript files, excluding test directories:

repo-toc --ext .js,.ts --exclude tests,__tests__,spec

Note: The tool automatically respects .gitignore files and excludes any files or directories listed there, in addition to your manual exclusions. This ensures your TOC only includes files that are actually tracked in your repository.

Use with Pre-commit Hooks

You can integrate repo-toc with pre-commit hooks to automatically generate and update the TOC before each commit. This ensures your TOC is always up-to-date.

Setup

1. Install pre-commit (if not already installed):

pip install pre-commit

2. Add repo-toc to your package.json:

{
  "devDependencies": {
    "repo-toc": "^1.2.0"
  },
  "scripts": {
    "generate-toc": "./.github/hooks/generate-toc.sh",
    "install-hooks": "pre-commit install"
  }
}

3. Create a pre-commit hook script (.github/hooks/generate-toc.sh):

#!/bin/bash
set -e

echo "🔄 Generating Table of Contents..."

# Check if Node.js and npm are available
if ! command -v node &> /dev/null || ! command -v npm &> /dev/null; then
    echo "❌ Node.js/npm is not installed. Please install Node.js to generate TOC."
    exit 1
fi

# Install repo-toc if not already installed
if ! npm list -g repo-toc &> /dev/null; then
    echo "📦 Installing repo-toc globally..."
    npm install -g repo-toc
fi

# Generate TOC for README.md
if [ -f "README.md" ]; then
    echo "📝 Updating Table of Contents in README.md..."
    
    # Create a backup
    cp README.md README.md.backup
    
    # Generate TOC with repo-toc
    repo-toc -i README.md
    
    # Check if the file was modified
    if ! cmp -s README.md README.md.backup; then
        echo "✅ Table of Contents updated successfully!"
        # Add the updated file to git staging area
        git add README.md
    else
        echo "ℹ️  Table of Contents is already up to date."
    fi
    
    # Clean up backup
    rm README.md.backup
else
    echo "❌ README.md not found in current directory"
    exit 1
fi

echo "🎉 TOC generation completed!"

4. Configure pre-commit (.pre-commit-config.yaml):

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-markdown
        args: [--fix]

  - repo: local
    hooks:
      - id: generate-toc
        name: Generate Table of Contents
        entry: ./.github/hooks/generate-toc.sh
        language: script
        files: '^README\.md$'
        pass_filenames: false
        stages: [commit]

  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.37.0
    hooks:
      - id: markdownlint
        args: [--fix]
        files: \.md$

5. Install the pre-commit hooks:

npm run install-hooks
# or
pre-commit install

Benefits

• Automatic TOC updates: TOC is generated/updated automatically before each commit
• Consistent formatting: Ensures TOC follows the same format across all commits
• No manual intervention: Developers don't need to remember to update the TOC
• Integration with other hooks: Works seamlessly with markdown linting and other pre-commit hooks

Use with Github actions

It will auto generate the TOC after you commit things on Github. You use this github action

name: Generate TOC

on:
  push:
    branches:
      - main

jobs:
  toc:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'

    - name: Install markdown-toc
      run: npm install -g repo-toc

    - name: Generate TOC
      run: repo-toc -i README.md

    - name: Commit and Push Changes
      run: |
        git config --global user.name "github-actions[bot]"
        git config --global user.email "github-actions[bot]@users.noreply.github.com"
        git add README.md
        git commit -m "Update TOC"
        git push
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Code Example

To generate the TOC:

const path = require('path');

const dirPath = path.join(__dirname, "mocks");
const filePath = path.join(__dirname, "README.md");

fs.writeFileSync(filePath, "## Table of contents");
generateTableOfContent({ dirPath, filePath });

// Generate TOC excluding specific directories
// Note: .gitignore files are automatically respected
generateTableOfContent({
  dirPath: __dirname,
  filePath: path.join(__dirname, "README.md"),
  excludedDirs: ["node_modules", "dist", "build"]
});

// Call the function to generate the TOC
generateTableOfContent();
// It will update the README.md file with the Table of Contents

API

generateTableOfContent(options)

Generates a Table of Contents for the specified directory.

Parameters:

• options (object): Configuration options for generating the TOC.
  • dirPath (string): The directory path to scan for files.
    • Default: process.cwd() (the current working directory).
  • extensions (array of strings): An array of file extensions to include in the TOC.
    • Default: [".md"].
  • filePath (string): The path where the generated TOC will be written.
    • Default: path.join(__dirname, "README.md").
  • excludedDirs (array of strings): An array of directory names to exclude from the TOC.
    • Default: [].
    • Automatic exclusions: Directories starting with . and files/directories listed in .gitignore files are automatically excluded, regardless of this parameter.
    • This parameter allows you to exclude additional directories beyond what's already ignored by .gitignore.

Returns:
void

Contributing

We welcome contributions! If you'd like to report issues, request features, or submit pull requests, please visit our GitHub repository.

Automated Publishing

This package uses automated publishing to NPM:

• Automatic: New versions are published automatically when changes are merged to the main branch
• Version Bumping: Semantic versioning based on conventional commit messages
• Release Notes: GitHub releases are created automatically with each publish

For setup details, see Release Setup Guide.

License

This package is licensed under the ISC License.

Feel free to customize this further based on additional features or specific instructions.